flutter-ai-harness: Instructions file for Claude Code

Flutter AI Harness 项目契约

本文件是仓库的权威工程契约。修改代码或文档前必须先读。其他工具入口可以摘要本文件，但不得覆盖本文件的规则。

项目目标

本仓库是一套 AI 原生工程 Harness，也是一套有明确架构取向的 Flutter 混合应用工作区。AI Agent 和开发者共同使用相同的架构规则、任务产物、执行命令与质量门禁。

仓库分两个阶段建设：

1. 建立中立的 Harness 和仓库边界。
2. 通过 Harness 设计并实现全新 Demo，让任务卡、Review、App 文档和项目 Memory 从真实工作中自然产生。

不得从其他应用复制业务代码、凭据、历史任务或私有依赖到本仓库。

技术栈

Flutter

• Flutter 3.41.9 / Dart 3.11
• 状态管理与轻量 DI：GetX 精简版 fork（公开 Git 源，固定 Commit）
• 路由：go_router ^15.1.2
• 网络：dio ^5.7.0 + Protocol Buffers ^6.0.0
• 本地存储：drift ^2.20.0 + flutter_secure_storage ^9.2.2
• 不可变数据：Freezed ^3.0.0
• JSON 序列化：json_serializable ^6.9.0
• 测试：flutter_test + mocktail ^1.0.4 + integration_test
• Monorepo 编排：Melos

原生平台

• Android：Kotlin / Gradle
• iOS：Swift / Xcode / CocoaPods

Demo 固定采用本节技术栈，不在产品设计或任务拆解阶段重新选型。依赖在首个真实消费者出现时加入所属 Package 并锁定兼容版本，不为填充清单引入未使用依赖。

仓库结构

app/
├── apps/demo/
└── packages/
    ├── app_core/
    ├── app_data/
    ├── app_ui/
    ├── app_features/
    ├── app_media/
    └── app_media_capture_bridge/

工作区随 Demo 实施逐步形成。不得为了填充目录而预先创建没有真实需求的业务抽象。

架构不变量

1. Domain Entity 或明确的 Value Object 是数据适配层进入业务层以及业务公共 API 之间唯一允许传递的数据类型。

2. app_core 只能定义并处理传输中立的 Request、Response、Failure 和不透明 Payload，不得定义、import 或解析具体 Fixture Payload、Proto Message 或数据库 Row；这些具体类型及其解析必须留在 app_data，不得进入 Feature、Controller 或 UI。MediaResourceId 是唯一批准的聚焦基础设施 ID 例外：它只提供传输中立的闭合格式校验，不包含路径、URI、Native handle、文件行为或业务规则；Store、Resolver、媒体 metadata 和预览 API 不得继续下沉到 app_core。

3. 每个包只定义自己需要的接口，不建立中央万能契约包。

4. 依赖方向保持单向。下图中 A -> B 表示 Package A 可以 import Package B：

   apps/demo -> app_features, app_data, app_ui
   app_features -> app_data, app_core, app_ui, app_media, app_media_capture_bridge
   app_media -> app_core, app_ui
   app_media_capture_bridge -> 不依赖其他 Workspace Package
   app_data -> app_core
   app_core / app_ui -> 不依赖其他 Workspace Package
   

5. Feature 不得 import 其他 Feature 的内部实现。

6. 业务抽象接口放在 app_features/lib/api/，具体实现放在对应 feature_xxx/api/；跨 Feature 交互只依赖抽象接口，并由统一 Registry 绑定实现。

7. app_data 提供 Domain Entity、LocalDataSource、确定性 Fixture 及其 Transport，以及协议或持久化出现后的 Mapper/Adapter；不得承载页面、Controller 或 Feature 业务编排。

8. 壳工程只负责模块与回调装配，不得 import Feature 实现类。

9. Controller 通过构造函数接收必需 API。服务定位器只允许出现在装配点或显式全局服务中。

10. 只有在确实降低复杂度或保护真实边界时才新增抽象。

11. Native Consumer 直接依赖对应 Native Module；Flutter Consumer 通过聚焦的 Dart Client 和 Android/iOS Bridge Adapter 委托同一 Module。Host 只负责装配和注册，Native Module 不依赖 Flutter。