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

快速开始

./gradlew :app:assembleDebug        # 构建调试 APK
./gradlew test testDebugUnitTest    # 运行单元测试（JVM + Android）
bash scripts/verify.sh              # 完整验证（格式 / 测试 / 构建 / 架构检查）

架构概览

多模块 NIA 架构：app 是组合根（Hilt 入口 + 单一 AppNavHost），feature/* 承载各业务界面，core/* 提供共享能力。依赖方向严格单向，由 verifyArchitecture Gradle 任务强制执行（违规即失败）。详见 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    确定性验证脚本

关键约定

依赖方向单向：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。
版本唯一事实源：所有依赖版本在 gradle/libs.versions.toml，禁止在模块里硬编码版本号。
模块配置走约定插件：每个模块只声明 mcl.* 插件 + namespace，不要手写 android {} 模板代码。新增模块/插件流程见 build-logic/convention/DESIGN_NOTES.md。
确定性格式化：spotlessCheck 必须通过（ktlint 规则在 .editorconfig）；提交前用 ./gradlew spotlessApply 修正。
命名空间规则：com.mingyuan.android_client.<路径点分>（如 feature:checkin → com.mingyuan.android_client.feature.checkin）。
验证优先于声称完成：任何"完成/通过"声明都必须以 scripts/verify.sh 的新鲜输出为证据。
Commit 格式：type(scope): description，一次提交一个变更集。
新 feature 模式：在 feature/<name>/ 下用 mcl.android.feature 插件，暴露 <Name>Screen 组合函数 + <NAME>_ROUTE 路由常量 + <Name>ViewModel，并在 app 的 AppNavHost 注册路由。
Git 分支流：feature/<name> 从 dev 拉、merge 回 dev；dev 稳定后经确认再 merge 到 main（详见 docs/gitflow.md，决策记录 ADR-0005）。

文档地图

主题	文档
架构与模块依赖	docs/architecture.md
编码规范 / 命名 / commit	docs/conventions.md
Git 分支策略（简化版 GitFlow）	docs/gitflow.md
测试策略与命令	docs/testing.md
构建 / 签名 / 发布	docs/deployment.md
工作状态与遗留项	docs/progress.md
架构决策记录（ADR）	docs/decisions/
约定插件设计说明	build-logic/convention/DESIGN_NOTES.md
domain 层设计说明	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`

5.1 KiB Raw Permalink Blame History Unescape Escape