# draw2code_generate 产品流程

状态：核心流程已实现；真实 Harness 回归验收中。

## 1. 产品定位

`draw2code_generate` 只负责把当前画板中用户选定的原型页面，转换成一个可直接打开、可以点击体验、并经过真实预览验收的单文件 HTML Demo。

它不负责重新梳理产品需求，不搭建正式前端工程，也不接管生成完成后的长期页面修改。用户只有再次明确提出“根据最新画板重新生成”时，才重新进入 generate。

三个阶段的职责边界：

| 阶段 | 负责 | 不负责 |
| --- | --- | --- |
| `create` | 产品目标、用户、核心流程、页面、模块和组件语义 | 品牌视觉与正式前端表现 |
| `draw2code_update` | 原型结构、文案、mock 数据和交互事实 | 品牌视觉与前端代码 |
| `generate` | 页面范围、整体视觉方向、单文件 HTML 和真实预览验收 | 重新设计产品、正式工程和后续长期修改 |

## 2. 设计原则

1. **智能补缺**：先读取画板、可用的 create 简报、已有 HTML 和已有视觉方向；能确定的内容直接继承，只询问会显著改变结果且当前无法判断的决策。
2. **选择优先**：页面范围和视觉方向让用户直接选择，不要求用户重新输入选项。
3. **推荐不替代决定**：系统将推荐页面置顶并显式标记、解释原因；宿主支持预选时可以默认勾选。当前 DSH 选择组件不支持预选，因此保持未选状态，用户拥有最终范围控制权。
4. **一次统一确认**：准备阶段不逐项复述确认；真正写页面前只展示一次生成简报。
5. **原型先成为事实**：结构、文案、mock 数据和交互缺失必须先补回画板，不能只在 HTML 中偷偷增加。
6. **实现问题由 Agent 闭环**：代码、样式和交互故障自动修复；只有修复会改变产品意图时才询问用户。
7. **原型是事实而不是像素模板**：页面、信息层级、文案、mock 数据、组件语义和交互关系必须保留；前端布局应使用内容流、Grid/Flex 和响应式约束重新组织，不能照搬 Excalidraw 绝对坐标。
8. **可见结果才算完成**：文件写出不等于完成，必须打开预览、逐页截图、检查控制台与 DOM/布局并走通核心流程。

## 3. 正常流程

```text
用户明确提出生成页面
  → 读取当前画板、create 简报、已有 HTML 和视觉方向
  → 展示全部页面，将智能推荐置顶并标记推荐原因
  → 用户确认页面范围
  → 确定、继承或修改整体视觉方向
  → 从原型推断移动端或桌面端；只有歧义时询问
  → 执行原型可生成性检查
  → 有阻断问题则返回画板补齐并由用户检查
  → 展示一次最终生成简报
  → 用户确认
  → 生成单文件 HTML
  → 自动打开预览，逐页截图并检查控制台、DOM 和布局
  → 走通核心流程
  → 自动修复实现问题并重新验收
  → 提交结构化验收证据
  → 工具门禁通过后报告完成，generate 结束
```

正常首次生成通常只有三次用户交互：

1. 选择页面范围；
2. 首次选择整体视觉方向；
3. 确认最终生成简报。

后续明确重新生成时通常只有两次：选择页面范围、确认生成简报。视觉方向默认继承。

## 4. 页面范围

每次 generate 都必须展示当前画板上的全部可识别页面，让用户明确选择本次范围。新页面由 `rectangle + customData.role=prototype-page + pageName` 表示；旧命名 Frame 继续作为兼容页面读取。

规范参数使用 `pages`，结果使用 `pageNames`；deprecated `frames`/`frameNames` 至少保留一个兼容版本。若 `pages` 与 `frames` 同时传入但页面集合不同，工具返回 `page-scope-conflict`，不猜测优先级。

新页面外框上方使用独立 `prototype-page-label` 文字；页面内容按几何位置归属，页面子元素保持 `frameId=null`。跨页 Arrow 通过两端 binding 或端点位置解析为 `pageRelations`，不作为任一页面的 UI 元素进入生成范围；同页 Arrow 仍作为页面内部交互。页面矩形重叠导致归属不唯一时只返回 warning，不移动用户内容。

系统必须将推荐页面置顶、标记为“推荐”并显示原因；宿主支持预选时可以默认勾选：

