flow-walkthrough 流程联动原型

把 flow-canvas 产出的流程图 SVG 和一组原型页面组装成单文件三栏联动 HTML：左侧可缩放拖拽的流程画布（点节点）、中间设备框（自动在手机框 / 后台宽窗口间切换）、右侧节点标注 + 页面状态切换。用于需求评审时"过流程"演示。

输入（三档，按可得材料降级）

必需：flow-canvas 产出的 SVG（根元素须带 data-flowspec="1"；没有流程图时先调 flow-canvas 生成）。 页面来源按可得性取其一：

1. 调用方已有原型 HTML：从中提取各页面/状态片段作为页面输入（最优）
2. 只有需求文档（PRD）：按 PRD 的页面与状态描述画页面片段，画法和模板内置组件（状态栏、导航栏、列表、弹窗、toast、后台表格等 wt-* 类）见 references/page-guide.md
3. 两者都没有：生成中性占位页，仅演示联动骨架

流程图与页面的对应原则（先于映射）

1. 流程图不画页面容器节点：页面本身不是节点，页面的多个状态才是节点。写 mermaid 时，判断节点之后直接接各状态节点（如「预约表单页：填写中」「预约表单页：约满弹窗」），不要先接一个「预约表单页」再分状态。
2. 无页面的步骤不建节点：纯后台动作、纯数据处理（如「释放已占用的寄养床位」）没有页面可展示，边直接连到下一个有页面的节点，动作说明写进前一节点的标注。
3. 状态只在页面因规则而不同时才建：弹窗、toast、只读态、空态这类由规则决定的页面差异才算状态；按钮文案变了一下、数字变了一下这类无规则差异的表现不建状态。构建器对「两个状态用同一页面文件」给警告。
4. 设备框内只放真实 UI：演示用的切换按钮（「查看接单 / 婉拒」「切到约满态」）一律放右侧「页面状态切换」，不放进手机框。

画页面片段（没有现成原型时）

动手前先读 references/page-guide.md。要点：

• 设备框里只放上线后用户真的会看到的内容；设计理由、边界条件、待确认事项写进节点标注，元素下方不加解释性小字。
• 标注要指向页面位置时用「[A] 位置描述」，编号不画进页面。
• 一个状态一个文件，弹窗态、toast 态用 wt-screen 包住原页面再叠加 wt-modal / wt-toast。
• 手机页面 375px、后台页面放 690px 宽窗口；灰度线框，只画 PRD 里有的内容，禁用 emoji。

执行流程

1. 自动做节点-页面关联：读流程图节点（id 与文案）与页面材料，按语义匹配生成 walkmap JSON（契约见 contract/walkmap-v1.md：pages 页面清单含 frame 类型 phone/wide，nodes 为节点 → 页面 + 标注，state_groups 为页面状态组）。后台类节点（双边线灰底）映射到 frame: "wide" 的页面。
2. 产出关联确认表：在生成最终页面前，把映射以 markdown 表格展示给用户确认——列：流程节点 / 匹配到的页面 / 页面状态（多状态页面写「组名：状态名」，单状态写「单状态」）/ 匹配依据 / 置信度（低置信度行明确标注）。用户确认或修正后再进入下一步。不要跳过这一步直接交付。
3. 构建：

   python3 scripts/build.py walkmap.json -o out.html
   python3 scripts/build.py walkmap.json --check     # 仅校验映射与契约

4. 构建器会校验：SVG 契约版本、页面文件存在、映射完整性（SVG 节点无映射 / 映射节点不在 SVG 都会警告）、产物无 emoji。有 error 必须修复；warning 逐条向用户说明。

右侧边栏：页面状态切换

右侧只有两块内容：节点标注（nodes[].anno）和「页面状态切换」。规则：

• 中间页面单状态：右侧不放任何按钮。
• 中间页面多状态：右侧出现一组状态按钮，当前态高亮不可点，其他态点击切到该态的代表节点，流程图选中同步跟过去。同一页面的所有状态节点看到的是同一组按钮，可以来回切。
• 不放「所属分支」「下一步」「上一步」之类的导航按钮：节点推进靠点左侧流程图，或页面内按钮调 goNode（如约满弹窗的「换个日期」、支付结果页的「完成」）。

walkmap 写法：state_groups 里按页面建组，每组列出状态与代表节点；处在同一状态但不是代表节点的节点（如「进入寄养频道」处在首页的未预约态、「关闭弹窗：停留预约表单页」处在表单页的填写中状态）用 state: "组id/状态id" 声明。示例：

"state_groups": {
  "home": { "title": "寄养首页", "states": [
    { "id": "none",     "label": "未预约",     "node": "C" },
    { "id": "pending",  "label": "待门店确认", "node": "F" },
    { "id": "declined", "label": "已婉拒",     "node": "H1" } ] },
  "form": { "title": "预约表单页", "states": [
    { "id": "filling",  "label": "填写中",       "node": "E" },
    { "id": "full",     "label": "约满弹窗",     "node": "E1" },
    { "id": "prefill",  "label": "带入上次信息", "node": "E2" } ] }
},
"nodes": {
  "A": { "page": "p-home-none", "state": "home/none",    "title": "进入寄养频道" },
  "N": { "page": "p-form",      "state": "form/filling", "title": "关闭弹窗：停留预约表单页" }
}

构建器校验：组内状态少于 2 个、状态引用未定义节点、节点 state 不在任何组里都是 error；两个状态共用同一页面文件、声明节点与代表节点页面不同是 warning。

样式

默认灰度线框（模板内置 CSS 变量）。调用方声明了自己的样式规范时，通过 walkmap 的 css_vars 覆盖（如 {"--wt-accent": "#2f6fed"}）；未声明则用默认。产物禁 emoji（构建器硬校验）。

页面内联动 API

页面片段内可调用 goNode('节点id') 驱动整体联动（如登录按钮点击后跳到下一个流程节点），实现"手机内按钮走通全流程"的演示效果。

环境降级

Windows 上 Python 命令通常是 python 或 py -3，不是 python3，按实际可用的命令替换即可。

无 python3 时：参照 templates/walkthrough.html 手工完成占位符替换（__TITLE__ / __SVG__ / __PAGES_PHONE__ / __PAGES_WIDE__ / __NODES_JSON__ / __PAGE_FRAME_JSON__ / __STATE_GROUPS_JSON__ / __DEFAULT__ / __CSS_VARS__），质量降级并告知用户（无自动校验）。

自检

安装后运行 python3 scripts/selftest.py（含 golden 走查构建、画布全屏、页面状态切换渲染、坏映射与坏状态组报错检查），全部 PASS 才算可用。