@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/design/frontend-architecture.md

@@ -1,147 +1,165 @@
-# 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。
-
-## 6. API 与数据边界
-
-| UI 需求 | API / Contract | 字段 | 错误态 | 前端兜底 |
-| --- | --- | --- | --- | --- |
-| | | | | |
-
-规则:
-
-- UI 字段必须能追溯到 contract 或 PRD 数据字典。
-- 展示组件不得拼接 HTTP URL 或处理响应状态码。
-- API client 抛出的错误必须映射到用户可理解的错误态。
-- mock 数据必须覆盖 default / empty / error / long_content / permission。
-
-## 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 明确要求时，才抽项目级复用组件。
-
-## 12. 完成标准
-
-- [ ] 组件分层与目录边界已明确。
-- [ ] 状态来源、持久化和事件已明确。
-- [ ] API 字段和错误态已追溯到 contract 或 PRD。
-- [ ] 响应式结构有 desktop / tablet / mobile 策略。
-- [ ] 动效、reduced motion、键盘和可访问性规则已定义。
+# 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 证据路径已定义。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/design/image-to-frontend-spec.md

@@ -17,11 +17,11 @@
 | Aside | | | | |
 | Footer / Action Bar | | | | |
 
-## 3. 组件实现映射
-
-| 图片元素 | 前端组件 | 层级 | 复用来源 | Props / 数据 | 事件 | 状态 |
-| --- | --- | --- | --- | --- | --- | --- |
-| | | page / feature / primitive | existing / new | | | default |
+## 3. 组件实现映射
+
+| 图片元素 | 前端组件 | 层级 | 复用来源 | Props / 数据 | 事件 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- |
+| | | page / feature / primitive | existing / new | | | default |
 
 ## 4. CSS / Token 映射
 
@@ -32,28 +32,38 @@
 | 间距 | `--space-*` | | |
 | 圆角 | `--radius-*` | | |
 
-## 5. 状态实现规格
-
-| State | 数据条件 | UI 行为 | 组件变化 | 动效 | 测试 |
-| --- | --- | --- | --- | --- | --- |
-| default | | | | | story / e2e / visual |
-| empty | | | | | story / e2e / visual |
-| loading | | | | | story / visual |
-| error | | | | | story / e2e / visual |
-
-## 5.1 响应式实现规格
-
-| Viewport | 布局 | 筛选策略 | 表格 / 列表策略 | 操作区策略 | 截图要求 |
-| --- | --- | --- | --- | --- | --- |
-| Desktop 1440x900 | | | | | required |
-| Tablet 768x1024 | | | | | required / optional |
-| Mobile 375x812 | | | | | required |
-
-## 5.2 动效与可访问性规格
-
-| 场景 | 动效 | reduced motion | 键盘 / 焦点 | ARIA / 状态提示 |
-| --- | --- | --- | --- | --- |
-| | | | | |
+## 5. 状态实现规格
+
+| State | 数据条件 | UI 行为 | 组件变化 | 动效 | 测试 |
+| --- | --- | --- | --- | --- | --- |
+| default | | | | | story / e2e / visual |
+| empty | | | | | story / e2e / visual |
+| loading | | | | | story / visual |
+| error | | | | | story / e2e / visual |
+| disabled | | | | | story / interaction / visual |
+| submitting | | | | | story / interaction / e2e |
+| retry | | | | | story / interaction / e2e |
+| offline | | | | | story / e2e / visual |
+
+## 5.1 响应式实现规格
+
+| Viewport | 布局 | 筛选策略 | 表格 / 列表策略 | 操作区策略 | 截图要求 |
+| --- | --- | --- | --- | --- | --- |
+| Desktop 1440x900 | | | | | required |
+| Tablet 768x1024 | | | | | required / optional |
+| Mobile 375x812 | | | | | required |
+
+## 5.2 动效与可访问性规格
+
+| 场景 | 动效 | reduced motion | 键盘 / 焦点 | ARIA / 状态提示 |
+| --- | --- | --- | --- | --- |
+| | | | | |
+
+### 5.3 表单与安全区规格
+
+| 场景 | 校验时机 | 错误提示 | 提交中策略 | 键盘类型 / 输入限制 | 安全区 / 键盘遮挡处理 |
+| --- | --- | --- | --- | --- | --- |
+| | blur / submit / input | inline / summary / toast | disabled / spinner / optimistic | | |
 
 ## 6. Mock 数据
 
