@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/docs/code-style-and-naming.md

@@ -0,0 +1,116 @@
+# 项目级命名词典与边界模板
+
+这份文档不是固定规则入口。固定不变的第五章规则已经放进 always-on 的 `coding-style.md`。
+
+这里专门承载项目特有、会随业务变化的内容：
+
+- 业务词典
+- 历史别名兼容
+- 某些目录的命名例外
+- 类型后缀禁用表和替代方案
+- 当前项目的文件命名分层表
+
+## 1. 适用原则
+
+- 先读规则文件 `coding-style.md`，这里不重复抄固定规则。
+- 这里的每一项都应当是“当前项目特有事实”，不是通用工程常识。
+- 如果某项约束对所有项目都成立，应上收回规则文件，而不是继续堆在本文。
+
+## 2. 业务词典
+
+先维护“一个概念一个名字”的项目词典。
+
+| 业务概念 | 统一名称 | 禁止混用的别名 | 说明 |
+| --- | --- | --- | --- |
+| 用户 | `user` | `member`、`customer`、`client` | 如果确实是不同角色，拆成独立概念 |
+| 商品 | `product` | `goods`、`item`、`commodity` | 只保留业务正式名词 |
+| 订单 | `order` | `bill`、`trade` | 支付单可单独定义 `paymentOrder` |
+| 优惠券 | `coupon` | `voucher`、`ticket` | 如果有券模板，再单独定义 `couponTemplate` |
+
+补齐项目自己的业务词典时，至少回答：
+
+- 这个概念在页面、接口、数据库、测试里是否同名。
+- 是否已经存在历史别名；如果有，兼容层放在哪里。
+- 新增同义词时，是新概念还是旧概念的脏别名。
+
+## 3. 项目文件命名分层表
+
+先按目录层级声明规则，再允许新增文件。
+
+| 路径 / 资产类型 | 命名规则 | 示例 | 禁止情况 |
+| --- | --- | --- | --- |
+| React / Vue 页面组件 | `PascalCase` | `UserProfilePage.tsx` | 与同层 `user-profile-page.tsx` 混用 |
+| 通用 hooks | `camelCase` 且以 `use` 开头 | `useUserProfile.ts` | `userHook.ts`、`getUserHook.ts` |
+| 纯工具函数 | `camelCase` | `formatPrice.ts` | `dealData.ts`、`tool.ts` |
+| 测试文件 | 跟随被测对象 + `.test` / `.spec` | `formatPrice.test.ts` | `test1.ts` |
+| 文档模板 | `kebab-case` | `code-style-and-naming.md` | `codeStyle.md`、`code_style.md` |
+
+新增文件前必须回答：
+
+- 这个文件属于页面、feature、shared、contract、testing 还是 scripts。
+- 同目录现有文件使用什么规则。
+- 如果要破例，为什么不能沿用当前目录规则。
+
+## 4. 项目特有命名例外
+
+这里只记录项目例外，不重复写通用函数命名原则。
+
+- 哪些历史目录仍在使用旧命名风格：
+- 哪些生成代码目录允许例外：
+- 哪些第三方契约文件不按项目规则命名：
+- 哪些 legacy 字段名必须保留原样：
+
+## 5. 类型命名边界
+
+同一个项目里，`Entity`、`DTO`、`Response`、`FormValues`、`ViewModel` 这些后缀必须先定义边界。
+
+| 类型后缀 | 用途 | 不该承载什么 |
+| --- | --- | --- |
+| `Entity` | 持久化模型 / 数据库实体 | 前端展示字段 |
+| `Dto` / `DTO` | 服务边界输入输出 | ORM 细节、UI 状态 |
+| `Response` | API 返回结构 | 表单临时状态 |
+| `Request` | API 请求参数 | 数据库存储字段 |
+| `FormValues` | 表单输入态 | 服务端完整实体 |
+| `ViewModel` | 页面展示聚合模型 | 持久化约束 |
+
+如果项目不使用这些后缀中的某些项，要在这里明确写：
+
+- 禁止使用哪些后缀。
+- 统一替代方案是什么。
+- 历史遗留命名如何兼容。
+
+## 6. 新增命名前必须确认
+
+实现前先确认这 5 件事：
+
+1. 这个名词是否已在业务词典中定义。
+2. 同类文件在当前目录如何命名。
+3. 这个函数名是否表达了主动作和对象。
+4. 这个类型属于哪一层边界，是否需要后缀。
+5. 是否会和历史别名、旧接口字段或数据库字段冲突。
+
+## 7. 自动化与人工门禁
+
+建议自动化命令：
+
+```text
+lint
+typecheck
+format
+test
+git diff --check
+```
+
+Harness 侧至少保留两层约束：
+
+- `coding-style.md` 默认自动加载固定规则。
+- `CURRENT_TASK.md` 和本文记录当前项目 / 当前任务的特有词典与边界。
+- `style-lint.ps1` 同时检查规则文件和项目级模板是否完整。
+
+## 8. 评审检查单
+
+- 同一业务概念是否出现多个别名。
+- 同层文件是否混用了多套命名风格。
+- 新函数名是否仍然依赖 `do/process/check` 这类模糊词。
+- `User`、`UserInfo`、`UserData`、`UserModel` 之类类型是否有明确边界。
+- 新增字段、接口、测试数据、文档是否与统一名词同步。

