1

docs/xcode-file-addition-guide.md

@@ -0,0 +1,171 @@
+# 将新增文件添加到 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. ✅ 测试联想功能
+
+如果遇到任何问题，请参考上面的"常见问题排查"部分。