@@ -64,22 +74,22 @@
 | error | | |
 | long_content | | |
 
-## 7. 实现任务输入
-
-- 必读:
-  - `docs/product/requirement-interface-matrix.md`
-  - `docs/harness/frontend-quality-rules.md`
-  - `docs/design/frontend-architecture.md`
-  - `docs/design/component-map.md`
+## 7. 实现任务输入
+
+- 必读:
+  - `docs/product/requirement-interface-matrix.md`
+  - `docs/harness/frontend-quality-rules.md`
+  - `docs/design/frontend-architecture.md`
+  - `docs/design/component-map.md`
   - `docs/design/screen-states.md`
   - `docs/design/design-tokens.json`
   - 本文件
 - 必须输出:
   - 前端组件 / 页面
   - stories
-  - mock 数据
-  - visual baseline 或截图证据
-  - a11y smoke 和 responsive 截图证据
+  - mock 数据
+  - visual baseline 或截图证据
+  - a11y smoke 和 responsive 截图证据
 
 ## 8. 视觉还原验证计划
 
@@ -87,22 +97,24 @@
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | page-001 | default | Desktop 1440x900 | | | `docs/design/assets/.../reference.png` | `artifacts/visual-review/.../actual.png` | `artifacts/visual-review/.../review.md` |
 
-规则:
-
-- 前端实现完成后，必须启动真实浏览器访问页面并截图。
-- 截图必须保存到 `artifacts/visual-review/<feature>/<page>/`。
-- 参考图必须来自已通过 `ui-image-review.md` 的设计图。
-- 对比过程使用 `visual-parity-review.md`，结论为 `PASS` 才能通过 Stage 1。
-- 如果 UI 和设计图不一致，必须修复前端代码并重新截图，不允许只改验收文档绕过。
+规则:
+
+- 前端实现完成后，必须启动真实浏览器访问页面并截图。
+- 截图必须保存到 `artifacts/visual-review/<feature>/<page>/`。
+- 参考图必须来自已通过 `ui-image-review.md` 的设计图。
+- 对比过程使用 `visual-parity-review.md`，结论为 `PASS` 才能通过 Stage 1。
+- 如果 UI 和设计图不一致，必须修复前端代码并重新截图，不允许只改验收文档绕过。
+- 如果 `复用来源 = existing`，实现任务必须在 `component-map.md` 或 `frontend-architecture.md` 里写清 props 兼容策略和受影响调用方。
 
 ## 9. 通过标准
 
 - [ ] 图片中的每个可见业务元素都有组件映射。
-- [ ] 每个组件都能追溯到数据、事件和状态。
-- [ ] 每个组件都声明了 page / feature / primitive 层级和复用边界。
-- [ ] CSS 实现可以从 token 或明确规则得出。
-- [ ] 响应式行为可以从 viewport 规格得出。
-- [ ] 动效和 reduced motion 行为已明确。
-- [ ] 没有直接从图片猜出的隐藏业务逻辑。
-- [ ] 前端实现任务不再需要重新做视觉决策。
-- [ ] 真实浏览器截图与设计参考图完成视觉还原对比，`visual-parity-review.md` 结论为 PASS。
+- [ ] 每个组件都能追溯到数据、事件和状态。
+- [ ] 每个组件都声明了 page / feature / primitive 层级和复用边界。
+- [ ] CSS 实现可以从 token 或明确规则得出。
+- [ ] 响应式行为可以从 viewport 规格得出。
+- [ ] 动效和 reduced motion 行为已明确。
+- [ ] 表单校验、submitting、retry、offline 和安全区处理已明确。
+- [ ] 没有直接从图片猜出的隐藏业务逻辑。
+- [ ] 前端实现任务不再需要重新做视觉决策。
+- [ ] 真实浏览器截图与设计参考图完成视觉还原对比，`visual-parity-review.md` 结论为 PASS。