spec-product-demo（R4：基于原型生成可交互 Demo）
概览
R4 的目标是把 {FEATURE_DIR}/requirements/prototype.md 的页面清单与交互说明落地为可运行、可交互的 Demo，用于走查/验证/对齐：
- 唯一页面来源：只能来自
prototype.md/页面/弹窗清单（P-xxx…）（禁止自创页面） - 共享工程模式：默认落到
{REPO_ROOT}/demo/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/ - 先骨架后细节：先跑通路由/导航/跳转链路，再补字段/状态/校验/错误处理
- 数据可 Mock：后端未就绪允许 Mock，但要把“真实数据接入”当作明确替换点
开始时宣布：「我正在使用 spec-product-demo 技能基于 prototype.md 生成可交互 Demo。」
R4 的核心价值是“把线框变成可点可跑”，不是替代设计稿，也不是在 Demo 里自由发挥新增需求。
何时使用 / 不使用
- 使用时机
- 已完成 R3，且存在 {FEATURE_DIR}/requirements/prototype.md - 需要更高保真走查（可用性验证/干系人对齐/研发与测试理解一致性校验）
- 不要用在
- spec-context 失败 → 立刻停止 - {FEATURE_DIR}/requirements/prototype.md 缺失 → 停止并回到 using-aisdlc（路由到 R3：spec-product-prototype） - 仓库里没有可运行的 Demo 工程根目录，且用户未提供 DEMO_PROJECT_ROOT → 停止并要求提供路径
输入 / 输出（落盘约定）
- 硬门禁输入：
FEATURE_DIR（必须由spec-context获取） - 读取
- {FEATURE_DIR}/requirements/prototype.md（必读，页面清单/交互说明 SSOT）
- 可选输入
- DEMO_PROJECT_ROOT：可运行的 Demo 工程根目录（存在 package.json 且包含可启动脚本）
- 写入
- Demo 代码：默认 {REPO_ROOT}/demo/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/（共享工程模式）
门禁（必须先过，否则停止）
1) REQUIRED SUB-SKILL：正在执行 spec-context 获取上下文，并回显 FEATURE_DIR=...（允许 (reuse)）
spec-context失败 → 停止{FEATURE_DIR}/requirements/prototype.md不存在 → 停止（不得“先做个占位 Demo”）
违反门禁=违反精神：无论“老板 10 分钟后评审/先做出来再补/在 main 上先跑一版”，都禁止跳过上下文与输入文件。
2) Demo 工程根目录定位（必须遵守；找不到就停止）
判定“可运行 Demo 工程根目录”的最低标准：
- 目录存在
- 存在
package.json package.json至少包含可启动脚本（例如dev/start/preview其一）
定位规则（从高到低）：
- 优先使用输入：用户提供
DEMO_PROJECT_ROOT→ 以其为准（仍需满足可运行判定） - 未提供则自动查找：
- {REPO_ROOT}/demo/ - {REPO_ROOT}/prototype/ 或 {REPO_ROOT}/prototypes/ - {REPO_ROOT}/apps/demo/、{REPO_ROOT}/packages/demo/
- 查找失败就停止：以上路径均不存在或不满足可运行判定 → 停止 R4，并要求用户提供
DEMO_PROJECT_ROOT
硬禁止：在“未找到可运行 Demo 工程根目录”时，擅自初始化新的前端工程（Vite/Next.js/CRA 等）来“先跑起来”。这会污染仓库、破坏流程可追溯性。
核心流程（从 prototype 到可跑 Demo）
0) 输出目录固定：只写到 prototypes/{SPEC_NUMBER}-{SHORT_NAME}/
在 DEMO_PROJECT_ROOT 下为当前需求创建独立命名空间：
OUTPUT_DIR = {DEMO_PROJECT_ROOT}/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/
规则：
- 需求实现必须落在
OUTPUT_DIR：页面/组件/样式/Mock/交互逻辑等都写在OUTPUT_DIR内，避免污染其他需求 - 允许最小粘合改动：可在 Demo 根工程做最小改动用于“挂载当前需求”（例如路由注册、入口菜单、通用 layout），但禁止修改其他需求的
prototypes/*目录 - 目录名必须精确等于
{SPEC_NUMBER}-{SHORT_NAME}（禁止手写或另起别名）
1) 从 prototype.md 生成页面任务清单（不落盘）
以 prototype.md/页面/弹窗清单 为唯一页面来源（SSOT）：
- 每个
P-xxx至少 1 个任务条目（可再细分） - 每个条目必须包含：
- 页面路由/入口、页面目标 - 主要控件/字段与默认值 - 关键状态（正常/加载/空/错误/无权限）与提示文案要点 - 与任务流节点（T-xxx）及 AC 的映射（引用 prototype.md 位置）
禁止：为“看起来更完整”而新增登录页/设置页/通用布局页等未在 prototype.md 声明的页面。需要新增页面 → 回流 R3 更新 prototype.md 后再做 R4。
2) 先搭骨架（必须先跑通）
先完成：
- 所有页面/弹窗的路由或入口占位
- 导航入口与关键跳转链路（至少覆盖核心任务流主链路）
此阶段允许：
- 仅用静态/Mock 数据渲染
- 仅实现关键按钮与跳转（字段/校验可后补）
3) 再补细节（按优先级）
按“核心主链路优先”补齐：
- 字段与校验（含错误提示要点）
- 状态与异常分支（加载/空/失败/无权限）
- 交互细节（取消/返回/二次确认/恢复路径）
数据依赖未就绪时：
- 用 Mock 数据/Mock API 让交互可跑
- 把“真实数据接入”作为明确替换点（避免把 Mock 当最终实现）
4) 运行与冒烟（完成检查）
最小完成标准（缺一不可）：
- Demo 工程可启动
- 可导航到
OUTPUT_DIR的页面集合 - 关键链路可走通（至少覆盖
prototype.md的核心任务流主链路）
完成后：立即调用 using-aisdlc 路由下一步（通常进入走查/回流，或继续后续阶段）。
完成后输出与自动路由（必须执行）
Demo 落盘至 {DEMO_PROJECT_ROOT}/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/ 后，必须完成以下动作（按顺序，不可省略）：
- 输出 ROUTER_SUMMARY（YAML 形态，供 Router 决策）：
ROUTER_SUMMARY:
stage: R4
artifacts:
- "{DEMO_PROJECT_ROOT}/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/"
needs_human_review: false
blocked: false
block_reason: ""
notes: "软检查点：Demo 建议走查；如不触发硬中断 Router 可继续自动推进"- 立即执行
using-aisdlc：将上述ROUTER_SUMMARY作为路由输入传递给 using-aisdlc，由 Router 判定下一步并自动推进（无需等待用户说「继续」）。
- 若 Router 判定可自动续跑：在同一轮对话内继续执行下一步 worker skill（如 D0、I1 等） - 若 Router 触发硬中断：停下并输出阻断原因、需要的输入、候选下一步
- 对话输出：在调用 using-aisdlc 前，可简短说明「本阶段产物已落盘，正在调用 using-aisdlc 路由下一步。」
Quick reference（高频规则速查）
- 必须
- 先执行 spec-context 获取上下文，只用其输出的 FEATURE_DIR/REPO_ROOT/SPEC_NUMBER/SHORT_NAME - 必须存在 {FEATURE_DIR}/requirements/prototype.md - 页面清单只来自 prototype.md（不加页） - Demo 根目录找不到/不可运行 → 立即停止并要求 DEMO_PROJECT_ROOT - 需求实现写在 {DEMO_PROJECT_ROOT}/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/；Demo 根工程只做最小粘合改动（路由/入口）
- 禁止
- 在 main（或非 {num}-{short-name} 分支）上硬做 R4 - 用“先做占位 Demo”替代缺失的 prototype.md - 未找到 Demo 工程根目录时擅自 npm create vite@latest / npx create-next-app 初始化新工程 - 自创页面/路由并声称“demo 常见”
红旗清单（出现任一条：停止并纠正）
- 没跑
spec-context就开始找/写requirements/*.md或 demo 目录 {FEATURE_DIR}/requirements/prototype.md不存在，却仍要继续- Demo 根目录不存在/不可运行，却仍要“先初始化一个 Vite 工程”
- 在 Demo 里新增
prototype.md未定义的页面（登录/设置/随便加页） - 输出目录不是
prototypes/{SPEC_NUMBER}-{SHORT_NAME}（写到根目录、写错 spec 目录名、或写到别的需求目录）
常见借口与反制（基线测试中的高频点）
| 借口（压力来源） | 常见违规行为 | 必须的反制动作 |
|---|---|---|
| “老板 10 分钟后要看，先在 main 上做一版” | 跳过 spec-context；在 main 上写 demo | 门禁不过就停止：先切到合法 spec 分支并跑 spec-context；否则只能交付“阻断原因 + 需要的输入/下一步” |
| “prototype 还没写/找不到，就先做个占位 Demo” | 自创页面与流程，导致不可追溯 | prototype.md 缺失 → 回到 using-aisdlc 路由到 R3；R4 禁止替代 R3 的交互决策 |
| “仓库里没有 demo/，我先初始化一个 Vite/Next.js 工程” | 在未知位置创建新工程污染仓库 | 停止并要求 DEMO_PROJECT_ROOT；只有在已存在可运行 demo 工程时才允许继续 |
| “顺便加登录页/设置页，demo 常见” | 自创页面，偏离 SSOT | 拒绝加页并回流 R3：先把页面写进 prototype.md 的页面清单（含编号、说明、AC 映射） |
一个好例子（找不到 Demo 根目录时如何正确停止）
当未提供 DEMO_PROJECT_ROOT 且自动查找失败时，应当输出类似结论：
- 阻断原因：当前仓库未发现可运行的 Demo 工程根目录（缺
demo/或缺package.json/启动脚本） - 需要用户提供：
DEMO_PROJECT_ROOT（例如E:\\path\\to\\demo），并说明其必须可启动 - 下一步：拿到
DEMO_PROJECT_ROOT后，在{DEMO_PROJECT_ROOT}/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/生成 Demo