package/package-source/docs/codex-harness-engineering/templates/docs/directory-structure-template.md

@@ -0,0 +1,88 @@
+# Directory Structure Template
+
+本文用于给项目补一份明确的目录结构真相源，减少 AI 在文件放置、目录新建和业务域组织上的随意性。
+
+## 适用场景
+
+- 项目目录较大，单靠 `repo-map.md` 不足以约束文件放置。
+- 同一项目中同时存在页面、组件、API、hooks、types、constants、测试等多类资产。
+- 团队已经反复遇到“文件放错位置”“随意新建目录”“按技术类型乱堆而不是按业务域组织”的问题。
+
+## 目标
+
+- 说明已有目录各自负责什么。
+- 说明新文件应该放到哪里。
+- 说明哪些目录名禁止新增。
+- 说明是按业务域组织，还是按技术层组织，或两者混合。
+
+## 目录规范模板
+
+```markdown
+# Directory Structure
+
+## 1. 组织原则
+
+- 当前项目主要按 `<业务域 / 技术层 / 混合模式>` 组织。
+- 业务域优先的模块：`<features/<domain> / packages/<domain> / apps/<domain>>`
+- 技术层优先的共享目录：`<components/common / services / hooks / types / constants>`
+- 当业务域目录与共享目录冲突时，优先规则：`<写清优先级>`
+
+## 2. 顶层目录说明
+
+| 路径 | 用途 | 应放内容 | 不应放内容 |
+| --- | --- | --- | --- |
+| `src/pages/` | 页面 / 路由 | 页面组合、路由入口 | 纯公共组件、HTTP 调用细节 |
+| `src/components/common/` | 通用组件 | 无业务语义组件 | 业务状态、业务权限 |
+| `src/features/` | 业务域模块 | 业务组件、业务 hooks、领域 model | 全局通用 primitive |
+| `src/services/` | API / service | HTTP client、service 封装 | 页面 UI 逻辑 |
+| `src/hooks/` | 通用 hooks | 跨页面复用 hooks | 页面专用临时逻辑 |
+| `src/types/` | 类型 | 通用类型、契约类型 | 页面样式、业务逻辑 |
+| `src/constants/` | 常量 | 枚举、配置常量 | 函数实现 |
+| `tests/` | 测试 | 同构测试、集成测试、E2E | 生产代码 |
+
+## 3. 新文件放置规则
+
+- 页面级组件：放到对应页面目录或 `features/<domain>/components`
+- 可复用业务组件：放到 `features/<domain>/components`
+- 全局公共组件：放到 `components/common`
+- 接口请求：放到 `services/` 或 `features/<domain>/api/`
+- 类型定义：放到 `types/` 或模块内 `model/` / `types/`
+- 测试文件：与源码保持同构，或进入明确的测试目录
+
+## 4. 禁止新增的目录名
+
+- `newFeature/`
+- `featureNew/`
+- `myComponents/`
+- `common2/`
+- `utils2/`
+- `helper/`
+- `temp/`
+- `test-new/`
+
+## 5. 新增目录前必须回答
+
+- 为什么需要新目录？
+- 现有目录为什么不能放？
+- 这个目录未来会放什么？
+- 是否符合当前项目现有结构？
+- 是否需要给该目录补 `AGENTS.md`？
+
+## 6. 业务域组织规则
+
+- 若按业务域组织，推荐域列表：`<domain-a> / <domain-b> / <domain-c>`
+- 新业务代码默认先进对应业务域目录。
+- 只有跨业务复用已被验证后，才允许上提到共享层。
+
+## 7. 测试与索引同步
+
+- 新增目录后，如影响导航，更新 `docs/ai/repo-map.md`
+- 新增目录后，如目录规则明显不同，补该目录 `AGENTS.md`
+- 新增目录后，补充相关测试入口或验证命令
+```
+
+## 使用建议
+
+- 根 `AGENTS.md` 只索引这份文档，不复制全文。
+- `repo-map.md` 负责导航；本文件负责放置规范。
+- 如果项目已有强约束的前端目录规则，优先和 `templates/design/frontend-architecture.md` 对齐。

