@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/examples/ticket-filter-demo/docs/design/frontend-architecture.md

@@ -1,107 +1,107 @@
-# Frontend Architecture
-
-## 1. 基本信息
-
-- Feature ID: `FEAT-TICKET-FILTER`
-- 页面 / 模块: 工单列表筛选与保存视图
-- 关联需求: `FR-001`, `FR-002`, `FR-003`
-- 关联路由: `/tickets`
-- 目标质量等级: P2
-- 设计真相源: `docs/design/design-brief.md`, `docs/design/image-to-frontend-spec.md`
-- Contract 真相源: `contracts/openapi.yaml`
-
-## 2. 架构目标
-
-- 把筛选、表格、保存视图弹窗拆成可独立实现和验证的 feature 组件。
-- 让筛选状态可被 URL 分享、刷新恢复和 E2E 验证。
-- 保持通用表格能力和工单业务字段分离，避免把业务枚举写进 UI primitive。
-- 覆盖 desktop / tablet / mobile，不把移动端降级为横向滚动表格。
-
-## 3. 分层与目录
-
-| 层级 | 建议路径 | 职责 | 禁止事项 |
-| --- | --- | --- | --- |
-| Page / Route | `app/tickets/page.tsx` | 组合页面、读取 query、挂载数据查询 | 直接写筛选控件细节 |
-| Feature | `features/tickets/` | 工单筛选、表格、保存视图、权限表现 | 放跨业务 primitive |
-| UI primitives | `packages/ui/` | button、select、dialog、badge、table shell | 依赖工单状态枚举 |
-| Data table | `packages/ui/data-table/` | 分页、列显隐、空态容器、行状态 | 写死 ticket 字段 |
-| API client | `packages/api-client/` | `listTickets`, `createTicketView` | 直接操作 React 状态 |
-| Model / Schema | `features/tickets/model/` | `TicketFilter`、query schema、优先级枚举 | 写入展示样式 |
-
-## 4. 组件树
-
-```text
-<TicketListPage>
-  <TicketListShell>
-    <TicketToolbar />
-    <TicketFilterBar />
-    <TicketFilterDrawer />
-    <TicketTable />
-    <TicketPagination />
-    <SavedViewModal />
-  </TicketListShell>
-</TicketListPage>
-```
-
-| 组件 | 层级 | 职责 | 数据输入 | 事件输出 | 可复用范围 |
-| --- | --- | --- | --- | --- | --- |
-| `TicketFilterBar` | Feature | 展示 desktop/tablet 筛选控件和 dirty 状态 | `TicketFilter`, `dirty`, `loading`, `canSaveView` | `onChange`, `onReset`, `onSaveView` | feature |
-| `TicketFilterDrawer` | Feature | 移动端筛选抽屉 | `TicketFilter`, `open` | `onApply`, `onClose` | feature |
-| `SavedViewModal` | Feature | 命名并保存筛选视图 | `TicketFilter`, `saving`, `error` | `onSubmit`, `onCancel` | feature |
-| `TicketTable` | Feature | 展示工单结果和错误 / 空态 | `Ticket[]`, `pagination`, `status` | `onRetry`, `onPageChange` | feature |
-| `DataTableShell` | Primitive | 表格布局、列显隐、分页容器 | generic rows | generic callbacks | project |
-
-## 5. 状态管理
-
-| 状态 | 所属层级 | 来源 | 持久化方式 | 变化事件 | 测试方式 |
-| --- | --- | --- | --- | --- | --- |
-| `status`, `priority`, `assigneeId`, `search` | Page / Feature | query string | URL | filter change / reset | e2e |
-| tickets remote data | Feature | `GET /tickets` | query cache | filter change / retry | mock + e2e |
-| saved view form | Component | user input | local | submit / cancel | story interaction |
-| drawer / modal open | Component | user interaction | local | open / close | story |
-| permission | Feature | user role | auth context / API | role change | e2e |
-
-## 6. 响应式架构
-
-| 视口 | 结构 | 筛选策略 | 列表 / 表格策略 | 操作区策略 | 必需截图 |
-| --- | --- | --- | --- | --- | --- |
-| Desktop >= 1200px | Header + inline filters + table | 横向筛选条，chip 回显 | 完整表格，保留分页 | 保存视图按钮在 header | default / empty / error |
-| Tablet 768-1199px | Header + wrapping filters + table | 筛选条换行，次要筛选收进菜单 | 隐藏低优先级列 | 操作区折叠为菜单 | default |
-| Mobile < 768px | Header + filter drawer + cards | 顶部筛选按钮打开抽屉 | 表格转工单卡片 | 保存视图进更多菜单 | default / mobile |
-
-## 7. 动效与可访问性
-
-| 组件 / 场景 | 动效 | reduced motion 行为 | 焦点 / 键盘规则 | ARIA / 语义 |
-| --- | --- | --- | --- | --- |
-| `SavedViewModal` | opacity + scale, 160ms | 直接显示 / 隐藏 | 打开聚焦名称输入，Esc 关闭并恢复焦点 | `role=dialog`, `aria-modal=true` |
-| `TicketFilterDrawer` | translateX + opacity, 180ms | 直接显示 / 隐藏 | focus trap，关闭后回到筛选按钮 | drawer label |
-| filter chips | opacity + slight translate, 120ms | 无位移动画 | 删除按钮可键盘访问 | chip 文案含字段名 |
-| table refresh | skeleton + row fade, 160ms | skeleton 不做 shimmer | 重试按钮可聚焦 | loading / error 状态可感知 |
-
-## 8. 性能预算
-
-| 风险 | 阈值 / 预算 | 处理策略 | 验证方式 |
-| --- | --- | --- | --- |
-| 表格行数 | 单页超过 100 行 | 服务端分页或虚拟滚动 | e2e + performance smoke |
-| 筛选请求 | 输入搜索 | debounce 300ms | interaction test |
-| 动效 | 表格刷新频繁 | 高频刷新禁用行级动画 | visual / manual |
-| 图标 | 操作按钮较多 | 使用 tree-shakeable icon import | bundle check |
-
-## 9. Story 与测试矩阵
-
-| 状态 / 场景 | Story | Interaction | E2E | Visual | A11y | Performance |
-| --- | --- | --- | --- | --- | --- | --- |
-| default | `TicketListPage/Default` | filters change | `/tickets` query | desktop | smoke | N/A |
-| loading | `TicketListPage/Loading` | disabled controls | N/A | desktop | smoke | shimmer off under reduced motion |
-| empty | `TicketListPage/Empty` | clear filters | no results | desktop | smoke | N/A |
-| error | `TicketListPage/Error` | retry | API failure | desktop | smoke | N/A |
-| permission | `TicketListPage/PermissionDenied` | save hidden | role=agent | desktop | smoke | N/A |
-| mobile | `TicketListPage/Mobile` | drawer apply | mobile viewport | mobile | focus trap | N/A |
-
-## 10. 复用决策
-
-| 候选组件 / Hook | 复用范围 | 是否抽象 | 原因 | 约束 |
-| --- | --- | --- | --- | --- |
-| `DataTableShell` | project | Yes | 表格分页、空态和列显隐可跨后台页面复用 | 不写业务字段 |
-| `TicketFilterBar` | feature | No | 工单字段和权限语义强 | 留在 tickets feature |
+# Frontend Architecture
+
+## 1. 基本信息
+
+- Feature ID: `FEAT-TICKET-FILTER`
+- 页面 / 模块: 工单列表筛选与保存视图
+- 关联需求: `FR-001`, `FR-002`, `FR-003`
+- 关联路由: `/tickets`
+- 目标质量等级: P2
+- 设计真相源: `docs/design/design-brief.md`, `docs/design/image-to-frontend-spec.md`
+- Contract 真相源: `contracts/openapi.yaml`
+
+## 2. 架构目标
+
+- 把筛选、表格、保存视图弹窗拆成可独立实现和验证的 feature 组件。
+- 让筛选状态可被 URL 分享、刷新恢复和 E2E 验证。
+- 保持通用表格能力和工单业务字段分离，避免把业务枚举写进 UI primitive。
+- 覆盖 desktop / tablet / mobile，不把移动端降级为横向滚动表格。
+
+## 3. 分层与目录
+
+| 层级 | 建议路径 | 职责 | 禁止事项 |
+| --- | --- | --- | --- |
+| Page / Route | `app/tickets/page.tsx` | 组合页面、读取 query、挂载数据查询 | 直接写筛选控件细节 |
+| Feature | `features/tickets/` | 工单筛选、表格、保存视图、权限表现 | 放跨业务 primitive |
+| UI primitives | `packages/ui/` | button、select、dialog、badge、table shell | 依赖工单状态枚举 |
+| Data table | `packages/ui/data-table/` | 分页、列显隐、空态容器、行状态 | 写死 ticket 字段 |
+| API client | `packages/api-client/` | `listTickets`, `createTicketView` | 直接操作 React 状态 |
+| Model / Schema | `features/tickets/model/` | `TicketFilter`、query schema、优先级枚举 | 写入展示样式 |
+
+## 4. 组件树
+
+```text
+<TicketListPage>
+  <TicketListShell>
+    <TicketToolbar />
+    <TicketFilterBar />
+    <TicketFilterDrawer />
+    <TicketTable />
+    <TicketPagination />
+    <SavedViewModal />
+  </TicketListShell>
+</TicketListPage>
+```
+
+| 组件 | 层级 | 职责 | 数据输入 | 事件输出 | 可复用范围 |
+| --- | --- | --- | --- | --- | --- |
+| `TicketFilterBar` | Feature | 展示 desktop/tablet 筛选控件和 dirty 状态 | `TicketFilter`, `dirty`, `loading`, `canSaveView` | `onChange`, `onReset`, `onSaveView` | feature |
+| `TicketFilterDrawer` | Feature | 移动端筛选抽屉 | `TicketFilter`, `open` | `onApply`, `onClose` | feature |
+| `SavedViewModal` | Feature | 命名并保存筛选视图 | `TicketFilter`, `saving`, `error` | `onSubmit`, `onCancel` | feature |
+| `TicketTable` | Feature | 展示工单结果和错误 / 空态 | `Ticket[]`, `pagination`, `status` | `onRetry`, `onPageChange` | feature |
+| `DataTableShell` | Primitive | 表格布局、列显隐、分页容器 | generic rows | generic callbacks | project |
+
+## 5. 状态管理
+
+| 状态 | 所属层级 | 来源 | 持久化方式 | 变化事件 | 测试方式 |
+| --- | --- | --- | --- | --- | --- |
+| `status`, `priority`, `assigneeId`, `search` | Page / Feature | query string | URL | filter change / reset | e2e |
+| tickets remote data | Feature | `GET /tickets` | query cache | filter change / retry | mock + e2e |
+| saved view form | Component | user input | local | submit / cancel | story interaction |
+| drawer / modal open | Component | user interaction | local | open / close | story |
+| permission | Feature | user role | auth context / API | role change | e2e |
+
+## 6. 响应式架构
+
+| 视口 | 结构 | 筛选策略 | 列表 / 表格策略 | 操作区策略 | 必需截图 |
+| --- | --- | --- | --- | --- | --- |
+| Desktop >= 1200px | Header + inline filters + table | 横向筛选条，chip 回显 | 完整表格，保留分页 | 保存视图按钮在 header | default / empty / error |
+| Tablet 768-1199px | Header + wrapping filters + table | 筛选条换行，次要筛选收进菜单 | 隐藏低优先级列 | 操作区折叠为菜单 | default |
+| Mobile < 768px | Header + filter drawer + cards | 顶部筛选按钮打开抽屉 | 表格转工单卡片 | 保存视图进更多菜单 | default / mobile |
+
+## 7. 动效与可访问性
+
+| 组件 / 场景 | 动效 | reduced motion 行为 | 焦点 / 键盘规则 | ARIA / 语义 |
+| --- | --- | --- | --- | --- |
+| `SavedViewModal` | opacity + scale, 160ms | 直接显示 / 隐藏 | 打开聚焦名称输入，Esc 关闭并恢复焦点 | `role=dialog`, `aria-modal=true` |
+| `TicketFilterDrawer` | translateX + opacity, 180ms | 直接显示 / 隐藏 | focus trap，关闭后回到筛选按钮 | drawer label |
+| filter chips | opacity + slight translate, 120ms | 无位移动画 | 删除按钮可键盘访问 | chip 文案含字段名 |
+| table refresh | skeleton + row fade, 160ms | skeleton 不做 shimmer | 重试按钮可聚焦 | loading / error 状态可感知 |
+
+## 8. 性能预算
+
+| 风险 | 阈值 / 预算 | 处理策略 | 验证方式 |
+| --- | --- | --- | --- |
+| 表格行数 | 单页超过 100 行 | 服务端分页或虚拟滚动 | e2e + performance smoke |
+| 筛选请求 | 输入搜索 | debounce 300ms | interaction test |
+| 动效 | 表格刷新频繁 | 高频刷新禁用行级动画 | visual / manual |
+| 图标 | 操作按钮较多 | 使用 tree-shakeable icon import | bundle check |
+
+## 9. Story 与测试矩阵
+
+| 状态 / 场景 | Story | Interaction | E2E | Visual | A11y | Performance |
+| --- | --- | --- | --- | --- | --- | --- |
+| default | `TicketListPage/Default` | filters change | `/tickets` query | desktop | smoke | N/A |
+| loading | `TicketListPage/Loading` | disabled controls | N/A | desktop | smoke | shimmer off under reduced motion |
+| empty | `TicketListPage/Empty` | clear filters | no results | desktop | smoke | N/A |
+| error | `TicketListPage/Error` | retry | API failure | desktop | smoke | N/A |
+| permission | `TicketListPage/PermissionDenied` | save hidden | role=agent | desktop | smoke | N/A |
+| mobile | `TicketListPage/Mobile` | drawer apply | mobile viewport | mobile | focus trap | N/A |
+
+## 10. 复用决策
+
+| 候选组件 / Hook | 复用范围 | 是否抽象 | 原因 | 约束 |
+| --- | --- | --- | --- | --- |
+| `DataTableShell` | project | Yes | 表格分页、空态和列显隐可跨后台页面复用 | 不写业务字段 |
+| `TicketFilterBar` | feature | No | 工单字段和权限语义强 | 留在 tickets feature |
 | `SavedViewModal` | feature | No | 视图保存依赖当前 filter schema | 后续第二个业务场景出现再抽象 |

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

