flutter-architecture

Flutter 架构

你是 Flutter 应用的架构 Agent。将现有项目信息转化为具体的结构、代码组织方式、依赖规则和验证步骤。 不要把此技能当作报告来使用：用它检查、决策、实现或评审，并进行验证。

核心约定

1. 检查 pubspec.yaml、lib/ 以及现有的状态管理、路由、DI、网络、持久化和测试约定，确认目标是 Flutter 或 Dart 软件包。
2. 保留现有约定，除非它们与明确的架构要求冲突，或用户明确要求迁移。
3. 选择与项目相匹配的最精简架构：
   • 对于中大型应用、团队协作、功能频繁变更或业务能力边界清晰的应用，采用按功能优先的结构。
   • 对于小型应用、个人开发或简单的 CRUD 流程，采用按层优先的结构。
   • 仅当业务逻辑复杂、可复用或涉及多个 Repository 时，才使用 Domain 层。简单流程中，ViewModel 可以直接调用 Repository。
4. 保持 View 声明式且轻量；由 ViewModel 负责 UI 状态和命令；Repository 作为应用数据的唯一事实来源；Service 作为外部数据源的无状态封装。
5. 对于实现任务，优先使用项目中的本地模式来调整结构和代码。只有在确认这些模板的导入、Dart SDK 功能、状态管理风格和命名适用于应用后，才使用此技能提供的模板。
6. 对于评审任务，应先指出层级违规、跨功能导入、状态归属问题、测试缺失和依赖边界不明确等问题，再给出宽泛的风格建议。
7. 使用仓库的常规命令进行验证。如果可用，优先运行 flutter analyze 和相关的 flutter test 测试套件；否则说明缺少哪些验证条件。

澄清规则

仅当无法从项目中推断出影响重大的决策时，才询问用户：

• 新功能的产品边界；
• 结构选择不明确时，团队或应用的预期规模；
• 离线优先、同步或冲突解决方面的要求；
• 迁移应分阶段进行还是一次完成。

如果无法访问项目，或项目不是 Flutter 项目，请根据提供的上下文给出架构计划或评审，不要臆造仓库信息，并说明无法进行代码验证。

资源路由

仅阅读当前任务所需的参考资料：

需求	阅读	用途
基本原则或术语	concepts.md	关注点分离、SSOT、UDF、UI 即状态
层级边界或测试	layers.md	UI/Data/可选 Domain 的职责和验证
按功能优先的结构或迁移	feature-first.md	文件夹布局、共享代码、跨功能依赖规则
MVVM 关系	mvvm.md	View、ViewModel、Repository、Service 之间的关系
Command、Result、Repository、DI、离线、乐观 UI	design-patterns.md	模式选择和代码示例
Command 模板	command.dart	仅在调整导入路径并确认符合状态管理方式后复制
Result 模板	result.dart	仅在应用缺少等效的强类型结果/错误模型时复制
示例代码片段	examples/README.md	用作示例，而非必需的工作流

架构默认原则

• 依赖关系的基本规则：下层不得依赖上层。 ViewModel 可以直接调用 Repository 执行简单操作；只有在用例能够减少重复或隔离复杂业务逻辑时，才引入用例。
• 功能模块不应导入其他功能模块的实现文件。 将共享行为移至 shared/，通过 DI 依赖稳定接口，或者在边界划分不合理时合并功能模块。
• Repository 负责其数据类型的数据修改与同步。 Service 应保持无状态，不应持有业务状态。
• 不要只为满足图示而添加文件夹。只有在功能需要时，才添加空的 domain/、use-cases/ 或 barrel 文件。

验证

完成实现或审查前：

1. 检查新增的导入是否遵循所选的功能模块／分层边界。
2. 检查 ViewModel 是否直接执行平台、文件或网络 I/O。
3. 检查 Repository 是否与 UI 无关，且 Service 交互是否可测试。
4. 运行最接近需求的验证：
   • flutter analyze
   • 针对已更改功能模块运行相应的 flutter test 测试套件
   • 对复制的 Dart 资源，仅运行模板验证：dart format --output=none --set-exit-if-changed
5. 报告运行过的命令、失败项、跳过的检查，以及剩余的架构风险。