80 lines
5.1 KiB
Markdown
80 lines
5.1 KiB
Markdown
# 明缘进阶场 Android 客户端
|
||
|
||
「明缘进阶场」的 Android 客户端（`com.mingyuan.android_client`），对接 `wechat-backend` 提供的 auth / checkin / plan / course-vote / survey / feedback / profile API。当前处于**基础建设阶段**：多模块骨架已就绪，各 feature 为空占位，尚未接入真实后端。
|
||
|
||
## 关联项目
|
||
|
||
本仓库是「明缘进阶场」三端之一。分析功能/业务时可跨仓库参考对应实现。
|
||
|
||
| 端 | 仓库地址 | 本地路径 |
|
||
|------|------|------|
|
||
| Android（本仓库） | https://git.muguaclub.cn/mingyuan/android-client | 当前目录（`android-client`） |
|
||
| 后端 | https://git.muguaclub.cn/mingyuan/wechat-backend | `../wechat-backend` |
|
||
| 小程序 | https://git.muguaclub.cn/mingyuan/wechat-clock-mini | `../wechat-clock-mini` |
|
||
|
||
## 快速开始
|
||
|
||
```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` 注册路由。
|
||
9. **Git 分支流**：`feature/<name>` 从 `dev` 拉、merge 回 `dev`；`dev` 稳定后经确认再 merge 到 `main`（详见 [docs/gitflow.md](docs/gitflow.md)，决策记录 ADR-0005）。
|
||
|
||
## 文档地图
|
||
|
||
| 主题 | 文档 |
|
||
|------|------|
|
||
| 架构与模块依赖 | [docs/architecture.md](docs/architecture.md) |
|
||
| 编码规范 / 命名 / commit | [docs/conventions.md](docs/conventions.md) |
|
||
| Git 分支策略（简化版 GitFlow） | [docs/gitflow.md](docs/gitflow.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` |
|