172 lines
3.9 KiB
Markdown
172 lines
3.9 KiB
Markdown
# 02. Layout、模块分层与状态边界
|
||
|
||
## 1. 组件层级原则
|
||
|
||
为保证长期维护，建议严格区分三层：
|
||
|
||
- Layout 层：只负责结构和容器
|
||
- Module 层：负责一个业务单元的交互和状态协调
|
||
- Component 层：负责纯展示或轻交互
|
||
|
||
页面只做组装，不应堆积大量业务逻辑。
|
||
|
||
## 2. Layout 层
|
||
|
||
Layout 层应只负责工作区结构，不直接依赖具体业务域。
|
||
|
||
建议的壳层对象包括：
|
||
|
||
- WorkspaceShell
|
||
- PrimaryRail
|
||
- SecondaryPane
|
||
- ContentViewport
|
||
- TopChromeBar
|
||
- BottomDock
|
||
- SplitPaneLayout
|
||
- SheetHost
|
||
|
||
这些对象负责：
|
||
|
||
- 左右分栏
|
||
- 顶部导航与 breadcrumb 承载
|
||
- 底部 composer 区承载
|
||
- 面板折叠与尺寸分配
|
||
- Web 响应式适配
|
||
|
||
## 3. Module 层
|
||
|
||
Module 是长期维护的关键层，承接复合业务交互。
|
||
|
||
### A. Assistant 模块
|
||
|
||
- ThreadListModule
|
||
- ThreadGroupsModule
|
||
- SessionHeaderModule
|
||
- ConversationModule
|
||
- RenderModeModule
|
||
- ConnectionStatusModule
|
||
- ComposerModule
|
||
- SessionSettingsSheetModule
|
||
|
||
### B. Focus / Favorites 模块
|
||
|
||
- FocusEntriesModule
|
||
- FocusSummaryCardModule
|
||
- FavoriteEntryManagerModule
|
||
|
||
### C. Settings 模块
|
||
|
||
- SettingsTopBarModule
|
||
- SettingsSubmissionBarModule
|
||
- SettingsTabsModule
|
||
- GatewayProfilesModule
|
||
- LlmEndpointsModule
|
||
- ExternalAcpModule
|
||
- AppearanceSettingsModule
|
||
- DiagnosticsModule
|
||
|
||
### D. Resource 模块
|
||
|
||
- TasksRegistryModule
|
||
- SkillsRegistryModule
|
||
- NodesRegistryModule
|
||
- SecretsRegistryModule
|
||
- LlmApiRegistryModule
|
||
|
||
一个 module 应该负责“完整业务语义”，而不是只拼几个 UI 组件。
|
||
|
||
## 4. Component 层
|
||
|
||
Component 层应尽可能保持纯展示和可复用。
|
||
|
||
建议沉淀为通用组件的对象包括：
|
||
|
||
- SurfaceCard
|
||
- SectionTabs
|
||
- SearchField
|
||
- StatusChip
|
||
- ConnectionBadge
|
||
- ActionChip
|
||
- EmptyState
|
||
- ErrorBanner
|
||
- ToolbarButton
|
||
- DropdownField
|
||
- ToggleField
|
||
- SummaryStatChip
|
||
- BottomSheetPanel
|
||
- ResizeHandle
|
||
|
||
这些组件不应知道线程、设置页、技能列表等具体业务语义。
|
||
|
||
## 5. 状态边界
|
||
|
||
虽然这里主要区分“全局状态”和“局部状态”，但在 Flutter Web 中还应单独重视路由状态。
|
||
|
||
### A. 全局状态
|
||
|
||
以下状态建议由 app-level controller / store 持有：
|
||
|
||
- 当前 workspace / 用户上下文
|
||
- 当前主题、语言
|
||
- feature flags
|
||
- 全局导航结构
|
||
- Focus / Favorites 入口列表
|
||
- 资源目录数据（任务、技能、节点、密钥、LLM API）
|
||
- Gateway profile 列表
|
||
- provider / model catalog
|
||
- 线程索引数据
|
||
- 全局通知 / 错误中心
|
||
|
||
### B. 路由状态
|
||
|
||
以下状态更适合映射到 URL / 路由层：
|
||
|
||
- 当前页面
|
||
- 当前线程 id
|
||
- 当前 Settings tab
|
||
- 当前 Integrations sub-tab
|
||
- 当前详情对象 id
|
||
- 左侧 pane 当前模式
|
||
- 可分享的搜索条件
|
||
|
||
这些状态如果仅放在内存里，会削弱 Flutter Web 的刷新恢复能力和链接可分享能力。
|
||
|
||
### C. 局部状态
|
||
|
||
以下状态建议严格留在模块或组件内部：
|
||
|
||
- side pane 折叠/展开
|
||
- split pane 临时尺寸
|
||
- bottom sheet 是否打开
|
||
- dropdown 是否展开
|
||
- 输入框内容
|
||
- 当前附件选择结果
|
||
- 卡片折叠状态
|
||
- 某个按钮 loading
|
||
- 某个 form 的未提交草稿
|
||
- hover / pressed / focused 视觉状态
|
||
- 局部滚动位置
|
||
|
||
## 6. 一条可执行的状态规则
|
||
|
||
建议全团队统一以下判断标准：
|
||
|
||
- 会影响多个页面或多个模块的，进入全局状态
|
||
- 需要刷新恢复或支持深链的，进入路由状态
|
||
- 只影响单个模块交互的，保持局部状态
|
||
|
||
## 7. 必须统一复用的状态机
|
||
|
||
长期维护时，最容易失控的不是 UI 样式，而是行为流。
|
||
|
||
建议优先统一以下状态机：
|
||
|
||
- Test / Save / Apply
|
||
- Connect / Connected / Error / Retry
|
||
- Thread Send / Streaming / Cancel / Complete
|
||
- Load / Empty / Error / Refresh
|
||
- Select / Attach / Remove / Oversize
|
||
- Collapse / Expand / Pin / Unpin
|
||
|
||
这些状态机一旦被各页面各写一套，后续 Assistant、Settings、Focus、资源域的交互会快速分叉。
|