From 50a42be9bcb58b513edd884bdb24ddf4331db3f7 Mon Sep 17 00:00:00 2001 From: xfy Date: Wed, 20 May 2026 13:26:19 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E5=90=84=E7=9B=AE=E5=BD=95=20AGENTS.md=20=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 为各模块和子目录添加 AGENTS.md，便于 AI 助手理解项目结构。 Co-Authored-By: Claude Opus 4.7 (1M context) --- AGENTS.md | 53 ++++++++++++++++ androidApp/AGENTS.md | 54 ++++++++++++++++ androidApp/src/main/AGENTS.md | 40 ++++++++++++ .../main/kotlin/plus/rua/project/AGENTS.md | 29 +++++++++ iosApp/AGENTS.md | 49 +++++++++++++++ iosApp/iosApp/AGENTS.md | 36 +++++++++++ shared/AGENTS.md | 49 +++++++++++++++ shared/src/androidMain/AGENTS.md | 37 +++++++++++ .../kotlin/plus/rua/project/AGENTS.md | 25 ++++++++ shared/src/commonMain/AGENTS.md | 55 +++++++++++++++++ .../src/commonMain/composeResources/AGENTS.md | 26 ++++++++ .../kotlin/plus/rua/project/AGENTS.md | 47 ++++++++++++++ .../kotlin/plus/rua/project/ui/AGENTS.md | 61 +++++++++++++++++++ shared/src/commonTest/AGENTS.md | 34 +++++++++++ .../kotlin/plus/rua/project/AGENTS.md | 35 +++++++++++ .../kotlin/plus/rua/project/ui/AGENTS.md | 30 +++++++++ shared/src/iosMain/AGENTS.md | 39 ++++++++++++ .../iosMain/kotlin/plus/rua/project/AGENTS.md | 27 ++++++++ 18 files changed, 726 insertions(+) create mode 100644 AGENTS.md create mode 100644 androidApp/AGENTS.md create mode 100644 androidApp/src/main/AGENTS.md create mode 100644 androidApp/src/main/kotlin/plus/rua/project/AGENTS.md create mode 100644 iosApp/AGENTS.md create mode 100644 iosApp/iosApp/AGENTS.md create mode 100644 shared/AGENTS.md create mode 100644 shared/src/androidMain/AGENTS.md create mode 100644 shared/src/androidMain/kotlin/plus/rua/project/AGENTS.md create mode 100644 shared/src/commonMain/AGENTS.md create mode 100644 shared/src/commonMain/composeResources/AGENTS.md create mode 100644 shared/src/commonMain/kotlin/plus/rua/project/AGENTS.md create mode 100644 shared/src/commonMain/kotlin/plus/rua/project/ui/AGENTS.md create mode 100644 shared/src/commonTest/AGENTS.md create mode 100644 shared/src/commonTest/kotlin/plus/rua/project/AGENTS.md create mode 100644 shared/src/commonTest/kotlin/plus/rua/project/ui/AGENTS.md create mode 100644 shared/src/iosMain/AGENTS.md create mode 100644 shared/src/iosMain/kotlin/plus/rua/project/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..077efcf --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,53 @@ + + +# YaYa + +## Purpose +YaYa 是一款基于 Kotlin Multiplatform + Compose Multiplatform 构建的日历应用，同时支持 Android 和 iOS 平台。应用功能包括农历显示、节气标注、节假日信息、个人班次排期（WORK/OFF 循环）以及月/周/年三种视图切换。 + +## Key Files + +| File | Description | +|------|-------------| +| `build.gradle.kts` | 根项目 Gradle 构建设置 | +| `settings.gradle.kts` | Gradle 项目包含模块声明 | +| `gradle.properties` | Gradle 构建设置与缓存配置 | +| `gradle/libs.versions.toml` | 版本目录（依赖版本统一管理） | +| `CLAUDE.md` | 项目开发指南与架构文档 | +| `CHANGELOG.md` | 版本变更历史 | +| `DEVELOPMENT.md` | 性能追踪与开发工具说明 | +| `COMMENTS.md` | KDoc 注释规范 | + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `androidApp/` | Android 应用壳层模块（见 `androidApp/AGENTS.md`） | +| `shared/` | KMP 共享模块：所有 UI、ViewModel 和业务逻辑（见 `shared/AGENTS.md`） | +| `iosApp/` | iOS Xcode 项目（见 `iosApp/AGENTS.md`） | +| `gradle/` | Gradle Wrapper 文件 | + +## For AI Agents + +### Working In This Directory +- 所有依赖版本在 `gradle/libs.versions.toml` 中声明 +- 修改依赖后需同步 Gradle +- 构建配置在根 `build.gradle.kts` 和各模块 `build.gradle.kts` 中 + +### Testing Requirements +- 共享模块测试：`./gradlew :shared:allTests` 或 `:shared:testAndroidHostTest` +- Android 构建：`./gradlew :androidApp:assembleDebug` + +### Common Patterns +- Kotlin 包名统一为 `plus.rua.project` +- UI 组件在 `plus.rua.project.ui` 包下 +- 平台相关代码通过 `expect/actual` 机制隔离 + +## Dependencies + +### External +- Kotlin 2.3.21, Compose Multiplatform 1.11.0, Material 3 1.10.0-alpha05 +- `kotlinx-datetime` 0.8.0, `tyme4kt`（农历/节气）, `sketch` 4.4.0（GIF） +- AGP 9.2.1, compileSdk/targetSdk 37, minSdk 24 + + \ No newline at end of file diff --git a/androidApp/AGENTS.md b/androidApp/AGENTS.md new file mode 100644 index 0000000..53d4db4 --- /dev/null +++ b/androidApp/AGENTS.md @@ -0,0 +1,54 @@ + + + +# androidApp + +## Purpose +Android 应用壳层模块，仅包含入口 `MainActivity` 和最小化的 Android 平台配置。所有 UI 和业务逻辑均来自 `:shared` 模块。 + +## Key Files + +| File | Description | +|------|-------------| +| `build.gradle.kts` | Android 应用模块构建配置 | +| `src/main/kotlin/plus/rua/project/MainActivity.kt` | Android 入口 Activity，设置 `App()` Composable | +| `src/main/AndroidManifest.xml` | Android 清单，声明 MainActivity 和主题 | +| `src/main/res/values/themes.xml` | 应用主题配置（Material 3） | +| `src/main/res/values-night/themes.xml` | 夜间模式主题 | +| `src/main/res/values/strings.xml` | 应用名称字符串 | +| `src/main/assets/app_icon.png` | 应用图标资源 | +| `src/main/assets/gifs/` | GIF 动画资源目录 | + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `src/main/` | 主源码与资源（见 `src/main/AGENTS.md`） | +| `src/debug/` | Debug 构建资源（如 debug 图标） | +| `src/release/` | Release 构建资源 | + +## For AI Agents + +### Working In This Directory +- 不要在此模块添加业务逻辑；所有代码应放在 `:shared` 模块 +- 仅修改 Android 特有的配置：Manifest、主题、权限、应用图标 +- `MainActivity.kt` 应保持简洁，仅负责调用 `App()` + +### Testing Requirements +- 构建验证：`./gradlew :androidApp:assembleDebug` +- 安装验证：`./gradlew :androidApp:installDebug` + +### Common Patterns +- 使用 `enableEdgeToEdge()` 实现全屏边缘到边缘显示 +- 主题继承自 `Theme.AppCompat.DayNight.NoActionBar` + +## Dependencies + +### Internal +- `:shared` 模块 — 提供所有 UI 和逻辑 + +### External +- Android Gradle Plugin 9.2.1 +- Material 3, Compose runtime + + \ No newline at end of file diff --git a/androidApp/src/main/AGENTS.md b/androidApp/src/main/AGENTS.md new file mode 100644 index 0000000..d1951f0 --- /dev/null +++ b/androidApp/src/main/AGENTS.md @@ -0,0 +1,40 @@ + + + +# main + +## Purpose +Android 应用主 source set，包含入口 Activity、应用清单、主题资源和图标资源。 + +## Key Files + +| File | Description | +|------|-------------| +| `kotlin/plus/rua/project/MainActivity.kt` | Android 入口 Activity | +| `AndroidManifest.xml` | Android 应用清单 | +| `res/values/themes.xml` | Material 3 主题定义 | +| `res/values-night/themes.xml` | 夜间模式主题 | +| `res/values/strings.xml` | 应用名称等字符串 | +| `assets/app_icon.png` | 应用图标 | + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `kotlin/plus/rua/project/` | Kotlin 源码（见 `kotlin/plus/rua/project/AGENTS.md`） | +| `res/` | Android 资源文件（图标、主题、字符串） | +| `assets/` | 原始资产文件（GIF 等） | + +## For AI Agents + +### Working In This Directory +- 仅放置 Android 平台特有的配置和入口代码 +- 不要在此添加业务逻辑 +- 主题和颜色配置在 `res/values/` 中 + +## Dependencies + +### Internal +- `:shared` 模块 — `MainActivity` 调用 `App()` 入口 + + \ No newline at end of file diff --git a/androidApp/src/main/kotlin/plus/rua/project/AGENTS.md b/androidApp/src/main/kotlin/plus/rua/project/AGENTS.md new file mode 100644 index 0000000..6d7f6ee --- /dev/null +++ b/androidApp/src/main/kotlin/plus/rua/project/AGENTS.md @@ -0,0 +1,29 @@ + + + +# project + +## Purpose +Android 应用入口源码目录，仅包含 `MainActivity.kt`。 + +## Key Files + +| File | Description | +|------|-------------| +| `MainActivity.kt` | Android 入口 Activity，继承 `ComponentActivity`，调用 `setContent { App() }` | + +## Subdirectories +无 + +## For AI Agents + +### Working In This Directory +- `MainActivity.kt` 应保持极简，不要添加额外逻辑 +- 所有 UI 和业务逻辑在 `:shared` 模块中 + +## Dependencies + +### Internal +- `shared/src/commonMain/kotlin/plus/rua/project/App.kt` — `App()` Composable 入口 + + \ No newline at end of file diff --git a/iosApp/AGENTS.md b/iosApp/AGENTS.md new file mode 100644 index 0000000..3f7782f --- /dev/null +++ b/iosApp/AGENTS.md @@ -0,0 +1,49 @@ + + + +# iosApp + +## Purpose +iOS 应用入口，Xcode 项目结构。使用 SwiftUI 的 `ComposeUIViewController` 承载共享模块中的 Compose UI，共享模块通过 CocoaPods/SPM 集成为 framework。 + +## Key Files + +| File | Description | +|------|-------------| +| `iosApp.xcodeproj/project.pbxproj` | Xcode 项目配置 | +| `iosApp/iOSApp.swift` | iOS 应用入口（`@main App`） | +| `iosApp/ContentView.swift` | SwiftUI 视图，嵌入 `ComposeUIViewController` | +| `iosApp/Info.plist` | iOS 应用信息配置 | +| `Configuration/Config.xcconfig` | Xcode 构建设置 | + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `iosApp/` | Swift 源码和资源（见 `iosApp/iosApp/AGENTS.md`） | +| `Configuration/` | Xcode 构建设置文件 | + +## For AI Agents + +### Working In This Directory +- 不要在此目录添加业务逻辑；所有逻辑在 `:shared` 模块 +- 首次打开 Xcode 前需运行 `./gradlew :shared:generateDummyFramework` +- 修改 `shared` 后需重新生成 framework + +### Testing Requirements +- 打开 `iosApp/iosApp.xcworkspace` 在 Xcode 中运行 +- iOS 测试通过 Xcode 执行 + +### Common Patterns +- `ContentView` 使用 `UIViewControllerRepresentable` 包装 `ComposeUIViewController` +- `MainViewController` 工厂在 `shared/src/iosMain/` 中定义 + +## Dependencies + +### Internal +- `:shared` 模块 — 作为 iOS framework 集成 + +### External +- SwiftUI, UIKit + + \ No newline at end of file diff --git a/iosApp/iosApp/AGENTS.md b/iosApp/iosApp/AGENTS.md new file mode 100644 index 0000000..e4676f1 --- /dev/null +++ b/iosApp/iosApp/AGENTS.md @@ -0,0 +1,36 @@ + + + +# iosApp + +## Purpose +iOS 应用的 Swift 源码和资源目录，包含 SwiftUI 入口和 Compose 嵌入视图。 + +## Key Files + +| File | Description | +|------|-------------| +| `iOSApp.swift` | iOS 应用入口，`@main struct iOSApp: App` | +| `ContentView.swift` | SwiftUI 视图，通过 `UIViewControllerRepresentable` 嵌入 Compose | +| `Info.plist` | iOS 应用配置 | +| `Assets.xcassets/` | iOS 应用图标和颜色资源 | + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `Assets.xcassets/` | iOS 图标和颜色资源 | +| `Preview Content/` | Xcode 预览资源 | + +## For AI Agents + +### Working In This Directory +- 不要在此添加业务逻辑 +- `ContentView.swift` 中的 `MainViewController()` 来自 `:shared` 模块的 iOS 工厂 + +## Dependencies + +### Internal +- `:shared` 模块 — 通过 `MainViewController()` 提供 Compose UI + + \ No newline at end of file diff --git a/shared/AGENTS.md b/shared/AGENTS.md new file mode 100644 index 0000000..b478f04 --- /dev/null +++ b/shared/AGENTS.md @@ -0,0 +1,49 @@ + + + +# shared + +## Purpose +Kotlin Multiplatform 共享模块，包含所有 Compose UI、ViewModel 和业务逻辑。通过 `expect/actual` 机制为 Android 和 iOS 提供平台特定实现。这是项目的核心模块。 + +## Key Files + +| File | Description | +|------|-------------| +| `build.gradle.kts` | 共享模块构建配置（KMP 插件设置、source sets、依赖） | + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `src/androidMain/` | Android 平台特定实现（见 `src/androidMain/AGENTS.md`） | +| `src/commonMain/` | 所有 Compose UI、ViewModel 和业务逻辑（见 `src/commonMain/AGENTS.md`） | +| `src/commonTest/` | 共享测试套件（见 `src/commonTest/AGENTS.md`） | +| `src/iosMain/` | iOS 平台特定实现（见 `src/iosMain/AGENTS.md`） | + +## For AI Agents + +### Working In This Directory +- 所有功能代码应放在 `commonMain` 中以跨平台复用 +- 仅在 `androidMain` / `iosMain` 中放置平台特有实现 +- 修改 `commonMain` 后需运行 `:shared:allTests` 验证 + +### Testing Requirements +- 全部测试：`./gradlew :shared:allTests` +- Android 主机测试：`./gradlew :shared:testAndroidHostTest` +- 单类测试：`./gradlew :shared:testAndroidHostTest --tests "ClassName"` + +### Common Patterns +- `expect` 声明在 `commonMain`，`actual` 实现在平台 source set +- Compose 资源放在 `commonMain/composeResources/` 下 +- 包名：`plus.rua.project`（逻辑层）、`plus.rua.project.ui`（UI 层） + +## Dependencies + +### External +- Compose Multiplatform 1.11.0, Material 3 1.10.0-alpha05 +- `kotlinx-datetime` 0.8.0, `kotlinx-coroutines` +- `tyme4kt`（农历/节气）, `sketch` 4.4.0（GIF 显示） +- `molecule`（测试用） + + \ No newline at end of file diff --git a/shared/src/androidMain/AGENTS.md b/shared/src/androidMain/AGENTS.md new file mode 100644 index 0000000..674fa5c --- /dev/null +++ b/shared/src/androidMain/AGENTS.md @@ -0,0 +1,37 @@ + + + +# androidMain + +## Purpose +Android 平台特定实现 source set，包含 `expect/actual` 的 Android 端实现和预览工具。 + +## Key Files + +| File | Description | +|------|-------------| +| `kotlin/plus/rua/project/ComposeTrace.android.kt` | `composeTraceBeginSection` / `composeTraceEndSection` 的 Android 实现（路由到 `android.os.Trace`） | +| `kotlin/plus/rua/project/Platform.android.kt` | `Platform` 接口的 Android 实现 | + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `kotlin/plus/rua/project/` | Android 平台实现源码（见 `kotlin/plus/rua/project/AGENTS.md`） | + +## For AI Agents + +### Working In This Directory +- 仅放置 `commonMain` 中 `expect` 声明的 Android `actual` 实现 +- 不要在此添加业务逻辑 + +## Dependencies + +### Internal +- `shared/src/commonMain/kotlin/plus/rua/project/ComposeTrace.kt` — expect 声明 +- `shared/src/commonMain/kotlin/plus/rua/project/Platform.kt` — expect 声明 + +### External +- `android.os.Trace` + + diff --git a/shared/src/androidMain/kotlin/plus/rua/project/AGENTS.md b/shared/src/androidMain/kotlin/plus/rua/project/AGENTS.md new file mode 100644 index 0000000..d9e2a5f --- /dev/null +++ b/shared/src/androidMain/kotlin/plus/rua/project/AGENTS.md @@ -0,0 +1,25 @@ + + + +# project + +## Purpose +Android 平台特定实现源码目录。 + +## Key Files + +| File | Description | +|------|-------------| +| `ComposeTrace.android.kt` | Trace 标记的 Android 实现 | +| `Platform.android.kt` | 平台接口实现 | + +## Subdirectories +无 + +## Dependencies + +### Internal +- `shared/src/commonMain/kotlin/plus/rua/project/ComposeTrace.kt` +- `shared/src/commonMain/kotlin/plus/rua/project/Platform.kt` + + diff --git a/shared/src/commonMain/AGENTS.md b/shared/src/commonMain/AGENTS.md new file mode 100644 index 0000000..d31de1f --- /dev/null +++ b/shared/src/commonMain/AGENTS.md @@ -0,0 +1,55 @@ + + + +# commonMain + +## Purpose +KMP 共享核心模块，包含所有 Compose UI、ViewModel 状态管理、业务逻辑和跨平台接口声明。这是 YaYa 应用的主体代码所在。 + +## Key Files + +| File | Description | +|------|-------------| +| `kotlin/plus/rua/project/App.kt` | 应用根 Composable，提供 Material 主题和导航入口 | +| `kotlin/plus/rua/project/AppInfo.kt` | 应用元数据（名称、版本、作者等） | +| `kotlin/plus/rua/project/CalendarViewModel.kt` | 日历状态管理（选中日期、展开/折叠、月/周/年视图） | +| `kotlin/plus/rua/project/ComposeTrace.kt` | `expect` 声明的 Trace 标记 API | +| `kotlin/plus/rua/project/Platform.kt` | `expect` 声明的平台接口 | +| `kotlin/plus/rua/project/ShiftPattern.kt` | 个人班次排期模型（WORK/OFF 循环） | + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `kotlin/plus/rua/project/` | 业务逻辑和根 Composable（见 `kotlin/plus/rua/project/AGENTS.md`） | +| `kotlin/plus/rua/project/ui/` | UI 组件层（见 `kotlin/plus/rua/project/ui/AGENTS.md`） | +| `composeResources/` | Compose 多平台资源（图片、文件）（见 `composeResources/AGENTS.md`） | + +## For AI Agents + +### Working In This Directory +- 所有新功能代码优先放在 `commonMain` 以保持跨平台兼容 +- 仅在需要平台 API 时使用 `expect/actual` 模式 +- `CalendarViewModel.kt` 是核心状态枢纽，修改需谨慎 + +### Testing Requirements +- 修改后运行 `./gradlew :shared:allTests` +- 状态逻辑测试在 `commonTest` 中 + +### Common Patterns +- `@Suppress("DEPRECATION")` 用于 `monthNumber` 访问时需加解释注释 +- 公共 `@Composable` 函数需要 KDoc（见 `COMMENTS.md`） +- `Modifier` 参数始终放在签名最后 +- 回调参数使用 `on` 前缀（`onDateClick`、`onMonthChanged`） +- UI 文本使用中文 + +## Dependencies + +### External +- Compose Multiplatform, Material 3 +- `kotlinx-datetime`, `kotlinx-coroutines` +- `tyme4kt`（农历/节气/节日） +- `sketch`（GIF 显示） +- `androidx-lifecycle-viewmodel-compose` + + diff --git a/shared/src/commonMain/composeResources/AGENTS.md b/shared/src/commonMain/composeResources/AGENTS.md new file mode 100644 index 0000000..e068d4f --- /dev/null +++ b/shared/src/commonMain/composeResources/AGENTS.md @@ -0,0 +1,26 @@ + + + +# composeResources + +## Purpose +Compose Multiplatform 共享资源目录，存放跨平台可访问的图片和文件资源。 + +## Key Files + +无（目录仅包含子目录） + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `drawable/` | 图片资源（图标、插图等） | +| `files/` | 原始文件资源 | + +## For AI Agents + +### Working In This Directory +- 资源通过 Compose 的 `Res` 对象访问（如 `Res.drawable.xxx`） +- 添加新资源后需重新编译以生成访问代码 + + diff --git a/shared/src/commonMain/kotlin/plus/rua/project/AGENTS.md b/shared/src/commonMain/kotlin/plus/rua/project/AGENTS.md new file mode 100644 index 0000000..d4ed603 --- /dev/null +++ b/shared/src/commonMain/kotlin/plus/rua/project/AGENTS.md @@ -0,0 +1,47 @@ + + + +# project + +## Purpose +共享模块的业务逻辑层，包含根 Composable、ViewModel、平台接口和班次模型。 + +## Key Files + +| File | Description | +|------|-------------| +| `App.kt` | 应用根 Composable，设置 Material 3 主题，管理月/年视图切换和关于页面导航 | +| `AppInfo.kt` | 应用信息常量：名称、版本号、构建日期、作者、仓库地址、许可证 | +| `CalendarViewModel.kt` | 日历核心状态管理：选中日期、折叠状态、月/周/年模式、ISO 周数计算 | +| `ComposeTrace.kt` | `expect` 声明的 Trace 标记 API（Android 实现用 Systrace，iOS no-op） | +| `Platform.kt` | `expect` 声明的平台接口 | +| `ShiftPattern.kt` | 个人班次排期模型：基于锚定日期和周期长度的 WORK/OFF 状态计算 | + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `ui/` | 所有 UI 组件（见 `ui/AGENTS.md`） | + +## For AI Agents + +### Working In This Directory +- `CalendarViewModel.kt` 是核心状态枢纽，包含 `selectedDate`、`isCollapsed`、`isYearView` 等 StateFlow +- `ShiftPattern` 使用模运算：`(date - anchorDate) mod cycle.size` +- 修改状态逻辑后务必运行 `commonTest` 中的测试 + +### Testing Requirements +- `ShiftPatternTest` — 班次计算验证 +- `CalendarViewModelTest` — ViewModel 状态流验证 +- `CalendarViewModelStateTest` — 状态转换验证 + +## Dependencies + +### Internal +- `ui/` 目录 — UI 组件消费 ViewModel 状态 + +### External +- `kotlinx-datetime`, `kotlinx-coroutines` +- `tyme4kt`（农历日期转换） + + diff --git a/shared/src/commonMain/kotlin/plus/rua/project/ui/AGENTS.md b/shared/src/commonMain/kotlin/plus/rua/project/ui/AGENTS.md new file mode 100644 index 0000000..53b8cc0 --- /dev/null +++ b/shared/src/commonMain/kotlin/plus/rua/project/ui/AGENTS.md @@ -0,0 +1,61 @@ + + + +# ui + +## Purpose +日历应用的所有 UI 组件层，基于 Compose Multiplatform + Material 3 构建。包含月视图、周视图、年视图、底部卡片、日期单元格、顶部标题栏以及关于/许可证页面。 + +## Key Files + +| File | Description | +|------|-------------| +| `CalendarMonthView.kt` | 月视图主屏幕：组合 MonthHeader + WeekdayHeader + CalendarPager + BottomCard，管理折叠/展开状态 | +| `CalendarMonthPage.kt` | 单月页面：6×7 日期网格，带选中日期高亮和非选中周压缩动画 | +| `CalendarPager.kt` | 月视图水平翻页器：`Int.MAX_VALUE` 页，映射到 yearMonth | +| `WeekPager.kt` | 周视图水平翻页器：折叠状态下替代 CalendarPager，单周分页 | +| `YearGridView.kt` | 年视图：4×3 迷你月网格，支持年份导航 | +| `MonthHeader.kt` | 月视图标题栏：显示年份月份 + ISO 周数 | +| `WeekdayHeader.kt` | 固定星期标题行：「一二三四五六日」 | +| `DayCell.kt` | 单个日期单元格：支持选中/今天/班次状态样式 | +| `BottomCard.kt` | 底部卡片：拖拽手柄，驱动折叠/展开手势，显示农历、节气、节假日和班次状态 | +| `AboutScreen.kt` | 关于页面：应用信息、开源许可入口 | +| `LicensesScreen.kt` | 许可证列表页面 | +| `Licenses.kt` | 许可证数据（依赖项名称 + 许可证文本） | +| `AnimatedGif.kt` | GIF 动画显示组件（基于 sketch） | +| `CalendarUtils.kt` | 日历工具：pager 常量、页码↔日期转换算法 | + +## Subdirectories +无 + +## For AI Agents + +### Working In This Directory +- 新增 UI 组件保持 `Modifier` 参数最后 +- 公共 `@Composable` 需要 KDoc（见 `COMMENTS.md`） +- 所有 UI 文本使用中文 +- `CalendarMonthView` 是顶层屏幕组件，修改前理解折叠动画和 pager 交互 + +### Testing Requirements +- `CalendarUtilsTest` — 页码与日期转换验证 +- `CalendarUtilsExtraTest` — 边界情况测试 + +### Common Patterns +- Pager 使用 `Int.MAX_VALUE` 页，中心点为 `Int.MAX_VALUE / 2` +- 折叠动画通过 `collapseProgress`（0f=月视图, 1f=周视图）驱动 +- `WeekPager` 仅在完全折叠时替换 `CalendarPager` +- 日历网格为 6 行 × 7 列（ISO 周，周一为起始） + +## Dependencies + +### Internal +- `shared/src/commonMain/kotlin/plus/rua/project/CalendarViewModel.kt` — 状态源 +- `shared/src/commonMain/kotlin/plus/rua/project/ShiftPattern.kt` — 班次数据 + +### External +- Compose Multiplatform, Material 3 +- `kotlinx-datetime` +- `tyme4kt`（农历、节气、节日） +- `sketch`（GIF） + + diff --git a/shared/src/commonTest/AGENTS.md b/shared/src/commonTest/AGENTS.md new file mode 100644 index 0000000..8898aaa --- /dev/null +++ b/shared/src/commonTest/AGENTS.md @@ -0,0 +1,34 @@ + + + +# commonTest + +## Purpose +共享模块的单元测试 source set，包含 ViewModel、班次模型和日历工具函数的测试。 + +## Key Files + +无（目录仅包含子目录） + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `kotlin/plus/rua/project/` | 核心逻辑测试（见 `kotlin/plus/rua/project/AGENTS.md`） | +| `kotlin/plus/rua/project/ui/` | UI 工具函数测试（见 `kotlin/plus/rua/project/ui/AGENTS.md`） | + +## For AI Agents + +### Working In This Directory +- 测试使用 `kotlin.test` 和 molecule（Turbine）进行状态流断言 +- 新增测试后运行 `./gradlew :shared:allTests` +- 测试类名遵循 `*Test.kt` 约定 + +## Dependencies + +### External +- `kotlin-test` +- `kotlinx-coroutines-test` +- `molecule`（Turbine 风格的状态流测试） + + diff --git a/shared/src/commonTest/kotlin/plus/rua/project/AGENTS.md b/shared/src/commonTest/kotlin/plus/rua/project/AGENTS.md new file mode 100644 index 0000000..aec970d --- /dev/null +++ b/shared/src/commonTest/kotlin/plus/rua/project/AGENTS.md @@ -0,0 +1,35 @@ + + + +# project + +## Purpose +核心逻辑层测试，覆盖 ViewModel 状态管理和班次模型计算。 + +## Key Files + +| File | Description | +|------|-------------| +| `ShiftPatternTest.kt` | `ShiftPattern` 班次状态计算测试 | +| `CalendarViewModelTest.kt` | `CalendarViewModel` 状态流和行为测试 | +| `CalendarViewModelStateTest.kt` | ViewModel 状态转换边界测试 | + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `ui/` | UI 工具函数测试（见 `ui/AGENTS.md`） | + +## For AI Agents + +### Working In This Directory +- 修改 `CalendarViewModel` 或 `ShiftPattern` 后应更新对应测试 +- 测试使用 molecule 进行状态流断言 + +## Dependencies + +### Internal +- `shared/src/commonMain/kotlin/plus/rua/project/ShiftPattern.kt` +- `shared/src/commonMain/kotlin/plus/rua/project/CalendarViewModel.kt` + + diff --git a/shared/src/commonTest/kotlin/plus/rua/project/ui/AGENTS.md b/shared/src/commonTest/kotlin/plus/rua/project/ui/AGENTS.md new file mode 100644 index 0000000..6f98d29 --- /dev/null +++ b/shared/src/commonTest/kotlin/plus/rua/project/ui/AGENTS.md @@ -0,0 +1,30 @@ + + + +# ui + +## Purpose +UI 工具函数测试，覆盖日历工具类 `CalendarUtils` 的日期转换算法。 + +## Key Files + +| File | Description | +|------|-------------| +| `CalendarUtilsTest.kt` | `CalendarUtils` 核心函数测试：页码↔年月、周起始计算 | +| `CalendarUtilsExtraTest.kt` | `CalendarUtils` 边界情况和额外场景测试 | + +## Subdirectories +无 + +## For AI Agents + +### Working In This Directory +- 修改 `CalendarUtils.kt` 中的转换算法后应更新测试 +- 测试覆盖 `pageToYearMonth`、`yearMonthToPage`、`pageToWeekMonday` 等函数 + +## Dependencies + +### Internal +- `shared/src/commonMain/kotlin/plus/rua/project/ui/CalendarUtils.kt` + + diff --git a/shared/src/iosMain/AGENTS.md b/shared/src/iosMain/AGENTS.md new file mode 100644 index 0000000..7689d81 --- /dev/null +++ b/shared/src/iosMain/AGENTS.md @@ -0,0 +1,39 @@ + + + +# iosMain + +## Purpose +iOS 平台特定实现 source set，包含 `ComposeUIViewController` 工厂和 `expect/actual` 的 iOS 端实现。 + +## Key Files + +| File | Description | +|------|-------------| +| `kotlin/plus/rua/project/MainViewController.kt` | `ComposeUIViewController` 工厂函数，iOS 应用通过此入口加载 Compose UI | +| `kotlin/plus/rua/project/ComposeTrace.ios.kt` | Trace 标记的 iOS 实现（no-op） | +| `kotlin/plus/rua/project/Platform.ios.kt` | `Platform` 接口的 iOS 实现 | + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `kotlin/plus/rua/project/` | iOS 平台实现源码（见 `kotlin/plus/rua/project/AGENTS.md`） | + +## For AI Agents + +### Working In This Directory +- 仅放置 `commonMain` 中 `expect` 声明的 iOS `actual` 实现 +- `MainViewController.kt` 是 iOS 侧的 Compose 入口，保持简洁 + +## Dependencies + +### Internal +- `shared/src/commonMain/kotlin/plus/rua/project/App.kt` — Compose 根界面 +- `shared/src/commonMain/kotlin/plus/rua/project/ComposeTrace.kt` — expect 声明 +- `shared/src/commonMain/kotlin/plus/rua/project/Platform.kt` — expect 声明 + +### External +- `platform.UIKit` + + diff --git a/shared/src/iosMain/kotlin/plus/rua/project/AGENTS.md b/shared/src/iosMain/kotlin/plus/rua/project/AGENTS.md new file mode 100644 index 0000000..e47b679 --- /dev/null +++ b/shared/src/iosMain/kotlin/plus/rua/project/AGENTS.md @@ -0,0 +1,27 @@ + + + +# project + +## Purpose +iOS 平台特定实现源码目录。 + +## Key Files + +| File | Description | +|------|-------------| +| `MainViewController.kt` | `ComposeUIViewController` 工厂，iOS 应用入口 | +| `ComposeTrace.ios.kt` | Trace 标记的 iOS no-op 实现 | +| `Platform.ios.kt` | 平台接口实现 | + +## Subdirectories +无 + +## Dependencies + +### Internal +- `shared/src/commonMain/kotlin/plus/rua/project/App.kt` +- `shared/src/commonMain/kotlin/plus/rua/project/ComposeTrace.kt` +- `shared/src/commonMain/kotlin/plus/rua/project/Platform.kt` + +