- 用户本次明确点名；
- 页面尚未生成；
- 页面在上次生成后发生变化；
- 页面属于核心流程；
- 页面是所选页面的必要入口；
- 页面与所选页面存在直接交互关系。

如果用户选择的范围无法形成完整流程，系统推荐关联页面并说明原因；宿主支持预选时可以默认勾选，但不强制加入。用户仍可只生成孤立页面。

## 5. create 不是前置条件

经过 create 的项目继承目标端、核心流程、页面、mock 数据要求和已确认假设，不重复询问。

没有经过 create 的手绘或导入画板也可以直接 generate：从统一页面边界、组件、箭头、文案和 mock 数据建立生成简报，只补充画板无法回答且会显著改变结果的事项。

## 6. 视觉方向

首次生成时，根据产品类型提供 3–5 个整体视觉方向并标出推荐项。用户可以选择方向、附参考图或自定义补充；不分别询问颜色、字体、圆角、阴影等参数。

视觉方向属于项目级生成设定：后续默认继承，在最终简报中显示，并允许用户修改。

用户仍然只选择一个整体方向，generate 在内部把它展开为结构化视觉简报：页面气质、背景层次、主操作、语义色、信息密度、字体层级、布局策略、动效和视觉焦点。这个展开过程不增加用户问题，但避免 Agent 只把“简洁现代”当成空泛形容词。

视觉冲突优先级：

1. 用户本次明确要求；
2. 本次参考图或所选视觉方向；
3. 已有 HTML 风格；
4. 系统默认推荐。

画板决定产品结构和内容，不参与品牌视觉冲突。只有本次文字要求与参考图无法兼容时才询问用户。

## 7. 设备与布局

- 手机尺寸页面默认生成移动端 H5；
- 桌面尺寸页面默认生成桌面 Web；
- 同一画板包含两类布局时，才让用户选择分别生成或指定主版本；
- 原型几何只用于理解相对关系，不作为最终 CSS 坐标；
- 默认使用内容流、CSS Grid/Flex、容器和响应式约束重排，减少 `absolute`/`fixed`；
- 移动端至少验证 320–430px 宽度，且必须检查横向溢出和内容裁切；
- 可以自动处理基础响应式布局，但不能自行发明原型未设计的另一套产品结构；
- 移动端页面本体不额外套手机边框。

## 8. 原型可生成性检查

阻断问题必须先解决：

- 页面只有空框或无法理解用途；
- 关键按钮没有文案；
- 列表、聊天、图表等缺少必要 mock 数据；
- 核心操作没有入口或核心流程断开；
- 组件严重裁切、错位或不可见；
- 用户选择的页面不存在；
- 当前画板没有可生成页面。

非阻断提醒允许使用合理默认值继续：

- 次要辅助文案或图标缺失；
- 次要动画未定义；
- 非核心状态没有完整设计；
- 不影响核心流程的装饰细节不明确。

非阻断提醒只进入最终简报，不逐项询问。

用户面对阻断问题时可以返回画板自行补充，或让 Agent 自动补齐。Agent 自动补齐必须先更新画板，用户看到并确认补齐结果后，才恢复原 generate 流程；页面范围和视觉方向不重复选择。

## 9. 最终生成简报

生成前只确认一次。简报展示后使用可点击的“确认生成 / 修改页面范围 / 修改视觉方向”选项，不要求用户在输入框里手动输入“确认”。简报包含：

- 当前画板；
- 本次选中的页面；
- 推荐加入的关联页面；
- 新增、更新和保持不变的页面；
- 整体视觉方向及参考图；
- 原型检查结果和非阻断提醒；
- 系统采用的默认假设；
- 会保留的已有内容；
- 可能覆盖用户手工修改的冲突；
- 输出为可直接打开、带 mock 数据和核心交互的单文件 HTML。

## 10. 生成标准

默认产物始终是单文件 HTML，不询问 React、Vue、路由或状态管理等技术选择，也不建立正式工程。

产物至少满足：

- CSS、JavaScript 和 mock 数据内联；
- 多页面在同一 HTML 中切换；
- 每个页面用稳定的 `d2c-page` 起止注释包裹，供后续重新生成时比较未选页面块哈希；
- 页面结构、文案和核心交互与原型一致；
- mock 数据可读且不使用真实敏感数据；
- 按钮、Tab、输入、筛选等具有实际反馈；
- 核心成功流程可以从头走到尾；
- 所有页面遵循同一视觉方向；
- 未选择页面不被误改。

