用途
ffca-feature 是一个面向 FFCA(Flutter Feature-Centered Architecture)单仓库的功能开发工作流技能,用于从零搭建一个新功能,或在现有功能上扩展代码。它不重复讲述约定本身,而是要求先阅读插件目录下 references/ffca/ 中的相关章节,再适配 references/code_templates/ 里的代码模板。
前置检查
开始前需确认仓库确实是 FFCA 结构:存在 features/ 目录,且其中包含 {feature}_{layer} 形式的包。如果不符合,应停止并使用 layered-architecture 技能。需阅读 overview.md 的 Feature layers 一节了解分层模型,阅读 project_structure.md 的 Naming conventions 一节了解包命名(hook 会校验命名)。此外要先检查是否已有预生成的 API 客户端;若后端提供统一的 OpenAPI/Swagger 定义,可参考 faq.md 中对应条目,客户端应放在 shared/,由各功能的数据层消费。
主要能力:按依赖顺序搭建三层
每个包先用 Very Good CLI 脚手架生成(domain 和 data 用 dart_package,presentation 用 flutter_package),再填充内容,保证每层都能基于下一层编译。
-
领域层({feature}_domain,Dart 包):模型放在 models/,为带值相等性的普通 Dart 类型,不加 Model 或 Entity 后缀;仓库接口放在 repositories/,每个功能一个抽象接口类,以其自身聚合命名,功能领域不定义其他功能的仓库;Commands 和 Queries 放在 use_cases/,仅在组合多个仓库或跨 Bloc 重复同一工作时才新增,单仓库透传不需要类。命名规则为 {Verb}{Thing}Command 和 {Get,Watch}{Thing}Query,命令用 execute,查询用 get 或 watch;类和文档中不称其为 “use case”。最后添加主 barrel 文件 {feature}_domain.dart。
-
数据层({feature}_data,Dart 包):数据源放在 data_sources/,每个数据源带 dtos/ 子目录,DTO 不得逃出该包;映射器放在 mappers/,优先使用 Converter<Dto, Domain> 子类,也可用 toDomain() 扩展方法或 auto_mappr 等生成器,每个来源每个方向一个转换器;仓库实现放在 repositories/,实现领域接口,并在数据离开数据源时完成映射。最后添加主 barrel 文件 {feature}_data.dart。
-
表现层({feature}_presentation,Flutter 包):每个页面包含一个 {screen}/bloc/ 下的 Cubit(密封状态 Initial、Loading、Loaded、Error)、一个按状态切换的 {screen}/views/ 页面,以及一个负责装配依赖并暴露导航回调的 {screen}/{screen}_module.dart。模块使用 Provider 构造依赖。需为每个独立入口添加子功能 barrel,并添加主 barrel {feature}_presentation.dart。导航接线使用 ffca-routing 技能。
其它功能形态
- 无界面功能:只有领域层和数据层,没有 UI;后续需要页面时再新增 {feature}_presentation 包,不改动已有包。若数据层与特定后端绑定,可命名为 {feature}data{backend},例如 auth_data_firebase。
- 纯表现层功能:只有一个表现层包,用于把其他功能的领域组合成一个页面;目录和命名不变,仍位于 features/{name}/{name}_presentation,缺少同级包本身就是信号。
组件插槽
当页面需要展示其他功能拥有的内容时,模块可以声明一个由应用填充的插槽,而不是直接导入该功能。参数类型为可空 Widget,默认无值,并按位置命名(如 trailingAction),不要按预期组件命名(如 cartBadgeBuilder 会把另一功能重新泄漏进来)。单个模块超过两个插槽时,组合逻辑应放到应用自有的外壳中。插槽与直接导入之间的选择可使用 ffca-cross-feature 技能。
依赖与测试
添加包间依赖时遵循 project_structure.md 的 Dependency rules:data 依赖自身的 domain,presentation 依赖各 domain 而绝不依赖 data 层,二者都不依赖应用。pubspec hook 会拦截违反分层规则的修改并提示修复方式。若应用延迟导入该功能,在依赖其他功能的表现层包前需阅读 Deferred loading 一节,避免急加载边静默取消下游代码拆分。每个包都需要测试;本技能不覆盖测试机制,blocTest、mocktail 和 golden 的细节交给 vgv-ai-flutter-plugin 的测试技能。需覆盖每个仓库实现、每个 Command 和 Query、每个 Cubit(成功、失败、边界情况)。插槽默认无值的模块无需其他功能的仓库即可进行 golden 测试。
适用场景与限制
适用于遵循 FFCA 结构、以 Flutter/Dart 构建的单仓库项目。若仓库非 FFCA 结构,应改用 layered-architecture 技能。具体代码样式以引用的参考文档和模板为准,本技能本身不重述约定。