brainwave/docs/quality-gates.md

质量门禁与验证策略

状态：测试策略已定义；命令在 Android 骨架初始化后启用 原则：完成必须有可重复证据，不能以“代码看起来正确”代替验证

1. 反馈循环

每个实现任务遵循：

需求编号 → 最小实现 → 就近测试 → 全量静态/单元检查 → 设备验证 → 文档同步
                         ↑                         ↓
                         └──── 失败归因与修复 ────┘

同类失败第二次出现时，应更新失败记忆；适合机械检查的规则必须转成测试、lint 或脚本。

2. 预期本地命令

工程创建后，Windows 环境至少提供以下稳定入口：

.\gradlew.bat spotlessCheck
.\gradlew.bat lintDebug
.\gradlew.bat testDebugUnitTest
.\gradlew.bat assembleDebug
.\gradlew.bat connectedDebugAndroidTest

若采用不同格式化插件，命令可以调整，但必须在本文件和 CI 同步更新。connectedDebugAndroidTest 需要模拟器或设备，应与纯 JVM 快速门禁分开。

建议再提供聚合任务：

.\gradlew.bat verifyLocal

它至少依赖格式、lint、JVM 单元测试和 debug 构建，使代理不必猜测正确验证组合。

当前仓库没有 Gradle Wrapper，所以上述命令尚未运行，也不能报告为通过。

3. 测试层次

3.0 原型验证（P-1 阻塞视觉确认）

• node --check prototype/app.js 无语法错误。
• node --check prototype/capture.mjs 无语法错误。
• git diff --check 无空白错误。
• 本地服务运行时，node prototype\capture.mjs 退出码为 0。
• Chromium 360 × 792 走通问题输入、六次录入、结果和解释选择。
• 9,8,8,8,8,8 显示复 24 → 坤 2、初爻动；全 7 显示乾 1、无动爻且无之卦。
• 欢迎、起念、录入、有/无动爻结果、AI 同意、解释和失败状态均有可复现截图。
• 浏览器控制台无应用错误；页面不发起外部请求；AI 状态明确标为本地模拟。

原型通过只表示流程可供评审，不替代纯 Kotlin 领域测试、Compose UI 测试或真机无障碍检查。

3.1 纯 JVM 领域测试（最快，阻塞合并）

• 三枚铜币 8 种排列映射。
• 六爻 4,096 种组合不变量。
• 64 卦模式映射唯一性。
• bottom-up 顺序和显示适配。
• CastResult 序列化往返。
• 本地内容 schema 与完整性。
• 本地解释模板选择。
• AI DTO schema、长度和纯文本校验。

3.2 ViewModel/Repository 测试（阻塞合并）

• 投币状态机、返回修改和第六次封印。
• SavedState 恢复。
• 只在用户点击且同意后调用 AI。
• 并发点击、取消和超时不重复提交。
• Room 保存/读取一致性。
• 删除与撤销/确认行为。

测试优先使用接口的 fake 实现，不依赖真实网络和实时模型。

3.3 Compose UI 测试（阻塞发布）

• 首次说明与方法约定可达。
• 六轮录入的进度、按钮启用状态和错误恢复。
• 结果页本卦/之卦/动爻语义。
• AI 同意、加载、失败、本地降级。
• 最大字体下关键操作可到达。
• TalkBack 语义、焦点顺序和触控目标。
• 旋转/横屏/大屏布局。

3.4 端到端与人工验收（阻塞发布）

• 飞行模式走完整核心流程。
• 真机上检查输入法、返回手势、深浅主题和触觉。
• 使用已知六爻夹具人工核对卦象绘制和文本。
• 后端 staging 环境验证同意、超时、限流、非法响应和安全分支。
• 验证安装包不包含生产密钥和未授权内容。

4. 需求追踪矩阵

需求	主要自动化证据	人工证据
FR-Q-001~004	ViewModel + Compose 输入测试	中文输入法、隐私文案
FR-C-001~003	状态机与 UI 测试	真实投币录入可理解性
FR-C-004~006	领域穷举与映射测试	已知卦象目视复核
FR-C-007	SavedState/重建测试	旋转、切后台、进程恢复
FR-R-001~003	UI 语义与 screenshot 测试	TalkBack、色觉与长文阅读
FR-R-004	网络失败测试	飞行模式
FR-R-005	内容 schema/授权清单检查	内容负责人签核
FR-E-001~003	网络调用次数与同意状态测试	首次同意流程
FR-E-004~006	输出 schema + 安全用例集	安全/产品审核
FR-H-001~004	Room、删除、权限边界测试	隐私设置与删除体验
NFR-OFF-001	fake/offline 集成测试	飞行模式真机
NFR-DET-001	4,096 组合属性测试	无
NFR-SEC/PRI	secret scan、日志测试	APK/代理抓包复核
NFR-A11Y-001	Compose accessibility checks	TalkBack、最大字体
NFR-RES-001	重建和恢复测试	厂商设备抽测

5. 架构与数据门禁

工程初始化时应新增可机械执行的规则：

• domain 包不得依赖 Android、Compose、Room 和网络包。
• data.ai 不得依赖或调用 CastEngine。
• feature UI 不得引用 DAO 或网络 DTO。
• 生产源码不得出现 API key 形态、真实用户问题测试样例或 HTTP body logger。
• 内容校验任务验证 64 卦、384 条爻辞、唯一模式、来源和许可证字段。
• 文档链接和需求编号无悬空引用。

可以使用现有静态工具、架构测试库或小型自定义 Gradle 任务；具体选型写入决策记录。规则的错误消息应告诉代理如何修复，而不只报告失败。

6. 发布门禁

发布候选必须满足：

• 格式、lint、JVM 测试、UI 测试和 release 构建全部通过。
• 64 卦内容校验与授权清单通过。
• 飞行模式核心流程通过。
• AI 安全测试集和故障降级通过；若 AI 未上线则功能关闭且不影响本地流程。
• 无生产密钥、敏感日志和真实用户内容进入 APK/测试产物。
• 浅色/深色、小屏/大屏、最大字体、TalkBack、减少动态效果完成抽测。
• 隐私政策和应用内数据说明与实际网络行为一致。
• 数据库迁移、备份策略和删除行为已验证。
• 已知阻塞缺陷为 0，非阻塞缺陷有记录和责任人。

7. 完成定义（Definition of Done）

一个任务只有在以下条件全部满足时才算完成：

1. 关联明确的需求或缺陷编号。
2. 实现遵守领域、架构、UX 和 AI 边界。
3. 新行为有自动化测试，缺陷有回归测试。
4. 执行了与风险相称的验证命令并记录结果。
5. 失败不是通过跳过测试、降低断言或吞异常来“解决”。
6. 用户可见行为或契约变化已经同步文档。
7. 没有引入秘密、未授权内容和敏感测试数据。
8. 交付说明列出变更、验证证据、剩余风险和未执行项。

8. 验证报告模板

### 验证
- 需求：FR-C-004, FR-C-006
- 已运行：`.\gradlew.bat testDebugUnitTest`
- 结果：通过，N tests
- 未运行：`connectedDebugAndroidTest`（原因：无可用模拟器）
- 人工检查：输入 9,8,8,8,8,8，得到复 24 → 坤 2，初爻动
- 剩余风险：无 / 明确列出

不得把未运行写成“应当通过”。