skills/promotion-check/references/checklist.md

# 代码变更与联调检查清单

仅选择与当前 diff 和仓库知识相关的条目。本文件定义通用检查方法，不内置某个业务仓库的字段名或规则。

## 1. 范围、知识与提交卫生

- 变更能否映射到明确业务场景；是否混入无关文件、重构或格式化噪音。
- 是否覆盖需求分支的已提交变更及相关已暂存、未暂存和未跟踪文件。
- 是否残留日志、断点、Mock、临时 URL、代理、配置或调试开关。
- 是否误提交密钥、令牌、个人信息或环境专属配置。
- 从仓库知识索引提取与变更相关的规则，并记录“规则、来源、影响点、代码或联调证据”。
- 知识缺失或来源冲突时是否明确标记，而不是用当前代码替代业务预期。

## 2. 领域规则

依据当前仓库知识逐项检查适用规则，例如数据归属与隔离、标识字段、单位与精度、状态流转、业务开关、兼容策略和权限边界。只有知识或需求明确要求时才检查具体规则，不把其他仓库的字段和约束当成默认事实。

- 规则是否在创建、编辑、列表、详情、状态操作和历史数据中保持一致。
- 条件、身份、组织或上下文切换时，缓存、表单和已选数据是否需要重置或重新加载。
- 数值、单位、精度、枚举、空值和边界值是否与明确约束一致。
- 旧数据、缺失字段、部分记录失效或功能降级是否有明确行为。

## 3. 接口与类型

- URL、Method、请求封装和错误处理是否符合仓库模式。
- 请求和响应字段的名称、类型、必填性、可空性、枚举、单位和嵌套结构是否一致。
- 类型定义是否覆盖真实消费字段；新增枚举是否同步影响筛选、展示、提交和回填。
- 接口或字段变化是否考虑旧数据、旧调用方和灰度期间兼容。
- 上传或预处理、业务保存、异步处理、查询和回显是否分别验证。

## 4. 页面、表单与回填

- 控件值、表单状态、参数转换和提交类型是否一致。
- 前端校验是否与需求和后端约束一致。
- 创建、编辑、复制、详情和列表是否完整处理新增或变更字段。
- 加载、成功、空数据、失败、部分成功和重试是否有明确页面行为。
- 提交失败后是否保留用户输入并提供可行动的提示。
- 快速切换、重复提交和异步竞态是否可能产生脏状态。

## 5. 权限与安全

- 页面、区块、按钮和操作权限是否使用仓库既有方式。
- 前端入口控制与后端鉴权是否分别验证；隐藏入口不能证明接口不可越权。
- 用户输入、富文本、URL、文件和外部数据是否经过必要校验或转义。
- 身份、数据隔离、金额或其他高风险领域变化是否完成对应安全检查。

## 6. 工程约定与验证

- 是否优先复用已有组件、Hook、类型和工具；新增依赖是否必要且兼容锁定版本。
- 异常是否显式处理；禁用规则是否说明原因并限制范围。
- 是否存在超出需求的结构调整，或遗漏文档、类型和配置同步。
- 仓库已有的 lint、测试、类型检查和构建命令是否按变更风险选择并实际执行。
- 命令失败或未执行时是否准确记录，未执行不得写成通过。

## 7. 是否需要联调

通常需要联调：新增或修改 API；请求响应契约变化；字段需要持久化或回填；权限、身份、隔离、状态机或业务规则需要前后端共同处理；错误码、部分成功或兼容逻辑变化。

通常不需要后端联调：纯样式、静态文案，或完全在前端完成且不改变接口和持久化行为的展示变化。判断必须以实际 diff 和仓库知识为准，不能只根据文件名。

## 8. 必验场景与最低证据

只有当前 diff、需求、仓库知识或接口契约能证明适用时，才将下列类型标记为必验：持久化字段；创建、编辑、复制和详情回填；请求响应契约；权限、身份或数据隔离；状态流转和业务开关；有明确依据的单位、精度或高风险数值；上传、保存、异步处理、查询和回显等多阶段链路；旧数据或旧调用方兼容。

| 场景类型 | 最低验证证据 |
|---|---|
| 请求或响应契约 | 真实请求响应，或可重复的契约/Mock 测试 |
| 保存与回填 | 保存结果加重新查询或页面回填结果 |
| 权限、身份或数据隔离 | 适用角色、身份或数据上下文的实际验证 |
| 异常和失败处理 | 错误响应、日志或可重复测试 |
| 纯前端展示 | 页面人工结果、截图或自动化测试 |
| 静态工程变更 | 与风险匹配的 lint、类型检查、测试或构建结果 |

代码存在只能证明实现存在，不能替代运行验证。必验场景缺少最低证据时不得标记 `已通过`，CR 准备度最高为 `PARTIAL`。

## 9. 联调场景模板

| 编号 | 功能场景 | 必验 | 必验依据 | 前置条件 | 操作入口 | 接口/阶段 | 请求核对 | 响应核对 | 预期结果 | 异常场景 | 责任方 | 状态 | 验证证据 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| IT-1 | 具体场景 | 是/否 | diff、需求、仓库知识或契约 | 权限、数据和环境条件 | 页面与操作 | Method + URL 或调用阶段 | 关键字段与转换 | 关键字段与错误 | 页面或数据行为 | 失败、空态、边界 | 前端/后端/产品/共同 | 待联调 | 待补充 |

至少覆盖适用的主成功路径、创建编辑、详情回填、旧数据、空值边界、业务与网络失败、权限差异、重复操作和状态切换。

## 10. 风险与完整报告模板

每个问题写清：`级别`、`问题`、`预期依据`、`实现或联调证据`、`影响`、`建议`、`状态`。级别使用：

- `阻塞`：满足 SKILL.md 的阻塞门槛，必须处理或确认后继续。
- `警告`：有明确风险但不直接阻断，需在 CR 中说明或确认。
- `提示`：改进建议，不影响当前验收。

完整报告依次包含：结论与准备度、范围与证据、变更摘要、风险、联调清单、阻塞与待确认、验证结果、下一步。没有发现明确问题时写“未发现与当前变更直接相关的明确风险”，不得声称绝对无风险。