# 明缘进阶场 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` |