263 lines
11 KiB
Markdown
263 lines
11 KiB
Markdown
# 时序图模板
|
||
|
||
> ⚠️ **本模板生成的是位图（PNG）**，不是 PlantUML / mermaid 可编辑时序图。
|
||
> 需要可编辑请用 mermaid / PlantUML / draw.io。
|
||
|
||
本文件用于生成"工程感时序图"：
|
||
|
||
- API 调用时序（前端 → 后端 → DB）
|
||
- 鉴权 / OAuth / 多步握手时序
|
||
- 微服务间消息传递时序
|
||
- 分布式事务 / Saga / 2PC 时序
|
||
- 客户端 - 服务器 - 第三方 三方协议时序
|
||
|
||
特征：
|
||
|
||
- 顶部一排 actor 框（带名字 + 类型 icon）
|
||
- 每个 actor 下方一条垂直虚线（lifeline）
|
||
- 水平消息箭头连接 actors（实箭头同步、虚线箭头异步 / return）
|
||
- lifeline 上有"激活条"（细长矩形）表示该 actor 正在处理
|
||
- 消息可编号（1, 2, 3...）
|
||
- 暗色 grid 背景 + 等宽字体
|
||
|
||
## 适用范围
|
||
|
||
- API 调用时序
|
||
- 鉴权 / OAuth 流程
|
||
- 微服务消息时序
|
||
- 分布式事务 / Saga / 2PC
|
||
- 第三方协议 / SDK 调用流
|
||
|
||
## 何时使用
|
||
|
||
- 用户提到 "时序图 / sequence diagram / 调用时序 / API 流 / OAuth 流 / 分布式事务"
|
||
- 用户希望「actor + lifeline + 消息箭头」标准 UML 时序图样式
|
||
- 用户接受位图
|
||
|
||
不要使用：
|
||
|
||
- 用户要的是「业务流程 / 决策」 → 用 `technical-diagrams/flowchart-decision.md`
|
||
- 用户要的是「状态机」 → 用 `technical-diagrams/state-machine.md`
|
||
- 用户要的是「系统架构」 → 用 `technical-diagrams/system-architecture.md`
|
||
|
||
## 缺失信息优先提问顺序
|
||
|
||
1. 时序名称（"OAuth 2.0 授权码流程 / 下单时序 / Saga 事务"）
|
||
2. 参与的 actors（按从左到右顺序）
|
||
3. 消息序列（按时间顺序，标明 sender → receiver、消息内容、同步 / 异步）
|
||
4. 是否有失败 / 重试分支
|
||
5. 是否有 self-call（actor 调用自己内部方法）
|
||
6. 是否需要消息编号（论文 / 协议描述常需要）
|
||
7. 比例（默认 16:9 横版；actor 多时可用 4:3）
|
||
|
||
## 主模板：标准 UML 时序图
|
||
|
||
📖 描述
|
||
|
||
整张图顶部一排 actor 框，下方每个 actor 一条垂直虚线 lifeline，水平消息箭头连接 actors，激活条标在 lifeline 上，消息编号 + 标签清晰。
|
||
|
||
📝 提示词
|
||
|
||
```json
|
||
{
|
||
"type": "工程感时序图（UML sequence diagram）",
|
||
"goal": "生成一张工程感时序图作为 README / blog / 协议文档配图",
|
||
"canvas": {
|
||
"aspect_ratio": "{argument name=\"aspect_ratio\" default=\"16:9\"}",
|
||
"background": "deep slate #0F172A with subtle 1px grid #1E293B at 32px spacing",
|
||
"outer_padding": "60px"
|
||
},
|
||
"title_strip": {
|
||
"title": "{argument name=\"title\" default=\"OAuth 2.0 Authorization Code Flow\"}",
|
||
"subtitle": "{argument name=\"subtitle\" default=\"with PKCE\"}",
|
||
"position": "top-left, JetBrains Mono / SF Mono, light gray"
|
||
},
|
||
"actors": {
|
||
"count": "{argument name=\"actor_count\" default=\"4\"}",
|
||
"items": [
|
||
{
|
||
"id": "A1",
|
||
"name": "{argument name=\"actor1_name\" default=\"User\"}",
|
||
"type": "{argument name=\"actor1_type\" default=\"user\"}",
|
||
"icon_glyph": "stick figure outline"
|
||
},
|
||
{
|
||
"id": "A2",
|
||
"name": "{argument name=\"actor2_name\" default=\"Web App\"}",
|
||
"type": "{argument name=\"actor2_type\" default=\"client\"}",
|
||
"icon_glyph": "browser window outline"
|
||
},
|
||
{
|
||
"id": "A3",
|
||
"name": "{argument name=\"actor3_name\" default=\"Auth Server\"}",
|
||
"type": "{argument name=\"actor3_type\" default=\"service\"}",
|
||
"icon_glyph": "shield outline"
|
||
},
|
||
{
|
||
"id": "A4",
|
||
"name": "{argument name=\"actor4_name\" default=\"Resource Server\"}",
|
||
"type": "{argument name=\"actor4_type\" default=\"service\"}",
|
||
"icon_glyph": "database / server outline"
|
||
}
|
||
],
|
||
"header_box_style": {
|
||
"shape": "rounded rectangle, corner radius 6px",
|
||
"fill": "type-coded color × 12% opacity",
|
||
"border": "1.5px solid type-coded color",
|
||
"size": "160px wide × 64px tall, all headers identical size, evenly spaced",
|
||
"label": "actor name in mono 11pt + small icon glyph above name"
|
||
},
|
||
"type_color_map": {
|
||
"user": "cyan #22D3EE",
|
||
"client": "blue #60A5FA",
|
||
"service": "emerald #34D399",
|
||
"database": "violet #A78BFA",
|
||
"external": "slate #94A3B8"
|
||
}
|
||
},
|
||
"lifelines": {
|
||
"rule": "每个 actor header 下方画一条垂直虚线 (1px dashed slate #475569)，从 header 底部一直延伸到画布底部",
|
||
"spacing": "lifelines 之间等距，间距 ≥ 200px"
|
||
},
|
||
"messages": {
|
||
"count": "{argument name=\"message_count\" default=\"10\"}",
|
||
"items": [
|
||
{ "id": "M1", "from": "A1", "to": "A2", "label": "1. Click 'Sign in'", "type": "sync" },
|
||
{ "id": "M2", "from": "A2", "to": "A3", "label": "2. GET /authorize?code_challenge=...", "type": "sync" },
|
||
{ "id": "M3", "from": "A3", "to": "A1", "label": "3. Show login page", "type": "return" },
|
||
{ "id": "M4", "from": "A1", "to": "A3", "label": "4. Submit credentials", "type": "sync" },
|
||
{ "id": "M5", "from": "A3", "to": "A2", "label": "5. Redirect with auth_code", "type": "return" },
|
||
{ "id": "M6", "from": "A2", "to": "A3", "label": "6. POST /token { code, code_verifier }", "type": "sync" },
|
||
{ "id": "M7", "from": "A3", "to": "A2", "label": "7. { access_token, refresh_token }", "type": "return" },
|
||
{ "id": "M8", "from": "A2", "to": "A4", "label": "8. GET /api/data (Bearer token)", "type": "sync" },
|
||
{ "id": "M9", "from": "A4", "to": "A4", "label": "9. validate token", "type": "self" },
|
||
{ "id": "M10", "from": "A4", "to": "A2", "label": "10. { data: ... }", "type": "return" }
|
||
],
|
||
"message_style": {
|
||
"sync": "solid line 1.5px slate #94A3B8, filled triangle arrowhead at target",
|
||
"async": "solid line 1.5px slate #94A3B8, hollow triangle arrowhead",
|
||
"return": "dashed line 1.5px slate #64748B, hollow triangle arrowhead",
|
||
"self": "horizontal arrow that loops out to the right and back to the same lifeline (bracket shape)"
|
||
},
|
||
"label_format": "<编号>. <消息内容>，例如 '5. Redirect with auth_code'，mono 10pt，标在 arrow 上方居中"
|
||
},
|
||
"activation_bars": {
|
||
"enabled": "{argument name=\"activation_bars_enabled\" default=\"true\"}",
|
||
"rule": "在 actor lifeline 上画细长矩形（4-6px 宽）覆盖该 actor 处理消息的时间段；颜色用 actor 的 type color，半透明",
|
||
"vertical_extent": "从该 actor 收到一个 message 开始，到它发出 return 结束"
|
||
},
|
||
"annotations": {
|
||
"notes": {
|
||
"enabled": "{argument name=\"notes_enabled\" default=\"false\"}",
|
||
"rule": "可在某段时序旁画黄色便签（amber 半透明圆角矩形），加注释；如 'PKCE prevents code interception'"
|
||
},
|
||
"loops_alts": {
|
||
"enabled": "{argument name=\"loops_alts_enabled\" default=\"false\"}",
|
||
"rule": "可用 UML alt / loop 框：圆角矩形包围多条消息，左上角标 'alt' / 'loop' + 条件文本"
|
||
}
|
||
},
|
||
"legend": {
|
||
"enabled": true,
|
||
"position": "bottom-right",
|
||
"content": "actor type → color, message style → meaning (sync solid arrow / async hollow / return dashed / self bracket)",
|
||
"style": "small panel, semi-transparent bg, mono 10pt"
|
||
},
|
||
"constraints": {
|
||
"must_keep": [
|
||
"actor headers 等大小、等间距、水平对齐",
|
||
"lifelines 垂直、等间距",
|
||
"messages 严格按时间从上到下排列",
|
||
"每条 message 有编号 + 简洁标签",
|
||
"sync / return / async 用不同箭头风格区分",
|
||
"暗色 grid 背景 + 等宽字体",
|
||
"legend 必画"
|
||
],
|
||
"avoid": [
|
||
"actor header 大小不一",
|
||
"messages 不按时间顺序",
|
||
"self-call 画成水平直线（必须 bracket / loop 形）",
|
||
"return 用实线箭头（破坏语义）",
|
||
"label 与 lifeline 重叠",
|
||
"用 emoji 当 actor 图标",
|
||
"actor > 6 个（拥挤；考虑拆分）",
|
||
"messages > 15 条（视觉爆炸；考虑分子时序）",
|
||
"声称这是可编辑 SVG"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 参数策略
|
||
|
||
- **必问**：`title`、actors 列表、messages 序列（含 from/to/label/type）
|
||
- **可默认**：`activation_bars_enabled`（true）、`type_color_map`、`notes_enabled`（false）、`loops_alts_enabled`（false）
|
||
- **可随机**：actor icon glyph 具体造型、消息标签字号微调
|
||
|
||
### 自动补全策略
|
||
|
||
- 用户给"我要画 OAuth 流程" → 默认 4 actor + 10 消息（用户 → web → auth → resource）
|
||
- 用户没说 sync / async → 默认 sync；明显的回调 / 通知场景默认 async
|
||
- 用户说"含失败重试" → 启用 `loops_alts_enabled` + alt block 包围
|
||
- 用户说"加注释解释" → 启用 `notes_enabled`
|
||
- 用户说要 light 模式 → 用变体 1
|
||
|
||
## 变体 1：浅色 Light 时序图
|
||
|
||
```json
|
||
{
|
||
"modify": {
|
||
"background": "warm off-white #F8FAFC + faint grid #E2E8F0",
|
||
"actor_header_fill": "type color × 8% opacity",
|
||
"actor_header_border": "1.5px solid (deeper shade for white bg)",
|
||
"label_color": "deep slate #0F172A",
|
||
"lifeline_color": "slate #94A3B8 dashed",
|
||
"vibe": "白底文档 / 印刷版友好"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 变体 2：协议握手 / OAuth / 鉴权专用风
|
||
|
||
```json
|
||
{
|
||
"modify": {
|
||
"messages_emphasis": "为安全 / token 类消息加 🔒 等价 glyph 或 'TLS' / 'signed' 小标签",
|
||
"extras": "在 message 上额外标 HTTP method（GET/POST/PUT），加微小 mono 标签",
|
||
"annotation": "加 PKCE / nonce / state 解释 note，notes_enabled = true",
|
||
"use_case": "OAuth 2.0 / OIDC / SAML / mTLS 等协议"
|
||
}
|
||
}
|
||
```
|
||
|
||
适用：协议教学、鉴权流程文档。
|
||
|
||
## 变体 3：分布式事务 / Saga / 2PC 风
|
||
|
||
```json
|
||
{
|
||
"modify": {
|
||
"actor_types": "通常 4-5 个 service actor + 1 个 coordinator + 1 个 message broker",
|
||
"messages_emphasis": "明确标 prepare / commit / rollback / compensate 阶段，用不同颜色 (commit 绿、rollback 红、prepare 蓝)",
|
||
"loops_alts_enabled": true,
|
||
"alt_blocks": "alt 'commit phase' / 'rollback phase' 包围相应消息",
|
||
"use_case": "Saga / 2PC / TCC / outbox pattern 教学和文档"
|
||
}
|
||
}
|
||
```
|
||
|
||
适用：分布式事务模式教学、架构 review、failure mode 分析。
|
||
|
||
## 避免事项
|
||
|
||
- 时序图但 messages 不按时间从上到下 → 失去时序性
|
||
- 用菱形 / 圆形当 actor（必须矩形 header）
|
||
- self-call 画成直线（必须 bracket）
|
||
- return 用实线（与 sync 混淆）
|
||
- actor > 6 → 视觉拥挤，考虑拆分
|
||
- messages > 15 → 视觉爆炸
|
||
- 用 emoji 当 actor 图标
|
||
- 把 actor 头像做成卡通人物 → 失去工程感
|
||
- 没有 activation 条 → 看不出谁在处理
|
||
- 没有 message 编号（教学场景必须有）
|
||
- 把"流程图"画成时序图（节点应该是动作而非 actor）
|