swift-ui-architect

SwiftUI Modular MVVM-C Architecture

面向诊所类 SwiftUI 应用的约束式架构。本技能遵循 iOS 26 / Swift 6.2 诊所架构：在本地 SPM 包中采用模块化 MVVM-C，在 App 目标中放置具体协调器和路由外壳，使用纯净的 Domain 协议，并将 Data 作为唯一的 I/O 层。

Mandated Architecture Stack

┌───────────────────────────────────────────────────────────────┐
│ App target: DependencyContainer, Coordinators, Route Shells   │
├───────────────┬───────────────┬───────────────┬──────────────┤
│ Feature* SPM  │ Feature* SPM  │ Feature* SPM  │ Feature* SPM │
│ View + VM     │ View + VM     │ View + VM     │ View + VM    │
├───────────────────────────────────────────────────────────────┤
│ Data SPM: repository impls, remote/local, retry, sync queue   │
├───────────────────────────────────────────────────────────────┤
│ Domain SPM: models, repository protocols, coordinator protocols│
│ and ErrorRouting/AppError                                      │
├───────────────────────────────────────────────────────────────┤
│ Shared SPMs: DesignSystem, SharedKit                           │
└───────────────────────────────────────────────────────────────┘

依赖规则：Feature 模块只能导入 Domain + DesignSystem。Feature 绝不能导入 Data 或其他 Feature。App 目标是唯一的汇合点。

Clinic Architecture Contract (iOS 26 / Swift 6.2)

本技能中的所有指导均基于诊所模块化 MVVM-C 架构：

• Feature 模块只能导入 Domain + DesignSystem（绝不导入 Data，也绝不导入同级 Feature）
• App 目标是汇合点，并负责管理 DependencyContainer、具体协调器和路由外壳的连接
• Domain 保持纯 Swift，并定义模型，以及仓库、*Coordinating、ErrorRouting 和 AppError 契约
• Data 负责 SwiftData/网络/同步/重试/后台 I/O，并实现 Domain 协议
• 读写流程默认采用过期后重新验证的读取方式和乐观排队写入
• ViewModel 直接调用仓库协议（不设默认用例/交互器层）

When to Apply

在以下情况下参考这些指南：

• 在本地 SPM 包中构建或重构 Feature 模块
• 连接协调器、路由外壳和依赖容器工厂
• 为仓库、协调器和错误路由定义 Domain 协议
• 确保网络、持久化和同步仅由 Data 负责
• 审查过期后重新验证的读取方式和乐观排队写入

Non-Negotiable Constraints (iOS 26 / Swift 6.2)

• ViewModel/协调器使用 @Observable，绝不使用 ObservableObject / @Published
• 不设专门的用例/交互器层：ViewModel 直接调用 Domain 仓库协议
• 协调器协议位于 Domain；具体协调器在 App 目标中管理 NavigationPath
• 路由外壳位于 App 目标，并负责管理 .navigationDestination 映射
• 由 AppError + ErrorRouting 驱动呈现策略；ViewModel 不硬编码全局错误 UI
• SwiftData / URLSession / 重试 / 同步队列逻辑只能放在 Data 包中

Rule Categories by Priority

优先级	类别	影响	前缀	规则
1	视图标识与差异比较	严重	diff-	6
2	状态架构	严重	state-	7
3	视图组合	高	view-	6
4	导航与协调	高	nav-	5
5	分层架构	高	layer-	6
6	依赖注入	中高	di-	4
7	列表与集合性能	中	list-	4
8	异步与数据流	中	data-	5

Quick Reference

1. View Identity & Diffing (CRITICAL)

• diff-equatable-views - 对每个 SwiftUI 视图应用 @Equatable 宏
• diff-closure-skip - 对闭包/处理器属性使用 @SkipEquatable
• diff-reference-types - 绝不存储未遵循 Equatable 的引用类型
• diff-identity-stability - 在 ForEach 中使用稳定的 O(1) 标识符
• diff-avoid-anyview - 绝不使用 AnyView — 使用 @ViewBuilder 或泛型
• diff-printchanges-debug - 使用 _printChanges() 诊断不必要的重新渲染

2. 状态架构（关键）

• state-observable-class - 所有 ViewModel 都使用 @Observable 类
• state-ownership - 自有数据使用 @State，注入的数据使用普通属性
• state-single-source - 每项状态都只有一个真实数据源
• state-scoped-observation - 利用 @Observable 的属性级跟踪
• state-binding-minimal - 仅在双向数据流中传递 @Binding
• state-environment-global - 使用 @Environment 管理应用范围内共享的依赖项
• state-no-published - 绝不使用 @Published 或 ObservableObject

3. 视图组合（高）

• view-body-complexity - view body 中最多包含 10 个节点
• view-extract-subviews - 将计算属性/辅助方法提取为独立的 View 结构体
• view-no-logic-in-body - body 中不得包含任何业务逻辑
• view-minimal-dependencies - 仅传递所需属性，不要传递整个模型
• view-viewbuilder-composition - 使用 @ViewBuilder 进行条件组合
• view-no-init-sideeffects - 绝不在 View init 中执行操作

4. 导航与协调（高）

• nav-coordinator-pattern - 每个功能都有一个负责管理 NavigationStack 的协调器
• nav-routes-enum - 将所有路由定义为 Hashable 枚举
• nav-deeplink-support - 协调器必须支持基于 URL 的深层链接
• nav-modal-sheets - 通过协调器展示模态视图，不要在视图中直接展示
• nav-no-navigationlink - 绝不使用 NavigationLink(destination:) — 使用 navigationDestination(for:)

5. 分层架构（高）

• layer-dependency-rule - Domain 层不导入任何框架
• layer-usecase-protocol - 不要添加用例层；在 ViewModel 和 repository 协议中处理编排
• layer-repository-protocol - Repository 协议位于 Domain 层，实现位于 Data 层
• layer-model-value-types - Domain 模型使用结构体，绝不使用类
• layer-no-view-repository - 视图绝不直接访问 repository；由 ViewModel 调用 repository 协议
• layer-viewmodel-boundary - ViewModel 仅公开可直接展示的状态

6. 依赖注入（中高）

• di-environment-injection - 通过 @Environment 注入由容器管理的协议依赖项
• di-protocol-abstraction - 所有注入的依赖项都必须是协议类型
• di-container-composition - 在 App target 中组合 DependencyContainer 并公开 VM 工厂
• di-mock-testing - 每个协议依赖项都必须有用于测试的 mock

7. 列表与集合性能（中）

• list-constant-viewcount - ForEach 对每个元素生成的视图数量必须恒定
• list-filter-in-model - 在 ViewModel 中筛选/排序，绝不要在 ForEach 中进行
• list-lazy-stacks - 对无界内容使用 LazyVStack/LazyHStack
• list-id-keypath - 明确提供 id keyPath — 绝不依赖隐式标识

8. 异步与数据流（中等）

• data-task-modifier - 使用 .task(id:) 作为功能数据加载的主要触发方式
• data-async-init - 切勿在 init 中执行异步操作
• data-error-loadable - 将加载状态建模为枚举，而非布尔值
• data-combine-avoid - 新代码优先使用 async/await，而非 Combine
• data-cancellation - 使用 .task 自动取消，切勿手动管理 Tasks

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息