# Spec To UI To Code Workflow 模板

## 1. 工作流目标

- 当前 feature:
- 当前设计来源:
- 当前 contract 来源:
- 当前需要打通的主流程:

## 2. 顺序

```text
Product Skeleton
  -> page-inventory draft + requirement-interface-matrix draft + page-rules-draft
  -> early-ai-image-brief
  -> AI 生成 / 编辑第一轮界面方向图
  -> early-ui-review
  -> PRD / 页面 / 状态 / 字段 / 验收反哺
  -> Product Spec
  -> acceptance-criteria + acceptance-examples
  -> requirement-interface-matrix + traceability-matrix + difficulty-research
  -> test-matrix + risk-based-test-plan + regression-plan + test-data-plan + test-data-matrix
  -> Design Brief
  -> Frontend Quality Rules + Frontend Architecture
  -> CSS / tokens / component / motion / responsive rules
  -> AI image brief
  -> AI 生成 / 编辑前端界面图
  -> UI image review
  -> image-to-frontend-spec
  -> component-map + screen-states + design-tokens
  -> frontend stories / components / pages
  -> browser screenshot + visual parity review
  -> OpenAPI contract
  -> generated client + mock server
  -> integration + e2e + visual regression
  -> failure triage + repair/retest loop
  -> knowledge archive + catalog update
```

## 3. 真相源

- Product Spec:
- Product Skeleton:
- Page Rules Draft:
- Early AI Image Brief:
- Early UI Review:
- Acceptance Criteria:
- Acceptance Examples:
- Traceability Matrix:
- Test Strategy:
- Risk Based Test Plan:
- Regression Plan:
- Evidence Protocol:
- Design Brief:
- Frontend Quality Rules:
- Frontend Architecture:
- 设计稿:
- Component Map:
- Screen States:
- Design Tokens:
- DEV-PLAN:
- OpenAPI:
- Verify Matrix:
- Knowledge Catalog:

## 4. 每阶段交付物

### Phase 1A: Product Skeleton

- [ ] `prd-lite.md` 初稿，至少包含目标、非目标、范围边界和角色。
- [ ] `page-inventory.md` 初稿，至少覆盖所有 P0 页面。
- [ ] `requirement-interface-matrix.md` 轻量版，至少把每条 P0/P1 需求映射到页面、区域、字段、操作和状态。
- [ ] `docs/design/page-rules-draft.md`，写清页面类型、信息密度、基础视觉方向、关键组件、状态要求和禁止事项。
- [ ] P0 页面已有主任务、核心字段、主要操作和异常/空/加载/权限状态草案。

### Phase 1B: Early AI Image Direction

- [ ] `docs/design/early-ai-image-brief.md`。
- [ ] 第一轮 AI 生成 / 编辑的界面方向图，保存到 `artifacts/ai-images/early/`。
- [ ] `docs/design/early-ui-review.md`。
- [ ] `early-ui-review.md` 已检查：每条 P0/P1 需求是否能在图中找到界面证据，图片是否暴露页面数量、字段过载、路径过长、后台表格密度、移动端状态和权限视图问题。
- [ ] `early-ui-review.md` 的结论已回填到 `prd-lite.md`、`page-inventory.md`、`state-matrix.yaml` 和 `requirement-interface-matrix.md`。

### Phase 1C: Product Spec Completion

- [ ] `prd-lite.md`
- [ ] `page-inventory.md`
- [ ] `state-matrix.yaml`
- [ ] `acceptance-criteria.md`
- [ ] `ACCEPTANCE_CRITERIA.md`
- [ ] `ACCEPTANCE_EXAMPLES.md`
- [ ] `requirement-interface-matrix.md`
- [ ] `TRACEABILITY_MATRIX.md`
- [ ] `difficulty-research.md`
- [ ] `TEST_STRATEGY.md`
- [ ] `test-matrix.md`
- [ ] `RISK_BASED_TEST_PLAN.md`
- [ ] `REGRESSION_PLAN.md`
- [ ] `test-data-plan.md`
- [ ] `TEST_DATA_MATRIX.md`
- [ ] `EVIDENCE_PROTOCOL.md`
- [ ] `failure-triage.md`
- [ ] 目标、非目标、范围边界
- [ ] 角色与权限矩阵
- [ ] 异常流程、风险、假设、待确认点
- [ ] 每条 P0/P1 需求都映射到界面、状态、字段、接口和验收
- [ ] 每条 P0/P1 需求都映射到测试层级、测试数据、owner 和 evidence path
- [ ] 每条 P0/P1 需求都映射到 affected tests 和回归范围
- [ ] 每条 P0/P1 需求至少包含一个正向验收示例和一个异常示例
- [ ] 高风险难点已有前置研究结论
- [ ] 完整 Product Spec 没有绕过 Phase 1B 的早期视觉方向图和反哺记录

### Phase 2: Design Brief

