AndroidProject-Compose 是一个基于 Kotlin、Jetpack Compose 和 Navigation 3 的 Android 脚手架。项目把通用能力放在 core/，把业务页面放在 feature/，通过包级边界组织代码。
| 领域 | 技术与用途 |
|---|---|
| 语言与 UI | Kotlin、Jetpack Compose、Material 3 |
| 页面与状态 | Route → Screen → Content、ViewModel、StateFlow |
| 依赖注入 | Hilt |
| 网络与模型 | Retrofit、OkHttp、Kotlin Serialization |
| 数据访问 | Repository、NetworkDataSource、Room、本地存储接口 |
| 导航 | AndroidX Navigation 3、类型安全 NavKey、模块级 Navigator |
| 开发与质量 | Gradle、JVM 单元测试、Compose Preview |
修改代码或文档前，先阅读任务对应的本地章节，再核对当前源码、调用方和测试。禁止根据类型名称、其他平台实现或记忆猜测 Android API。
资料优先级如下：
- 用户当前任务与本文件的项目级约束。
- AndroidProject-Compose 框架文档。
- 当前源码、同类实现、调用关系和测试用例。
- Android、Kotlin 和第三方依赖的官方文档。
文档与代码不一致时，以可运行源码和测试结果为依据，并同步更新项目内副本与在线文档。
| 开发任务 | 必读章节 |
|---|---|
| 项目架构与模块拆分 | 项目架构与职责 → 工程组织与模块边界 |
| 主题、布局与公共 UI | 设计系统 → 主题系统 → UI 组件 |
| 编写 Route、Screen、Content | Feature 概览 → View 规范 |
| 编写 ViewModel 与页面状态 | ViewModel 规范 → ViewModel 基类 |
| 接入网络、数据与分页 | 数据模型 → 请求结果处理 → 网络请求 → 数据层 → 非分页网络基类或分页列表 |
| 使用 Room、本地存储或全局状态 | 数据层 → Room 数据库、本地存储或全局状态 |
| 配置路由、参数、拦截与结果 | 导航概览 → 路由配置 → 导航流程 → 登录与路由拦截 → 参数传递与结果回传 |
| 创建完整 Feature 页面 | 目录与命名规范 → 创建页面流程 → 页面模板 |
| 配置 Preview 与屏幕适配 | 注解 → 数据层的预览数据 → 屏幕适配 → View 预览规范 |
core/提供跨 Feature 复用的基础能力；feature/承载业务页面。通用层不得反向依赖具体 Feature。文档中的目录均为逻辑目录，不绑定源码包名或本地文件系统路径。core/data/不只是 Repository 目录，也承载跨 Feature 复用的 Preview 数据；单个 Feature 专用的静态数据和PreviewParameterProvider留在该 Feature 的data/。core/annotation/用于项目通用注解。当前包含页面预览、组件预览和多设备预览注解；新增通用注解仍放入该目录。core/extension/是按需创建的 Kotlin 扩展位置。跨多个 Feature 复用且具有明确语义的扩展才提升到 Core，Feature 私有扩展保留在业务域。- 网络、数据库和本地存储都通过 Repository 进入页面；ViewModel 不直接创建 Service、DAO 或具体存储实例。
core/navigation/声明类型安全路由、模块 Navigator 和导航运行时；feature/<domain>/navigation/只注册本功能域 Graph。- 当前工程为单
:app模块。只有当功能域需要独立编译、独立依赖或独立发布时，才按模块化设计拆分 Gradle 模块。 - 文档中的文件位置使用
core/、feature/<domain>/等逻辑目录；代码示例里的package和import只代表当前源码基线，包名迁移使用 Android Studio 重构同步更新。
- 每个普通页面都使用
${PAGE_NAME}Route→${PAGE_NAME}Screen→${PAGE_NAME}Content三层。MainScreen是顶级页面容器的特殊实现，不使用Scaffold，但仍保留对应的 Route、Screen 和 Content 层。 - Route 只负责注入 ViewModel、收集公开只读
StateFlow、转发事件，并在每个状态变量旁说明状态含义。典型写法是val uiState by viewModel.uiState.collectAsState()。 - Screen 负责
Scaffold、AppBar、页面骨架和 Loading、Empty、Error 等缺省状态；成功状态下的最终业务布局必须交给 Content。 - Content 只接收可渲染数据与事件回调，不直接访问 ViewModel、Repository、DataSource 或导航实现。
- 页面中的大部分业务逻辑通过 View 回调进入 ViewModel；页面顶部栏的普通返回操作直接调用
navigateBack()，不为它额外创建只转发返回的方法。 - ViewModel 负责状态、请求、Repository 调用和导航副作用；View 不负责业务判断、网络请求或持久化。
- 完整页面至少提供
@ScreenPreview与@ScreenPreviewDark；组件使用@ComponentPreview、@ComponentPreviewDark或组合注解。复杂页面通过@PreviewParameter注入静态预览数据，Preview 不发起真实请求。
- 遵循 Kotlin 官方编码规范。文件使用
PascalCase.kt并与主要类型同名，类型使用PascalCase，变量和方法使用camelCase，常量使用UPPER_SNAKE_CASE，包名使用全小写英文。 - import 下方、主要声明前添加中文 KDoc，说明文件或类型职责。类型、构造参数、字段、状态、公开与私有方法均使用 KDoc；参数使用
@param，非Unit返回值使用@return。 - Route 中每个
collectAsState()、关键状态转换、失败分支和不直观的布局计算必须添加中文行内注释。重写属性和重写方法仍需说明其业务含义，不能因为接口已有声明而省略。 - 注释只描述最终职责、业务含义和设计原因，不记录修改过程、协作对话或人称表达。
- 代码关键字与 API 保持英文，注释使用中文。避免
Common.kt、Utils.kt、Manager.kt、Data.kt等无法表达领域职责的名称。
- 代码变更至少运行
./gradlew assembleDebug和./gradlew testDebugUnitTest；涉及静态检查时追加./gradlew lint。 - 文档变更运行项目内链接检查，并在文档站仓库运行
pnpm docs:build；网站与本地副本的页面、图片和链接保持一致。 - 提交前运行
git diff --check，不得提交build/、.gradle/、文档站dist/或缓存目录。 - 保留工作区中与任务无关的修改，不使用整体重置或覆盖方式清理文件。