package/package-source/docs/codex-harness-engineering/templates/docs/env-and-deployment-template.md

@@ -0,0 +1,60 @@
+# 环境变量与部署模板
+
+这份模板承载第16章“配置与环境问题”的项目级真相源。它不替代 `.env.example`，而是把变量含义、构建命令、部署入口和风险写清楚。
+
+## 1. 环境变量清单
+
+| 变量名 | 用途 | 必填 | 默认值 | dev/test/prod 差异 | 示例 |
+| --- | --- | --- | --- | --- | --- |
+| `APP_BASE_URL` | | 是/否 | | | |
+| `DATABASE_URL` | | 是/否 | | | |
+| `REDIS_URL` | | 是/否 | | | |
+
+规则:
+
+- 不把真实密钥写入仓库。
+- 每个变量都要说明“谁读取它”“在什么阶段生效”“缺失时会怎样”。
+- 若变量只属于某一部署环境，必须写明该环境的注入方式。
+
+## 2. 构建与运行命令
+
+| 场景 | 命令 | 预期结果 | 失败时常见原因 |
+| --- | --- | --- | --- |
+| 开发 | | | |
+| 构建 | | | |
+| Lint | | | |
+| Typecheck | | | |
+| Test | | | |
+| Docker build | | | |
+
+规则:
+
+- `dev/build/lint/test/typecheck` 至少列出存在与否和替代命令。
+- 如果某个命令本地能跑但 CI 不能跑，必须记录差异来源。
+
+## 3. CI / CD 入口
+
+| 入口 | 文件位置 | 用途 | 依赖变量 / Secret | 失败影响 |
+| --- | --- | --- | --- | --- |
+| GitHub Action / CI | | | | |
+| Dockerfile | | | | |
+| nginx / ingress | | | | |
+| k8s / compose | | | | |
+
+## 4. 健康检查与发布约束
+
+| 项目 | 约束 | 验证方式 | 失败处理 |
+| --- | --- | --- | --- |
+| 健康检查 | | | |
+| 端口 / host | | | |
+| 日志路径 | | | |
+| 迁移 / seed | | | |
+| 灰度 / 回滚 | | | |
+
+## 5. 配置变更前必须说明
+
+- 改了哪些配置文件：`.env*` / `package.json` / `Dockerfile` / `nginx` / `k8s yaml` / `CI workflow` / `tsconfig` / `vite/next config`
+- 为什么要改
+- 会影响哪些环境
+- 哪些命令必须重跑
+- 回滚方式是什么

package/package-source/docs/codex-harness-engineering/templates/docs/frontend-quality-rules.md