@@ -1,72 +1,72 @@
-# Image To Frontend Spec
-
-## 1. 输入图片
-
-| Image ID | Page ID | State | 图片路径 / 链接 | 评审结论 |
-| --- | --- | --- | --- | --- |
-| IMG-001 | ticket-list | default | `images/ticket-list-default.png` | PASS |
-| IMG-002 | ticket-list | empty | `images/ticket-list-empty.png` | PASS |
-| IMG-003 | ticket-list | loading | `images/ticket-list-loading.png` | PASS |
-| IMG-004 | ticket-list | error | `images/ticket-list-error.png` | PASS |
-| IMG-005 | ticket-list | permission_denied | `images/ticket-list-permission.png` | PASS |
-
-## 2. 页面布局规格
-
-| 区域 | 位置 | 尺寸 / 约束 | 内容 | 响应式行为 |
-| --- | --- | --- | --- | --- |
-| Header | 顶部 | 高度约 64px | 标题、说明、保存视图按钮 | mobile 保留标题，操作进菜单 |
-| Filter Bar | Header 下方 | 横向排列 | 状态、优先级、负责人、搜索 | mobile 折叠为筛选抽屉 |
-| Main Table | 主区域 | 宽度自适应 | 工单表格、状态标签、操作 | mobile 转卡片列表 |
-| Pagination | 底部 | 右对齐 | 页码、每页数量 | mobile 简化为上一页/下一页 |
-
-## 3. 组件实现映射
-
-| 图片元素 | 前端组件 | 层级 | 复用来源 | Props / 数据 | 事件 | 状态 |
-| --- | --- | --- | --- | --- | --- | --- |
-| 筛选条 | `TicketFilterBar` | feature | existing business component | `TicketFilter` | `onChange`, `onReset` | default / dirty / mobile |
-| 移动端筛选抽屉 | `TicketFilterDrawer` | feature | new business component | `TicketFilter`, `open` | `onApply`, `onClose` | mobile |
-| 保存视图弹窗 | `SavedViewModal` | feature | new business component | `CreateTicketViewRequest` | `onSubmit`, `onCancel` | default / validation-error |
-| 工单表格 | `TicketTable` | feature | table base component | `Ticket[]`, pagination | `onRetry` | default / empty / loading / error |
-| 表格基础容器 | `DataTableShell` | primitive | new reusable component | rows, columns, pagination | generic callbacks | default / empty / loading |
-
-## 4. CSS / Token 映射
-
-| 图片表现 | Token / CSS 变量 | 值 | 备注 |
-| --- | --- | --- | --- |
-| 页面背景 | `--color-bg-subtle` | `#F6F7F9` | 来自 design tokens |
-| 主面板 | `--color-bg-default` | `#FFFFFF` | |
-| 高优先级强调 | `--color-status-warning` | `#B45309` | |
-| 错误提示 | `--color-status-danger` | `#B91C1C` | |
-| 面板圆角 | `--radius-md` | `8px` | |
-
-## 5. 状态实现规格
-
-| State | 数据条件 | UI 行为 | 组件变化 | 动效 | 测试 |
-| --- | --- | --- | --- | --- | --- |
-| default | `items.length > 0` | 展示表格和分页 | `TicketTable` default | rows fade in 160ms | story / e2e / visual |
-| empty | `items.length === 0` | 展示空态和清除筛选 | `TicketTable` empty | opacity 160ms | story / e2e / visual |
-| loading | 请求中 | 展示骨架屏并禁用保存 | `TicketTable` loading | skeleton, reduced motion disables shimmer | story / visual |
-| error | 请求失败 | 展示错误和重试 | `TicketTable` error | opacity 160ms | story / e2e / visual |
-| permission_denied | role=agent | 隐藏保存视图入口 | `TicketFilterBar` permission | none | e2e |
-| mobile | viewport < 768px | 筛选进入抽屉，表格转卡片 | `TicketFilterDrawer`, `TicketCardList` | drawer 180ms | story / e2e / visual |
-
-## 6. 响应式与动效规格
-
-| Viewport | 布局 | 筛选策略 | 表格 / 列表策略 | 操作区策略 | 截图要求 |
-| --- | --- | --- | --- | --- | --- |
-| Desktop 1440x900 | Header + inline filter + table | 横向筛选条和 chip 回显 | 完整表格 | 保存按钮在 header | required |
-| Tablet 768x1024 | Header + wrapping filter + table | 筛选条换行，次要筛选进菜单 | 隐藏低优先级列 | 操作进菜单 | optional |
-| Mobile 375x812 | Header + filter drawer + cards | 筛选按钮打开抽屉 | 表格转卡片 | 保存视图进更多菜单 | required |
-
-动效规则:
-
-- 弹窗和抽屉必须支持 reduced motion。
-- 表格刷新不得造成分页、表头和筛选区位移。
-- 筛选 chip 删除按钮必须可键盘访问。
-
-## 7. 架构输入
-
-- 前端质量规则: `docs/harness/frontend-quality-rules.md`
-- 前端架构: `docs/design/frontend-architecture.md`
-- 通用能力候选: `DataTableShell`
-- 业务内保留: `TicketFilterBar`, `TicketFilterDrawer`, `SavedViewModal`, `TicketTable`
+# Image To Frontend Spec
+
+## 1. 输入图片
+
+| Image ID | Page ID | State | 图片路径 / 链接 | 评审结论 |
+| --- | --- | --- | --- | --- |
+| IMG-001 | ticket-list | default | `images/ticket-list-default.png` | PASS |
+| IMG-002 | ticket-list | empty | `images/ticket-list-empty.png` | PASS |
+| IMG-003 | ticket-list | loading | `images/ticket-list-loading.png` | PASS |
+| IMG-004 | ticket-list | error | `images/ticket-list-error.png` | PASS |
+| IMG-005 | ticket-list | permission_denied | `images/ticket-list-permission.png` | PASS |
+
+## 2. 页面布局规格
+
+| 区域 | 位置 | 尺寸 / 约束 | 内容 | 响应式行为 |
+| --- | --- | --- | --- | --- |
+| Header | 顶部 | 高度约 64px | 标题、说明、保存视图按钮 | mobile 保留标题，操作进菜单 |
+| Filter Bar | Header 下方 | 横向排列 | 状态、优先级、负责人、搜索 | mobile 折叠为筛选抽屉 |
+| Main Table | 主区域 | 宽度自适应 | 工单表格、状态标签、操作 | mobile 转卡片列表 |
+| Pagination | 底部 | 右对齐 | 页码、每页数量 | mobile 简化为上一页/下一页 |
+
+## 3. 组件实现映射
+
+| 图片元素 | 前端组件 | 层级 | 复用来源 | Props / 数据 | 事件 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 筛选条 | `TicketFilterBar` | feature | existing business component | `TicketFilter` | `onChange`, `onReset` | default / dirty / mobile |
+| 移动端筛选抽屉 | `TicketFilterDrawer` | feature | new business component | `TicketFilter`, `open` | `onApply`, `onClose` | mobile |
+| 保存视图弹窗 | `SavedViewModal` | feature | new business component | `CreateTicketViewRequest` | `onSubmit`, `onCancel` | default / validation-error |
+| 工单表格 | `TicketTable` | feature | table base component | `Ticket[]`, pagination | `onRetry` | default / empty / loading / error |
+| 表格基础容器 | `DataTableShell` | primitive | new reusable component | rows, columns, pagination | generic callbacks | default / empty / loading |
+
+## 4. CSS / Token 映射
+
+| 图片表现 | Token / CSS 变量 | 值 | 备注 |
+| --- | --- | --- | --- |
+| 页面背景 | `--color-bg-subtle` | `#F6F7F9` | 来自 design tokens |
+| 主面板 | `--color-bg-default` | `#FFFFFF` | |
+| 高优先级强调 | `--color-status-warning` | `#B45309` | |
+| 错误提示 | `--color-status-danger` | `#B91C1C` | |
+| 面板圆角 | `--radius-md` | `8px` | |
+
+## 5. 状态实现规格
+
+| State | 数据条件 | UI 行为 | 组件变化 | 动效 | 测试 |
+| --- | --- | --- | --- | --- | --- |
+| default | `items.length > 0` | 展示表格和分页 | `TicketTable` default | rows fade in 160ms | story / e2e / visual |
+| empty | `items.length === 0` | 展示空态和清除筛选 | `TicketTable` empty | opacity 160ms | story / e2e / visual |
+| loading | 请求中 | 展示骨架屏并禁用保存 | `TicketTable` loading | skeleton, reduced motion disables shimmer | story / visual |
+| error | 请求失败 | 展示错误和重试 | `TicketTable` error | opacity 160ms | story / e2e / visual |
+| permission_denied | role=agent | 隐藏保存视图入口 | `TicketFilterBar` permission | none | e2e |
+| mobile | viewport < 768px | 筛选进入抽屉，表格转卡片 | `TicketFilterDrawer`, `TicketCardList` | drawer 180ms | story / e2e / visual |
+
+## 6. 响应式与动效规格
+
+| Viewport | 布局 | 筛选策略 | 表格 / 列表策略 | 操作区策略 | 截图要求 |
+| --- | --- | --- | --- | --- | --- |
+| Desktop 1440x900 | Header + inline filter + table | 横向筛选条和 chip 回显 | 完整表格 | 保存按钮在 header | required |
+| Tablet 768x1024 | Header + wrapping filter + table | 筛选条换行，次要筛选进菜单 | 隐藏低优先级列 | 操作进菜单 | optional |
+| Mobile 375x812 | Header + filter drawer + cards | 筛选按钮打开抽屉 | 表格转卡片 | 保存视图进更多菜单 | required |
+
+动效规则:
+
+- 弹窗和抽屉必须支持 reduced motion。
+- 表格刷新不得造成分页、表头和筛选区位移。
+- 筛选 chip 删除按钮必须可键盘访问。
+
+## 7. 架构输入
+
+- 前端质量规则: `docs/harness/frontend-quality-rules.md`
+- 前端架构: `docs/design/frontend-architecture.md`
+- 通用能力候选: `DataTableShell`
+- 业务内保留: `TicketFilterBar`, `TicketFilterDrawer`, `SavedViewModal`, `TicketTable`

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/examples/ticket-filter-demo/docs/design/screen-states.md

