scenario-architect

Skill: Scenario Architect

将 Phase 1/2 已定义的业务场景展开为技术时序图，让 API 设计自然浮现，并设计完整的异常用例。场景编号沿用 Phase 1 定义。

触发条件

• 用户要求画时序图、设计业务场景或进行场景建模
• 用户提到 "Phase 3 Step 1"、"场景驱动"、"技术方案设计"
• 已有需求文档和产品设计文档（含场景定义），需要开始技术实现
• 用户指定某个场景编号（如 S01）需要展开为时序图

核心能力

1. 读取 Phase 1/2 的场景定义和验收条件，作为时序图的输入
2. 为每个场景绘制 Mermaid 时序图（严格遵循编号规范）
3. 为关键步骤撰写说明文字（解释"为什么"而非"做什么"）
4. 识别每个步骤的异常情况，设计结构化的异常用例
5. 生成场景概览文档（场景地图 + 场景索引）

与 Phase 1/2 的衔接

Phase 3 不再从零识别场景。 场景在 Phase 1 已定义（S01, S02...），Phase 2 已细化交互流程，Step 0 已确定技术架构和选型。Phase 3 Step 1 的工作是将同一个场景从"交互视角"展开为"技术视角"，时序图的参与方应与架构图中的系统组件一致：

输入（来自 Phase 1/2）	输出（Phase 3）
场景编号和名称	时序图标题保留编号
触发条件	时序图的起始箭头
主路径描述	时序图的 Step 序列
GIVEN/WHEN/THEN（业务级）	时序图步骤的行为描述
异常验收条件	EX 异常用例（技术级）
涉及的页面和交互（Phase 2）	参与方识别

执行步骤

Step 1: 加载场景上下文

读取 Phase 1 需求文档、Phase 2 产品设计文档和 Phase 3 Step 0 技术架构概要中的场景定义。不要重新发明场景——直接沿用已有编号和描述。参与方命名应与架构图中的系统组件保持一致。

场景粒度前置检查（绘制时序图之前必须执行）：

在继续之前，先验证 Phase 1 中的场景定义是否粒度合理。检查以下反模式：

• 单 API 场景：如果一个场景的主路径只有 1-2 个步骤（如"创建任务"= 仅 POST /api/tasks），粒度过细
• CRUD 碎片化：如果场景列表中对同一实体出现了独立的"创建X"、"查询X"、"更新X"、"删除X"场景，应合并为目标导向的场景
• 缺少业务目标：如果场景的结果只是"数据被写入/读取了"，说明缺少真正的用户目标

如果检测到以上任何反模式：停止绘制时序图，建议回到 Phase 1 按业务目标重新组织场景。为粒度过细的场景绘制时序图会将问题传导到 API 设计、测试用例和代码实现。

确认每个场景的：

• 场景编号：沿用 Phase 1 的 S01, S02...（或 Phase 2 的子场景 S01.1）
• 参与方：从 Phase 2 的交互流程中识别涉及哪些系统组件
• 主路径：从 Phase 1/2 的验收条件中提取正常流程
• 已知异常：从 Phase 1/2 的异常验收条件中提取

Step 2: 绘制时序图

为每个场景绘制 Mermaid 时序图，严格遵循以下规范：

编号规范：

• 每个箭头必须带 Step N: 编号前缀
• 编号从 1 开始连续递增
• 每个箭头附一行行为描述：HTTP方法 /api/路径 — 一句话说明

参与方规范：

• 使用短别名：U（User/Browser）、W（Web/Frontend）、SB（Supabase）、DB（Database）
• 每个参与方的全名在 participant 声明中注明

场景编号规范：

• 文档标题格式：S01: 邮箱注册 — 时序图
• 一个场景一个文件，编号对应 Phase 1

格式示例：

sequenceDiagram
    participant U as User/Browser
    participant W as Web (Astro)
    participant SB as Supabase Auth
    participant DB as Supabase DB

    U->>W: Step 1: POST /api/auth/register — 提交 {email, password, referral_code?}
    W->>SB: Step 2: supabase.auth.signUp(email, password, metadata) — 发起用户创建
    SB-->>W: Step 3: 返回 {user, session} 或 error
    W->>DB: Step 4: INSERT INTO profiles — 写入用户扩展信息
    DB-->>W: Step 5: 返回写入结果
    W-->>U: Step 6: 返回注册结果 + 提示验证邮件