@umacloud/knowledge 1.0.1

package/development/03-checklists/data-migration-checklist.md

@@ -0,0 +1,157 @@
+---
+id: data-migration-checklist
+title: 数据迁移检查清单 (Data Migration Checklist)
+domain: development
+category: 03-checklists
+difficulty: intermediate
+tags: [checklist, data, development, migration, 人员与沟通, 参考, 回滚方案, 对业务的影响评估]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 数据迁移检查清单 (Data Migration Checklist)
+
+> 适用场景：数据库 Schema 变更、数据库引擎迁移、数据中心迁移、数据格式转换、大规模数据回填。
+> 通过标准：所有 MUST 项全部通过方可执行生产迁移；SHOULD 项未通过需迁移负责人签字确认。
+
+---
+
+## 1. 迁移规划
+
+### 1.1 范围与目标
+
+- [ ] **迁移范围已明确** — 涉及的数据库 / 表 / 字段 / 记录范围已列出，有明确的包含和排除列表。
+- [ ] **迁移目标已量化** — 预期迁移的数据量（行数 / 存储大小）、迁移完成时间已估算。
+- [ ] **迁移类型已确定** — 在线迁移（零停机）/ 停机迁移 / 双写渐进迁移，方案已选定并论证。
+- [ ] **迁移依赖已梳理** — 上下游服务、定时任务、数据消费方的影响已评估。
+- [ ] **成功标准已定义** — 迁移完成的判定条件已量化（如数据一致率 >= 99.99%，性能不退化）。
+
+### 1.2 时间窗口
+
+- [ ] **迁移时间窗口已确定** — 选择业务低峰期，预留足够的执行 + 验证 + 回滚时间。
+- [ ] **时间里程碑已拆分** — 准备阶段、执行阶段、验证阶段、切换阶段的时间节点已标记。
+- [ ] **超时策略已定义** — 迁移超过预期时间 150% 时的决策流程（继续 / 暂停 / 回滚）已确定。
+
+---
+
+## 2. 迁移前准备
+
+### 2.1 数据分析
+
+- [ ] **源数据质量已评估** — 空值、异常值、重复数据、编码问题已统计并处理。
+- [ ] **数据分布已分析** — 大表行数、索引大小、热点分布已确认，用于估算迁移耗时。
+- [ ] **Schema 差异已映射** — 源和目标的 Schema 差异已列出，字段类型转换规则已定义。
+- [ ] **外键与约束已梳理** — 外键依赖关系已理清，迁移顺序按依赖拓扑排序。
+- [ ] **触发器 / 存储过程已评估** — 迁移过程中触发器是否需要临时禁用已确认。
+
+### 2.2 环境准备
+
+- [ ] **目标环境已就绪** — 目标数据库实例已创建，配置（字符集 / 排序规则 / 参数组）已对齐。
+- [ ] **网络连通性已验证** — 源和目标数据库之间的网络延迟和带宽满足迁移需求。
+- [ ] **存储空间已确认** — 目标存储空间 >= 源数据大小的 2x（预留临时表和日志空间）。
+- [ ] **权限已配置** — 迁移账号具有源端 SELECT 和目标端 INSERT / UPDATE / DDL 权限。
+
+### 2.3 脚本与工具
+
+- [ ] **迁移脚本已编写** — 迁移脚本（SQL / ETL / 自定义程序）已完成，代码已 review。
+- [ ] **脚本幂等性已保证** — 迁移脚本可安全重复执行，不产生重复数据或错误。
+- [ ] **分批策略已实施** — 大表迁移按主键 / 时间范围分批执行，单批 <= 10000 行，避免长事务。
+- [ ] **进度记录机制已实施** — 迁移进度可实时查看（已迁移行数 / 百分比 / 预计剩余时间）。
+- [ ] **断点续传已支持** — 迁移中断后可从断点恢复，不需要从头开始。
+
+---
+
+## 3. 数据校验
+
+### 3.1 迁移前校验
+
+- [ ] **源数据快照已保存** — 迁移前的关键统计数据已记录（总行数 / 校验和 / 关键字段汇总值）。
+- [ ] **抽样数据已导出** — 随机抽取 >= 1000 条记录用于迁移后逐行比对。
+- [ ] **业务规则校验已定义** — 关键业务规则（如余额非负、状态机合法、关联关系完整）的校验查询已编写。
+
+### 3.2 迁移后校验
+
+- [ ] **行数一致性校验** — 源和目标的各表行数一致（允许偏差范围已定义）。
+- [ ] **数据完整性校验** — 主键唯一性、外键完整性、非空约束均通过。
+- [ ] **字段值校验** — 抽样数据逐字段比对通过，关键汇总值（SUM / COUNT / MAX / MIN）一致。
+- [ ] **业务规则校验** — 迁移后数据满足所有预定义的业务规则。
+- [ ] **索引与约束校验** — 目标表的索引、唯一约束、检查约束已正确创建。
+- [ ] **编码与精度校验** — 中文 / 特殊字符未乱码，数值精度未丢失。
+
+### 3.3 性能校验
+
+- [ ] **查询性能对比** — 核心查询在目标库上的执行计划和耗时与源库一致或更优。
+- [ ] **索引命中率正常** — 关键查询使用了预期的索引，无全表扫描。
+- [ ] **应用性能验证** — 应用连接目标库后，核心接口延迟在可接受范围内。
+
+---
+
+## 4. 双写与切换（在线迁移专用）
+
+- [ ] **双写逻辑已实现** — 写操作同时写入源和目标，或通过 CDC（Change Data Capture）实时同步增量。
+- [ ] **双写一致性已验证** — 双写期间源和目标的数据差异 <= 可接受延迟（如 < 5s）。
+- [ ] **读切换策略已定义** — 灰度切换读流量（如先切查询 -> 再切写入），每步有验证点。
+- [ ] **写切换策略已定义** — 写流量切换窗口最小化，切换时的在途请求处理方案已确认。
+- [ ] **切换回退机制** — 切换后发现问题可快速回退到源库，回退操作 <= 5 分钟。
+
+---
+
+## 5. 回滚方案
+
+- [ ] **回滚脚本已编写** — 数据回滚脚本已完成，可将目标数据恢复到迁移前状态。
+- [ ] **回滚触发条件已定义** — 明确什么情况下触发回滚（如数据不一致率 > 0.01%，应用错误率 > 5%）。
+- [ ] **回滚时间已评估** — 回滚操作预计耗时已估算，在可接受范围内。
+- [ ] **回滚已演练** — 在预发布环境执行过完整的迁移 + 回滚流程。
+- [ ] **回滚后业务影响已评估** — 回滚后的数据损失范围（迁移后新增的数据如何处理）已有方案。
+- [ ] **备份已创建** — 迁移前的数据库全量备份已完成，备份可用性已验证。
+
+---
+
+## 6. 对业务的影响评估
+
+- [ ] **业务方已知晓** — 迁移时间 / 影响范围 / 预期停机（如有）已通知业务方。
+- [ ] **定时任务已暂停** — 迁移期间相关的定时任务 / Cron Job 已暂停，迁移后恢复。
+- [ ] **消息消费已暂停**（如需要）— 迁移期间相关消息队列消费者已暂停，积压量在可控范围。
+- [ ] **缓存失效策略已定义** — 迁移后缓存中的旧数据清理方案已确定（全量清除 / 逐步过期）。
+- [ ] **下游通知已发送** — 数据消费方（报表 / 分析 / 同步任务）已知悉迁移计划。
+
+---
+
+## 7. 人员与沟通
+
+- [ ] **迁移负责人已指定** — 有明确的迁移协调人，对迁移过程全程负责。
+- [ ] **DBA 支持已确认** — DBA 在迁移窗口内可提供支持。
+- [ ] **值班安排已确认** — 迁移后 >= 4 小时有工程师值守观察。
+- [ ] **升级路径已明确** — 迁移异常时的升级联系人和决策链已确认。
+- [ ] **沟通渠道已建立** — 迁移过程的实时沟通群组 / 频道已创建。
+
+---
+
+## 8. 迁移后收尾
+
+- [ ] **源库处理方案已确定** — 迁移完成后源库保留时间已定义（建议 >= 7 天只读保留）。
+- [ ] **监控已切换** — 监控和告警已指向目标库，源库监控降级为备用。
+- [ ] **连接串已全部切换** — 所有应用 / 脚本 / 定时任务的数据库连接已指向目标。
+- [ ] **迁移文档已归档** — 迁移方案、执行日志、校验结果、回滚记录已存档。
+- [ ] **事后复盘已排期** — 迁移完成后一周内安排复盘，总结经验和改进点。
+
+---
+
+## 参考
+
+- AWS Database Migration Service Best Practices — https://docs.aws.amazon.com/dms/latest/userguide/CHAP_BestPractices.html
+- Flyway / Liquibase Migration Best Practices
+- Martin Kleppmann: Designing Data-Intensive Applications, Chapter 4
+
+---
+
+## Agent Checklist
+
+供 AI Agent 在执行或监督数据迁移时使用的自检项：
+
+- [ ] 已确认迁移脚本在预发布环境完整执行通过。
+- [ ] 已核对源和目标的 Schema 差异映射无遗漏。
+- [ ] 已验证数据校验覆盖行数 / 完整性 / 业务规则三个维度。
+- [ ] 已确认回滚方案可实际执行（非纸面方案）。
+- [ ] 已验证迁移后应用性能无退化。
+- [ ] 已确认所有定时任务和消息消费者已正确暂停 / 恢复。
+- [ ] 迁移执行日志和校验报告已存档至 `output/` 目录。