@@ -1,25 +1,25 @@
-# Screen States
-
-## 工单列表页
-
-- `default`: 默认表格 + 筛选条
-- `empty`: 空态插图或空态文案 + 清空筛选按钮
-- `loading`: 表格骨架屏 + 顶部筛选禁用
-- `error`: 顶部提示 + 表格区错误块 + 重试按钮
-- `permission_denied`: 保存视图按钮隐藏
-- `long_content`: 工单标题两行截断，负责人超长显示 tooltip，状态标签不换行
-- `mobile`: 筛选条进入抽屉，表格转卡片列表，分页简化为上一页/下一页
-- `reduced_motion`: 弹窗、抽屉、chip 和表格刷新取消位移动效，只保留即时状态变化
-
-## 状态到测试映射
-
-| 状态 | Story | E2E | Visual | A11y |
-| --- | --- | --- | --- | --- |
-| default | `TicketListPage/Default` | `/tickets` | desktop | smoke |
-| empty | `TicketListPage/Empty` | no results | desktop | smoke |
-| loading | `TicketListPage/Loading` | N/A | desktop | smoke |
-| error | `TicketListPage/Error` | API failure + retry | desktop | smoke |
-| permission_denied | `TicketListPage/PermissionDenied` | role=agent | desktop | smoke |
-| long_content | `TicketListPage/LongContent` | N/A | desktop | N/A |
-| mobile | `TicketListPage/Mobile` | mobile viewport | mobile | focus trap |
-| reduced_motion | `TicketListPage/ReducedMotion` | N/A | optional | smoke |
+# Screen States
+
+## 工单列表页
+
+- `default`: 默认表格 + 筛选条
+- `empty`: 空态插图或空态文案 + 清空筛选按钮
+- `loading`: 表格骨架屏 + 顶部筛选禁用
+- `error`: 顶部提示 + 表格区错误块 + 重试按钮
+- `permission_denied`: 保存视图按钮隐藏
+- `long_content`: 工单标题两行截断，负责人超长显示 tooltip，状态标签不换行
+- `mobile`: 筛选条进入抽屉，表格转卡片列表，分页简化为上一页/下一页
+- `reduced_motion`: 弹窗、抽屉、chip 和表格刷新取消位移动效，只保留即时状态变化
+
+## 状态到测试映射
+
+| 状态 | Story | E2E | Visual | A11y |
+| --- | --- | --- | --- | --- |
+| default | `TicketListPage/Default` | `/tickets` | desktop | smoke |
+| empty | `TicketListPage/Empty` | no results | desktop | smoke |
+| loading | `TicketListPage/Loading` | N/A | desktop | smoke |
+| error | `TicketListPage/Error` | API failure + retry | desktop | smoke |
+| permission_denied | `TicketListPage/PermissionDenied` | role=agent | desktop | smoke |
+| long_content | `TicketListPage/LongContent` | N/A | desktop | N/A |
+| mobile | `TicketListPage/Mobile` | mobile viewport | mobile | focus trap |
+| reduced_motion | `TicketListPage/ReducedMotion` | N/A | optional | smoke |

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/examples/ticket-filter-demo/docs/design/ui-image-review.md

