# 架构

## 概述

本项目采用 Google Now in Android（NIA）风格的多模块架构，将应用按**职责边界**拆分为 `app`、`core/*`、`feature/*` 三类模块。核心目标是让依赖方向**严格单向**、让每一层**可独立编译与测试**、让领域逻辑**与 Android 框架解耦**。

## 模块结构

| 模块 | 类型 | 职责 |
|------|------|------|
| `app` | application + compose + hilt | 组合根：`@HiltAndroidApp` Application、`MainActivity`、单一 `AppNavHost` |
| `core:common` | 纯 JVM | 无 Android 依赖的通用工具 |
| `core:model` | 纯 JVM | 领域模型（跨层共享的不可变数据） |
| `core:domain` | 纯 JVM | UseCase + Repository 接口（业务规则，框架无关） |
| `core:data` | android library + hilt | Repository 实现，编排 network/database/datastore |
| `core:network` | android library + serialization | Retrofit/OkHttp、DTO、序列化 |
| `core:database` | android library + room | Room 实体 / DAO / 数据库 |
| `core:datastore` | android library | DataStore 偏好存储 |
| `core:designsystem` | android library + compose | 主题 / 颜色 / 字体 / 通用组件 |
| `core:ui` | android library + compose + hilt | 共享 Compose UI 与导航辅助 |
| `feature:*` | feature | 各业务功能（auth/checkin/plan/course/survey/feedback/profile） |

## 分层与依赖方向

依赖必须**单向向下**，杜绝环。完整 allow-list 编码在 `build-logic/convention/src/main/kotlin/RootPlugin.kt` 的 `verifyArchitecture` 任务中——任何越层依赖都会在 `./gradlew verifyArchitecture` 时失败。

```
app ────────────► 所有模块（组合根）
feature/* ──────► core:ui, core:designsystem, core:domain, core:model
core:data ──────► core:domain, core:model, core:network, core:database, core:datastore
core:network ───► core:common, core:model
core:database ──► core:model
core:datastore ─► core:model
core:ui ────────► core:designsystem, core:model
core:designsystem ► core:common
core:model, core:common ► （叶子，无项目依赖）
```

分层语义（自上而下）：

- **UI 层**（`feature/*` + `core:ui` + `core:designsystem`）：渲染界面、处理交互、持有 `ViewModel`。
- **领域层**（`core:domain` + `core:model`）：业务规则（UseCase）、领域模型、Repository 接口。**纯 Kotlin，不依赖 Android**，可快速跑在 JVM 上测试。
- **数据层**（`core:data` + `core:network`/`database`/`datastore`）：Repository 实现、网络与本地数据源，依赖领域层接口。

## 模块配置（约定插件）

每个模块的 `build.gradle.kts` 只声明 `mcl.*` 约定插件 + namespace，不手写模板。插件语义：

| 插件 | 适用 |
|------|------|
| `mcl.kotlin.library` | 纯 JVM 模块（common/model/domain） |
| `mcl.android.library` | Android 库（network/database/datastore/data） |
| `mcl.android.library.compose` | Android 库 + Compose（designsystem/ui） |
| `mcl.android.feature` | feature 模块（= library.compose + hilt + 导航/lifecycle 依赖） |
| `mcl.android.application.compose` | app（= application + compose） |
| `mcl.android.hilt` | Hilt（KSP） |
| `mcl.android.room` | Room（KSP） |
| `mcl.android.lint` | Android Lint 配置 |

## 新增一个模块

1. 建目录 + `build.gradle.kts`（选对 `mcl.*` 插件 + 设 namespace）+ 空 `AndroidManifest.xml`（仅 Android 模块）。
2. 在 `settings.gradle.kts` 里 `include(":...")`。
3. 在 `RootPlugin.kt` 的 allow-list 里加一条（模块路径 → 允许依赖的模块）。
4. 更新本文件的分层图。

## 组合根（app）

`app` 负责把各模块**装配**起来：`MingyuanApplication` 标注 `@HiltAndroidApp`；`AppNavHost` 用 Navigation Compose 把各 feature 的路由常量（`<NAME>_ROUTE`）与 Screen 组合成单一导航图。后续接入数据层时，`app` 会直接依赖 `core:data`（以及含 Hilt `@Module` 的 network/database/datastore）完成 DI 聚合。