@@ -1,138 +1,165 @@
-# Frontend Quality Rules
-
-本文件定义前端页面从“能用”到“可交付”的最低质量尺子。它服务于 `spec-to-ui-to-code-workflow.md`、`design-brief.md`、`image-to-frontend-spec.md`、`component-map.md`、`screen-states.md` 和 `visual-parity-review.md`，不替代项目自己的品牌规范或产品需求。
-
-## 1. 质量分级
-
-| 等级 | 定义 | 必备证据 | 不能声称 |
-| --- | --- | --- | --- |
-| P0 可用 | 主路径能完成，关键控件可操作 | 主路径 story 或 E2E，基本截图 | 生产级体验 |
-| P1 完整 | default / loading / empty / error / permission / long content / mobile 有规格和验证 | 状态矩阵、story 覆盖、移动端截图 | 视觉精修完成 |
-| P2 精修 | 视觉层级、响应式、动效、可访问性和文案有明确标准并通过评审 | visual parity、a11y smoke、responsive matrix | 可无限复用 |
-| P3 生产级 | 架构可维护，组件边界清晰，性能预算和回归证据完整 | frontend architecture、performance budget、regression evidence | 无需后续治理 |
-
-`feature_impl` 的前端任务如果没有写明目标等级，默认按 P1 验收；用户可见核心流程默认至少 P2。
-
-## 2. 审美反模式
-
-以下情况出现任意一项，Stage 1 或视觉评审应要求返工，除非 Design Brief 明确说明原因：
-
-- 页面只由大块卡片堆叠组成，缺少信息层级。
-- 全页面灰白无重点，主要操作、危险操作和状态反馈不可区分。
-- 使用无意义渐变、装饰图形或营销式 hero 来包装操作型后台页面。
-- 所有按钮、标签、状态、表格行的视觉权重相同。
-- 表格密度失控：行高、列宽、数字、标签和操作区没有扫描节奏。
-- 移动端只做横向滚动，没有重排、折叠或卡片化策略。
-- loading / empty / error 只是一行临时文案，没有恢复路径。
-- 图标、颜色或动画只起装饰作用，不能帮助识别状态或操作。
-
-## 3. 动效规则
-
-动效必须解释状态变化，不承担主要信息表达。
-
-| 场景 | 推荐动效 | 时长 | 约束 |
-| --- | --- | --- | --- |
-| 弹窗 / 抽屉打开 | opacity + scale 或 translate | 120-180ms | 必须有焦点管理 |
-| 筛选 chip 增删 | opacity + slight translate | 100-160ms | 不得推动整页大范围跳动 |
-| 表格刷新 | skeleton / row fade | 120-220ms | 高频刷新时禁用行级动画 |
-| 空态 / 错误态切换 | opacity | 120-180ms | 文案和恢复操作优先 |
-| 保存成功 / dirty 清除 | button state + inline status | 120-180ms | 不得只依赖 toast |
-
-硬约束：
-
-- 首选 `transform` 和 `opacity`，不得用会持续触发布局的动画属性。
-- 必须支持 `prefers-reduced-motion` 或等价 reduced motion 开关。
-- 动效不能隐藏错误、禁用、权限不足或保存失败。
-- 动效失败时页面仍必须可用。
-
-## 4. 响应式规则
-
-每个用户可见页面都必须写清楚 desktop / tablet / mobile 的布局策略。
-
-| 视口 | 必须说明 | 常见策略 |
-| --- | --- | --- |
-| Desktop >= 1200px | 主内容宽度、侧栏、表格列、操作区位置 | 横向筛选条 + 数据表 + 分页 |
-| Tablet 768-1199px | 筛选换行、列显隐、操作折叠 | 筛选条换行，次要列隐藏 |
-| Mobile < 768px | 筛选入口、表格替代形态、底部操作、触控尺寸 | 筛选抽屉，表格转卡片，分页简化 |
-
-移动端禁止只依赖横向滚动完成主要流程。若表格必须横向滚动，必须说明原因、最小宽度、冻结列或摘要卡片替代方案。
-
-## 5. 组件复用边界
-
-- `ui primitives`: 只放按钮、输入、弹窗、菜单、表格基础结构等无业务语义组件。
-- `data-table`: 只放排序、筛选、分页、列显隐、空态容器等表格通用行为。
-- `features/<domain>`: 放业务组件、业务 hooks、字段映射、权限逻辑和页面组合。
-- `api-client`: 放契约生成或手写 API 调用，不直接依赖 UI。
-- `model/schema`: 放类型、枚举、表单校验和 URL query 解析。
-
-复用准入：
-
-- 新通用组件必须至少有两个明确使用场景，或是基础 primitive。
-- 业务语义不稳定时留在 feature 内，不提前抽到 `packages/ui`。
-- 通用组件必须有 props 契约、状态矩阵、story 和可访问性说明。
-- generated types 可以作为数据输入类型，不能决定 UI primitive 的命名和职责。
-
-## 6. 交互与文案规则
-
-每个关键操作必须定义：
-
-- 触发条件、禁用条件、加载反馈、成功反馈、失败反馈。
-- inline error、toast、modal confirm 的使用边界。
-- dirty 状态如何产生、如何保存、何时清除。
-- 重试、取消、关闭、返回是否保留用户输入。
-- 空态文案、错误文案、权限文案、按钮文案和长文本截断规则。
-
-空态必须区分“系统没有数据”和“筛选后没有结果”。错误态必须包含用户可执行的恢复路径。
-
-状态不是给评审看的页面说明。`loading / empty / error / disabled / permission / mobile` 等状态必须由真实状态源驱动，例如 API 请求状态、权限结果、空数据集合、表单 dirty/valid 状态、路由或 query 参数、feature flag、响应式断点、story controls 或可控 mock。页面可以有用户可见文案，但不能出现“这里是 loading 状态”“权限态展示如下”等占位说明来冒充实现。
-
-每个 P0/P1 状态都必须能在代码和证据中追溯到：
-
-- 状态源：store、query、hook、props、fixture、mock response、viewport 或权限判断。
-- 渲染分支：组件条件分支、状态组件、disabled 属性、error boundary、empty renderer 或 responsive layout。
-- 触发路径：用户操作、API 响应、测试 seed、story control、query 参数、mock scenario 或 viewport。
-- 复验证据：story、interaction test、E2E 步骤、截图矩阵或 visual parity finding。
-
-## 7. 可访问性规则
-
-前端规格至少覆盖：
-
-- 键盘路径和焦点顺序。
-- 弹窗、抽屉、菜单的 focus trap 和关闭方式。
-- 表单错误与输入控件的关联。
-- 加载、保存成功、失败的屏幕阅读器提示。
-- 色彩不能作为唯一信息来源。
-- 移动端触控目标不小于 44x44px，除非平台规范另有说明。
-
-## 8. 性能预算
-
-前端设计阶段必须说明是否存在以下风险：
-
-- 首屏依赖过多组件、图标、图表或动画库。
-- 表格超过 100 行、复杂筛选、虚拟滚动或服务端分页需求。
-- 图片、头像、缩略图或远程媒体影响布局稳定。
-- 动效或重排可能影响滚动和输入响应。
-
-如果页面包含复杂表格、图表或列表，必须在 `frontend-architecture.md` 或 DEV-PLAN 中写明 client/server 分界和性能验证方式。
-
-## 9. 证据要求
-
-前端任务完成声明至少包含：
-
-- story / interaction / E2E 中的对应状态覆盖。
-- desktop 和 mobile 的真实浏览器截图。
-- visual parity 结论。
-- 可访问性 smoke 结论或明确豁免。
-- 性能风险检查结论；复杂页面需附性能预算验证。
-
-## 10. State Surface Gate
-
-前端任务进入实现前，必须把状态暴露方式写进 plan 或当前 task 的 `state_surface`。可接受的状态表面包括：
-
-- Storybook / story 文件：适合组件、页面片段、状态矩阵和视觉回归。
-- 真实 route + query / fixture：适合页面级状态、权限态和深链路复现。
-- Mock scenario / MSW / API fixture：适合 loading、empty、error、权限和异常返回。
-- E2E seed / test data：适合跨页面流程、保存、删除、批量操作和副作用验证。
-- Viewport matrix：适合响应式、移动端重排和触控行为。
-
-每个 P0/P1 状态至少要有一个可运行入口，并写明评审看哪里、回归跑什么、失败证据放哪里。状态只存在于设计稿、截图或聊天说明中时，Stage 1 应要求补状态表面，而不是让实现任务继续猜。
+# Frontend Quality Rules
+
+本文件定义前端页面从“能用”到“可交付”的最低质量尺子。它服务于 `spec-to-ui-to-code-workflow.md`、`design-brief.md`、`image-to-frontend-spec.md`、`component-map.md`、`screen-states.md` 和 `visual-parity-review.md`，不替代项目自己的品牌规范或产品需求。
+
+## 1. 质量分级
+
+| 等级 | 定义 | 必备证据 | 不能声称 |
+| --- | --- | --- | --- |
+| P0 可用 | 主路径能完成，关键控件可操作 | 主路径 story 或 E2E，基本截图 | 生产级体验 |
+| P1 完整 | default / loading / empty / error / permission / long content / mobile 有规格和验证 | 状态矩阵、story 覆盖、移动端截图 | 视觉精修完成 |
+| P2 精修 | 视觉层级、响应式、动效、可访问性和文案有明确标准并通过评审 | visual parity、a11y smoke、responsive matrix | 可无限复用 |
+| P3 生产级 | 架构可维护，组件边界清晰，性能预算和回归证据完整 | frontend architecture、performance budget、regression evidence | 无需后续治理 |
+
+`feature_impl` 的前端任务如果没有写明目标等级，默认按 P1 验收；用户可见核心流程默认至少 P2。
+
+## 2. 审美反模式
+
+以下情况出现任意一项，Stage 1 或视觉评审应要求返工，除非 Design Brief 明确说明原因：
+
+- 页面只由大块卡片堆叠组成，缺少信息层级。
+- 全页面灰白无重点，主要操作、危险操作和状态反馈不可区分。
+- 使用无意义渐变、装饰图形或营销式 hero 来包装操作型后台页面。
+- 所有按钮、标签、状态、表格行的视觉权重相同。
+- 表格密度失控：行高、列宽、数字、标签和操作区没有扫描节奏。
+- 移动端只做横向滚动，没有重排、折叠或卡片化策略。
+- loading / empty / error 只是一行临时文案，没有恢复路径。
+- 图标、颜色或动画只起装饰作用，不能帮助识别状态或操作。
+
+## 3. 动效规则
+
+动效必须解释状态变化，不承担主要信息表达。
+
+| 场景 | 推荐动效 | 时长 | 约束 |
+| --- | --- | --- | --- |
+| 弹窗 / 抽屉打开 | opacity + scale 或 translate | 120-180ms | 必须有焦点管理 |
+| 筛选 chip 增删 | opacity + slight translate | 100-160ms | 不得推动整页大范围跳动 |
+| 表格刷新 | skeleton / row fade | 120-220ms | 高频刷新时禁用行级动画 |
+| 空态 / 错误态切换 | opacity | 120-180ms | 文案和恢复操作优先 |
+| 保存成功 / dirty 清除 | button state + inline status | 120-180ms | 不得只依赖 toast |
+
+硬约束：
+
+- 首选 `transform` 和 `opacity`，不得用会持续触发布局的动画属性。
+- 必须支持 `prefers-reduced-motion` 或等价 reduced motion 开关。
+- 动效不能隐藏错误、禁用、权限不足或保存失败。
+- 动效失败时页面仍必须可用。
+
+## 4. 响应式规则
+
+每个用户可见页面都必须写清楚 desktop / tablet / mobile 的布局策略。
+
+| 视口 | 必须说明 | 常见策略 |
+| --- | --- | --- |
+| Desktop >= 1200px | 主内容宽度、侧栏、表格列、操作区位置 | 横向筛选条 + 数据表 + 分页 |
+| Tablet 768-1199px | 筛选换行、列显隐、操作折叠 | 筛选条换行，次要列隐藏 |
+| Mobile < 768px | 筛选入口、表格替代形态、底部操作、触控尺寸 | 筛选抽屉，表格转卡片，分页简化 |
+
+移动端禁止只依赖横向滚动完成主要流程。若表格必须横向滚动，必须说明原因、最小宽度、冻结列或摘要卡片替代方案。
+
+移动端和嵌入式 WebView 额外约束:
+
+- 必须说明 iOS 刘海屏、灵动岛、底部 Home Indicator、Android 状态栏 / 导航栏的安全区策略。
+- 键盘弹起后，输入框、提交按钮和错误提示不得被遮挡。
+- 横竖屏切换后，主流程不能丢失状态或出现不可操作区域。
+- 必须说明 iOS / Android 差异处理，例如返回行为、系统分享、文件选择、支付或推送能力差异。
+- 如果存在相机、相册、定位、麦克风、通知、蓝牙、文件等权限，必须说明权限申请、拒绝回退和二次授权路径。
+- 如果存在切后台、切前台、登录过期、支付中断、网络重连或推送唤起，必须说明生命周期 / 中断恢复策略。
+- 发布前至少定义真机 / 系统版本矩阵，不允许只在桌面浏览器或单一模拟器上声称移动端通过。
+
+## 5. 组件复用边界
+
+- `ui primitives`: 只放按钮、输入、弹窗、菜单、表格基础结构等无业务语义组件。
+- `data-table`: 只放排序、筛选、分页、列显隐、空态容器等表格通用行为。
+- `features/<domain>`: 放业务组件、业务 hooks、字段映射、权限逻辑和页面组合。
+- `api-client`: 放契约生成或手写 API 调用，不直接依赖 UI。
+- `model/schema`: 放类型、枚举、表单校验和 URL query 解析。
+
+复用准入：
+
+- 新通用组件必须至少有两个明确使用场景，或是基础 primitive。
+- 业务语义不稳定时留在 feature 内，不提前抽到 `packages/ui`。
+- 通用组件必须有 props 契约、状态矩阵、story 和可访问性说明。
+- generated types 可以作为数据输入类型，不能决定 UI primitive 的命名和职责。
+- 修改 existing 公共组件时，必须列出受影响调用方、兼容策略和回归测试；不能为了一个页面直接改坏全局行为。
+- 优先通过 wrapper、variant、slot、可选 props 扩展现有组件，不直接破坏旧 props 契约。
+
+## 6. 交互与文案规则
+
+每个关键操作必须定义：
+
+- 触发条件、禁用条件、加载反馈、成功反馈、失败反馈。
+- inline error、toast、modal confirm 的使用边界。
+- dirty 状态如何产生、如何保存、何时清除。
+- 重试、取消、关闭、返回是否保留用户输入。
+- 空态文案、错误文案、权限文案、按钮文案和长文本截断规则。
+
+表单体验至少补充：
+
+- 校验触发时机：blur / submit / input
+- 错误字段聚焦策略
+- submitting 与 disabled 的区分
+- 防重复提交策略
+- 输入格式与键盘类型策略
+- 成功 / 失败后的恢复或保留输入策略
+
+空态必须区分“系统没有数据”和“筛选后没有结果”。错误态必须包含用户可执行的恢复路径。
+
+状态不是给评审看的页面说明。`loading / empty / error / disabled / permission / mobile` 等状态必须由真实状态源驱动，例如 API 请求状态、权限结果、空数据集合、表单 dirty/valid 状态、路由或 query 参数、feature flag、响应式断点、story controls 或可控 mock。页面可以有用户可见文案，但不能出现“这里是 loading 状态”“权限态展示如下”等占位说明来冒充实现。
+
+每个 P0/P1 状态都必须能在代码和证据中追溯到：
+
+- 状态源：store、query、hook、props、fixture、mock response、viewport 或权限判断。
+- 渲染分支：组件条件分支、状态组件、disabled 属性、error boundary、empty renderer 或 responsive layout。
+- 触发路径：用户操作、API 响应、测试 seed、story control、query 参数、mock scenario 或 viewport。
+- 复验证据：story、interaction test、E2E 步骤、截图矩阵或 visual parity finding。
+
+除 `loading / empty / error / disabled / permission / mobile` 外，如场景存在，还应显式覆盖：
+
+- `submitting`
+- `retry`
+- `offline`
+
+## 7. 可访问性规则
+
+前端规格至少覆盖：
+
+- 键盘路径和焦点顺序。
+- 弹窗、抽屉、菜单的 focus trap 和关闭方式。
+- 表单错误与输入控件的关联。
+- 加载、保存成功、失败的屏幕阅读器提示。
+- 色彩不能作为唯一信息来源。
+- 移动端触控目标不小于 44x44px，除非平台规范另有说明。
+
+## 8. 性能预算
+
+前端设计阶段必须说明是否存在以下风险：
+
+- 首屏依赖过多组件、图标、图表或动画库。
+- 表格超过 100 行、复杂筛选、虚拟滚动或服务端分页需求。
+- 图片、头像、缩略图或远程媒体影响布局稳定。
+- 动效或重排可能影响滚动和输入响应。
+
+如果页面包含复杂表格、图表或列表，必须在 `frontend-architecture.md` 或 DEV-PLAN 中写明 client/server 分界和性能验证方式。
+
+## 9. 证据要求
+
+前端任务完成声明至少包含：
+
+- story / interaction / E2E 中的对应状态覆盖。
+- desktop 和 mobile 的真实浏览器截图。
+- visual parity 结论。
+- 可访问性 smoke 结论或明确豁免。
+- 性能风险检查结论；复杂页面需附性能预算验证。
+
+## 10. State Surface Gate
+
+前端任务进入实现前，必须把状态暴露方式写进 plan 或当前 task 的 `state_surface`。可接受的状态表面包括：
+
+- Storybook / story 文件：适合组件、页面片段、状态矩阵和视觉回归。
+- 真实 route + query / fixture：适合页面级状态、权限态和深链路复现。
+- Mock scenario / MSW / API fixture：适合 loading、empty、error、权限和异常返回。
+- E2E seed / test data：适合跨页面流程、保存、删除、批量操作和副作用验证。
+- Viewport matrix：适合响应式、移动端重排和触控行为。
+
+每个 P0/P1 状态至少要有一个可运行入口，并写明评审看哪里、回归跑什么、失败证据放哪里。状态只存在于设计稿、截图或聊天说明中时，Stage 1 应要求补状态表面，而不是让实现任务继续猜。