视觉实现至少还应满足：

- 使用 CSS 变量形成一致的颜色、间距、圆角和层级；
- 页面具有明确视觉焦点，每页只突出一个主要任务；
- 真实 mock 数据参与排版，不以空框代替内容；
- 避免无目的渐变、过度圆角、平均用力和通用 AI 模板感；
- 按钮文案水平、垂直居中，底部导航栏目完整且位置一致。

即使原型没有逐项画出，也可以补充让现有交互可用的通用反馈，例如必填校验、提交成功提示、短暂加载和选中状态；不能自行新增页面、模块、角色、业务流程或重大业务规则。

已有 HTML 再次明确 generate 时，只更新本次选中页面；未选择页面保持不变，不与画板冲突的已有增强尽量保留。即将覆盖用户明确的手工修改时，必须在最终简报中说明冲突。始终覆盖统一的当前入口，不创建 generate 版本历史。

## 11. 自动预览验收

生成完成后必须自动打开预览，并验证：

- 本次选择的页面真实可见；
- 每个所选页面都有对应的浏览器截图；
- 目标设备视口已经实际检查；
- 浏览器控制台没有 error 或 warning；
- 页面切换和核心按钮可用；
- 必要的输入、筛选和 Tab 可操作；
- mock 数据正常显示；
- 核心流程可以走通；
- 页面没有横向溢出或关键内容裁切；
- 按钮文案居中，底部导航内容完整；
- 未选择页面没有被误改。

页面打不开、脚本报错、按钮无响应、跳转错误、样式错位或内容未显示，均属于实现问题，Agent 自动修复并重复验收。只有修复需要新增或删除页面、改变流程、模块或业务规则时，才暂停让用户决策。

`action=complete` 不再接受几个自报布尔值作为完成依据。Agent 必须提交结构化 `verificationEvidence`：同一次验收的 `captureId`、生成入口 `outputSha256`、可访问的本地预览 URL、实际视口、覆盖所有相关页面的 PNG 截图文件及 SHA-256、浏览器导出的 DOM 文字快照文件及 SHA-256、控制台 error/warning 列表、布局检查和核心交互检查；多页面范围还必须包含实际页面切换证据。工具会亲自读取预览，确认其内容哈希就是当前生成入口，核对证据文件位于 workspace、属于同一 capture、验证哈希、PNG 尺寸和有限解压，并用 DOM 快照检查原型关键文案和 mock 数据。证据缺失、控制台存在 error/warning、布局检查失败或核心流程失败时，工具保持 `confirmed` 状态并拒绝完成。

已有页面再次生成时，工具在确认阶段保存所有未选 `d2c-page` 页面块的内容哈希，完成时直接比较；不能再用 `unselectedPagesPreserved=true` 代替。旧文件尚无页面边界标记时，首轮迁移要求为未选页面补充截图、DOM 快照和 `unselected-pages-preserved` 检查；当用户选择了全部页面时不产生无意义的未选页面门禁。

文件写出但未通过证据门禁时，不得报告“生成完成”。

## 12. 中断、恢复与结束

中断时保留本次页面选择、视觉方向、原型检查结果和待确认简报。恢复后从中断阶段继续，不重复提问；未通过验收的半成品不能作为完成结果交付。

当 HTML 已写入、预览已打开、所选页面可见、核心流程通过后，generate 结束并把控制权交还给普通 Agent 协作。之后的视觉、内容或交互修改不再属于 generate；只有用户再次明确要求根据画板重新生成时，才开启新一轮流程。

## 13. 产品级实施阶段

### 阶段一：准备与选择

让 generate 从一次性参数调用升级为可恢复的准备流程：读取已有事实、展示全部页面、给出推荐原因、收集页面范围与必要视觉方向。

### 阶段二：原型门禁与统一确认

建立阻断问题和非阻断提醒，支持返回画板补齐后恢复，并输出一次最终生成简报；避免重复确认。

### 阶段三：生成与真实验收

生成单文件 HTML，自动打开预览，按核心流程验收；实现问题自动修复，产品变化才打断用户。

### 阶段四：中断恢复与职责收口

保留未完成流程的准备状态，禁止半成品冒充完成；验收通过后明确结束 generate，后续修改回归普通协作。