@@ -1,38 +1,38 @@
-# UI Image Review
-
-## 1. 评审对象
-
-| Image ID | Page ID | State | 图片路径 / 链接 | 版本 |
-| --- | --- | --- | --- | --- |
-| IMG-001 | ticket-list | default | `images/ticket-list-default.png` | v1 |
-| IMG-002 | ticket-list | empty | `images/ticket-list-empty.png` | v1 |
-| IMG-003 | ticket-list | loading | `images/ticket-list-loading.png` | v1 |
-| IMG-004 | ticket-list | error | `images/ticket-list-error.png` | v1 |
-| IMG-005 | ticket-list | permission_denied | `images/ticket-list-permission.png` | v1 |
-| IMG-006 | ticket-list | mobile | `images/ticket-list-mobile.png` | v1 |
-
-## 2. 需求匹配检查
-
-| Requirement ID | 图片是否体现 | 证据 | 问题 | 结论 |
-| --- | --- | --- | --- | --- |
-| FR-001 | Yes | 筛选条、表格、分页 | 无 | Pass |
-| FR-002 | Yes | 保存视图按钮和弹窗入口 | 无 | Pass |
-| FR-003 | Yes | permission 图隐藏保存入口 | 无 | Pass |
-
-## 3. 状态覆盖检查
-
-| Page ID | State | 是否有图 | 是否符合 Screen States | 问题 | 结论 |
-| --- | --- | --- | --- | --- | --- |
-| ticket-list | default | Yes | Yes | 无 | Pass |
-| ticket-list | empty | Yes | Yes | 无 | Pass |
-| ticket-list | loading | Yes | Yes | 无 | Pass |
-| ticket-list | error | Yes | Yes | 无 | Pass |
-| ticket-list | permission_denied | Yes | Yes | 无 | Pass |
-| ticket-list | mobile | Yes | Yes | 无 | Pass |
-
-## 4. 评审结论
-
-- Verdict: PASS
-- 必须重生成的图片: 无
-- 可通过编辑修复的图片: 无
-- 通过后进入: `image-to-frontend-spec.md`
+# UI Image Review
+
+## 1. 评审对象
+
+| Image ID | Page ID | State | 图片路径 / 链接 | 版本 |
+| --- | --- | --- | --- | --- |
+| IMG-001 | ticket-list | default | `images/ticket-list-default.png` | v1 |
+| IMG-002 | ticket-list | empty | `images/ticket-list-empty.png` | v1 |
+| IMG-003 | ticket-list | loading | `images/ticket-list-loading.png` | v1 |
+| IMG-004 | ticket-list | error | `images/ticket-list-error.png` | v1 |
+| IMG-005 | ticket-list | permission_denied | `images/ticket-list-permission.png` | v1 |
+| IMG-006 | ticket-list | mobile | `images/ticket-list-mobile.png` | v1 |
+
+## 2. 需求匹配检查
+
+| Requirement ID | 图片是否体现 | 证据 | 问题 | 结论 |
+| --- | --- | --- | --- | --- |
+| FR-001 | Yes | 筛选条、表格、分页 | 无 | Pass |
+| FR-002 | Yes | 保存视图按钮和弹窗入口 | 无 | Pass |
+| FR-003 | Yes | permission 图隐藏保存入口 | 无 | Pass |
+
+## 3. 状态覆盖检查
+
+| Page ID | State | 是否有图 | 是否符合 Screen States | 问题 | 结论 |
+| --- | --- | --- | --- | --- | --- |
+| ticket-list | default | Yes | Yes | 无 | Pass |
+| ticket-list | empty | Yes | Yes | 无 | Pass |
+| ticket-list | loading | Yes | Yes | 无 | Pass |
+| ticket-list | error | Yes | Yes | 无 | Pass |
+| ticket-list | permission_denied | Yes | Yes | 无 | Pass |
+| ticket-list | mobile | Yes | Yes | 无 | Pass |
+
+## 4. 评审结论
+
+- Verdict: PASS
+- 必须重生成的图片: 无
+- 可通过编辑修复的图片: 无
+- 通过后进入: `image-to-frontend-spec.md`

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/examples/ticket-filter-demo/docs/product/difficulty-research.md

