Branch API Diff Design Skill
语言规范
-
默认输出语言：zh-CN
-
所有技术分析、风险评估、工时评估使用中文
-
所有错误 message 必须为 en-US
-
严禁输出中文错误 message
-
输出必须结构化、可直接用于技术评审
使用场景
当出现以下情况必须使用本 Skill：
-
分支准备合并至 master
-
涉及接口变更
-
涉及参数变更
-
涉及数据库变更
-
涉及错误码变更
-
需要做风险与工时评估
执行步骤
Step 1
git fetch origin
Step 2
git diff --name-status origin/master...HEAD
分析优先级
必须按顺序分析：
-
controllers
-
validator
-
services
-
models
-
response/ErrorCode.php
-
config
-
其他文件
重点目录
-
modules/*/controllers/
-
modules/*/validator/
-
modules/*/services/
-
modules/common/models/
-
response/ErrorCode.php
-
config/
Breaking Change 判定
以下属于破坏性变更：
-
删除接口
-
删除字段
-
新增必填字段
-
字段类型改变
-
返回结构改变
-
错误码语义改变
若存在，必须标记：
⚠️ 该分支包含破坏性变更
输出结构（强制）
技术设计文档
一、变更背景
-
需求来源
-
业务目标
-
风险等级（低 / 中 / 高）
二、接口变更说明
| 模块 | 控制器 | 方法 | 变更类型 | 是否破坏兼容 | 影响范围 |
三、参数变更对比
旧版本
{}
新版本
{}
必须说明兼容性结论。
四、返回结构校验
必须保持：
{ "code": 0, "msg": "","data": {} }
五、数据库影响评估
-
是否修改表结构
-
是否需要 migration
-
是否需要数据回填
-
是否影响读写分离
-
是否影响索引
六、错误码审查
确认：
-
全部在 ErrorCode.php
-
无硬编码
-
message 为英文
七、风险分析
必须覆盖：
-
向后兼容风险
-
数据一致性风险
-
性能风险
-
权限风险
-
部署风险
八、部署方案
-
是否需要 migration
-
是否灰度发布
-
是否清理缓存
-
回滚步骤
-
回滚影响
九、工时评估（后端主程模型）
必须对每个接口单独评估, 按7.5h=1人日计算。
Complexity Points 计算
基础类型
-
新增接口：3
-
修改接口：2
-
小范围 bug 修复：1
-
删除或不兼容修改：4
参数复杂度
1-3 个字段：+1
4-10 个字段：+2
10 或复杂校验：+3
输出变更
-
data 扩展字段：+1
-
结构变化：+2
-
错误码体系变化：+2
权限复杂度
-
普通鉴权：+1
-
权限模型变化：+2
数据库复杂度
-
查询：+1
-
写入/事务：+2
-
表结构变更：+4
-
多表复杂关系：+3
外部依赖
-
跨模块：+1
-
支付/RPA/客户端协议：+3
不确定性
-
需求模糊：+2
-
灰度或兼容复杂：+2
工时映射
CP 1-2：2h
CP 3-4：4h
CP 5-6：8h
CP 7-8：12h
CP 9-10：16h
CP 11+：24h+
必须输出三档：
-
乐观
-
常规
-
保守
输出表格
| 模块 | 控制器 | 方法 | 变更摘要 | CP | 乐观(h) | 常规(h) | 保守(h) | 风险说明 |
最后输出：
-
总工时（常规）
-
折算人日
-
是否建议拆分任务
强制校验清单
-
所有异常使用 ServiceException
-
无硬编码错误码
-
错误 message 英文
-
Validator default 在前
-
统一 OutPut 输出
-
读写分离规范
-
无 echo/exit
结论必须明确
-
是否建议合并
-
是否存在破坏性变更
-
是否建议升级 API 版本
-
是否建议拆分发布
End