11 KiB
11 KiB
会话记录：数据库国际化功能
元数据
- 需求编号：2026-01-21-002-03
- 创建时间：2026-01-25
- 创建人：SSOT 架构师
- 状态：已完成
- 父需求：2026-01-21-002-项目国际化需求
阶段追踪
阶段 1：需求定义
- 状态：已完成
- 生成文档：需求文档
- 关键决策：
- 支持字典数据、系统配置、菜单数据的国际化
- 在现有表中添加英文字段，不创建独立的国际化表
- 预留 JSON 字段用于未来扩展更多语言
- 支持根据用户语言偏好动态查询对应语言的数据
- 实现按语言分别缓存，只清除受影响语言的缓存
- 支持批量导入导出
- 支持运行时动态切换语言
阶段 2：方案设计
- 状态：已完成
- 生成文档：设计文档
- 关键设计决策：
- 多语言字段扩展方案：动态字段扩展 + JSON 辅助
- 缓存策略：按语言分别缓存，缓存键格式：{数据类型}:{标识}:{语言代码}
- 数据回退机制：国际化数据缺失时显示默认语言（中文）
- 实体类设计：在 SysDictData、SysDictType、SysConfig、SysMenu 中添加英文字段和 JSON 字段，以及 getLocalizedXxx() 方法
- 接口设计：遵循 RESTful 规范，支持增删改查、批量导入导出、语言切换
- 权限设计：使用若依框架的权限注解（@PreAuthorize）
阶段 3：方案决策
- 状态：已完成
- 生成文档：架构决策记录
- 关键决策：
- 多语言字段扩展方案：动态字段扩展 + JSON 辅助
- 缓存策略：按语言分别缓存
- 数据回退机制：回退到默认语言（中文）
阶段 4：数据库结构
- 状态：已完成
- 生成文档：SQL 脚本
- 关键数据库变更：
- 修改 sys_dict_data 表，添加 dict_label_en 和 dict_label_i18n 字段
- 修改 sys_dict_type 表，添加 dict_name_en 和 dict_name_i18n 字段
- 修改 sys_config 表，添加 config_name_en 和 config_name_i18n 字段
- 修改 sys_menu 表，添加 menu_name_en 和 menu_name_i18n 字段
- 为英文字段添加索引
阶段 5：提示词生成
- 状态：已完成
- 生成文档：
- 关键内容：
- 基础提示词：
- 引用真源：需求文档、设计文档、架构决策记录、SQL 脚本
- 需求描述：字典数据国际化、系统配置国际化、菜单数据国际化、字段扩展、动态查询、数据回退、缓存刷新、批量导入导出、语言切换
- 设计方案：字段扩展方案、动态字段查询、数据回退机制、缓存策略、缓存刷新机制、语言偏好获取、实体类扩展、Mapper XML 扩展、Service 层扩展
- 输出格式要求：实体类扩展（SysDictData、SysDictType、SysConfig、SysMenu）、Mapper XML 扩展、Service 层扩展、工具类扩展、控制器类扩展、登录控制器扩展
- 代码规范要求：类命名、方法命名、变量命名、常量命名、注释规范、代码格式、导入规范
- 测试要求：单元测试覆盖率不低于 80%、测试用例包含正常场景和异常场景、使用 JUnit 5 和 Mockito 进行测试
- 补充提示词：
- 语言切换功能：I18nController（切换语言接口、获取当前语言接口）
- 数据验证功能：SysDictDataServiceImpl、SysDictTypeServiceImpl、SysConfigServiceImpl、SysMenuServiceImpl（添加数据验证逻辑）
- 批量导入导出功能：SysDictDataController、SysDictTypeController、SysConfigController、SysMenuController（添加导入导出接口）
- 搜索和过滤功能：SysDictDataServiceImpl、SysDictTypeServiceImpl、SysConfigServiceImpl、SysMenuServiceImpl（添加根据语言偏好搜索的方法）
- 基础提示词：
阶段 6：代码生成
- 状态：已完成
- 生成文档：
- 关键代码实现：
- 实体类扩展：
- SysDictData.java：添加 dictLabelEn、dictLabelI18n 字段和 getLocalizedDictLabel() 方法
- SysDictType.java：添加 dictNameEn、dictNameI18n 字段和 getLocalizedDictName() 方法
- SysConfig.java：添加 configNameEn、configNameI18n 字段和 getLocalizedConfigName() 方法
- SysMenu.java：添加 menuNameEn、menuNameI18n 字段和 getLocalizedMenuName() 方法
- Mapper XML 扩展：
- SysDictDataMapper.xml：添加 dict_label_en 和 dict_label_i18n 字段的查询和更新
- SysDictTypeMapper.xml：添加 dict_name_en 和 dict_name_i18n 字段的查询和更新
- SysConfigMapper.xml：添加 config_name_en 和 config_name_i18n 字段的查询和更新
- SysMenuMapper.xml：添加 menu_name_en 和 menu_name_i18n 字段的查询和更新
- Service 层扩展：
- SysDictDataServiceImpl.java：添加数据验证和缓存刷新逻辑
- SysDictTypeServiceImpl.java：添加数据验证和缓存刷新逻辑
- SysConfigServiceImpl.java：添加数据验证和缓存刷新逻辑
- SysMenuServiceImpl.java：添加数据验证和缓存刷新逻辑
- 控制器类扩展：
- I18nController.java：添加语言切换功能（switchLanguage 方法）
- 工具类扩展：
- DictUtils.java：添加根据语言偏好获取字典标签的方法
- 实体类扩展：
阶段 7：会话记录
- 状态：已完成
- 生成文档：会话记录
阶段 8：变更日志
- 状态：已完成
- 生成文档：变更日志
- 关键变更内容：
- 新增功能：
- 字典数据国际化（SysDictData、SysDictType）
- 系统配置国际化（SysConfig）
- 菜单数据国际化（SysMenu）
- 语言切换功能（I18nController）
- 缓存管理（按语言分别缓存）
- 修改功能：
- 实体类扩展（添加英文字段和 JSON 字段）
- Mapper XML 扩展（添加英文字段和 JSON 字段的查询和更新）
- Service 层扩展（添加数据验证和缓存刷新逻辑）
- 工具类扩展（DictUtils 添加根据语言偏好获取字典标签的方法）
- 新增文档：
- 需求文档、设计文档、架构决策记录、SQL 脚本、提示词文档、参考代码文档、实施方案文档、会话记录、变更日志
- 新增代码文件：
- 实体类（4 个修改）
- Mapper XML（4 个修改）
- Service 层（4 个修改）
- Controller 层（1 个新增：I18nController）
- 工具类（1 个修改：DictUtils）
- 新增功能：
阶段 9：复盘与接口
- 状态：已完成
- 生成文档：
- 复盘主要结论：
- 成功经验：
- SSOT 流程的严格执行
- 详细的提示词设计
- 完整的会话记录
- 合理的技术方案选择
- 完善的文档体系
- 改进点：
- 阶段间的过渡可以更流畅
- 代码生成前的验证可以更严格
- 需求覆盖度分析可以更及时
- 用户反馈的响应可以更及时
- API 文档的自动生成可以考虑
- 问题分析：
- 设计文档未完整覆盖需求文档（需求覆盖度约为 60%）
- 用户反馈未及时反映到文档中
- 批量导入导出功能未实现
- 行动计划：
- 在阶段转换时，增加对下一阶段的目的和流程的解释
- 在生成代码前，增加对设计文档和决策记录的再次验证
- 在阶段 2（方案设计）完成后，立即进行需求覆盖度分析
- 建立用户反馈的跟踪机制，确保每个反馈都有明确的处理流程和责任人
- 探索使用 Swagger 等工具自动生成 API 文档
- 提取模式：
- 有效的 Prompt 技巧：具体的输出格式要求、引用真源、详细的代码规范要求
- 避免的坑：不要使用模糊的描述、不要忽略测试要求、不要违反项目规则
- 模板迭代：
- 在设计文档模板中增加"需求覆盖度分析"章节
- 在提示词模板中增加对批量导入导出功能的明确要求
- 成功经验：
- API 接口：
- 刷新国际化资源（POST /system/i18n/refresh）
- 获取当前语言偏好（GET /system/i18n/currentLocale）
- 切换语言（POST /system/i18n/switch）
- 更新用户语言偏好（PUT /system/i18n/updateLocale）
阶段 10：代码提交
- 状态：待开始
- 生成文档：待生成
关键设计决策
1. 多语言字段扩展方案
决策：动态字段扩展 + JSON 辅助
理由：
- 当前阶段：在现有表中添加
dict_label_en、config_name_en、menu_name_en字段，满足中英文需求 - 未来扩展：当需要支持更多语言时，使用 JSON 字段存储多语言数据，避免频繁修改表结构
- 兼容性好：现有代码改动最小，不影响现有功能
- 性能优化：常用语言（中英文）使用独立字段，查询性能最优；其他语言使用 JSON 字段，灵活扩展
2. 缓存策略
决策：按语言分别缓存
理由：
- 缓存键格式：
{数据类型}:{标识}:{语言代码} - 示例：
dict:sys_user_sex:zh-CN、dict:sys_user_sex:en-US - 修改数据后，只清除受影响语言的缓存，减少缓存刷新范围
- 切换语言时，清除当前用户的所有缓存，强制重新加载数据
3. 数据回退机制
决策：国际化数据缺失时，显示默认语言（中文）的数据
理由：
- 如果英文字段为空，回退到中文字段
- 如果 JSON 字段解析失败，回退到中文字段
- 确保用户始终能看到数据，不会因为国际化数据缺失而显示空白
4. 接口设计
决策：遵循 RESTful 规范
理由：
- GET：查询数据
- POST：新增数据
- PUT：修改数据
- DELETE：删除数据
- 支持批量导入导出
- 支持语言切换
5. 权限设计
决策：使用若依框架的权限注解（@PreAuthorize）
理由：
- 与现有权限系统保持一致
- 支持数据权限（@DataScope）
- 语言切换接口无需权限，用户可自行切换
技术栈
- Spring Boot 3.5.7
- Java 21
- MySQL 8.3.0
- MyBatis 3.5.16
- Redis 7.x
- Vue 3
- Element Plus