package/development/03-checklists/oncall-handover-checklist.md

@@ -0,0 +1,173 @@
+---
+id: oncall-handover-checklist
+title: 值班交接检查清单 (On-Call Handover Checklist)
+domain: development
+category: 03-checklists
+difficulty: intermediate
+tags: [checklist, development, handover, oncall, 交接确认, 升级路径与联系人, 变更与发布, 已知风险与临时方案]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 值班交接检查清单 (On-Call Handover Checklist)
+
+> 适用场景：值班轮换交接、跨团队值班交接、重大事件期间的临时交接、假期前交接。
+> 通过标准：所有 MUST 项在交接会议中完成确认，交接记录双方签字认可。
+
+---
+
+## 1. 当前系统状态
+
+### 1.1 告警与事故
+
+- [ ] **活跃告警已同步** — 当前所有未恢复的告警已逐条说明，包含触发时间、影响范围、当前处理状态。
+- [ ] **进行中的事故已交接** — 正在处理的 P0/P1 事故的时间线、当前进展、下一步行动已说明。
+- [ ] **近期已恢复的告警已说明** — 过去 24 小时内恢复的告警已说明，标注是否有复发风险。
+- [ ] **静默 / 抑制的告警已说明** — 当前被静默的告警及其原因、预期恢复时间已交代。
+- [ ] **误报告警已标注** — 已知的误报告警已说明，避免接班人花时间排查。
+
+### 1.2 系统健康度
+
+- [ ] **核心服务状态** — 各核心服务的健康状态已确认（正常 / 降级 / 部分不可用）。
+- [ ] **资源使用趋势** — CPU / 内存 / 磁盘 / 连接数的使用趋势已说明，标注是否有接近阈值的风险。
+- [ ] **依赖服务状态** — 第三方服务和上下游服务的当前状态已确认。
+- [ ] **SLI / SLO 消耗情况** — 当前 Error Budget 消耗百分比已说明，是否处于风险区间。
+
+---
+
+## 2. 已知风险与临时方案
+
+- [ ] **已知风险清单** — 当前存在但尚未修复的风险项已列出，包含影响范围和优先级。
+- [ ] **临时绕行方案** — 正在使用的临时修复 / 绕行方案已说明，标注方案的有效期和限制条件。
+- [ ] **技术债务风险** — 可能在值班期间触发问题的技术债务已标注（如快满的磁盘、即将过期的证书）。
+- [ ] **定时任务注意事项** — 值班期间将运行的重要定时任务（如结算 / 对账 / 备份）已说明。
+- [ ] **即将过期的资源** — 域名 / 证书 / License / API Key 等在值班期间可能过期的资源已标注。
+
+---
+
+## 3. 变更与发布
+
+- [ ] **近期变更已同步** — 过去 48 小时内的生产变更已说明，包含变更内容、影响范围、负责人。
+- [ ] **计划中的变更** — 值班期间计划执行的变更已列出，包含时间窗口、执行人、回滚方案。
+- [ ] **灰度发布状态** — 正在进行的灰度 / 金丝雀发布的当前比例和观察指标已说明。
+- [ ] **变更冻结期** — 是否处于变更冻结期（如大促前）已确认，冻结期规则已说明。
+- [ ] **Feature Flag 状态** — 正在灰度中的 Feature Flag 状态已说明，包含启停条件。
+
+---
+
+## 4. 运维工具与入口
+
+### 4.1 监控面板
+
+- [ ] **核心监控 Dashboard 入口** — Grafana / CloudWatch / Datadog 等核心面板的 URL 已共享。
+- [ ] **业务监控面板入口** — 业务关键指标（GMV / 订单量 / 转化率等）面板 URL 已共享。
+- [ ] **基础设施面板入口** — 集群资源 / 数据库 / 缓存 / 队列的监控面板 URL 已共享。
+
+### 4.2 操作工具
+
+- [ ] **告警管理平台入口** — PagerDuty / OpsGenie / 自建告警平台的登录方式和操作权限已确认。
+- [ ] **日志查询平台入口** — ELK / Loki / CloudWatch Logs 的查询入口和常用查询语句已共享。
+- [ ] **CI/CD 平台入口** — Jenkins / GitHub Actions / ArgoCD 等部署平台的访问方式已确认。
+- [ ] **数据库管理工具** — 数据库连接方式（跳板机 / 管理平台）和只读 / 读写权限已确认。
+
+### 4.3 文档入口
+
+- [ ] **Runbook 入口已确认** — 常见故障处理手册的最新版本位置已确认。
+- [ ] **架构文档入口** — 系统架构图、服务依赖图的位置已确认。
+- [ ] **应急预案入口** — 重大故障应急预案的位置已确认。
+
+---
+
+## 5. 升级路径与联系人
+
+- [ ] **升级联系人可达** — 一级升级人（技术 Lead）、二级升级人（技术总监）、三级升级人（CTO）的联系方式已确认且可达。
+- [ ] **DBA 支持联系方式** — DBA 值班人员的联系方式和响应时间承诺已确认。
+- [ ] **安全团队联系方式** — 安全事件的上报联系人和沟通渠道已确认。
+- [ ] **业务方联系人** — 需要业务决策时的对接人联系方式已确认。
+- [ ] **第三方支持联系方式** — 云厂商 / CDN / 支付渠道等第三方的技术支持联系方式和 SLA 已确认。
+- [ ] **升级触发条件已明确** — P0 事件 5 分钟升级、P1 事件 15 分钟升级等规则已复述确认。
+
+---
+
+## 6. 未完成事项
+
+- [ ] **待修复项清单** — 上一班次遗留的待修复项已列出，包含优先级和预期完成时间。
+- [ ] **待观察项清单** — 需要持续观察的指标或行为已列出，包含观察频率和判定标准。
+- [ ] **待跟进的工单** — 已创建但未关闭的事故工单 / 问题工单的状态已同步。
+- [ ] **待回复的沟通** — 来自业务方 / 用户 / 上下游的待回复沟通已说明。
+
+---
+
+## 7. 特殊情况说明
+
+- [ ] **业务高峰期预警** — 值班期间是否有大促 / 活动 / 流量高峰已告知，峰值预估已说明。
+- [ ] **计划内维护** — 值班期间的计划内维护（如数据库维护窗口 / 网络调整）已标注。
+- [ ] **跨时区协调** — 需要跨时区沟通的事项已说明，对方团队的工作时间已标注。
+- [ ] **合规审计事项** — 值班期间是否有审计访问或合规检查已告知。
+
+---
+
+## 8. 交接确认
+
+- [ ] **交接时间已记录** — 交接发生的日期和时间已记录。
+- [ ] **交接双方已确认** — 交班人和接班人姓名已记录，双方均确认交接内容完整。
+- [ ] **值班日历已更新** — 值班排班表中的当前值班人已更新。
+- [ ] **告警通知已切换** — PagerDuty / OpsGenie 等告警通知的接收人已切换到接班人。
+- [ ] **IM 群组已更新** — 值班 IM 群组中的值班人标识已更新。
+- [ ] **VPN / 跳板机已测试** — 接班人的远程访问权限已验证可用。
+- [ ] **交接记录已存档** — 本次交接记录已保存到团队知识库或值班日志中。
+
+---
+
+## 交接记录模板
+
+```
+## 值班交接记录
+
+- 交接时间: YYYY-MM-DD HH:MM
+- 交班人: [姓名]
+- 接班人: [姓名]
+- 值班周期: YYYY-MM-DD ~ YYYY-MM-DD
+
+### 当前系统状态
+- [ ] 全部正常 / [ ] 存在异常（详见下方说明）
+
+### 活跃告警
+| 告警名称 | 触发时间 | 影响范围 | 当前状态 |
+|----------|---------|---------|---------|
+| | | | |
+
+### 已知风险
+| 风险描述 | 优先级 | 临时方案 | 预期修复时间 |
+|---------|--------|---------|------------|
+| | | | |
+
+### 待跟进事项
+| 事项 | 优先级 | 负责人 | 备注 |
+|-----|--------|-------|------|
+| | | | |
+
+### 交班人签字: ___________
+### 接班人签字: ___________
+```
+
+---
+
+## 参考
+
+- Google SRE: Being On-Call — https://sre.google/sre-book/being-on-call/
+- PagerDuty Incident Response Guide — https://response.pagerduty.com/
+- Increment: On-Call — https://increment.com/on-call/
+
+---
+
+## Agent Checklist
+
+供 AI Agent 在协助值班交接时使用的自检项：
+
+- [ ] 已收集当前所有活跃告警和进行中事故的状态。
+- [ ] 已核对已知风险和临时绕行方案的完整性。
+- [ ] 已确认所有升级联系人的可达性。
+- [ ] 已验证监控面板和运维工具的访问链接有效。
+- [ ] 已确认交接双方对所有待跟进事项达成一致理解。
+- [ ] 已生成交接记录并存档至团队知识库。
+- [ ] 已提醒接班人检查值班期间的特殊事项（高峰期 / 维护窗口）。

