FFCA Architecture 是用于 Feature-First Clean Architecture(FFCA)monorepo 的导览技能,主要帮助开发者理解并遵守该架构的结构与规则。它不重复架构约定本身;约定内容位于 ${CLAUDE_PLUGIN_ROOT}/references/ffca/ 下的文件中,技能中每一步都会指明应阅读的文件和章节。
用途与判断仓库类型:首先确认当前仓库是否为 FFCA 仓库。检测信号是存在 features/ 文件夹,且其中的包遵循 {feature}_domain、{feature}_data 或 {feature}_presentation 的命名。如果仓库采用标准 VGV 分层结构(packages/ 下含 _repository/_api_client),则不属于 FFCA,应改用 layered-architecture 技能。
代码位置决策:阅读 references/ffca/overview.md 的“The structure”一节,将工作归入 apps/、features/、shared/ 三个顶层文件夹之一。区分 feature 与 shared 包时,使用同一文件“Shared libraries”一节的两问决策规则:应用组合的业务能力放入 features/;可以发布到 pub.dev 且陌生人无需修改即可使用的放入 shared/。边界情况可参考该节组件表。
功能所需层:阅读 overview.md 的“Headless features”和“Presentation-only features”两节。没有界面的功能只保留 domain 与 data,之后可再增加 presentation 包而无需结构变更;只把其他功能的 domain 组合成界面的功能只有 presentation 包。命名任何包之前,阅读 references/ffca/project_structure.md 的“Naming conventions”一节,名称由 hook 机械校验,不可随意更改。文件放置则参考同文件“Layer subfolders”一节中的各层文件夹映射,如 models/、repositories/、use_cases/、data_sources/、dtos/、mappers/,以及按屏幕组织的 bloc/、views/、module 布局。
术语约定:use_cases/ 中的类应命名为 Command(会变更状态,方法为 execute)和 Query(只读,方法为 get 或 watch),讨论和命名时使用这两个词。文件夹仍保留 use_cases/ 传统名称以匹配其他整洁架构项目,但不对类使用“use case”一词。参见 references/ffca/domain.md 的“Business rules”一节。
依赖规则:在 pubspec 中添加对其他工作区包的依赖前,阅读 project_structure.md 的“Dependency rules”一节,该节表格即完整策略,也是 scripts/validate_layers.dart 的实现依据。hook 会在每次编辑 pubspec 时执行规则,违规会阻止编辑。方向为:apps 依赖 features 和 shared;shared 只依赖外部包;domain 层导入其他 domain 与 shared,不导入其他内容;data 层导入自身 domain、其他 domain 与 shared;presentation 层导入 domain 与其他 presentation 包,绝不导入 data 层。另有两个重要约束:任何 presentation 包不得依赖任何 _data 包(包括自身);任何 shared 包不得依赖 feature。
延迟加载:应用可用 deferred as import 按需加载功能,用于拆分 Web 包并支持 Android deferred components。前提是该延迟加载的包不能同时通过非延迟路径从应用可达,否则拆分无效且不会产生报错或分析器警告。该规则视为硬性要求,详见 project_structure.md 的“Deferred loading”一节。仅发布 iOS 和 Android 时,AOT 快照包含整个程序,此规则仅作信息参考。
应拒绝的反模式:表现层导入数据层(应依赖 domain 并通过 repository 接口访问);shared 包依赖 feature;业务逻辑放入 shared/(易变且应用特定的逻辑应属于 feature domain);ui_kit 中需要 repository 的 widget(shared 包只能依赖外部包,无法编译,应拆分:展示性视图放入 ui_kit,有状态部分留在所属 feature)。
后续指引:创建或扩展功能使用 ffca-feature 技能;路由、导航或深链接使用 ffca-routing;一个功能需要另一功能的数据或 widget 使用 ffca-cross-feature;检查整个仓库健康状况使用 ffca-audit。完整结构示例可参考 mealify 参考实现。