@@ -1,39 +1,39 @@
-# Difficulty Research
-
-## 1. 难点总览
-
-| Difficulty ID | 难点 / 不确定点 | 来源需求 | 影响页面 / 接口 | 风险等级 | 是否阻塞 | 负责人 | 状态 |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| DR-001 | 筛选状态、保存视图和 URL 查询参数如何保持一致 | FR-001, FR-002 | ticket-list / `GET /tickets` | Medium | No | Demo | Closed |
-| DR-002 | 普通客服无保存权限时按钮隐藏还是禁用 | FR-003 | ticket-list | Low | No | Demo | Closed |
-
-## 2. 研究记录
-
-### DR-001: 筛选状态一致性
-
-- 关联需求: FR-001, FR-002
-- 关联界面: ticket-list, saved-view-modal
-- 问题描述: 筛选条件需要同时驱动列表查询、保存视图和刷新恢复。
-- 为什么现在必须研究: 如果实现阶段才决定状态来源，前端、contract 和 mock 数据会漂移。
-- 已知约束: demo 使用 OpenAPI contract 作为 API 真相源。
-
-| 方案 | 优点 | 缺点 | 风险 | 验证方式 |
-| --- | --- | --- | --- | --- |
-| URL 查询参数为主 | 可刷新恢复，便于分享当前筛选 | 保存视图时需要序列化 query | 低 | e2e 刷新后检查筛选 |
-| 组件本地状态为主 | 实现简单 | 刷新丢失，保存视图易漂移 | 中 | 不采用 |
-
-**结论**: 以 URL 查询参数和 generated client 参数为主，组件内部只保留临时输入状态。
-
-**选择理由**: 保证刷新、保存视图、mock 和真实接口使用同一组字段。
-
-**后续任务影响**: `TicketFilterBar` 的 props 使用 `TicketFilter`，stories 要覆盖 default、empty、error、long_content。
-
-**仍需确认**: 无。
-
-### DR-002: 无权限保存视图
-
-**结论**: 普通客服隐藏保存视图按钮，不展示不可用入口。
-
-**选择理由**: 保存视图不是客服核心任务，隐藏能降低误操作。
-
-**后续任务影响**: permission_denied story 中不渲染保存视图按钮，e2e 验证按钮不存在。
+# Difficulty Research
+
+## 1. 难点总览
+
+| Difficulty ID | 难点 / 不确定点 | 来源需求 | 影响页面 / 接口 | 风险等级 | 是否阻塞 | 负责人 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| DR-001 | 筛选状态、保存视图和 URL 查询参数如何保持一致 | FR-001, FR-002 | ticket-list / `GET /tickets` | Medium | No | Demo | Closed |
+| DR-002 | 普通客服无保存权限时按钮隐藏还是禁用 | FR-003 | ticket-list | Low | No | Demo | Closed |
+
+## 2. 研究记录
+
+### DR-001: 筛选状态一致性
+
+- 关联需求: FR-001, FR-002
+- 关联界面: ticket-list, saved-view-modal
+- 问题描述: 筛选条件需要同时驱动列表查询、保存视图和刷新恢复。
+- 为什么现在必须研究: 如果实现阶段才决定状态来源，前端、contract 和 mock 数据会漂移。
+- 已知约束: demo 使用 OpenAPI contract 作为 API 真相源。
+
+| 方案 | 优点 | 缺点 | 风险 | 验证方式 |
+| --- | --- | --- | --- | --- |
+| URL 查询参数为主 | 可刷新恢复，便于分享当前筛选 | 保存视图时需要序列化 query | 低 | e2e 刷新后检查筛选 |
+| 组件本地状态为主 | 实现简单 | 刷新丢失，保存视图易漂移 | 中 | 不采用 |
+
+**结论**: 以 URL 查询参数和 generated client 参数为主，组件内部只保留临时输入状态。
+
+**选择理由**: 保证刷新、保存视图、mock 和真实接口使用同一组字段。
+
+**后续任务影响**: `TicketFilterBar` 的 props 使用 `TicketFilter`，stories 要覆盖 default、empty、error、long_content。
+
+**仍需确认**: 无。
+
+### DR-002: 无权限保存视图
+
+**结论**: 普通客服隐藏保存视图按钮，不展示不可用入口。
+
+**选择理由**: 保存视图不是客服核心任务，隐藏能降低误操作。
+
+**后续任务影响**: permission_denied story 中不渲染保存视图按钮，e2e 验证按钮不存在。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/examples/ticket-filter-demo/docs/product/page-inventory.md

@@ -1,5 +1,5 @@
-# Page Inventory
-
-| 页面 | 入口 | 目标 | 核心组件 |
-| --- | --- | --- | --- |
-| 工单列表页 | `/tickets` | 筛选和查看工单 | 筛选条、工单表格、保存视图弹窗 |
+# Page Inventory
+
+| 页面 | 入口 | 目标 | 核心组件 |
+| --- | --- | --- | --- |
+| 工单列表页 | `/tickets` | 筛选和查看工单 | 筛选条、工单表格、保存视图弹窗 |