package/development/03-checklists/pr-checklist.md

@@ -0,0 +1,158 @@
+---
+id: pr-checklist
+title: PR 检查清单 (Pull Request Checklist)
+domain: development
+category: 03-checklists
+difficulty: intermediate
+tags: [checklist, development, 代码质量, 兼容性, 变更范围与描述, 安全, 性能, 文档]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# PR 检查清单 (Pull Request Checklist)
+
+> 适用场景：代码评审、合并请求审核、自动化 CI 门禁配合使用。
+> 通过标准：所有 MUST 项通过方可合并；SHOULD 项未通过需在 PR 描述中说明理由。
+
+---
+
+## 1. 变更范围与描述
+
+- [ ] **PR 标题清晰且符合规范** — 使用 Conventional Commits 格式（feat / fix / refactor / docs / test / chore），标题 <= 72 字符。
+- [ ] **变更目的单一且明确** — 一个 PR 只解决一个问题或实现一个功能，不混合无关变更。
+- [ ] **PR 描述完整** — 包含变更背景、实现方案概述、影响范围、测试方式，关联 Issue / Ticket 编号。
+- [ ] **Breaking Change 已标注** — 如有不兼容变更，在 PR 描述和 commit message 中明确标注 `BREAKING CHANGE`。
+- [ ] **变更规模合理** — 新增 / 修改代码 <= 400 行（不含自动生成代码），超大 PR 应拆分。
+- [ ] **截图 / 录屏已附加**（如涉及 UI）— 变更前后对比截图已附加，覆盖关键状态。
+
+---
+
+## 2. 代码质量
+
+### 2.1 可读性
+
+- [ ] **命名清晰有意义** — 变量 / 函数 / 类 / 模块命名准确表达意图，无 `tmp` / `data` / `handler2` 等模糊名称。
+- [ ] **函数职责单一** — 每个函数只做一件事，长度 <= 50 行（不含空行和注释），超长函数已拆分。
+- [ ] **无重复代码** — 不引入 copy-paste 代码块，公共逻辑已提取为共享函数或模块。
+- [ ] **注释说明 Why 而非 What** — 注释解释业务背景和设计决策，不重复描述代码逻辑。
+- [ ] **魔术数字已消除** — 数值字面量提取为命名常量，含义一目了然。
+
+### 2.2 设计
+
+- [ ] **符合项目架构规范** — 新代码放在正确的模块 / 层级，遵循已有的分层与依赖方向。
+- [ ] **接口设计合理** — 公开接口参数最小化，返回值类型明确，错误处理一致。
+- [ ] **无过度设计** — 不引入当前不需要的抽象层、不提前优化，遵循 YAGNI 原则。
+- [ ] **向后兼容** — API / 数据格式变更向后兼容，或有明确的迁移路径和版本计划。
+
+### 2.3 代码规范
+
+- [ ] **Lint 检查通过** — Ruff / ESLint / Prettier 等格式化与规范检查零错误。
+- [ ] **类型检查通过** — MyPy / TypeScript 类型检查无新增错误。
+- [ ] **无 TODO/FIXME/HACK 残留** — 临时代码已清理，或关联了对应的 Issue 进行后续跟踪。
+- [ ] **import 排序正确** — 导入按标准库 / 三方库 / 项目内部排序，无未使用的导入。
+
+---
+
+## 3. 测试
+
+### 3.1 测试覆盖
+
+- [ ] **新增代码有对应测试** — 业务逻辑新增 / 修改的代码有单元测试覆盖，覆盖率不低于既有基线。
+- [ ] **边界条件已覆盖** — 空值、零值、最大值、异常输入、并发场景的测试用例已编写。
+- [ ] **错误路径已测试** — 异常抛出、错误码返回、降级逻辑均有测试用例验证。
+- [ ] **回归测试已通过** — 既有测试套件全部通过，无因本次变更导致的测试失败。
+
+### 3.2 测试质量
+
+- [ ] **测试独立可重复** — 测试不依赖执行顺序或外部状态，可单独运行且结果稳定。
+- [ ] **断言具体明确** — 不使用 `assertTrue(result)` 式模糊断言，校验具体字段和值。
+- [ ] **Mock 范围合理** — 仅 Mock 外部依赖（HTTP / DB / 第三方），不 Mock 被测试对象的内部方法。
+- [ ] **测试命名描述行为** — 测试函数名描述被测行为和预期结果，如 `test_login_fails_with_invalid_password`。
+
+### 3.3 集成与端到端
+
+- [ ] **集成测试已补充**（如涉及跨模块交互）— 模块间交互的关键路径有集成测试覆盖。
+- [ ] **E2E 测试已更新**（如涉及用户流程变更）— 核心用户流程的 E2E 测试已同步更新。
+
+---
+
+## 4. 文档
+
+- [ ] **代码注释已更新** — 修改的函数 / 类的 docstring 与实际行为一致。
+- [ ] **API 文档已同步** — 接口变更同步更新 OpenAPI / Swagger / GraphQL Schema 文档。
+- [ ] **README 已更新**（如涉及使用方式变更）— 安装步骤、配置项、使用示例已同步更新。
+- [ ] **CHANGELOG 已更新** — 用户可感知的变更已记录在 CHANGELOG 中。
+- [ ] **架构决策已记录**（如涉及设计变更）— ADR（Architecture Decision Record）已创建或更新。
+
+---
+
+## 5. 安全
+
+- [ ] **无敏感信息提交** — 代码中无硬编码的密钥、Token、密码、内部 URL。
+- [ ] **用户输入已校验** — 新增的外部输入已做白名单校验或参数化处理。
+- [ ] **权限检查已覆盖** — 新增的接口 / 资源访问有对应的认证和授权校验。
+- [ ] **SQL 查询参数化** — 新增 / 修改的数据库查询使用参数化查询，无字符串拼接。
+- [ ] **依赖安全** — 新增依赖无已知 Critical / High 漏洞（npm audit / pip-audit 通过）。
+- [ ] **日志不含敏感数据** — 新增日志语句不输出用户密码、Token、PII 等敏感信息。
+
+---
+
+## 6. 性能
+
+- [ ] **无 N+1 查询** — 数据库访问无循环内单条查询的模式，使用批量查询或预加载。
+- [ ] **无不必要的全表扫描** — 新增查询已 EXPLAIN 分析，必要字段已建索引。
+- [ ] **大数据量处理已分页/流式** — 返回列表数据有分页，大文件处理使用流式读取。
+- [ ] **缓存策略合理** — 频繁访问的不变数据已缓存，缓存键与失效策略已定义。
+- [ ] **无内存泄漏风险** — 事件监听器已正确清理，大对象引用在使用后释放。
+- [ ] **异步操作已正确处理** — Promise / async-await 无未捕获的异常，无 fire-and-forget 的关键操作。
+
+---
+
+## 7. 兼容性
+
+- [ ] **API 版本兼容** — 接口变更不影响现有客户端，或有版本号隔离。
+- [ ] **数据库 Schema 兼容** — DDL 变更可前向兼容（先加后删，不改类型），migration 可回滚。
+- [ ] **配置变更兼容** — 新增配置有默认值，删除配置有迁移路径。
+- [ ] **浏览器 / 运行时兼容**（如前端变更）— 在目标浏览器 / Node.js 版本上测试通过。
+- [ ] **国际化兼容**（如涉及文案）— 新增文案已抽取为 i18n 资源，不硬编码中文 / 英文。
+
+---
+
+## 8. 运维影响
+
+- [ ] **回滚方案已确认** — 本次变更可通过 revert commit 或功能开关快速回滚。
+- [ ] **Feature Flag 已配置**（如涉及灰度）— 新功能可通过 Feature Flag 控制开关，默认关闭。
+- [ ] **监控指标已添加** — 新增功能的关键路径有延迟 / 错误率 / 调用量指标。
+- [ ] **告警规则已配置** — 新增指标的异常阈值已配置对应告警。
+- [ ] **日志可追踪** — 关键业务操作有结构化日志，包含 traceId 和业务上下文。
+
+---
+
+## PR 合并前最终确认
+
+- [ ] CI 流水线全部通过（lint + type check + test + security scan）。
+- [ ] 至少 1 位 reviewer 已 Approve。
+- [ ] 所有 review comment 已 resolve。
+- [ ] 分支已 rebase 到最新 main，无冲突。
+- [ ] PR 描述中的 checklist 已全部勾选或注明豁免理由。
+
+---
+
+## 参考
+
+- Conventional Commits — https://www.conventionalcommits.org/
+- Google Engineering Practices: Code Review — https://google.github.io/eng-practices/review/
+- Thoughtbot Code Review Guide — https://github.com/thoughtbot/guides/tree/main/code-review
+
+---
+
+## Agent Checklist
+
+供 AI Agent 在创建或审核 PR 时使用的自检项：
+
+- [ ] 已检查 PR 标题符合 Conventional Commits 格式。
+- [ ] 已核对变更文件列表，确认无意外文件被包含（如 .env / lock 文件 / 构建产物）。
+- [ ] 已逐文件 review 代码差异，非仅检查 CI 是否通过。
+- [ ] 已验证新增测试实际覆盖了变更代码的核心路径。
+- [ ] 已检查是否有未处理的 review comment。
+- [ ] 已确认变更不引入安全风险（密钥泄露 / 注入 / 越权）。
+- [ ] 审核结果已记录，包含通过项和待修复项清单。