AI_coding_guide
================================================================================
AI 辅助模块开发标准流程
================================================================================
适用于：有 specs 规范、docs 文档、业务分支多、需可追溯的业务模块（如 Closing、Settlement 等）。
【项目目录约定】
源码工程 业务实现（如 posnet-crc/app/src/...）
specs/ 测试用例、接口规范、验收用例
docs/{Module}/ 本模块全套设计与归档文档
【模块占位符】
下文 {Module} 表示当前模块名（如 Closing）。
全流程必须统一，禁止混用 Closing / settlement 等不同名称。
--------------------------------------------------------------------------------
极简核心规则（4 条）
--------------------------------------------------------------------------------
1. 先设计，再 spec，最后写代码 — 不直接上手编码。
2. 每一小步同步更新 spec 测试用例 — 代码与 spec 双向绑定。
3. 双门禁 — 每步必须 build 编译通过 + spec 自动化测试通过，才算完成。
4. 模块名全文统一 — Prompt、目录、包名、文档标题均使用同一 {Module}。
--------------------------------------------------------------------------------
流程分级
--------------------------------------------------------------------------------
完整版 结算、对账、联机、密钥等核心链路 阶段 1～6 全部执行
裁剪版 POC、单点 bugfix、纯 UI/文案 阶段 1（一页纸）+ 阶段 4；
无 spec 则先建最小测试脚手架
================================================================================
阶段 1：架构方案（先设计）
================================================================================
【固定 Prompt】
你是安卓工程师。项目目录：源码工程、specs/、docs/。
本次开发模块：{Module}
请完成以下事项，输出并保存为 docs/{Module}/01_{Module}架构方案.md：
1. 范围边界（必写）
- In scope / Out of scope
- 依赖的外部系统（Host、TMS、Print、DB 等）
- 明确不做的假设
2. 依赖梳理（限定范围，勿泛泛全库扫描）
- 指定包路径下的上下游调用
- 公共工具、数据库表、外部接口
3. 业务流转图
- 正常流程 + 全部异常分支（可用 Mermaid）
4. 模块规范
- 分层职责（UI / ViewModel / Domain / Data 等）
- 入参/出参基础规范
- 全局错误码约束
5. 验证与构建（占位，按项目实际填写）
- 构建命令：例 ./gradlew :posnet-crc:app:assembleDebug
- 单元测试命令：例 ./gradlew :posnet-crc:app:testDebugUnitTest
【人工动作】
通读 review；业务逻辑、依赖有误直接让 AI 修改。方案完全通过后再进入阶段 2。
================================================================================
阶段 2：Spec 验收核对清单
================================================================================
【固定 Prompt】
基于 docs/{Module}/01_{Module}架构方案.md，
完整检索 specs/ 内所有 {Module} 相关测试、接口规范、验收用例。
请完成：
1. 逐条提取硬性校验规则：
- 入参校验、业务分支、异常报错、数据落库、返回体格式
2. 生成《Spec 验收核对清单》，保存为 docs/{Module}/02_Spec验收清单.md
3. 每条规则使用统一格式：
ID | 规则描述 | spec 文件路径 | 优先级 P0/P1/P2 | 自动化/手工 | 代码锚点（开发后补）
4. 清单版本号：v1.0.0，文末附「变更记录」表（日期、版本、变更说明）
5. 明确约束：后续代码须与清单一致；若 spec 与清单冲突，以 spec 为准并更新清单版本，
不得擅自简化逻辑。
【人工动作】
逐条核对；漏用例、约束不全立刻补充。清单定稿后再拆分开发步骤。
================================================================================
阶段 3：分步开发计划
================================================================================
【固定 Prompt】
根据 docs/{Module}/01_{Module}架构方案.md
和 docs/{Module}/02_Spec验收清单.md，
拆分独立开发步骤，保存为 docs/{Module}/03_分步开发计划.md。
拆分规则：
- 单步只实现单一业务分支
- 完成后可独立 build、可独立跑对应用例
输出内容：
1. 有序任务列表（Step 1, 2, 3...）
2. 每步标注对应 Spec 清单 ID（如 S-001, S-002）
3. 每步验证方式：构建命令、spec 测试命令（可只跑本步相关用例）
4. 区分：单元 spec（每步必过）/ 集成或手工验收（标注在 Phase 5）
【人工动作】
确认步骤粒度合理；单步过大则要求 AI 再拆。
================================================================================
阶段 4：分步编码（循环执行）
================================================================================
【循环】
执行 Step N → 编码 → 更新 spec → build → spec 测试 → 清单勾选 → 通过后再 Step N+1
【每一步固定 Prompt】
当前执行 docs/{Module}/03_分步开发计划.md 第 N 步。
对应 Spec 清单条目：S-xxx, S-xxx
要求：
1. 编写 src 下 {Module} 业务代码，注释标注对应 spec ID（如 // spec: S-001）
2. 同步新增/更新 specs/ 下该分支单元测试
3. 输出修改文件清单（新增/修改）
4. 输出构建命令，保证可编译
完成后输出「本步已满足 Spec 清单 ID」列表，供人工 spot check。
【测试失败时 Prompt】
执行 {Module} 当前步骤相关 spec 测试，输出完整测试报告。
若有失败：对比代码与 docs/{Module}/02_Spec验收清单.md，自动修复代码与测试用例。
修复后重新列出已满足的 Spec ID。
【双门禁（缺一不可）】
编译 本地执行 AI 给出的 build 命令，无报错
Spec 执行对应用例，全部通过
清单 核对 AI 输出的「已满足 Spec ID」；P0 项人工必查
【人工动作】
全部通过再开下一步；失败则让 AI 定位修复，直到通过。
================================================================================
阶段 5：模块全量回归
================================================================================
【固定 Prompt】
{Module} 模块全部开发步骤已完成，执行全量回归：
1. 重读 01 架构方案、02 Spec 验收清单，全局校验代码是否满足全部约束
2. 一次性执行模块全部 spec 测试，生成完整测试报告
3. 汇总本模块所有新增/修改文件
4. 保存为 docs/{Module}/04_全量测试报告.md（含：通过数/失败数、未覆盖的「手工」项说明）
【人工动作】
全量测试无失败用例；手工项按清单补测。通过后代表模块开发完成。
================================================================================
阶段 6：文档归档
================================================================================
【固定 Prompt】
汇总 {Module} 模块全套资料至 docs/{Module}/：
- 01_{Module}架构方案.md
- 02_Spec验收清单.md
- 03_分步开发计划.md
- 04_全量测试报告.md
另输出 docs/{Module}/05_开发总结.md：
- 核心逻辑摘要
- 重点 spec 约束（P0）
- 开发注意事项与已知遗留项
【收尾】
文档归档完成即本模块闭环；后续迭代、交接可直接查阅 docs/{Module}/。
--------------------------------------------------------------------------------
Spec 形态说明（Android 项目）
--------------------------------------------------------------------------------
执行前约定本项目「spec」指什么，写入 02_Spec验收清单.md 头部：
单元测试 app/src/test/... 阶段 4 每步必跑
仪器测试 app/src/androidTest/... 可选，Phase 5
用例文档 specs/{Module}/*.md 阶段 2 提取规则来源
参数/配置 util/param/*.xml 业务规则引用，非自动化 spec
集成依赖（DB、Host、密钥、真机 Pinpad）：
在分步计划中标注 mock 策略；纯 mock 通过的用例需在 Phase 5 注明「需联调/真机补测」。
--------------------------------------------------------------------------------
docs/{Module}/ 目录结构（标准）
--------------------------------------------------------------------------------
docs/{Module}/
01_{Module}架构方案.md
02_Spec验收清单.md （含版本号与变更记录）
03_分步开发计划.md
04_全量测试报告.md
05_开发总结.md
--------------------------------------------------------------------------------
快速检查表（每阶段结束）
--------------------------------------------------------------------------------
阶段 1 范围边界清晰；流程图含异常分支；人工 review 通过
阶段 2 清单有条目 ID、spec 路径、优先级；无遗漏用例
阶段 3 每步可独立 build；绑定 Spec ID
阶段 4 每步 build + spec + 清单 ID 勾选
阶段 5 全量 spec 通过；手工项有说明
阶段 6 五份文档齐全
--------------------------------------------------------------------------------
使用示例（Closing 模块）
--------------------------------------------------------------------------------
将全文 {Module} 替换为 Closing：
docs/Closing/01_Closing架构方案.md
docs/Closing/02_Spec验收清单.md
./gradlew :posnet-crc:app:testDebugUnitTest --tests "*Closing*"
禁止在同一会话中混用 Closing 与 settlement 作为模块名。
--------------------------------------------------------------------------------
文档版本：v1.0
含流程分级、范围边界、Spec 清单格式、双门禁+清单勾选、Android spec 约定
--------------------------------------------------------------------------------
浙公网安备 33010602011771号