# 键盘多语言/多布局功能实现总结

## 已完成的工作

### 1. 配置中心外置 ✅
- ✅ 创建 `/Shared/Resource/kb_input_profiles.json` 配置文件
- ✅ 创建 `KBInputProfileManager` 管理器（Shared）
- ✅ 支持的语言和布局：
  - 英语：QWERTY
  - 西班牙语：QWERTY / AZERTY / QWERTZ
  - 葡萄牙语：QWERTY
  - 繁体中文：拼音（繁体）/ 注音全键盘 / 注音标准
  - 印尼语：QWERTY
  - 简体中文：QWERTY

### 2. 布局 JSON 配置补充 ✅
- ✅ 在 `kb_keyboard_layout_config.json` 中新增：
  - `letters_azerty`：AZERTY 布局（西班牙语）
  - `letters_qwertz`：QWERTZ 布局（西班牙语）
  - `letters_bopomofo_full`：繁体注音全键盘布局
  - `letters_bopomofo_standard`：繁体注音标准布局

### 3. 扩展侧布局切换 ✅
- ✅ 创建 `KBKeyboardLayoutResolver`（扩展侧）
  - 从 App Group 读取 `profileId`
  - 根据 `profileId` 解析对应的 `layoutJsonId`
  - 根据 `profileId` 解析对应的联想引擎类型
- ✅ 修改 `KBKeyboardView`：
  - 新增 `currentLayoutJsonId` 属性
  - 新增 `reloadLayoutWithProfileId:` 方法
  - 初始化时从 App Group 读取 profileId 并加载对应布局
- ✅ 修改 `KBKeyBoardMainView`：
  - 新增 `reloadLayoutWithProfileId:` 方法
- ✅ 修改 `KeyboardViewController`：
  - 新增 `kb_checkAndApplyLayoutIfNeeded` 方法
  - 在 `viewDidLoad` 和 `viewDidLayoutSubviews` 中检查并应用布局
  - 检测到 profileId 变化时自动切换布局

### 4. 主 App 配置管理器集成 ✅
- ✅ 修改 `KBPersonInfoVC.m`：
  - 使用 `KBInputProfileManager` 替代硬编码配置
  - 皮肤下发逻辑使用配置管理器

### 5. 繁体联想引擎分流 ✅
- ✅ 扩展 `KBSuggestionEngine`：
  - 新增 `KBSuggestionEngineType` 枚举
  - 支持 4 种引擎类型：Latin / PinyinSimplified / PinyinTraditional / Bopomofo
  - 实现 `setEngineTypeFromString:` 方法
  - 实现各引擎类型的联想逻辑（基础框架）
- ✅ 修改 `KeyboardViewController`：
  - 实现 `kb_updateSuggestionEngineType:` 方法
  - 切换布局时自动切换联想引擎

## 待完成的工作

### 1. 将新增文件添加到 Xcode 工程 ⚠️
**操作指南**: 参考 `docs/xcode-file-addition-guide.md`

需要添加的文件：
- [ ] `Shared/Resource/kb_input_profiles.json`（主 App + 扩展）
- [ ] `Shared/KBInputProfileManager.h`（主 App + 扩展）
- [ ] `Shared/KBInputProfileManager.m`（主 App + 扩展）
- [ ] `CustomKeyboard/Manager/KBKeyboardLayoutResolver.h`（扩展）
- [ ] `CustomKeyboard/Manager/KBKeyboardLayoutResolver.m`（扩展）

### 2. 完善联想引擎实现 ⚠️
**当前状态**: 已实现基础框架，但联想词库需要完善

**需要完善的部分**:
- [ ] 繁体拼音联想：实现拼音到繁体字的映射
- [ ] 注音联想：实现注音符号到繁体字的映射
- [ ] 简体拼音联想：实现拼音到简体字的映射
- [ ] 加载更完整的中文词库

**建议实现方式**:
1. 创建拼音/注音到汉字的映射表（可以使用 JSON 或 plist 文件）
2. 在 `kb_traditionalPinyinSuggestionsForPrefix:` 中实现拼音匹配逻辑
3. 在 `kb_bopomofoSuggestionsForPrefix:` 中实现注音匹配逻辑
4. 可以考虑集成第三方拼音/注音输入法库

