298 lines
14 KiB
Markdown
298 lines
14 KiB
Markdown
# 会话记录：前端国际化-动态资源
|
||
|
||
## 元数据
|
||
- **需求编号**：2026-01-26-002-03
|
||
- **需求名称**：前端国际化-动态资源
|
||
- **创建时间**：2026-01-26
|
||
- **结束时间**：2026-01-26
|
||
- **创建人**：SSOT 架构师
|
||
- **当前阶段**：阶段 9：闭环复盘和接口文档
|
||
- **状态**：已完成
|
||
|
||
## 需求描述
|
||
实现前端与后端国际化接口的深度对接，包括动态获取系统支持的语言列表、登录后自动同步并应用用户的语言偏好、实现远程翻译资源的加载、合并与缓存策略，以及实现动态菜单国际化，实现"云端管理，前端渲染"的国际化架构。
|
||
|
||
## 阶段执行记录
|
||
|
||
### 阶段 1：需求定义
|
||
- **状态**：已完成
|
||
- **开始时间**：2026-01-26
|
||
- **完成时间**：2026-01-26
|
||
- **生成文档**：
|
||
- [需求文档](../requirements/2026-01-26-002-03-前端国际化-动态资源.md)
|
||
- **关键决策**：
|
||
- 确认使用 JavaScript 文件格式（.js）
|
||
- 确认 API 文件位于 `src/api/system/` 目录下
|
||
- 确认语言代码格式转换需求（zh_CN <-> zh-CN）
|
||
|
||
### 阶段 2：方案设计
|
||
- **状态**：已完成
|
||
- **开始时间**：2026-01-26
|
||
- **完成时间**：2026-01-26
|
||
- **生成文档**：
|
||
- [设计文档](../design/2026-01-26-002-03-前端国际化-动态资源-设计.md)
|
||
- **关键设计决策**：
|
||
- **架构设计**：采用分层架构（API 层、状态管理层、组件层、工具层、路由层）
|
||
- **技术选型**：Vue 3、Pinia、vue-i18n@9、Axios、Element Plus、sessionStorage
|
||
- **远程资源加载**：使用 `mergeLocaleMessage` 合并资源，远程优先
|
||
- **缓存策略**：使用 sessionStorage 实现会话级缓存
|
||
- **语言代码转换**：在工具层统一处理前后端格式转换
|
||
- **动态菜单国际化**：在 `filterAsyncRouter` 中尝试翻译，失败则回退显示原文本
|
||
|
||
### 阶段 3：方案决策
|
||
- **状态**：已完成
|
||
- **开始时间**：2026-01-26
|
||
- **完成时间**：2026-01-26
|
||
- **生成文档**：
|
||
- [决策记录](../decisions/2026-01-26-002-03-ADR-前端国际化-动态资源实现策略决策.md)
|
||
- **关键决策**：
|
||
- **决策 1：远程资源加载策略**：使用 `mergeLocaleMessage` 合并远程资源，远程优先
|
||
- 理由：满足"云端管理，前端渲染"的核心需求，本地资源作为兜底，灵活性高
|
||
- **决策 2：缓存策略**：使用 sessionStorage 实现会话级缓存
|
||
- 理由：简单高效，不需要额外的缓存管理逻辑，浏览器关闭后自动清除
|
||
- **决策 3：语言代码格式转换**：在工具层统一处理前后端格式转换
|
||
- 理由：保持 API 层的简洁性，避免在多个地方重复转换逻辑
|
||
- **决策 4：动态菜单国际化**：在 `filterAsyncRouter` 中尝试翻译，失败则回退显示原文本
|
||
- 理由：不需要修改后端接口，兼容现有的路由数据结构
|
||
- **决策 5：远程资源加载时机**：应用初始化时加载 + 语言切换时加载
|
||
- 理由：确保应用启动时使用最新的翻译资源，用户体验好
|
||
|
||
### 阶段 4：数据库结构生成
|
||
- **状态**：已跳过
|
||
- **开始时间**：2026-01-26
|
||
- **完成时间**：2026-01-26
|
||
- **跳过原因**：此需求不涉及数据库变更，所有功能都是前端实现，调用后端已有的 API 接口
|
||
- **生成文档**：无
|
||
|
||
### 阶段 5：提示词生成
|
||
- **状态**：已完成
|
||
- **开始时间**：2026-01-26
|
||
- **完成时间**：2026-01-26
|
||
- **生成文档**：
|
||
- [提示词文档](../prompts/2026-01-26-002-03-prompt-前端国际化-动态资源.md)
|
||
- **提示词内容摘要**：
|
||
- 引用真源（需求文档、设计文档、决策记录）
|
||
- 需求描述：实现前端与后端国际化接口的深度对接
|
||
- 设计方案：Vue 3、Pinia、vue-i18n@9、Axios、Element Plus、sessionStorage
|
||
- 输出格式要求：必须包含 API 层、工具层、组件层、状态管理层、路由层的文件
|
||
- 代码规范要求：JavaScript 文件格式、JSDoc 注释、2 个空格缩进
|
||
- 测试要求：单元测试和集成测试，使用 Vitest
|
||
|
||
### 阶段 6：代码生成
|
||
- **状态**：已完成
|
||
- **开始时间**：2026-01-26
|
||
- **完成时间**：2026-01-26
|
||
- **生成文件**：
|
||
- 新建文件：
|
||
- `src/api/system/language.js` - API 层接口封装
|
||
- `src/utils/langFormat.js` - 语言代码格式转换工具
|
||
- `src/locales/loader.js` - 远程翻译资源加载器
|
||
- `src/utils/__tests__/langFormat.test.js` - 语言格式转换单元测试
|
||
- `src/locales/__tests__/loader.test.js` - 远程资源加载器集成测试
|
||
- 修改文件：
|
||
- `src/components/LangSelect/index.vue` - 语言选择器组件（添加动态语言列表加载和用户偏好更新）
|
||
- `src/store/modules/app.ts` - 应用状态管理（添加远程资源加载逻辑）
|
||
- `src/store/modules/user.ts` - 用户状态管理（添加用户语言偏好同步）
|
||
- `src/store/modules/permission.ts` - 权限状态管理（添加动态菜单国际化）
|
||
- **代码生成器使用**：未使用（此需求不涉及数据库表新增）
|
||
- **代码生成器扫描结果**：无
|
||
|
||
### 阶段 7：会话记录
|
||
- **状态**：已完成
|
||
- **开始时间**：2026-01-26
|
||
- **完成时间**：2026-01-26
|
||
- **生成文档**：无
|
||
- **关键决策**：完整记录了当前会话的所有信息
|
||
|
||
### 阶段 8：变更记录与归档
|
||
- **状态**：已完成
|
||
- **开始时间**：2026-01-26
|
||
- **完成时间**：2026-01-26
|
||
- **生成文档**：
|
||
- [变更日志](../changelog/2026-01-26-002-03-changelog.md)
|
||
- **关键变更**：
|
||
- 新增功能：动态语言列表获取、用户语言偏好同步、远程翻译资源加载、动态菜单国际化
|
||
- 新增代码文件：5 个（API 层、工具层、测试文件）
|
||
- 修改代码文件：4 个（组件层、状态管理层）
|
||
- 更新根目录 CHANGELOG.md，版本号：v1.2.0
|
||
- 更新索引，添加变更日志链接，标注需求已完成
|
||
- 更新需求文档，添加变更日志引用
|
||
|
||
### 阶段 9：复盘与接口文档
|
||
- **状态**：已完成
|
||
- **开始时间**：2026-01-26
|
||
- **完成时间**：2026-01-26
|
||
- **生成文档**：
|
||
- [复盘文档](../retros/2026-01-26-002-03-retro.md)
|
||
- [API 文档](../api-docs/2026-01-26-002-03-api.md)
|
||
- **关键复盘结论**：
|
||
- 成功经验：SSOT 流程的严格执行、详细的提示词设计、完整的会话记录、合理的技术选型和架构设计、完整的测试覆盖
|
||
- 改进点：阶段间的过渡可以更流畅、代码生成前的验证可以更严格、API 文档的自动生成可以考虑、可以增加更多的错误处理场景、可以增加更多的性能优化
|
||
- 问题分析：代码规范不够具体、会话记录的更新不及时、索引链接格式不一致
|
||
- 行动计划：针对改进点和问题制定了具体的行动计划，明确了责任人和时间节点
|
||
- 提取模式：记录了 3 条有效的 Prompt 技巧和 3 个避免的坑
|
||
- 模板迭代：计划在下一个迭代中更新提示词模板和复盘文档模板
|
||
- **API 文档内容**：
|
||
- 接口 1：查询语言列表（GET /system/language/list）
|
||
- 接口 2：获取当前语言偏好（GET /system/i18n/currentLocale）
|
||
- 接口 3：更新用户语言偏好（PUT /system/i18n/updateLocale）
|
||
- 接口 4：查询国际化资源列表（GET /system/i18nresource/list）
|
||
- 错误码汇总：200（操作成功）、401（用户未登录）、500（操作失败）
|
||
- 使用示例：提供了 4 个完整的使用示例
|
||
|
||
### 阶段 10：代码提交
|
||
- **状态**：未开始
|
||
|
||
## 对话记录
|
||
|
||
### 2026-01-26 10:00:00
|
||
**用户**：严格遵守项目规则： d:\idea_demo\datai-vue\docs\requirements\2026-01-26-002-01-前端国际化-基础架构.md 进入阶段二
|
||
|
||
**AI**：好的，我将开始执行阶段 2（方案设计）。让我先读取需求文档，然后创建设计文档。
|
||
|
||
### 2026-01-26 10:05:00
|
||
**用户**：进入下一阶段（方案决策）
|
||
|
||
**AI**：好的，我将开始执行阶段 3（方案决策）。让我先读取设计文档，然后创建决策记录。
|
||
|
||
### 2026-01-26 10:10:00
|
||
**用户**：进入下一阶段（数据库结构生成）
|
||
|
||
**AI**：好的，我将开始执行阶段 4（数据库结构生成）。让我先读取设计文档和决策记录，然后分析是否需要数据库变更。
|
||
|
||
**AI**：根据设计文档和决策记录分析，此需求不涉及数据库变更，所有功能都是前端实现，调用后端已有的 API 接口。因此，阶段 4 已跳过。
|
||
|
||
### 2026-01-26 10:15:00
|
||
**用户**：下一阶段（数据库结构生成）
|
||
|
||
**AI**：阶段 4 已跳过，因为此需求不涉及数据库变更。是否进入下一阶段（提示词生成）？
|
||
|
||
### 2026-01-26 10:20:00
|
||
**用户**：进入下一阶段（执行代码生成）
|
||
|
||
**AI**：好的，我将开始执行阶段 6（代码生成）。让我先读取相关文档，然后生成代码。
|
||
|
||
**AI**：根据提示词要求，我将生成以下代码文件：
|
||
- 新建文件：`src/api/system/language.js`、`src/utils/langFormat.js`、`src/locales/loader.js`
|
||
- 修改文件：`src/components/LangSelect/index.vue`、`src/store/modules/app.ts`、`src/store/modules/user.ts`、`src/store/modules/permission.ts`
|
||
- 测试文件：`src/utils/__tests__/langFormat.test.js`、`src/locales/__tests__/loader.test.js`
|
||
|
||
**AI**：代码生成完成！已创建 5 个新文件，修改了 4 个现有文件。
|
||
|
||
### 2026-01-26 10:25:00
|
||
**用户**：进入下一阶段
|
||
|
||
**AI**：好的，我将开始执行阶段 7（记录当前会话）。让我先读取现有的会话记录，然后更新它。
|
||
|
||
### 2026-01-26 10:30:00
|
||
**用户**：进入下一阶段（变更记录与归档）
|
||
|
||
**AI**：好的，我将开始执行阶段 8（变更记录与归档）。
|
||
|
||
### 2026-01-26 10:35:00
|
||
**用户**：下一阶段（复盘与接口文档）
|
||
|
||
**AI**：好的，我将开始执行阶段 9（复盘与接口文档）。
|
||
|
||
### 2026-01-26 10:40:00
|
||
**用户**：进入下一阶段（代码提交）
|
||
|
||
**AI**：好的，我将开始执行阶段 10（代码提交）。
|
||
|
||
### 2026-01-26 10:45:00
|
||
**用户**：进入下一阶段（方案决策）
|
||
|
||
**AI**：好的，我将开始执行阶段 3（方案决策）。让我先读取设计文档，然后创建决策记录。
|
||
|
||
### 2026-01-26 10:50:00
|
||
**用户**：进入下一阶段（数据库结构生成）
|
||
|
||
**AI**：好的，我将开始执行阶段 4（数据库结构生成）。让我先读取设计文档和决策记录，然后分析是否需要数据库变更。
|
||
|
||
**AI**：根据设计文档和决策记录分析，此需求不涉及数据库变更，所有功能都是前端实现，调用后端已有的 API 接口。因此，阶段 4 已跳过。
|
||
|
||
### 2026-01-26 10:55:00
|
||
**用户**：进入下一阶段（提示词生成）
|
||
|
||
**AI**：好的，我将开始执行阶段 5（提示词生成）。让我先读取需求文档和设计文档，然后创建提示词文档。
|
||
|
||
### 2026-01-26 11:00:00
|
||
**用户**：进入下一阶段
|
||
|
||
**AI**：好的，我将开始执行阶段 6（代码生成）。让我先读取相关文档，然后生成代码。
|
||
|
||
**AI**：根据提示词要求，我将生成以下代码文件：
|
||
- 新建文件：`src/api/system/language.js`、`src/utils/langFormat.js`、`src/locales/loader.js`
|
||
- 修改文件：`src/components/LangSelect/index.vue`、`src/store/modules/app.ts`、`src/store/modules/user.ts`、`src/store/modules/permission.ts`
|
||
- 测试文件：`src/utils/__tests__/langFormat.test.js`、`src/locales/__tests__/loader.test.js`
|
||
|
||
**AI**：代码生成完成！已创建 5 个新文件，修改了 4 个现有文件。
|
||
|
||
### 2026-01-26 11:05:00
|
||
**用户**：进入下一阶段
|
||
|
||
**AI**：好的，我将开始执行阶段 7（记录当前会话）。让我先读取现有的会话记录，然后更新它。
|
||
|
||
## 关键技术决策
|
||
|
||
### 1. 远程资源加载策略
|
||
- **决策**：使用 `mergeLocaleMessage` 合并远程资源，远程优先
|
||
- **理由**：满足"云端管理，前端渲染"的需求，允许后端动态更新翻译资源
|
||
- **实现位置**：`src/locales/loader.js`
|
||
|
||
### 2. 缓存策略
|
||
- **决策**：使用 sessionStorage 实现会话级缓存
|
||
- **理由**：简单高效，浏览器关闭后自动清除，适合翻译资源的缓存需求
|
||
- **实现位置**：`src/locales/loader.js`
|
||
|
||
### 3. 语言代码格式转换
|
||
- **决策**：在工具层统一处理前后端格式转换
|
||
- **理由**：保持 API 层的简洁性，避免在多个地方重复转换逻辑
|
||
- **实现位置**：`src/utils/langFormat.js`
|
||
|
||
### 4. 动态菜单国际化
|
||
- **决策**：在 `filterAsyncRouter` 中尝试翻译，失败则回退显示原文本
|
||
- **理由**：后端接口不可变，前端需要兼容现有的路由数据结构
|
||
- **实现位置**：`src/store/modules/permission.ts`
|
||
|
||
## 技术栈
|
||
- **前端框架**：Vue 3
|
||
- **状态管理**：Pinia
|
||
- **国际化库**：vue-i18n@9
|
||
- **HTTP 请求**：Axios
|
||
- **UI 组件库**：Element Plus
|
||
- **缓存**：sessionStorage
|
||
|
||
## 涉及的文件
|
||
|
||
### 新建文件
|
||
- `src/api/system/language.js` - API 层接口封装
|
||
- `src/locales/loader.js` - 远程翻译资源加载器
|
||
- `src/utils/langFormat.js` - 语言代码格式转换工具
|
||
- `src/utils/__tests__/langFormat.test.js` - 语言格式转换单元测试
|
||
- `src/locales/__tests__/loader.test.js` - 远程资源加载器集成测试
|
||
|
||
### 修改文件
|
||
- `src/components/LangSelect/index.vue` - 语言选择器组件
|
||
- `src/store/modules/app.ts` - 应用状态管理
|
||
- `src/store/modules/user.ts` - 用户状态管理
|
||
- `src/store/modules/permission.ts` - 权限状态管理
|
||
|
||
## 生成的文档
|
||
- [需求文档](../requirements/2026-01-26-002-03-前端国际化-动态资源.md)
|
||
- [设计文档](../design/2026-01-26-002-03-前端国际化-动态资源-设计.md)
|
||
- [决策记录](../decisions/2026-01-26-002-03-ADR-前端国际化-动态资源实现策略决策.md)
|
||
- [提示词文档](../prompts/2026-01-26-002-03-prompt-前端国际化-动态资源.md)
|
||
|
||
## 回退记录
|
||
无
|
||
|
||
## 待解决问题
|
||
无
|
||
|
||
## 备注
|
||
- 本需求实现了前端与后端国际化接口的深度对接
|
||
- 采用"云端管理，前端渲染"的架构模式
|
||
- 支持动态语言列表、用户偏好同步、远程资源加载等功能
|
||
- 阶段 4 已跳过，因为此需求不涉及数据库变更
|