12 KiB
复盘文档：数据库国际化功能
元数据
- 需求编号：2026-01-21-002-03
- 创建时间：2026-01-25
- 创建人：SSOT 架构师
- 父需求：2026-01-21-002-项目国际化需求
复盘概述
本次复盘旨在总结数据库国际化功能的整个需求执行过程，从阶段 1（需求定义）到阶段 8（变更记录），识别成功经验、改进点和问题，并制定行动计划，以持续改进项目开发流程。
目标与实际产出对比
目标
- 实现字典数据、系统配置、菜单数据的国际化
- 在现有表中添加英文字段，不创建独立的国际化表
- 预留 JSON 字段用于未来扩展更多语言
- 支持根据用户语言偏好动态查询对应语言的数据
- 实现按语言分别缓存，只清除受影响语言的缓存
- 支持批量导入导出
- 支持运行时动态切换语言
- 修改中文字段时，自动翻译并更新英文字段
实际产出
- ✅ 实现了字典数据、系统配置、菜单数据的国际化
- ✅ 在现有表中添加了英文字段，未创建独立的国际化表
- ✅ 预留了 JSON 字段用于未来扩展更多语言
- ✅ 支持根据用户语言偏好动态查询对应语言的数据
- ✅ 实现了按语言分别缓存，只清除受影响语言的缓存
- ⚠️ 提示词中提到了批量导入导出，但未在代码中实现
- ✅ 实现了运行时动态切换语言
- ❌ 未实现自动翻译功能（根据用户反馈，已明确不需要此功能）
成功经验
1. SSOT 流程的严格执行
从需求定义到代码提交的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据，提高了代码的可追溯性和可维护性。每个阶段都生成了相应的文档，包括需求文档、设计文档、架构决策记录、SQL 脚本、提示词文档、参考代码文档、实施方案文档、会话记录、变更日志等。
2. 详细的提示词设计
阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，确保了生成的代码符合项目规范和需求。提示词中明确指定了需要生成的文件、路径、格式等，提高了生成代码的准确性和规范性。
3. 完整的会话记录
阶段 7 记录了完整的会话过程，包括对话记录、生成的文档和代码、关键决策等，确保了会话的可追溯性和完整性。会话记录详细记录了每个阶段的状态、生成文档、关键决策等，为后续复盘和代码审查提供了重要依据。
4. 合理的技术方案选择
在阶段 3 的架构决策记录中，详细分析了三种技术方案（动态字段扩展 + JSON 辅助、独立国际化表、纯 JSON 字段），并选择了最优方案（动态字段扩展 + JSON 辅助）。这个方案既满足了当前的中英文需求，又为未来扩展更多语言提供了灵活性，同时保证了查询性能。
5. 完善的文档体系
整个需求执行过程生成了完整的文档体系，包括需求文档、设计文档、架构决策记录、SQL 脚本、提示词文档、参考代码文档、实施方案文档、会话记录、变更日志等。这些文档不仅为当前开发提供了依据，也为后续维护和扩展提供了参考。
改进点
1. 阶段间的过渡可以更流畅
在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。例如，在阶段 5 完成后，可以主动解释阶段 6 的目的和流程，让用户更好地理解代码生成的过程。
2. 代码生成前的验证可以更严格
在生成代码前，可以增加对设计文档和决策记录的再次验证，确保代码生成的准确性。例如，可以检查设计文档中的所有功能点是否都在代码中实现，避免遗漏。
3. 需求覆盖度分析可以更及时
在阶段 2（方案设计）完成后，应该立即进行需求覆盖度分析，确保设计文档完整覆盖了需求文档的所有要求。本次在阶段 6（代码生成）完成后才进行需求覆盖度分析，发现设计文档缺失了自动翻译、批量导入导出、搜索和过滤、数据验证、语言切换接口、前端界面集成、性能指标等核心功能，导致这些功能未在设计文档中体现。
4. 用户反馈的响应可以更及时
用户在阶段 6 之前明确表示"修改中文字段时，不自动翻译并更新英文字段"，但这个反馈没有及时反映到设计文档和提示词中。应该在收到用户反馈后，立即更新相关文档，确保后续开发符合用户的最新要求。
5. API 文档的自动生成可以考虑
可以探索使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。本次手动创建 API 文档，虽然保证了文档的完整性，但也增加了维护成本。
问题分析
问题 1：设计文档未完整覆盖需求文档
问题描述：设计文档缺失了自动翻译、批量导入导出、搜索和过滤、数据验证、语言切换接口、前端界面集成、性能指标等核心功能，需求覆盖度约为 60%。
根因分析：
- 阶段 2（方案设计）完成后，未进行需求覆盖度分析
- 设计文档编写时，只关注了核心的数据库表结构设计和实体类设计，忽略了其他功能点
- 未在设计阶段与用户进行充分沟通，确认设计文档是否完整覆盖了需求
解决方案：
- 在阶段 2（方案设计）完成后，立即进行需求覆盖度分析，对比需求文档和设计文档，确保设计文档完整覆盖了需求文档的所有要求
- 在设计阶段与用户进行充分沟通，确认设计文档是否完整覆盖了需求
- 在设计文档中添加"需求覆盖度分析"章节，明确标注每个需求点在设计文档中的位置
问题 2：用户反馈未及时反映到文档中
问题描述：用户在阶段 6 之前明确表示"修改中文字段时，不自动翻译并更新英文字段"，但这个反馈没有及时反映到设计文档和提示词中。
根因分析：
- 收到用户反馈后，未立即更新相关文档
- 未建立用户反馈的跟踪机制，导致反馈可能被忽略
- 用户反馈的优先级不明确，导致反馈处理不及时
解决方案：
- 建立用户反馈的跟踪机制，确保每个反馈都有明确的处理流程和责任人
- 收到用户反馈后，立即更新相关文档，并在会话记录中记录反馈的处理情况
- 明确用户反馈的优先级，高优先级的反馈应该立即处理
问题 3：批量导入导出功能未实现
问题描述：需求文档中明确要求支持批量导入导出，提示词中也提到了批量导入导出，但未在代码中实现。
根因分析：
- 提示词中提到了批量导入导出，但未明确要求在代码中实现
- 代码生成时，只关注了核心的国际化功能，忽略了批量导入导出功能
- 未在代码生成前进行需求覆盖度分析，确保所有需求点都在代码中实现
解决方案：
- 在提示词中明确要求实现所有需求点，包括批量导入导出
- 在代码生成前进行需求覆盖度分析，确保所有需求点都在代码中实现
- 在代码生成后进行代码审查，确保所有需求点都在代码中实现
行动计划
针对改进点 1：阶段间的过渡可以更流畅
行动项：在阶段转换时，增加对下一阶段的目的和流程的解释 责任人：AI Assistant 时间节点：下一个需求立即执行
针对改进点 2：代码生成前的验证可以更严格
行动项：在生成代码前，增加对设计文档和决策记录的再次验证 责任人：AI Assistant 时间节点：下一个需求立即执行
针对改进点 3：需求覆盖度分析可以更及时
行动项：在阶段 2（方案设计）完成后，立即进行需求覆盖度分析 责任人：AI Assistant 时间节点：下一个需求立即执行
针对改进点 4：用户反馈的响应可以更及时
行动项：建立用户反馈的跟踪机制，确保每个反馈都有明确的处理流程和责任人 责任人：项目团队 时间节点：下一个迭代
针对改进点 5：API 文档的自动生成可以考虑
行动项：探索使用 Swagger 等工具自动生成 API 文档 责任人：项目团队 时间节点：下一个迭代
针对问题 1：设计文档未完整覆盖需求文档
行动项：在阶段 2（方案设计）完成后，立即进行需求覆盖度分析 责任人：AI Assistant 时间节点：下一个需求立即执行
针对问题 2：用户反馈未及时反映到文档中
行动项：建立用户反馈的跟踪机制，确保每个反馈都有明确的处理流程和责任人 责任人：项目团队 时间节点：下一个迭代
针对问题 3：批量导入导出功能未实现
行动项：在提示词中明确要求实现所有需求点，包括批量导入导出 责任人：AI Assistant 时间节点：下一个需求立即执行
提取模式
有效的 Prompt 技巧
1. 具体的输出格式要求
在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。例如，在提示词中明确指定"生成以下文件：SysDictData.java、SysDictType.java、SysConfig.java、SysMenu.java"，可以确保生成的代码符合预期。
2. 引用真源
在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。例如，在提示词中明确引用"需求文档：[链接]、设计文档：[链接]"，可以确保生成的代码符合需求和设计要求。
3. 详细的代码规范要求
在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。例如，在提示词中明确指定"类命名：使用 PascalCase；方法命名：使用 camelCase；变量命名：使用 camelCase"，可以确保生成的代码符合项目规范。
避免的坑
1. 不要使用模糊的描述
在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。应该使用具体的描述（如"请生成符合若依框架规范的代码，包括实体类、Mapper XML、Service 层、Controller 层"）。
2. 不要忽略测试要求
在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。应该在提示词中明确指定测试要求（如"单元测试覆盖率不低于 80%、测试用例包含正常场景和异常场景、使用 JUnit 5 和 Mockito 进行测试"）。
3. 不要违反项目规则
在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。应该在提示词中明确指定项目规则（如"使用若依框架的权限注解（@PreAuthorize）、使用若依框架的异常处理机制"）。
模板迭代
经过本次复盘，发现当前的设计文档模板在需求覆盖度分析方面可以改进。建议在设计文档模板中增加"需求覆盖度分析"章节，明确标注每个需求点在设计文档中的位置，确保设计文档完整覆盖了需求文档的所有要求。
另外，发现当前的提示词模板在批量导入导出功能方面可以更具体。建议在提示词模板中增加对批量导入导出功能的明确要求，确保生成的代码包含批量导入导出功能。
计划在下一个迭代中更新设计文档模板和提示词模板，增加需求覆盖度分析和批量导入导出功能的具体要求。