- [ ] `design-brief.md`
- [ ] `docs/harness/frontend-quality-rules.md` 已读取，目标质量等级已声明
- [ ] `frontend-architecture.md` 或等价架构说明
- [ ] 信息架构
- [ ] 布局、交互、响应式、动效和可访问性规则
- [ ] CSS / token 要求
- [ ] 审美反模式和禁止事项
- [ ] UX writing、空态、错误态、权限文案规则
- [ ] 性能预算和复杂列表 / 表格处理策略
- [ ] 默认态、加载态、空态、错误态、权限态、极端数据态、移动端状态

### Phase 3: Final AI Image Maker

- [ ] `ai-image-brief.md`
- [ ] 基于 `early-ui-review.md` 和 Design Brief 生成 / 编辑的多状态前端界面图
- [ ] `ui-image-review.md`

### Phase 4: Image To Frontend Spec

- [ ] `component-map.md`
- [ ] `screen-states.md`
- [ ] `design-tokens.json`
- [ ] `frontend-architecture.md`
- [ ] `image-to-frontend-spec.md`
- [ ] `visual-parity-review.md` 截图矩阵已定义
- [ ] stories / interaction / e2e / visual / a11y / performance 映射
- [ ] 稳定测试选择器和关键视觉断言
- [ ] 每个关键状态都写清状态源、渲染分支、触发路径和复验证据，禁止用页面说明文案冒充状态实现
- [ ] desktop / tablet / mobile 响应式行为已写成可验证规格
- [ ] 动效和 reduced motion 规则已写成可验证规格

### Phase 5: Frontend

- [ ] 组件实现
- [ ] 页面实现
- [ ] stories
- [ ] 相关测试已新增或更新
- [ ] 真实浏览器截图保存到 `artifacts/visual-review/`
- [ ] 设计参考图与浏览器实拍图对比 PASS

### Phase 6: Contract First

- [ ] `contracts/openapi.yaml`
- [ ] generated client
- [ ] mock server
- [ ] contract / schema / negative examples

### Phase 7: Regression

- [ ] Stage 1 review
- [ ] Stage 2 review
- [ ] verify
- [ ] affected tests 与 P0/P1 regression 已运行
- [ ] 契约验证、回归计划和 evidence protocol 已按本次变更刷新
- [ ] `verify-matrix.md` 中必需项都有 fresh evidence
- [ ] 若测试失败，`failure-findings.json` 已生成并进入 repair/retest loop

### Phase 8: Knowledge Archive

- [ ] `docs/knowledge/knowledge-catalog.md` 已存在
- [ ] `docs/knowledge/catalog.md` 已按新增或更新条目刷新
- [ ] 可复用 decision / guideline / pitfall / process / model 已归档
- [ ] trace 或最终报告中的 `knowledge_references` 已被处理
- [ ] 新增条目默认 maturity 为 `draft`，不得把单次经验直接提升为 `proven`

## 5. 闸门

- 不能完成 Product Skeleton: 缺 P0 页面清单、需求-界面轻量映射或 `docs/design/page-rules-draft.md`。
- 不能完成 Product Spec: 缺第一轮 AI 界面方向图、`docs/design/early-ui-review.md`，或 early review 结论未反哺到 PRD、页面清单、状态矩阵和需求-界面追溯矩阵。
- 不能进入 Design Brief: Product Spec 缺目标、非目标、范围、角色、页面、可执行验收示例、TRACEABILITY_MATRIX、需求-界面追溯矩阵或早期视觉评审结论。
- 不能进入 AI Image Maker: Design Brief 缺视觉、CSS/tokens、布局、交互、响应式、动效、可访问性、文案或质量等级规则；高风险难点未研究。
- 不能进入 Image To Frontend Spec: UI 图片未评审通过。
- 不能进入前端实现: 缺 `image-to-frontend-spec.md`、`component-map.md`、`screen-states.md`、`design-tokens.json`、`frontend-architecture.md`、稳定测试选择器、响应式规格、动效规格或关键视觉断言。
- 不能通过前端实现: 缺浏览器截图、缺移动端截图、缺设计参考图对比报告、缺 a11y smoke 结论，或 `visual-parity-review.md` Verdict 不是 PASS。
- 不能通过前端实现: `loading / empty / error / disabled / permission / mobile` 等状态只作为界面说明文案出现，缺少真实状态源、渲染分支、触发路径或复验证据。
- 不能进入联调: API / 数据变化没有 contract 或明确豁免。
- 不能结束任务: 缺 Stage 1、Stage 2、verify、affected tests、P0/P1 regression 或 P0/P1 test matrix 的 fresh evidence。
- 不能完成归档: 知识索引与条目不一致，或把一次性结论升级成全局规则却没有 evidence。

## 6. 前端质量参考

前端任务默认读取 `docs/harness/frontend-quality-rules.md`。如项目已有更具体的品牌、设计系统或平台规范，以项目规范为准，但不得低于本流程的状态覆盖、响应式、可访问性、证据和完成声明要求。
