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

分析优先级

必须按顺序分析：

1. controllers
2. validator
3. services
4. models
5. response/ErrorCode.php
6. config
7. 其他文件

重点目录

• modules/*/controllers/
• modules/*/validator/
• modules/*/services/
• modules/common/models/
• response/ErrorCode.php
• config/

输出结构（强制）

接口变更分析文档

仅允许输出以下三部分，禁止追加背景、数据库、错误码、部署方案、合并建议等无关章节。

一、接口改动变更说明

必须逐个接口输出，且每个接口必须包含以下信息：

1. 模块 / 控制器 / 方法
2. 准确 URL（含路由路径）
3. HTTP Method（若代码中可判定）
4. 变更类型：新增 / 修改 / 删除
5. 参数变化：新增 / 删除 / 必填改动 / 类型改动 / 默认值改动 / 校验规则改动
6. 响应变化：顶层结构、data 字段、字段类型、字段语义、错误码变化
7. 兼容性结论：兼容 / 不兼容

先输出汇总表：

| 模块 | 控制器 | 方法 | URL | Method | 变更类型 | 参数变化 | 响应变化 | 兼容性 |

再按接口输出详细对比：

1. <controller>/<action>

• URL: /api/xxx/xxx
• Method: GET/POST
• 变更类型：修改
• 参数变化：

旧版本参数

{}

新版本参数

{}

• 响应变化：

旧版本响应

{ "code": 0, "msg": "", "data": {} }

新版本响应

{ "code": 0, "msg": "", "data": {} }

• 兼容性结论：明确说明是否影响现有调用方

如果无法从 diff 中直接推导 URL / Method，必须基于 Yii2 控制器路由规则做出最合理推断，并明确标注“推断”。

二、工时评估（资深后端模型）

必须对每个接口单独评估，按资深后端开发 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+

输出表格

| 模块 | 控制器 | 方法 | URL | 变更摘要 | CP | 估时(h) | 人日(7.5h) | 说明 |

最后输出：

• 总工时（h）
• 折算人日
• 是否建议拆分任务（仅从开发工作量角度）

三、风险评估（仅影响范围）

只允许评估“影响范围”，不要展开性能、权限、部署、数据一致性等维度。

输出表格：

| 模块 | 控制器 | 方法 | URL | 风险等级 | 影响范围 | 受影响对象 | 说明 |

评估口径：

• 风险等级仅允许：低 / 中 / 高
• 影响范围仅描述波及面，例如：仅后台前端、特定客户端、全部调用方、下游服务
• 受影响对象必须尽量具体，例如：运营后台、H5、APP、第三方回调、定时任务
• 若为不兼容修改，必须明确指出需要联动改造的调用方

强制校验清单

• 只输出三部分内容
• 每个接口都要给出准确 URL 或显式标注“推断 URL”
• 每个接口都要给出参数变化与响应变化
• 工时统一按资深后端 7.5h = 1 人日
• 风险评估仅讨论影响范围

End