feat: add domain core and verification harness
This commit is contained in:
QiuSW
+1
-1
@@ -2,7 +2,7 @@
|
||||
|
||||
> 文档状态：方案基线
|
||||
> 最后核验：2026-08-04
|
||||
> 当前阶段：P-1 核心原型已确认；首页、问卦簿与默认本机保存 v0.3 已实现并待视觉复核；Android 工程尚未初始化
|
||||
> 当前阶段：P-1 v0.3 待视觉复核；P1 纯 Kotlin 领域核心已完成；P0 仓库门禁与 P2 内容契约已部分完成；可发布 Android 壳仍等待正式身份与 `minSdk` 决策
|
||||
|
||||
本目录是 Brainwave 的项目知识事实源。产品决策、领域算法、架构边界、验收标准和已知失败模式必须写入仓库；聊天记录、口头约定和临时提示不构成项目规范。
|
||||
|
||||
|
||||
@@ -96,7 +96,7 @@ core/designsystem → Compose/Material + core model（仅绘制需要）
|
||||
|
||||
### `CastEngine`
|
||||
|
||||
纯 Kotlin、无副作用。输入六轮铜币和方法版本，输出不可变 `CastResult`。所有规则来自[领域规则](domain-rules.md)。
|
||||
纯 Kotlin、无副作用。输入六轮铜币，使用 API 固定的 `coin-v1` 约定输出不可变 `CastComputation`；随后由记录工厂附加 `contentVersion` 与 `createdAt`，组成不可变 `CastResult`。方法版本不是调用方可随意传入的自由字符串，记录元数据也不能进入计算。所有规则来自[领域规则](domain-rules.md)。
|
||||
|
||||
### `HexagramContentRepository`
|
||||
|
||||
|
||||
@@ -24,6 +24,10 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"contentVersion": "zh-Hans-2026.1",
|
||||
"specialUsageTexts": {
|
||||
"qian": true,
|
||||
"kun": true
|
||||
},
|
||||
"sources": [
|
||||
{
|
||||
"id": "source-id",
|
||||
@@ -54,6 +58,8 @@
|
||||
|
||||
示例中的省略号不是可发布内容。禁止由 AI 在构建时临时补齐缺失卦辞或爻辞。
|
||||
|
||||
机器契约位于 `content/schema/hexagram-content.schema.json`。`specialUsageTexts` 显式声明当前内容版本是否提供乾“用九”和坤“用六”；声明为 `false` 时对应条目的 `specialUsageText` 必须为 `null`，不能用空字符串暗示内容存在。Android parser 尚未建立前，`scripts/verify-content-contract.mjs` 已提供独立构建期校验、稳定 SHA-256 摘要和不含可发布卦辞的自动化夹具；`HexagramContentRepository` 接口与测试 fake 已建立，缺少 ID 或内容版本不匹配时抛出数据完整性错误，不回退到相邻条目。
|
||||
|
||||
## 3. 内容完整性门禁
|
||||
|
||||
内容包进入应用前必须自动验证：
|
||||
|
||||
+10
-1
@@ -121,6 +121,16 @@
|
||||
- 后果：P4 必须实现保存策略、事务关联、设置、单次退出、删除、迁移和备份排除测试；ADR-012 是生产事实源，决策时尚未同步的 v0.2 原型只能作为旧流程评审材料，现行 v0.3 已完成同步。
|
||||
- 复审触发：引入账号、导出、云同步、系统备份、跨设备迁移或新的隐私/合规要求。
|
||||
|
||||
## ADR-013：仓库门禁采用无外部依赖脚本并由 Gradle 聚合
|
||||
|
||||
- 状态：`Accepted`
|
||||
- 日期：2026-08-04
|
||||
- 关联：解决 TBD-012、P0/P1/P2/P6
|
||||
- 决定：在 Android application 壳建立前，使用仓库内 Node 脚本执行格式、文档链接、高置信 secret scan、domain 依赖边界、原型语法和内容完整性检查；Gradle 8.2 的 `verifyLocal` 聚合这些检查与 JVM 测试，CI 调用同一入口。
|
||||
- 原因：当前系统已实测 Node 22、JDK 17 和 Gradle 8.2，且无需新增全局工具或把个人路径写进工程；门禁错误能够给出可修复的文件位置。
|
||||
- 后果：`spotlessCheck` 当前是仓库内的无依赖格式兼容入口，不表示已引入 Spotless 插件。Android 壳建立后必须把 lint/debug build 加入 `verifyLocal`；将来若采用维护良好的专用插件，应保留命令兼容或同步更新 CI 与文档。
|
||||
- 复审触发：Android 工具链启用、现有脚本无法表达新边界，或专用工具能以可接受成本提供明显更强的检查。
|
||||
|
||||
## 未决问题
|
||||
|
||||
| ID | 问题 | 推荐默认 | 阻塞阶段 |
|
||||
@@ -134,7 +144,6 @@
|
||||
| TBD-009 | AI 模型供应商与自有后端 | 供应商无关接口；先交付本地版 | P5 |
|
||||
| TBD-010 | 服务端问题/回复保留期 | 最小化且明确披露，优先不持久化正文 | P5，发布阻塞 |
|
||||
| TBD-011 | 高风险本地资源表覆盖地区 | 首发市场确认后维护，不让模型编号码 | P5 |
|
||||
| TBD-012 | 架构检查工具 | 选择维护活跃工具或小型自定义测试 | P0/P1 |
|
||||
|
||||
## 新增决策模板
|
||||
|
||||
|
||||
@@ -5,6 +5,8 @@
|
||||
|
||||
本文件定义本项目唯一允许的计算规则。UI 文案、AI 输出和数据源都不能覆盖这些规则。
|
||||
|
||||
实现状态：`coin-v1` 纯 Kotlin 核心位于 `app/src/main/java/brainwave/domain/casting/`；`.\gradlew.bat :app:test --offline` 覆盖 8 种币面、4,096 种六爻、64 模式、已知夹具和 DTO 往返。记录时间与内容版本在确定性计算完成后附加。
|
||||
|
||||
## 1. 术语和类型
|
||||
|
||||
建议使用有语义的封闭类型，避免裸 `Int` 在层间传播：
|
||||
@@ -102,7 +104,7 @@ createdAt // 只用于记录，不参与计算
|
||||
3. 从各爻阴阳形成本卦模式并查得本卦编号。
|
||||
4. 收集值为 6 或 9 的位置作为动爻。
|
||||
5. 仅翻转动爻阴阳，形成之卦模式并查得之卦编号。
|
||||
6. 将全部原始输入、版本和确定结果构造成不可变 `CastResult`。
|
||||
6. 先将全部原始输入和确定结果构造成不可变 `CastComputation`，再附加 `methodVersion`、`coinConvention`、`contentVersion` 与 `createdAt` 记录元数据，组成不可变 `CastResult`；元数据不得反向影响步骤 1～5。
|
||||
|
||||
## 6. 读取内容的产品规则
|
||||
|
||||
|
||||
+9
-6
@@ -39,7 +39,7 @@
|
||||
| Node.js / npm | `22.22.1` / `11.12.1` |
|
||||
| Google Chrome | `150.0.7871.188`，`C:\Program Files\Google\Chrome\Application\chrome.exe` |
|
||||
|
||||
环境文件写入前，仓库没有 Gradle Wrapper、`build.gradle*`、`settings.gradle*` 或根 `AGENTS.md`。这些属于 Android 工程初始化阶段的交付物，不应被误认为已存在。
|
||||
首次环境审计时仓库没有 Gradle Wrapper、`build.gradle*`、`settings.gradle*` 或根 `AGENTS.md`。当前这些仓库级入口已经建立；`app` 暂时是纯 Kotlin/JVM 领域 harness，不是可安装 Android application。
|
||||
|
||||
Windows 路径可能较长；如果后续依赖缓存或生成代码触发路径长度错误，应优先缩短包/生成目录或评估仓库级长路径配置，并把实际决定写入[决策记录](decisions.md)。
|
||||
|
||||
@@ -101,15 +101,17 @@ Android Studio 不是当前环境的可用前提。项目必须先支持 PowerSh
|
||||
| 已验证 Gradle | `8.2` |
|
||||
| Gradle 使用的 JVM | Temurin `17.0.13` |
|
||||
| 缓存的 Android Gradle Plugin | `8.2.0` |
|
||||
| 缓存的 Kotlin Gradle Plugin | `1.9.20` |
|
||||
| 缓存的 JUnit | `4.13.2` |
|
||||
| 用户级 `~/.gradle/gradle.properties` | 不存在 |
|
||||
|
||||
项目初始化应提交 `gradlew`、`gradlew.bat`、`gradle/wrapper/gradle-wrapper.jar` 和版本明确的 `gradle-wrapper.properties`。所有项目命令使用：
|
||||
仓库已提交 `gradlew`、`gradlew.bat`、`gradle/wrapper/gradle-wrapper.jar` 和固定 Gradle 8.2 及 SHA-256 的 `gradle-wrapper.properties`。所有项目命令使用：
|
||||
|
||||
```powershell
|
||||
.\gradlew.bat <task>
|
||||
```
|
||||
|
||||
不要要求用户安装全局 Gradle。当前缓存能证明 Gradle 8.2 本体可运行，但不能证明 Compose、Kotlin、Hilt、Room 等全部 Maven 依赖已离线缓存；第一次构建仍需实际验证。
|
||||
不要要求用户安装全局 Gradle。当前缓存已实际证明 Gradle 8.2、Kotlin 1.9.20 与 JUnit 4.13.2 可离线完成领域构建和测试；Compose、Hilt、Room 等 Android 依赖仍未配置或验证，不能据此推断可离线解析。
|
||||
|
||||
## 7. 已连接 Android 真机
|
||||
|
||||
@@ -151,13 +153,14 @@ Android Studio 不是当前环境的可用前提。项目必须先支持 PowerSh
|
||||
|
||||
## 10. 已知缺口
|
||||
|
||||
- Android 工程和 Gradle Wrapper 尚未创建。
|
||||
- 可安装的 Android application 壳尚未创建；正式名称、组织所有的 application ID 与最终 `minSdk` 仍待确认。
|
||||
- Android Studio 未安装。
|
||||
- Android Emulator、system image 和 AVD 不可用。
|
||||
- 本机只确认安装了 Android Platform 34 / Build Tools 34.0.0。
|
||||
- Maven 依赖能否完整离线解析尚未验证。
|
||||
- Compose、Hilt、Room、DataStore 与 Navigation 的 Maven 依赖尚未完整离线验证。
|
||||
- 代理已配置，但外部仓库和 Android CLI 网络连通性尚未验证。
|
||||
- 没有根 `AGENTS.md` 和可执行的 `verifyLocal` 聚合任务。
|
||||
|
||||
已解除的缺口：Gradle Wrapper、Version Catalog、根 `AGENTS.md`、CI 与可执行的 `verifyLocal` 已建立；`verifyLocal --offline` 已在 JDK 17 上通过。它当前不包含 Android lint、APK 构建或设备测试。
|
||||
|
||||
这些缺口分别由[实施计划](implementation-plan.md)的 P0 和[质量门禁](quality-gates.md)处理。环境缺口不是跳过验证的理由；无法运行的门禁必须在交付报告中准确说明。
|
||||
|
||||
|
||||
+24
-22
@@ -1,6 +1,6 @@
|
||||
# 分阶段实施计划
|
||||
|
||||
> 状态：P-1 核心原型已确认，首页/问卦簿与默认本机保存 v0.3 已完成待视觉复核；P0 尚未开始
|
||||
> 状态：P-1 v0.3 待视觉复核；P0 仓库门禁已建立但 Android 壳受 TBD-001～003 阻塞；P1 已完成并通过穷举测试；P2 内容契约已建立但授权内容未开始
|
||||
> 计划原则：先用原型确认高返工成本体验，再锁定确定性领域核心，随后接内容和 UI，最后接网络 AI
|
||||
|
||||
## 1. 依赖图
|
||||
@@ -46,14 +46,14 @@ P1 与 P2 可并行，但 P3 不能在领域与内容契约未稳定时复制原
|
||||
|
||||
任务：
|
||||
|
||||
- 读取并遵守[本地开发环境](environment.md)：JDK 17、SDK 34、命令行优先、Gradle Wrapper、真机验证。
|
||||
- 基于 Google `android/architecture-templates` 的 `base` 分支初始化。
|
||||
- 确认正式应用名称、package/application ID、minSdk。
|
||||
- 配置 Kotlin、Compose、Material 3、Hilt、Room、DataStore、Navigation 和 Version Catalog。
|
||||
- 配置 Gradle Wrapper、格式化、lint、单元测试和 CI。
|
||||
- 建立 [系统架构](architecture.md)中的包结构和空 feature 边界。
|
||||
- 将根 `AGENTS.md` 设计为短地图，指向本目录和验证命令。
|
||||
- 增加 `verifyLocal` 聚合任务及基础 secret scan。
|
||||
- [x] 读取并遵守[本地开发环境](environment.md)：JDK 17、SDK 34、命令行优先、Gradle Wrapper、真机验证。
|
||||
- [ ] 基于 Google `android/architecture-templates` 的 `base` 分支初始化 Android 壳；模板定制需要 TBD-002 的正式 application ID，不能用临时发布身份替代。
|
||||
- [ ] 确认正式应用名称、package/application ID、minSdk（TBD-001～003）。
|
||||
- [ ] 配置 Compose、Material 3、Hilt、Room、DataStore 和 Navigation；Version Catalog 已先用于 JVM harness。
|
||||
- [ ] 配置 Gradle Wrapper、格式化、lint、单元测试和 CI：Wrapper、无依赖格式门禁、JVM 单测与 CI 已完成；Android lint 要等 application 插件启用。
|
||||
- [ ] 建立 [系统架构](architecture.md)中的包结构和空 feature 边界：`domain/casting` 已落地，其余随 Android 壳建立。
|
||||
- [x] 将根 `AGENTS.md` 设计为短地图，指向本目录和验证命令。
|
||||
- [x] 增加 `verifyLocal` 聚合任务、文档链接、领域边界、内容契约与基础 secret scan。
|
||||
|
||||
退出条件：
|
||||
|
||||
@@ -68,13 +68,13 @@ P1 与 P2 可并行，但 P3 不能在领域与内容契约未稳定时复制原
|
||||
|
||||
任务：
|
||||
|
||||
- 建立 `CoinSide`、`LineValue`、`Polarity`、`CastRound`、`CastResult`。
|
||||
- 实现六轮输入校验和 `CastEngine`。
|
||||
- 建立经过双重校验的 64 卦模式映射表。
|
||||
- 实现之卦变换和动爻位置。
|
||||
- 实现版本化序列化 DTO。
|
||||
- 完成 8 种币面、4,096 种六爻、64 模式和已知夹具测试。
|
||||
- 增加 domain 无 Android/网络依赖的架构门禁。
|
||||
- [x] 建立 `CoinSide`、`LineValue`、`Polarity`、`CastRound`、`CastResult`。
|
||||
- [x] 实现六轮输入校验和纯 `CastEngine`；记录时间与内容版本在计算后附加。
|
||||
- [x] 建立带完整性自检的 64 卦文王序号映射表。
|
||||
- [x] 实现之卦变换和 1～6 的 bottom-up 动爻位置。
|
||||
- [x] 实现 `schemaVersion=1` 的序列化 DTO，并在读取时用保存的十八枚币重新计算校验派生值。
|
||||
- [x] 完成 8 种币面、4,096 种六爻、64 模式和已知夹具测试。
|
||||
- [x] 增加 domain 无 Android、数据库和网络依赖的机械架构门禁。
|
||||
|
||||
退出条件：
|
||||
|
||||
@@ -82,18 +82,20 @@ P1 与 P2 可并行，但 P3 不能在领域与内容契约未稳定时复制原
|
||||
- 测试无随机、无网络、无系统时间依赖。
|
||||
- `CastEngine` API 经评审后冻结为 `coin-v1`。
|
||||
|
||||
当前证据：`.\gradlew.bat :app:test --offline` 中 `CastEngineTest` 执行 10 个测试、0 失败；实现位于 `app/src/main/java/brainwave/domain/casting/`。`brainwave` 是内部代码命名空间，不是 TBD-002 的 application ID。
|
||||
|
||||
## 5. P2：内容数据管线
|
||||
|
||||
目标：建立可追踪、可校验、可发布的本地内容包。
|
||||
|
||||
任务：
|
||||
|
||||
- 决定原文版本、现代白话来源和授权。
|
||||
- 实现 JSON schema、解析器和内容版本。
|
||||
- 录入/导入 64 卦、卦辞、384 条爻辞及所需特殊文本。
|
||||
- 建立来源清单、许可证清单和内容审核记录。
|
||||
- 实现构建期完整性校验与映射交叉校验。
|
||||
- 实现 `HexagramContentRepository` fake 与 assets 版本。
|
||||
- [ ] 决定原文版本、现代白话来源和授权（TBD-005，发布阻塞）。
|
||||
- [ ] 实现 JSON schema、解析器和内容版本：`schemaVersion=1` 的机器 schema 已完成；Android/Kotlin assets 解析器待 Android 壳建立。
|
||||
- [ ] 录入/导入 64 卦、卦辞、384 条爻辞及所需特殊文本。
|
||||
- [ ] 建立来源清单、许可证清单和内容审核记录；schema 已强制每个来源包含版本、许可证与 URL。
|
||||
- [x] 实现构建期完整性校验、文王序号/上下卦/bottom-up 交叉校验、稳定 SHA-256 摘要及 8 个负向夹具。
|
||||
- [ ] 实现 `HexagramContentRepository` fake 与 assets 版本：接口、强校验只读模型和测试 fake 已完成，assets 实现待 Android parser。
|
||||
|
||||
退出条件：
|
||||
|
||||
|
||||
+16
-11
@@ -1,6 +1,6 @@
|
||||
# 质量门禁与验证策略
|
||||
|
||||
> 状态：测试策略已定义；命令在 Android 骨架初始化后启用
|
||||
> 状态：JVM/harness 门禁已启用；Android lint、构建、UI 与设备门禁等待 Android application 壳
|
||||
> 原则：完成必须有可重复证据，不能以“代码看起来正确”代替验证
|
||||
|
||||
## 1. 反馈循环
|
||||
@@ -17,7 +17,18 @@
|
||||
|
||||
## 2. 预期本地命令
|
||||
|
||||
工程创建后，Windows 环境至少提供以下稳定入口：
|
||||
当前可重复的 Windows 快速门禁：
|
||||
|
||||
```powershell
|
||||
.\gradlew.bat spotlessCheck --offline
|
||||
.\gradlew.bat :app:test --offline
|
||||
.\gradlew.bat verifyContentContract --offline
|
||||
.\gradlew.bat verifyLocal --offline
|
||||
```
|
||||
|
||||
`verifyLocal` 当前聚合无依赖格式检查、10 个领域测试、3 个内容 repository 测试、domain 依赖边界、内容契约与负向夹具、文档链接、高置信 secret scan 和原型 JavaScript 语法检查。CI 执行同一个聚合任务。
|
||||
|
||||
Android application 插件配置后，Windows 环境还必须提供：
|
||||
|
||||
```powershell
|
||||
.\gradlew.bat spotlessCheck
|
||||
@@ -29,15 +40,7 @@
|
||||
|
||||
若采用不同格式化插件，命令可以调整，但必须在本文件和 CI 同步更新。`connectedDebugAndroidTest` 需要模拟器或设备，应与纯 JVM 快速门禁分开。
|
||||
|
||||
建议再提供聚合任务：
|
||||
|
||||
```powershell
|
||||
.\gradlew.bat verifyLocal
|
||||
```
|
||||
|
||||
它至少依赖格式、lint、JVM 单元测试和 debug 构建，使代理不必猜测正确验证组合。
|
||||
|
||||
当前仓库没有 Gradle Wrapper，所以上述命令尚未运行，也不能报告为通过。
|
||||
到那时必须把 Android lint 和 debug build 加入现有 `verifyLocal`，使代理仍不必猜测验证组合。在完成这一步之前，`verifyLocal` 通过只证明 JVM 与仓库门禁，不代表 APK 已构建或真机测试已通过。
|
||||
|
||||
## 3. 测试层次
|
||||
|
||||
@@ -148,6 +151,8 @@
|
||||
|
||||
可以使用现有静态工具、架构测试库或小型自定义 Gradle 任务；具体选型写入[决策记录](decisions.md)。规则的错误消息应告诉代理如何修复，而不只报告失败。
|
||||
|
||||
当前由无外部依赖的 Node 脚本与 Gradle 任务执行上述已落地规则，见 ADR-013。引入 Android 源码后应扩展同一入口，不应建立一套互不相干的新命令。
|
||||
|
||||
## 6. 发布门禁
|
||||
|
||||
发布候选必须满足：
|
||||
|
||||
Reference in New Issue
Block a user