ZQYY.FQ-ETL/.kiro/steering/governance.md

inclusion

inclusion
always

Governance / Engineering Rigour

Hard Rules（必须遵守）

1) Logic Change → Change Impact Review + Doc Updates

任何逻辑改动必须做 Change Impact Review，并评估/必要时更新：

• .kiro/steering/product.md
• .kiro/steering/structure.md
• .kiro/steering/tech.md
• README.md

逻辑改动包括（不限于）：

• 业务规则/计算口径/资金处理（精度、舍入、阈值等）
• 数据处理与 ETL 逻辑（含 SQL 逻辑、清洗/聚合/映射）
• API 行为（返回结构、错误码、鉴权/权限）
• 小程序交互逻辑（校验、关键流程状态机）

通常不视为逻辑改动（仍需判断是否影响结构文档/运行方式）：

• 纯格式化、拼写/文案微调、仅注释调整、无行为变化的重命名

2) DB Schema / Table Structure Change → Must Update BD Manual

任何数据库 schema / 表结构变化（DDL/迁移/字段类型/默认值/非空/约束/索引/外键等），必须同步到：

• docs/bd_manual 下对应 schema 目录与表结构文档

文档必须包含：变更原因、影响范围、回滚策略、数据迁移注意事项、验证 SQL。

---

Audit & Annotation Requirements（审计与标注）

A) Per-change Audit Artifact（一次 Prompt 一份记录）

每次修改（以一次用户 Prompt 驱动为单位）必须创建/追加：

• docs/ai_audit/changes/<YYYY-MM-DD>__<slug>.md

内容至少包含：

• 日期（Asia/Taipei，YYYY-MM-DD）
• 原始原因：用户 Prompt（原文或 ≤5 行摘录，需可追溯完整 Prompt）
• 直接原因：为什么必须改 + 修改方案简介
• Changed：涉及模块/接口/表（或关键文件）
• Risk/Verify：风险点、回归范围、验证步骤
• 如涉及 DB 结构：回滚要点 + 验证 SQL

B) Per-file AI_CHANGELOG（每个被修改文件必须可追溯）

每个被修改的代码/文档文件必须追加/更新 AI_CHANGELOG 条目，至少包含：

• 日期（Asia/Taipei，YYYY-MM-DD）
• Prompt（原文或引用 Prompt-ID + 摘录）
• 直接原因（必要性 + 方案简介）
• 变更摘要（改了什么）
• 风险与验证（至少 1 条验证方式）

C) Inline CHANGE Markers（逻辑变更处必须可读）

对“逻辑变更”的代码块，在变更附近增加 CHANGE 标记注释，包含：

• intent（变更意图）
• assumptions（前置假设）
• edge cases / money semantics（边界条件与资金口径：精度/舍入等）