docs: harness 工程文档

AGENTS.md

@@ -0,0 +1,67 @@
+# 明缘进阶场 Android 客户端
+
+「明缘进阶场」的 Android 客户端（`com.mingyuan.android_client`），对接 `wechat-backend` 提供的 auth / checkin / plan / course-vote / survey / feedback / profile API。当前处于**基础建设阶段**：多模块骨架已就绪，各 feature 为空占位，尚未接入真实后端。
+
+## 快速开始
+
+```bash
+./gradlew :app:assembleDebug        # 构建调试 APK
+./gradlew test testDebugUnitTest    # 运行单元测试（JVM + Android）
+bash scripts/verify.sh              # 完整验证（格式 / 测试 / 构建 / 架构检查）
+```
+
+## 架构概览
+
+多模块 NIA 架构：`app` 是组合根（Hilt 入口 + 单一 `AppNavHost`），`feature/*` 承载各业务界面，`core/*` 提供共享能力。依赖方向严格单向，由 `verifyArchitecture` Gradle 任务强制执行（违规即失败）。详见 [docs/architecture.md](docs/architecture.md)。
+
+## 目录结构
+
+```
+app/                 组合根：MingyuanApplication、MainActivity、AppNavHost
+core/common          纯 Kotlin 工具（无 Android 依赖）
+core/model           领域模型（纯 Kotlin）
+core/domain          UseCase + Repository 接口（纯 Kotlin）
+core/data            Repository 实现，编排 network/database/datastore
+core/network         Retrofit/OkHttp、DTO、序列化
+core/database        Room 实体 / DAO / 数据库
+core/datastore       DataStore 偏好
+core/designsystem    主题 / 颜色 / 字体 / 通用组件
+core/ui              共享 Compose UI + 导航辅助
+feature/*            业务功能（auth/checkin/plan/course/survey/feedback/profile）
+build-logic/         约定插件（mcl.*）+ verifyArchitecture
+docs/                架构 / 规范 / 决策记录（见下方文档地图）
+scripts/verify.sh    确定性验证脚本
+```
+
+## 关键约定
+
+1. **依赖方向单向**：`app → 所有`；`feature/* → core(ui/designsystem/domain/model)`；`core:data → domain/model/network/database/datastore`；`core:model`/`core:domain` 保持纯 Kotlin、不依赖 Android。新增模块或跨层依赖必须同步更新 `build-logic` 的 `RootPlugin.kt` allow-list 与 `docs/architecture.md`。
+2. **版本唯一事实源**：所有依赖版本在 [gradle/libs.versions.toml](gradle/libs.versions.toml)，禁止在模块里硬编码版本号。
+3. **模块配置走约定插件**：每个模块只声明 `mcl.*` 插件 + namespace，不要手写 `android {}` 模板代码。新增模块/插件流程见 [build-logic/convention/DESIGN_NOTES.md](build-logic/convention/DESIGN_NOTES.md)。
+4. **确定性格式化**：`spotlessCheck` 必须通过（ktlint 规则在 [.editorconfig](.editorconfig)）；提交前用 `./gradlew spotlessApply` 修正。
+5. **命名空间规则**：`com.mingyuan.android_client.<路径点分>`（如 `feature:checkin` → `com.mingyuan.android_client.feature.checkin`）。
+6. **验证优先于声称完成**：任何"完成/通过"声明都必须以 `scripts/verify.sh` 的新鲜输出为证据。
+7. **Commit 格式**：`type(scope): description`，一次提交一个变更集。
+8. **新 feature 模式**：在 `feature/<name>/` 下用 `mcl.android.feature` 插件，暴露 `<Name>Screen` 组合函数 + `<NAME>_ROUTE` 路由常量 + `<Name>ViewModel`，并在 `app` 的 `AppNavHost` 注册路由。
+
+## 文档地图
+
+| 主题 | 文档 |
+|------|------|
+| 架构与模块依赖 | [docs/architecture.md](docs/architecture.md) |
+| 编码规范 / 命名 / commit | [docs/conventions.md](docs/conventions.md) |
+| 测试策略与命令 | [docs/testing.md](docs/testing.md) |
+| 构建 / 签名 / 发布 | [docs/deployment.md](docs/deployment.md) |
+| 工作状态与遗留项 | [docs/progress.md](docs/progress.md) |
+| 架构决策记录（ADR） | [docs/decisions/](docs/decisions/) |
+| 约定插件设计说明 | [build-logic/convention/DESIGN_NOTES.md](build-logic/convention/DESIGN_NOTES.md) |
+| domain 层设计说明 | [core/domain/DESIGN_NOTES.md](core/domain/DESIGN_NOTES.md) |
+
+## 常见任务
+
+| 任务 | 做法 |
+|------|------|
+| 新增一个 feature 模块 | 建 `feature/<name>/` + `mcl.android.feature` + Screen/ViewModel，在 `RootPlugin.kt` 与 `settings.gradle.kts` 注册，更新 `docs/architecture.md` |
+| 新增一个依赖 | 加进 `gradle/libs.versions.toml`，模块里用 `libs.xxx` 引用 |
+| 修改模块依赖关系 | 改对应模块的 `build.gradle.kts`，跑 `./gradlew verifyArchitecture` 确认不违规 |
+| 本地完整验证 | `bash scripts/verify.sh` |