### 3. 本地化资源补齐 ⚠️
需要新增并接入：
- [ ] `es.lproj/Localizable.strings`（西班牙语）
- [ ] `pt.lproj/Localizable.strings`（葡萄牙语）
- [ ] `zh-Hant.lproj/Localizable.strings`（繁体中文）
- [ ] `id.lproj/Localizable.strings`（印尼语）

并在 `project.pbxproj` 中更新 `knownRegions`。

### 4. 完整测试 ⚠️
**测试清单**: 参考 `docs/testing-checklist.md`

主要测试项：
- [ ] 主 App 语言选择流程
- [ ] 扩展侧布局切换
- [ ] 联想引擎切换
- [ ] 皮肤下发
- [ ] 异常情况处理
- [ ] 性能测试
- [ ] 回归测试

#### 主流程测试
1. 进入个人资料页，看到 `Input Language` 行
2. 选择单布局语言（如葡语）：
   - 底部 `Confirm` 显示
   - 点击 `Confirm` 后触发切换
3. 选择多布局语言（如西语/繁体）：
   - 底部 `Confirm` 隐藏
   - 进入 `Choose Layout`
   - 在布局页点击 `Confirm` 后触发切换

#### 扩展侧测试
1. 切换到西班牙语 AZERTY：
   - 键盘第一行应显示 `azertyuiop`
2. 切换到西班牙语 QWERTZ：
   - 键盘第一行应显示 `qwertzuiop`
3. 切换到繁体注音全键盘：
   - 键盘应显示注音符号
   - 联想功能应使用注音引擎
4. 切换到繁体拼音：
   - 键盘应显示 QWERTY 布局
   - 联想应显示繁体字

#### 数据落盘测试
确认 App Group 键值写入：
- `AppGroup_SelectedKeyboardLanguageCode`
- `AppGroup_SelectedKeyboardLayoutVariant`
- `AppGroup_SelectedKeyboardProfileId`

#### 皮肤测试
切换语言后确认已发布对应的默认皮肤请求。

## 关键文件清单

### 新增文件
1. `/Shared/Resource/kb_input_profiles.json`
2. `/Shared/KBInputProfileManager.h`
3. `/Shared/KBInputProfileManager.m`
4. `/CustomKeyboard/Manager/KBKeyboardLayoutResolver.h`
5. `/CustomKeyboard/Manager/KBKeyboardLayoutResolver.m`

### 修改文件
1. `/CustomKeyboard/Resource/kb_keyboard_layout_config.json`
2. `/CustomKeyboard/View/KBKeyboardView.h`
3. `/CustomKeyboard/View/KBKeyboardView.m`
4. `/CustomKeyboard/View/KBKeyBoardMainView.h`
5. `/CustomKeyboard/View/KBKeyBoardMainView.m`
6. `/CustomKeyboard/KeyboardViewController.m`
7. `/keyBoard/Class/Me/VC/KBPersonInfoVC.m`

## 注意事项

1. **繁体注音布局**：注音符号的排列顺序需要根据实际台湾键盘标准调整
2. **联想引擎**：繁体注音联想是核心功能，需要重点实现
3. **回退机制**：如果 profileId 不合法，应回退到 `en_US_qwerty`
4. **布局 JSON 缺失**：如果布局 JSON 不存在，不要崩溃，回退到默认布局
5. **皮肤 zip 缺失**：皮肤 zip 缺失时不应阻断输入流程

## 下一步建议

1. **优先级 1**：实现繁体联想引擎分流（最关键）
2. **优先级 2**：将新增文件添加到 Xcode 工程并编译测试
3. **优先级 3**：补齐本地化资源
4. **优先级 4**：完整回归测试

## 给下一个 AI 的任务描述

"请完成繁体中文联想引擎分流功能：在 `KBSuggestionEngine.m` 中实现 `pinyin_traditional`（繁体拼音）和 `bopomofo`（注音）两种联想引擎，并在 `KeyboardViewController.m` 的 `kb_updateSuggestionEngineType:` 方法中调用。同时将新增的文件添加到 Xcode 工程中，确保编译通过并进行完整测试。"