datai/datai-scenes/datai-scene-salesforce/docs/retros/2026-02-05-002-07-retro.md

复盘文档 - WSDL 转换功能

元数据

• 需求编号：002-07
• 需求名称：WSDL 转换
• 创建时间：2026-02-05
• 创建人：AI Assistant
• 状态：已完成

复盘概述

本次复盘对 WSDL 转换功能的开发过程进行了全面回顾，从需求定义到变更日志的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。

目标与实际产出对比

目标

• 实现 WSDL 转换功能，支持从 URL 和 XML 两种方式转换 WSDL 到 Apex
• 提供转换历史查询功能，支持分页和筛选
• 提供转换详情查询功能，包含生成的 Apex 类代码
• 遵循 SSOT 流程，确保所有开发活动都有文档依据
• 生成符合项目规范的代码

实际产出

• 成功实现了 WSDL 转换功能，支持从 URL 和 XML 两种方式转换
• 实现了转换历史查询功能，支持分页和按状态、时间范围筛选
• 实现了转换详情查询功能，包含生成的 Apex 类列表
• 实现了删除和批量删除转换记录功能
• 实现了生成的 Apex 类管理功能（列表查询、详情查询）
• 严格按照 SSOT 流程执行，从阶段 1 到阶段 8 都有相应的文档
• 生成了 16 个代码文件，符合项目规范
• 创建了 2 个数据库表，包含完整的索引设计
• 定义了 8 个错误码，覆盖常见错误场景
• 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等

成功经验

1. SSOT 流程的严格执行

• 从需求定义到变更日志的 8 个阶段都严格按照项目规则执行
• 每个阶段都有相应的文档记录，确保了所有开发活动都有文档依据
• 提高了代码的可追溯性和可维护性

2. 详细的提示词设计

• 阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求
• 提示词中引用了真源（需求文档、设计文档、决策记录、SQL 脚本）
• 确保了生成的代码符合项目规范和需求

3. 独立的数据库表设计

• WSDL 转换功能使用了独立的数据库表（datai_apex_wsdl_conversion、datai_apex_wsdl_class）
• 与代码覆盖率、Flow 覆盖率等其他功能的数据库表分离
• 遵循了单一职责原则，便于后续维护和扩展

4. 完整的错误码体系

• 定义了 8 个错误码，覆盖了常见的错误场景
• 错误码命名规范，易于理解和维护
• 便于前端进行错误处理和用户提示

5. 代码生成器的高效使用

• 使用代码生成器生成了 16 个基础代码文件
• 大大提高了开发效率，减少了重复劳动
• 生成的代码符合项目规范，包含了基本的 CRUD 操作

改进点

1. 阶段间的过渡可以更流畅

• 在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程
• 提高用户的理解和参与度
• 减少用户的认知负担

2. API 接口设计可以更加统一

• WSDL 转换 Controller 提供了 6 个接口，但部分接口的命名和路径可以更加统一
• 后续应在设计阶段就明确所有接口的命名规范
• 保持设计文档与实际代码的一致性

3. 缺少单元测试

• 生成的 16 个代码文件中不包含单元测试
• 提示词中未明确要求生成单元测试
• 后续应在提示词中增加单元测试的生成要求

4. 部分功能可以进一步优化

• 当前实现了基本的 WSDL 转换功能，但缺少一些高级功能
• 例如：WSDL 验证、批量转换、转换结果导出等
• 后续迭代可以考虑增加这些功能

问题分析

问题 1：设计文档与实际代码不完全一致

现象：设计文档规划了 6 个接口，但实际生成的代码中部分接口的参数和响应结构与设计文档略有差异

根因：

• 代码生成器根据数据库表结构自动生成代码，部分字段命名与设计文档不完全一致
• 设计文档中的部分字段类型和约束在 SQL 脚本中有所调整

解决方案：

• 在代码生成前，再次核对设计文档和 SQL 脚本的一致性
• 在代码生成后，人工检查生成的代码是否符合设计文档的要求
• 保持设计文档与实际代码的一致性

问题 2：缺少 WSDL 转换的核心业务逻辑

现象：代码生成器生成的代码只包含基本的 CRUD 操作，缺少 WSDL 转换的核心业务逻辑（调用 apex.jar 进行转换）

根因：

• 代码生成器只能根据数据库表结构生成基础代码
• WSDL 转换的核心业务逻辑需要手动实现

解决方案：

• 在代码生成后，手动实现 WSDL 转换的核心业务逻辑
• 在 Service 层添加 convertWsdlFromUrl 和 convertWsdlFromXml 方法
• 集成 apex.jar 中的 WsdlToApexInfo、WsdlToApexResult 等类

问题 3：部分字段类型选择不够合理

现象：WSDL XML 内容字段（wsdl_xml）使用了 TEXT 类型，可能无法存储大型 WSDL 文件

根因：

• 设计阶段未充分考虑 WSDL 文件的大小
• TEXT 类型最大存储 64KB，可能无法满足大型 WSDL 文件的需求

解决方案：

• 评估 WSDL 文件的实际大小
• 考虑使用 LONGTEXT 类型或分表存储
• 在后续迭代中优化数据库设计

行动计划

序号	行动项	责任人	时间节点	优先级
1	在阶段转换时，增加对下一阶段的目的和流程的解释	AI Assistant	立即执行	中
2	在代码生成前，核对设计文档和 SQL 脚本的一致性	AI Assistant	立即执行	高
3	手动实现 WSDL 转换的核心业务逻辑	开发人员	下一个迭代	高
4	评估 WSDL 文件大小，优化数据库字段类型	开发人员	下一个迭代	中
5	在提示词中增加单元测试的生成要求	AI Assistant	立即执行	中
6	考虑增加 WSDL 验证、批量转换、转换结果导出等高级功能	项目团队	后续迭代	低

提取模式

有效的 Prompt 技巧

1. 引用真源：在提示词开头引用需求文档、设计文档、决策记录和 SQL 脚本的链接，可以确保生成的代码符合需求和设计要求
2. 具体的输出格式要求：在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性
3. 详细的代码规范要求：在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性

避免的坑

1. 不要期望代码生成器生成所有代码：代码生成器只能生成基础的 CRUD 代码，核心业务逻辑需要手动实现
2. 不要忽略数据库设计的重要性：数据库表结构设计直接影响代码生成结果，需要在设计阶段充分考虑
3. 不要违反项目规则：在代码生成过程中违反项目规则（如不遵循分层架构），会导致生成的代码不符合项目要求

模板迭代

经过本次复盘，发现当前的提示词模板在以下方面可以改进：

1. 增加核心业务逻辑实现要求：在提示词中明确要求哪些方法需要手动实现核心业务逻辑
2. 增加单元测试生成要求：在提示词中明确要求生成单元测试，并指定测试覆盖范围
3. 增加数据库字段类型评估要求：在提示词中要求评估字段类型是否满足实际需求

计划在下一个迭代中更新提示词模板，增加以上内容。

相关文档

• 需求文档
• 设计文档
• 决策记录
• SQL 脚本
• 提示词文档
• 变更日志
• 会话记录