docs: harness 工程文档

docs/decisions/0001-multi-module-nia.md

@@ -0,0 +1,22 @@
+# ADR 0001：多模块 NIA 架构，feature 单模块（不做 api/impl 拆分）
+
+- **状态**：已接受
+- **日期**：2026-09-03
+
+## 背景
+
+项目从单模块 Compose 模板起步，需要确立可扩展、可测试、可维护的架构基础。
+
+## 决策
+
+采用 Google Now in Android（NIA）风格多模块架构：`app`（组合根）+ `core/*`（共享能力）+ `feature/*`（业务功能）。每个 feature 用**单模块**，不做 nowinandroid 的 `feature:*/api` + `feature:*/impl` 拆分。
+
+## 理由
+
+- 依赖方向单向、职责清晰，符合参考项目 `nowinandroid` 与 `app_device` 的共识。
+- 团队规模小、feature 间共享少，api/impl 拆分会带来额外模块与样板，收益有限。
+
+## 后果
+
+- 约定插件 `mcl.android.feature` 预置 feature 通用依赖，新增 feature 只需一个插件声明。
+- 若未来 feature 间需要稳定 API 边界，再引入 api/impl 拆分（成本可控）。

docs/decisions/0002-convention-plugins-and-version-catalog.md

@@ -0,0 +1,23 @@
+# ADR 0002：约定插件 + 版本目录作为唯一配置事实源
+
+- **状态**：已接受
+- **日期**：2026-09-03
+
+## 背景
+
+多模块项目若在每个模块手写 `android {}` 模板，会出现配置漂移、版本不一致、样板重复。
+
+## 决策
+
+- **约定插件**（`build-logic/`，included build）：提供 `mcl.*` 插件，集中编码 compileSdk/minSdk、Java/Kotlin target、Compose、Hilt、Room、Lint、Spotless 等配置。模块只声明插件 + namespace。
+- **版本目录**（`gradle/libs.versions.toml`）：所有依赖版本唯一事实源，主构建与 build-logic 共用。
+
+## 理由
+
+- 把"严谨性"编码进确定性规则（harness-engineering 的"严谨性转移"原则），而非依赖人工记忆。
+- 一个版本改一处，全项目生效。
+
+## 后果
+
+- 新增/调整模块配置需改 build-logic；新增依赖需改版本目录。
+- 好处：`verifyArchitecture` 等约束可挂在约定插件体系里统一执行。

docs/decisions/0003-toolchain-and-versions.md

@@ -0,0 +1,23 @@
+# ADR 0003：工具链与版本选型
+
+- **状态**：已接受
+- **日期**：2026-09-03
+
+## 背景
+
+需要为一套现代化 Android 技术栈锁定版本。项目原本是 AGP 9.4.0 + Kotlin 2.2.10 + Gradle 9.6.0。
+
+## 决策
+
+- **保留**：Gradle 9.6.0（wrapper）、AGP 9.4.0、compileSdk/targetSdk 37、minSdk 28、Compose BOM 2026.02.01。
+- **对齐 nowinandroid 已验证矩阵**：Kotlin 2.3.0、KSP 2.3.4、Hilt 2.59、Room 2.8.3、Retrofit 2.11.0、OkHttp 4.12.0、kotlinx-coroutines 1.10.1、kotlinx-serialization 1.8.0、Navigation Compose 2.8.5、DataStore 1.2.0、Lifecycle 2.10.0、truth 1.4.4、turbine 1.2.0、spotless 8.3.0、ktlint 1.4.0。
+
+## 理由
+
+- 采用 AGP 9 内置 Kotlin（不显式应用 `org.jetbrains.kotlin.android`），与项目原有模板一致，且经 nowinandroid 验证可与 KSP/Hilt/Room 共存。
+- Kotlin 升到 2.3.0 是为了直接复用 nowinandroid 已证明可用的 KSP 2.3.4 / Hilt 2.59 / Room 2.8.3 组合，避免为旧 Kotlin 猜测 KSP 补丁版本。
+
+## 后果
+
+- 全量构建已验证通过（`:app:assembleDebug`）。
+- 若未来 AGP 升级改变内置 Kotlin 行为，需回归验证 KSP/Hilt/Room 兼容性。

docs/decisions/0004-package-name.md

@@ -0,0 +1,22 @@
+# ADR 0004：包名与显示名
+
+- **状态**：已接受
+- **日期**：2026-09-03
+
+## 背景
+
+项目原有包名 `com.mingyuan.android_client`（applicationId 与 namespace），显示名 `android-client`。
+
+## 决策
+
+- **保留包名** `com.mingyuan.android_client`（避免牵连改动），仅把显示名 `app_name` 改为「明缘进阶场」。
+- 模块命名空间沿用 `com.mingyuan.android_client.<路径点分>`。
+
+## 理由
+
+- 重命名 applicationId/namespace 会牵连 manifest、包目录、DI 组件等；基础建设阶段优先把架构骨架跑通。
+- 下划线命名虽不符合惯例，但不影响构建与运行，作为已知小问题保留。
+
+## 后果
+
+- 显示名已是「明缘进阶场」；包名中的下划线如需规范化，可在后续单独决策并一次性迁移。