# Frontend Architecture 模板

> 目标: 在前端实现前声明页面、feature、组件、状态、API、样式和测试边界，防止把整页逻辑堆到一个组件里。

## 1. 基本信息

- Feature ID:
- 页面 / 模块:
- 关联需求:
- 关联路由:
- 目标质量等级: P0 / P1 / P2 / P3
- 设计真相源:
- Contract 真相源:
- 最后更新:

## 2. 架构目标

- 本次前端架构要解决的问题:
- 需要支持的用户流程:
- 本期不处理的能力:
- 主要风险:

## 3. 分层与目录

| 层级 | 建议路径 | 职责 | 禁止事项 |
| --- | --- | --- | --- |
| Page / Route | `app/...` / `pages/...` | 路由、布局组合、数据预取入口 | 写业务细节和 UI primitive |
| Feature | `features/<domain>/` | 业务组件、业务 hooks、权限、字段映射 | 放跨业务通用组件 |
| UI primitives | `packages/ui/` / `components/ui/` | 无业务语义的基础组件 | 依赖 API、权限或业务枚举 |
| Data table / List | `packages/ui/data-table/` 或 feature 内 | 排序、筛选、分页、列显隐 | 混入具体业务字段文案 |
| API client | `packages/api-client/` / `features/<domain>/api/` | HTTP 调用、契约生成 client | 直接操作 UI 状态 |
| Model / Schema | `features/<domain>/model/` | 类型、枚举、校验、URL query 解析 | 把展示样式写进 schema |

## 4. 组件树

```text
<Page>
  <FeatureShell>
    <Toolbar />
    <FilterBar />
    <Content />
    <Pagination />
    <DialogOrDrawer />
  </FeatureShell>
</Page>
```

| 组件 | 层级 | 职责 | 数据输入 | 事件输出 | 可复用范围 |
| --- | --- | --- | --- | --- | --- |
| | Page / Feature / Primitive | | | | local / feature / project |

## 5. 状态管理

| 状态 | 所属层级 | 来源 | 持久化方式 | 变化事件 | 测试方式 |
| --- | --- | --- | --- | --- | --- |
| URL filters | Page / Feature | query string | URL | filter change / reset | e2e |
| Remote data | Feature | API client | cache / none | fetch / refetch | mock + e2e |
| Form state | Component | user input | local | submit / cancel | interaction |
| UI state | Component | user interaction | local | open / close | story |

规则:

- 可分享、可回退、影响查询结果的状态优先进入 URL。
- 远程数据状态不得散落在多个展示组件中。
- 表单 dirty、提交中、提交失败必须有明确状态来源。
- 权限状态必须能追溯到 PRD、auth context 或 contract。
- 同一业务条件只能有一个主状态来源；不要同时放在 URL、store、本地 state 和 form 中。
- 页面级临时 UI 状态默认留在本地，不要为了方便提升到全局 store。
- 远程数据、缓存 key、失效时机和 refetch 触发条件必须写清。

## 5.1 缓存与失效策略

| 数据 | 缓存层 | key / query 标识 | 失效触发条件 | 手动刷新入口 | 验证方式 |
| --- | --- | --- | --- | --- | --- |
| | query cache / local cache / browser storage / none | | create / update / delete / permission change / timeout | | unit / integration / e2e |

规则:

- 写操作完成后，必须明确哪些列表、详情、统计或徽标需要失效或同步更新。
- 如果存在 optimistic update、回滚或离线缓存，必须说明失败恢复策略。
- 不允许只写“自动刷新”而不写状态来源、key 或触发条件。

## 6. API 与数据边界

| UI 需求 | API / Contract | 字段 | 错误态 | 前端兜底 |
| --- | --- | --- | --- | --- |
| | | | | |

规则:

- UI 字段必须能追溯到 contract 或 PRD 数据字典。
- 展示组件不得拼接 HTTP URL 或处理响应状态码。
- API client 抛出的错误必须映射到用户可理解的错误态。
- mock 数据必须覆盖 default / empty / error / long_content / permission。
- 页面或组件中不得直接手写 `fetch/axios/baseURL/token/error` 处理逻辑，统一走项目 API client。
- 如果 contract 已生成 types / client，前端不得再手写一套重复 request/response schema。

## 7. 响应式架构

| 视口 | 结构 | 筛选策略 | 列表 / 表格策略 | 操作区策略 | 必需截图 |
| --- | --- | --- | --- | --- | --- |
| Desktop >= 1200px | | | | | |
| Tablet 768-1199px | | | | | |
| Mobile < 768px | | | | | |

规则:

- 移动端主要流程不能只依赖横向滚动。
- 表格转卡片时必须说明字段优先级。
- 操作区折叠时必须保留主操作可见或一跳可达。

## 8. 动效与可访问性

| 组件 / 场景 | 动效 | reduced motion 行为 | 焦点 / 键盘规则 | ARIA / 语义 |
| --- | --- | --- | --- | --- |
| | | | | |

规则:

- 动效只用于状态解释，不用于隐藏加载或错误。
- 弹窗、抽屉、菜单必须定义焦点进入、循环、关闭和恢复。
- 状态变化、错误和保存结果必须有屏幕阅读器可感知的反馈。

## 9. 性能预算

| 风险 | 阈值 / 预算 | 处理策略 | 验证方式 |
| --- | --- | --- | --- |
| 列表行数 | | client / server / virtualized | |
| 首屏依赖 | | lazy / split / avoid | |
| 图片 / 图标 | | optimize / sprite / lazy | |
| 动效 | | transform / opacity | |

## 10. Story 与测试矩阵

| 状态 / 场景 | Story | Interaction | E2E | Visual | A11y | Performance |
| --- | --- | --- | --- | --- | --- | --- |
| default | | | | | | |
| loading | | | | | | |
| empty | | | | | | |
| error | | | | | | |
| permission | | | | | | |
| long_content | | | | | | |
| mobile | | | | | | |

## 11. 复用决策

| 候选组件 / Hook | 复用范围 | 是否抽象 | 原因 | 约束 |
| --- | --- | --- | --- | --- |
| | local / feature / project | Yes / No | | |

抽象规则:

- 基础 primitive 可以直接进入通用层。
- 业务组件默认留在 feature 内。
- 只有当第二个真实使用场景出现或 DEV-PLAN 明确要求时，才抽项目级复用组件。
- 修改既有公共组件时，必须先列出受影响调用方、兼容策略和回归验证，不允许为单页需求直接破坏旧 props 或旧样式语义。

## 12. 完成标准

- [ ] 组件分层与目录边界已明确。
- [ ] 状态来源、持久化和事件已明确。
- [ ] API 字段和错误态已追溯到 contract 或 PRD。
- [ ] 响应式结构有 desktop / tablet / mobile 策略。
- [ ] 动效、reduced motion、键盘和可访问性规则已定义。
- [ ] Story / E2E / visual / a11y / performance 证据路径已定义。
