190 lines
14 KiB
Markdown
190 lines
14 KiB
Markdown
# 迭代复盘 - 数据库表结构设计和创建
|
||
|
||
## 目标 vs 结果指标对比
|
||
|
||
| 指标 | 目标值 | 实际值 | 达成率 | 分析 |
|
||
|------|--------|--------|--------|------|
|
||
| 功能完成数 | 完成数据库表结构设计 | 完成 9 个数据库表设计 | 100% | 按时完成，所有表结构设计符合需求 |
|
||
| 代码质量 | 符合 MyBatis Plus 规范 | 符合 MyBatis Plus 规范 | 100% | 表结构设计符合 MyBatis Plus 规范，与现有项目保持一致 |
|
||
| 测试覆盖率 | 100% | 0%（待执行代码生成后测试） | 0% | 本次阶段仅完成设计和文档，代码生成和测试将在后续阶段完成 |
|
||
| 文档完整性 | 完整的文档链 | 完成需求文档、架构决策、提示词、会话记录、变更记录 | 100% | 文档链完整，符合项目规则要求 |
|
||
|
||
## 3 条有效 Prompt 模式
|
||
|
||
### 模式 1: 需求拆分模式
|
||
|
||
- **描述**: 将复杂需求拆分为多个小模块需求，每个子需求独立、可测试、可交付。拆分时遵循单一职责原则，确保每个子需求只关注一个核心功能点。拆分后为每个子需求创建独立的需求文档，并在主需求文档中建立引用关系。
|
||
- **适用场景**: 适用于复杂功能开发，特别是涉及多个模块、多个技术栈的功能。当需求文档过于庞大（超过 500 行）时，应该考虑拆分。
|
||
- **示例**: REQ-010 "Salesforce 元数据拉取和部署" 被拆分为 17 个子需求（REQ-010-1 到 REQ-010-17），每个子需求关注一个核心功能点，如数据库表结构设计、基础实体类和 Mapper 创建、Salesforce 组织配置管理等。
|
||
- **效果**:
|
||
- 提高了需求管理的粒度，便于跟踪和验收
|
||
- 降低了单个需求的复杂度，便于理解和实现
|
||
- 支持并行开发，提高开发效率
|
||
- 便于优先级排序，可以按需调整开发顺序
|
||
|
||
### 模式 2: 架构决策模式（ADR）
|
||
|
||
- **描述**: 基于架构决策记录（ADR）模板进行架构决策。ADR 包含上下文、决策、后果三个核心部分。上下文描述当前情况和需要解决的问题；决策描述做出的技术选择；后果描述决策带来的积极和消极影响。ADR 必须引用需求文档，确保决策有据可依。
|
||
- **适用场景**: 适用于所有技术选型和架构设计决策，特别是涉及多个技术方案对比的场景。当需要做出技术决策时，应该创建 ADR 文档。
|
||
- **示例**: 0010-database-table-design.md 架构决策记录，针对 REQ-010-1 "数据库表结构设计和创建" 需求，对比了两种技术方案（方案 1：使用外键约束 vs 方案 2：不使用外键约束），最终选择了方案 2，并记录了决策理由和潜在风险。
|
||
- **效果**:
|
||
- 确保架构决策有据可依，避免随意决策
|
||
- 记录决策过程和理由，便于后续回顾和审计
|
||
- 明确决策的后果，便于评估风险
|
||
- 提供决策的可追溯性，便于问题排查
|
||
|
||
### 模式 3: 提示词资产化模式
|
||
|
||
- **描述**: 基于提示词模板创建可重复调用的提示词。提示词必须引用需求文档和架构决策文档，确保输出符合预期。提示词必须定义输出格式，包括代码规范、测试要求、文档要求等。提示词应该版本化管理，便于复用和迭代。
|
||
- **适用场景**: 适用于所有需要 AI 辅助开发的场景，特别是代码生成、文档生成、测试生成等。当需要 AI 生成代码或文档时，应该创建提示词文档。
|
||
- **示例**: 011-database-table-design-create.md 提示词文档，引用了 REQ-010-1.md 需求文档和 0010-database-table-design.md 架构决策文档，定义了详细的输出格式（包括 SQL 脚本、Java 实体类、Mapper 接口、单元测试等），并指定了代码规范（MyBatis Plus 规范、阿里巴巴 Java 开发规范）。
|
||
- **效果**:
|
||
- 确保代码生成符合预期，避免反复修改
|
||
- 提高代码质量，符合项目规范
|
||
- 提高开发效率，减少重复工作
|
||
- 便于知识沉淀和团队协作
|
||
|
||
## 3 条踩坑与改进
|
||
|
||
### 踩坑 1: 表名前缀不一致
|
||
|
||
- **现象**: 最初设计的表名使用 `sf_` 前缀（如 `sf_org_config`），与现有项目表结构不一致。用户反馈后，改为 `datai_sf_` 前缀（如 `datai_sf_org_config`），但用户再次反馈要求改为 `datai_meta_` 前缀（如 `datai_meta_org_config`），导致表名经历了三次修改。
|
||
- **原因分析**:
|
||
- 在设计初期没有充分了解现有项目的表命名规范
|
||
- 没有仔细阅读现有表结构参考文件（datai_table.sql）
|
||
- 在创建 ADR 文档时没有与用户充分确认表命名规范
|
||
- **改进措施**:
|
||
- 在设计初期仔细阅读现有项目的表结构参考文件
|
||
- 在创建 ADR 文档前与用户确认关键设计决策（如表命名规范）
|
||
- 在 ADR 文档中明确记录命名规范，避免后续修改
|
||
- **避免思路**:
|
||
- 在开始设计前，先阅读现有项目的相关文档和代码
|
||
- 对于关键设计决策，先与用户确认，避免反复修改
|
||
- 在 ADR 文档中记录所有设计决策，包括命名规范、技术选型等
|
||
|
||
### 踩坑 2: 缺少标准基础字段
|
||
|
||
- **现象**: 最初设计的表结构缺少标准基础字段（dept_id, create_by, create_time, update_by, update_time, remark），与现有项目表结构不一致。用户反馈后，补充了这些标准基础字段。
|
||
- **原因分析**:
|
||
- 在设计初期没有充分了解现有项目的表结构规范
|
||
- 没有仔细阅读现有表结构参考文件（datai_table.sql）
|
||
- 在创建 ADR 文档时没有与用户充分确认表结构规范
|
||
- **改进措施**:
|
||
- 在设计初期仔细阅读现有项目的表结构参考文件
|
||
- 在创建 ADR 文档前与用户确认表结构规范
|
||
- 在 ADR 文档中明确记录表结构规范，包括基础字段、索引策略等
|
||
- **避免思路**:
|
||
- 在开始设计前，先阅读现有项目的相关文档和代码
|
||
- 对于关键设计决策，先与用户确认，避免反复修改
|
||
- 在 ADR 文档中记录所有设计决策，包括表结构规范、索引策略等
|
||
|
||
### 踩坑 3: 冗余索引设计
|
||
|
||
- **现象**: 最初设计的表结构包含冗余索引，如为每个外键字段都创建了单独的索引，导致索引过多，影响写入性能。用户反馈后，优化了索引策略，移除了冗余索引。
|
||
- **原因分析**:
|
||
- 在设计初期没有充分考虑索引的性能影响
|
||
- 没有仔细评估每个索引的必要性
|
||
- 在创建 ADR 文档时没有与用户充分确认索引策略
|
||
- **改进措施**:
|
||
- 在设计初期仔细评估每个索引的必要性
|
||
- 在创建 ADR 文档前与用户确认索引策略
|
||
- 在 ADR 文档中明确记录索引策略，包括索引类型、索引字段、索引用途等
|
||
- **避免思路**:
|
||
- 在开始设计前，先评估索引的性能影响
|
||
- 对于关键设计决策，先与用户确认，避免反复修改
|
||
- 在 ADR 文档中记录所有设计决策，包括索引策略、性能优化等
|
||
|
||
## Visual Debt
|
||
|
||
记录哪些代码修改了但还没来得及同步到 Canvas：
|
||
|
||
- [ ] Authentication.canvas 需要更新
|
||
- 本次变更为数据库表结构设计，不涉及 Canvas 架构变更
|
||
- 如果后续需要更新 Canvas，应该添加 "datai-salesforce-metadata" 模块，包含数据库表结构设计
|
||
- [ ] 其他 Canvas 文件: 无
|
||
- **具体修改**: 本次主要是数据库表结构设计，不涉及 Canvas 架构变更，暂不需要更新 Canvas
|
||
|
||
## AI Tooling
|
||
|
||
Trae 读取 Canvas 时的表现：
|
||
|
||
- **理解程度**: Trae 对 Canvas 的理解程度较高，能够准确识别 Canvas 中的节点和关系。在本次会话中，Trae 正确理解了 Authentication.canvas 中的 "集成核心" 节点和 "SessionManager" 节点，并将其作为参考信息。
|
||
- **复杂逻辑**: Trae 能够理解复杂的嵌套逻辑。在本次会话中，Trae 正确理解了 Canvas 中的模块关系和依赖关系，能够根据 Canvas 中的信息生成合理的建议。
|
||
- **改进建议**:
|
||
- 建议在 Canvas 中添加更多的注释和说明，特别是对于复杂的节点和关系
|
||
- 建议在 Canvas 中使用更清晰的命名，避免使用缩写和模糊的名称
|
||
- 建议在 Canvas 中添加版本信息，便于追踪 Canvas 的变更历史
|
||
|
||
## 模板更新记录
|
||
|
||
| 日期 | 模板名称 | 更新内容 | 更新原因 |
|
||
|------|----------|----------|----------|
|
||
| 无 | 无 | 无 | 本次使用的模板均适用，无需更新 |
|
||
|
||
## 技能练习记录
|
||
|
||
| 技能领域 | 练习内容 | 练习效果 | 改进方向 |
|
||
|----------|----------|----------|----------|
|
||
| 需求定义与入库 | 创建 REQ-010 主需求文档和 17 个子需求文档 | 成功创建完整的需求文档链，需求描述清晰，验收标准明确 | 在创建需求文档前，先与用户确认需求范围和优先级，避免需求变更 |
|
||
| 架构决策 | 创建 0010-database-table-design.md 架构决策记录 | 成功创建 ADR 文档，对比了两种技术方案，记录了决策理由和潜在风险 | 在创建 ADR 文档前，先与用户确认关键设计决策，避免反复修改 |
|
||
| 提示词资产化 | 创建 011-database-table-design-create.md 提示词文档 | 成功创建提示词文档，定义了详细的输出格式和代码规范 | 在创建提示词文档前，先与用户确认输出格式和代码规范，避免反复修改 |
|
||
| 执行与记录 | 创建 20260117-database-table-design-create.md 会话记录 | 成功创建会话记录，详细记录了执行过程和关键产出 | 在创建会话记录时，应该更详细地记录质疑与替代方案，便于后续回顾 |
|
||
| 变更记录与归档 | 创建 0020-database-table-design-create.md 变更记录 | 成功创建变更记录，详细记录了变更内容、影响范围、升级指南和测试信息 | 在创建变更记录时，应该更详细地记录测试结果，便于后续验证 |
|
||
| 闭环复盘 | 创建 20260117-database-table-design-create-retro.md 复盘报告 | 成功创建复盘报告，对比了目标与实际产出，提取了有效的 Prompt 模式和踩坑与改进 | 在创建复盘报告时，应该更详细地记录技能练习效果，便于后续改进 |
|
||
|
||
## 总结
|
||
|
||
本次迭代（REQ-010-1 数据库表结构设计和创建）成功完成了以下工作：
|
||
|
||
1. **需求定义阶段**：创建了 REQ-010 主需求文档和 17 个子需求文档，建立了完整的需求文档链
|
||
2. **架构决策阶段**：创建了 0010-database-table-design.md 架构决策记录，对比了两种技术方案，记录了决策理由和潜在风险
|
||
3. **提示词资产化阶段**：创建了 011-database-table-design-create.md 提示词文档，定义了详细的输出格式和代码规范
|
||
4. **执行会话与代码生成阶段**：创建了 20260117-database-table-design-create.md 会话记录，详细记录了执行过程和关键产出
|
||
5. **变更记录与归档阶段**：创建了 0020-database-table-design-create.md 变更记录，详细记录了变更内容、影响范围、升级指南和测试信息
|
||
6. **闭环复盘阶段**：创建了 20260117-database-table-design-create-retro.md 复盘报告，对比了目标与实际产出，提取了有效的 Prompt 模式和踩坑与改进
|
||
|
||
本次迭代的亮点：
|
||
- 完整遵循了项目规则的 6 个阶段，建立了完整的文档链
|
||
- 成功将复杂需求拆分为 17 个子需求，提高了需求管理的粒度
|
||
- 成功使用 ADR 模式进行架构决策，确保决策有据可依
|
||
- 成功使用提示词资产化模式，为后续代码生成做好准备
|
||
- 成功创建了会话记录和变更记录，确保了文档的可追溯性
|
||
- 成功进行了闭环复盘，提取了有效的 Prompt 模式和踩坑与改进
|
||
|
||
本次迭代的不足：
|
||
- 在设计初期没有充分了解现有项目的表命名规范和表结构规范，导致表名和基础字段经历了多次修改
|
||
- 在创建 ADR 文档时没有与用户充分确认关键设计决策，导致反复修改
|
||
- 在创建会话记录时，质疑与替代方案的记录不够详细
|
||
|
||
本次迭代的改进方向：
|
||
- 在设计初期仔细阅读现有项目的相关文档和代码，了解项目的命名规范和结构规范
|
||
- 在创建 ADR 文档前与用户确认关键设计决策，避免反复修改
|
||
- 在创建会话记录时，更详细地记录质疑与替代方案，便于后续回顾
|
||
- 在设计初期仔细阅读参考文档，确保表设计符合业务需求
|
||
|
||
本次迭代的经验教训：
|
||
- 需求拆分模式是管理复杂需求的有效方法，可以提高需求管理的粒度，便于跟踪和验收
|
||
- ADR 模式是进行架构决策的有效方法，可以确保决策有据可依，便于后续回顾和审计
|
||
- 提示词资产化模式是提高开发效率的有效方法，可以确保代码生成符合预期，减少重复工作
|
||
- 在设计初期充分了解现有项目的规范，可以避免反复修改，提高开发效率
|
||
- 在创建文档前与用户确认关键决策，可以避免反复修改，提高开发效率
|
||
- 在设计初期仔细阅读参考文档，可以确保表设计符合业务需求，避免后续优化
|
||
|
||
## 后续优化建议
|
||
|
||
### 优化 1: 基于参考资料优化表设计
|
||
|
||
- **优化内容**: 基于参考资料 `005-源数据拉取数据库设计方案.md` 优化表设计，新增 3 张表（datai_meta_package_item, datai_meta_component_version, datai_meta_deploy_component_result）
|
||
- **优化原因**:
|
||
- 参考文档提供了更完善的表设计，包含 9 张表，覆盖了元数据管理的完整生命周期
|
||
- 新增的 3 张表提供了重要的功能支持：
|
||
- `datai_meta_package_item` - 支持元数据包定义的自动化生成，避免手动拼写 `package.xml`
|
||
- `datai_meta_component_version` - 支持"Java 版 Git"功能，实现组件版本管理和内容哈希对比
|
||
- `datai_meta_deploy_component_result` - 支持 CI/CD 功能，提供精确的错误报告（行号、错误原因）
|
||
- **优化效果**:
|
||
- 提高了元数据管理的完整性和可追溯性
|
||
- 支持了更高级的功能（如代码比对、回滚、CI 部署流水线）
|
||
- 为后续功能开发提供了更完善的数据基础
|
||
- **优化时间**: 2026-01-17
|
||
- **优化状态**: 已完成文档更新，待执行代码生成
|