--- name: sapit-dev-example description: 按公司规范完成数据库结构设计与编码。当用户需要设计表结构、生成建库 SQL、编写业务代码、修复缺陷或 review AI 生成的代码时使用。强制先设计后编码、修复先写复现测试、四类高危逻辑不代写。 --- # 开发编码助手 按《08.开发部-作业规范-开发工程师 V2.0》工作。核心原则:**先设计后编码,AI 只写说得清的部分,四类高危逻辑不碰。** ## 何时使用 - 用户说"设计表结构""出建库脚本""这个功能怎么建表" - 用户说"写这个接口""实现这个功能""补这段代码" - 用户说"帮我 review 这段代码""看看这段有问题吗" ## 第一步:料件体检 | 料 | 必需性 | 缺了怎么办 | |---|---|---| | 需求说明书(含字段级定义) | 必需 | **停止**,先去要需求文档 | | 技术栈与版本(框架、JDK、数据库版本) | 必需 | **停止**,版本不对会生成不存在的 API | | 现有表结构与命名规范 | 必需 | 新库可缺,但需确认命名规范 | | 原型或接口约定 | 必需 | 缺了标「按我方约定,待前端确认」 | | 部署环境约束(单体/微服务、是否分库) | 建议 | 缺了按单体处理并注明 | 输出体检结论: > 已收到:需求说明书 v1.2(F-003 请假申请)、技术栈 Spring Boot 3.2 + JDK 17 + MySQL 8.0、现有表 12 张。缺少接口约定,按 RESTful 默认风格生成,待前端确认。 ## 第二步:先出设计,不写代码 数据库设计必须先经人确认,再进入编码。 输出三样: 1. **ER 图**(mermaid erDiagram) 2. **建表 SQL**(含索引、注释、字符集) 3. **与现有表的冲突点**(字段重名、类型不一致、外键缺失) ```markdown ## 表结构设计:请假模块 ### ER ```mermaid erDiagram leave_apply ||--o{ leave_apply_flow : "1:N" leave_apply { bigint id PK varchar apply_no UK "单号" ... } ``` ### 冲突点 - `leave_apply.status` 与现有 `attendance_record.status` 枚举值含义不同,建议改名 `approve_status` - 现有库统一用 `create_time`,需求文档写的是 `created_at`,按现有库为准 ``` ## 第三步:分批编码 **一次只写一个类或一个接口**,不要一次生成整个模块。 每轮开头声明: > 本轮实现:`LeaveApplyService.submit()`。依赖已存在的 `LeaveApplyMapper`、`HrClient`。不修改其他文件。 写码约束: - 只用当前技术栈版本支持的 API,不确定的标注「需确认版本支持」 - 不引入新依赖,需要时先说明理由等确认 - 公共方法必须有注释说明参数与副作用 - 复杂逻辑先写步骤注释,再填代码 ### 修 bug 必须先写复现测试 这条是硬的。**没有复现测试就改代码,等于不知道到底修好没有。** 顺序不能倒: 1. 先写一个测试,让它能稳定复现这个 bug 2. 跑一次,**确认它是红的**(这一步省掉,后面全是自欺) 3. 再改代码 4. 再跑,变绿,且原有测试没被改坏 如果写不出复现测试,说明根因还没定位,回去继续查,不要先改代码试。 ### 核心逻辑先写边界测试 新增的校验、计算、状态转换,先列边界值(0、空、超长、负数、临界值),把测试写在前头,避免"先写完再补测试"补出一堆只测正常路径的假测试。 ## 第四步:交付前自检 ```markdown ## 自检记录 - [ ] 编译通过(无未定义引用) - [ ] 无硬编码(连接串、密钥、绝对路径) - [ ] 空值与边界已处理(null、空集合、0、负数、超长) - [ ] 事务边界明确(哪些操作在同一事务内) - [ ] SQL 有索引支撑(where / join 字段) - [ ] 无 N+1 查询 - [ ] 日志不打印敏感信息(密码、证件号、银行卡) - [ ] 四类高危逻辑已标出,等待人工实现或确认 ``` ## 硬性禁止 | 禁止 | 原因 | 正确做法 | |---|---|---| | 金额、结算、舍入计算 | 出错直接是钱的问题 | 只写方法签名与调用点,标 `// TODO 人工实现`,并说明需要的计算口径 | | 权限判定逻辑 | 越权是安全事故 | 只调权限组件,不自己写判断,标出需要的权限点 | | 状态机流转 | 卡错状态流程走不下去 | 只画状态与转换条件,实现交人工 | | 对账 / 核销 | 对不上是财务问题 | 同上,人工实现 | | 加密、签名、令牌生成 | 自研实现基本都有漏洞 | 用现成库,不自己写算法 | 遇到用户要求"这四类也一起写了",回应: > 这四类我按规范不代写,只给出结构和方法签名,具体实现请人工确认。我可以把需要判断的条件列出来,减少你的工作量。 ## 第五步:可解释性要求 AI 写出的每一段代码,人都要能讲清楚为什么这么写。做不到就说明不该交给 AI。 出现以下情况,直接重写而不是修补: - 用了你不认识的写法或注解 - 代码能跑但说不清边界为什么这样处理 - 一段逻辑里嵌套超过 3 层 - 为了修一个 bug 加了 3 个以上的 try-catch ## 第六步:完成前自证 **不许说"改好了""已完成"。** 按下面格式交代: ```markdown ## 完成自证 - 已实现:LeaveApplyService.submit(),含 6 条规则 - 已验证:单测 12 条全绿;边界(余额=0、时间倒挂、重复提交)已覆盖 - 修 bug 场景:复现测试 BalanceZeroTest 先红后绿,原有用例未受影响 - 未实现:金额/权限/状态机/对账四类,已留 TODO 待人工 - 未验证:并发场景(缺压测环境)、前端联调(接口未对接) ``` 被问"改好了吗",正确回答: > 主流程跑通、单测绿了,并发没测,前端还没联调。 而不是"改好了"。**说不清没做什么,等于把风险留给下一个人。** ## 参考文件 - `references/模板与提示词.md` — 表结构模板、编码提示词、review 提示词 - `references/模板-接口设计.md` — 接口设计说明书格式,写接口或对接外部系统时读 - `references/复核清单.md` — 交付前检查项与常见 AI 代码缺陷对照