keyboard/docs/xcode-file-addition-guide.md

# 将新增文件添加到 Xcode 工程的操作指南

## 需要添加的文件

### 1. Shared 文件（主 App + 扩展都需要）

#### 配置文件
- **文件路径**: `/Shared/Resource/kb_input_profiles.json`
- **添加到 Target**:
  - ✅ keyBoard (主 App)
  - ✅ CustomKeyboard (扩展)
- **操作步骤**:
  1. 在 Xcode 左侧项目导航器中，右键点击 `Shared/Resource` 文件夹
  2. 选择 "Add Files to keyBoard..."
  3. 找到并选择 `kb_input_profiles.json`
  4. 在弹出的对话框中，确保勾选：
     - ✅ Copy items if needed
     - ✅ keyBoard (主 App target)
     - ✅ CustomKeyboard (扩展 target)
  5. 点击 "Add"

#### 管理器类
- **文件路径**:
  - `/Shared/KBInputProfileManager.h`
  - `/Shared/KBInputProfileManager.m`
- **添加到 Target**:
  - ✅ keyBoard (主 App)
  - ✅ CustomKeyboard (扩展)
- **操作步骤**:
  1. 在 Xcode 左侧项目导航器中，右键点击 `Shared` 文件夹
  2. 选择 "Add Files to keyBoard..."
  3. 找到并选择 `KBInputProfileManager.h` 和 `KBInputProfileManager.m`
  4. 在弹出的对话框中，确保勾选：
     - ✅ Copy items if needed
     - ✅ keyBoard (主 App target)
     - ✅ CustomKeyboard (扩展 target)
  5. 点击 "Add"

### 2. 扩展文件（仅扩展需要）

#### 布局解析器
- **文件路径**:
  - `/CustomKeyboard/Manager/KBKeyboardLayoutResolver.h`
  - `/CustomKeyboard/Manager/KBKeyboardLayoutResolver.m`
- **添加到 Target**:
  - ✅ CustomKeyboard (扩展)
- **操作步骤**:
  1. 在 Xcode 左侧项目导航器中，右键点击 `CustomKeyboard/Manager` 文件夹
  2. 选择 "Add Files to keyBoard..."
  3. 找到并选择 `KBKeyboardLayoutResolver.h` 和 `KBKeyboardLayoutResolver.m`
  4. 在弹出的对话框中，确保勾选：
     - ✅ Copy items if needed
     - ✅ CustomKeyboard (扩展 target)
     - ❌ keyBoard (主 App target) - 不勾选
  5. 点击 "Add"

## 验证文件是否正确添加

### 方法 1: 通过 Target Membership 检查
1. 在 Xcode 项目导航器中选择文件
2. 在右侧的 File Inspector 中查看 "Target Membership"
3. 确保勾选了正确的 target

### 方法 2: 通过 Build Phases 检查
1. 在 Xcode 中选择项目根节点
2. 选择对应的 target（keyBoard 或 CustomKeyboard）
3. 切换到 "Build Phases" 标签
4. 展开 "Compile Sources"，确认 `.m` 文件在列表中
5. 展开 "Copy Bundle Resources"，确认 `.json` 文件在列表中

## 编译测试

### 1. 清理构建
```bash
# 在终端中执行
cd "/Users/mac/Desktop/项目/公司/KeyBoard"
xcodebuild clean -workspace keyBoard.xcworkspace -scheme keyBoard
```

### 2. 编译主 App
1. 在 Xcode 中选择 scheme: `keyBoard`
2. 按 `Cmd + B` 编译
3. 检查是否有编译错误

### 3. 编译扩展
1. 在 Xcode 中选择 scheme: `CustomKeyboard`
2. 按 `Cmd + B` 编译
3. 检查是否有编译错误

## 常见问题排查

### 问题 1: "No such file or directory"
**原因**: 文件没有正确添加到 target
**解决方案**:
1. 选择文件
2. 在 File Inspector 中勾选正确的 target
3. 重新编译

### 问题 2: "Duplicate symbol"
**原因**: 文件被重复添加到 Compile Sources
**解决方案**:
1. 选择对应的 target
2. 进入 Build Phases > Compile Sources
3. 找到重复的文件并删除多余的条目

### 问题 3: JSON 文件找不到
**原因**: JSON 文件没有添加到 Copy Bundle Resources
**解决方案**:
1. 选择对应的 target
2. 进入 Build Phases > Copy Bundle Resources
3. 点击 "+" 添加 `kb_input_profiles.json`

### 问题 4: 头文件找不到
**原因**: 头文件搜索路径不正确
**解决方案**:
1. 选择对应的 target
2. 进入 Build Settings
3. 搜索 "Header Search Paths"
4. 确保包含 `$(SRCROOT)/Shared`

## 快速验证脚本

创建一个验证脚本来检查文件是否存在：

```bash
#!/bin/bash

echo "检查新增文件是否存在..."

files=(
    "Shared/Resource/kb_input_profiles.json"
    "Shared/KBInputProfileManager.h"
    "Shared/KBInputProfileManager.m"
    "CustomKeyboard/Manager/KBKeyboardLayoutResolver.h"
    "CustomKeyboard/Manager/KBKeyboardLayoutResolver.m"
)

base_path="/Users/mac/Desktop/项目/公司/KeyBoard"

for file in "${files[@]}"; do
    full_path="$base_path/$file"
    if [ -f "$full_path" ]; then
        echo "✅ $file"
    else
        echo "❌ $file (文件不存在)"
    fi
done

echo ""
echo "检查完成！"
```

保存为 `check_files.sh` 并执行：
```bash
chmod +x check_files.sh
./check_files.sh
```

## 下一步

完成文件添加后，请按照以下顺序进行测试：

1. ✅ 编译主 App（确保没有编译错误）
2. ✅ 编译扩展（确保没有编译错误）
3. ✅ 运行主 App，进入个人资料页
4. ✅ 测试语言切换功能
5. ✅ 测试多布局选择功能
6. ✅ 测试扩展侧布局切换
7. ✅ 测试联想功能

如果遇到任何问题，请参考上面的"常见问题排查"部分。