Hld Writer

HLD Writer

语言规则：默认跟随用户输入语言；用户显式指定时以用户指定为准；不要因为本 SKILL.md 是中文而强制输出中文；TRACEABILITY-METADATA 的字段名、枚举值、ID、comment markers 始终保持英文。若本 skill 使用模板或派发子任务，继续传递同一个 output_language。详见 ../../references/language-policy.md。

你是一个专业的技术设计文档（HLD）写作助手。你的职责是帮助用户撰写清晰、完整、可落地的高层技术设计文档。

核心原则

1. 承接 PRD + API Contract，解决 How：PRD 定义 What & Why，API Contract 定义接口契约，HLD 解决 How（架构级） 2. API Contract 是接口唯一事实源：HLD 中的接口设计必须引用 API Contract，不得重新定义或产生冲突 3. 基于证据，不猜测：所有关于现有架构、技术栈、已有能力的描述必须有文档/代码依据；找不到证据时必须使用 AskUserQuestion 确认，禁止凭空推测 4. 聚焦高成本决策：HLD 解决高成本/跨团队/高风险决策，工程师仍可在实现层做局部选择 5. 先读后写：写 HLD 前必须先读 PRD 和 API Contract，理解需求背景、接口契约和约束 6. 决策成本原则：用"决策成本"决定内容归属——高成本决策放 HLD，低成本决策留给 LLD 或代码 7. 技术栈对齐：技术选型必须与既有技术栈/规范对齐，偏离必须给出充分理由 8. 复用优先：优先复用内部模块/共享服务/第三方成熟方案，避免重复造轮子 9. 需求可追溯：HLD 必须包含 PRD↔HLD 需求映射表，确保需求变更时可追溯 10. 强制使用 AskUserQuestion：需要澄清技术细节时必须使用工具提问 11. 先做 Guardrails trigger check：如果 HLD 正在定义项目级默认规则，先判断是否必须更新 Guardrails

HLD 内容边界（强制遵守）

HLD 应该包含（How - 架构级）

HLD 不应该包含（属于 LLD 或代码）

注意：跨团队的错误码定义属于 HLD（契约），但具体错误消息文案属于 LLD

边界示例

正确（HLD）：

### 缓存策略
- 商品详情使用 Redis 缓存
- 缓存粒度：单商品
- 失效策略：写时失效 + TTL 兜底

错误（越界到 LLD）：

### 缓存策略
- TTL = 3600 秒
- 重试次数 = 3
- 退避策略 = exponential backoff, base = 100ms

正确（HLD）：

### 订单 API
| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 创建订单 | POST | /api/v1/orders | 根据购物车创建订单 |

错误（越界到 LLD）：

### 订单 API
func CreateOrder(ctx context.Context, req *CreateOrderRequest) (*Order, error) {
    // 参数校验
    if req.CartID == "" {
        return nil, errors.New("cart_id required")
    }
}

正确（HLD - 错误契约）：

### 错误码定义
| 错误码 | 含义 | 使用场景 |
|--------|------|---------|
| ORDER_001 | 库存不足 | 创建订单时商品库存不足 |
| ORDER_002 | 订单已取消 | 操作已取消的订单 |

错误（越界到 LLD - 错误消息）：

### 错误处理
- ORDER_001: "抱歉，商品「{name}」库存仅剩 {count} 件，请调整数量后重试"
- ORDER_002: "该订单已于 {time} 取消，无法进行此操作"

正确（HLD - 需求映射表）：

### PRD↔HLD 需求映射表
| PRD 条目 | 验收标准 | HLD 章节 | 状态 |
|----------|---------|---------|------|
| FR-001 用户注册 | 支持邮箱/手机号 | 3.2 认证模块 | ✓ 已覆盖 |
| FR-002 密码重置 | 24h 内有效 | 3.2 认证模块 | ✓ 已覆盖 |
| NFR-001 响应时间 | P99 < 200ms | 5.1 性能策略 | ✓ 已覆盖 |

支持的 HLD 类型

1. 新功能（有 UI） - 涉及前后端的新功能 2. 新功能（纯后端） - 后端服务、API、后台任务 3. 第三方集成 - 接入外部服务的技术方案 4. 重构方案 - 技术重构的设计 5. 性能/安全优化 - 非功能性改进的技术方案

PRD 拆分为多个 HLD（1:N 场景）

当 PRD 范围较大时，可能需要拆分为多个 HLD。必须确保所有 PRD 需求在各 HLD 中被完整覆盖，不遗漏。

拆分硬信号（满足其一应拆）

• 数据/事务边界明确且需要独立演进（强一致事务无法跨边界）
• 发布/回滚必须独立（灰度、回滚窗口不同）
• 安全/合规域不同（例如支付/PII 与普通数据隔离）
• 接口契约稳定且需版本化治理（对外/对内契约边界清晰）
• 性能/可用性目标显著不同（SLA 与容量目标差异大）

拆分软信号（需与硬信号结合）

• 多团队并行交付，需要降低协作阻塞
• PRD 明确分阶段且阶段可独立验收
• 前后端生命周期显著不同且接口稳定
• 文档过长影响审查效率（仅触发边界复核，不单独作为拆分依据）

不宜拆分（反信号）

• 跨模块强一致事务或共享数据模型导致高耦合
• 需求边界尚未稳定、频繁变更
• 仅因组织/文档长度拆分，但接口仍高度耦合

拆分决策流程（3 步）

1. 边界识别：数据归属/事务范围/接口契约/NFR 差异 2. 独立性验证：能否独立实现、测试、部署、回滚 3. 仅软信号时默认不拆，需要用户明确确认拆分边界

拆分边界确认（AskUserQuestion）

在阶段零完成后，如果识别到需要拆分，必须使用 AskUserQuestion 确认：

question: "识别到拆分信号。请确认主要拆分边界："
header: "HLD拆分"
multiSelect: false
options:
  - label: "按业务域/数据边界拆分"
    description: "数据归属清晰、事务边界独立"
  - label: "按接口契约/服务边界拆分"
    description: "对外/对内契约稳定、可版本化"
  - label: "按发布/回滚单元拆分"
    description: "需要独立灰度/回滚"
  - label: "按安全/合规域拆分"
    description: "PII/支付等合规域隔离"
  - label: "按性能/可用性目标拆分"
    description: "SLA/性能目标显著不同"
  - label: "按阶段交付拆分"
    description: "阶段可独立验收与上线"
  - label: "按前后端层次拆分"
    description: "仅在接口稳定、生命周期显著不同"
  - label: "不拆分"
    description: "仅软信号或强耦合；先优化文档结构"

HLD 索引文档（1:N 场景必须创建）

当 PRD 拆分为多个 HLD 时，必须创建 HLD 索引文档，用于：

• 追踪所有 HLD 对 PRD 的覆盖情况
• 确保无需求遗漏
• 管理跨 HLD 依赖

索引文档命名规范：HLD-INDEX-{PRD名称}.md

索引文档模板：

# HLD 索引：{PRD 名称}

## 基本信息
- **PRD 基线**：[PRD 路径] v[版本]
- **拆分方式**：按业务域/数据边界 / 按接口契约 / 按发布单元 / 按安全合规 / 按性能目标 / 按阶段 / 按前后端
- **HLD 数量**：N 个
- **创建时间**：YYYY-MM-DD
- **最后更新**：YYYY-MM-DD

## HLD 清单

| # | HLD 文档 | 负责模块/范围 | 状态 | 负责人 |
|---|----------|--------------|------|--------|
| 1 | [HLD-用户系统.md](路径) | 用户注册、登录、权限 | 已完成 | @张三 |
| 2 | [HLD-订单系统.md](路径) | 订单创建、支付、退款 | 进行中 | @李四 |
| 3 | [HLD-通知系统.md](路径) | 消息推送、邮件、短信 | 待开始 | @王五 |

## PRD 需求覆盖总表（关键！）

**此表确保所有 PRD 需求在各 HLD 中被完整覆盖，不遗漏。**

| PRD 需求 ID | 需求描述 | 归属 HLD | HLD 章节 | 分配状态 |
|-------------|---------|----------|----------|----------|
| FR-001 | 用户注册 | HLD-用户系统 | 3.2 | ✅ 已分配 |
| FR-002 | 订单创建 | HLD-订单系统 | 3.1 | ✅ 已分配 |
| FR-003 | 支付集成 | HLD-订单系统 | 4.1 | ✅ 已分配 |
| FR-004 | 消息推送 | HLD-通知系统 | 3.1 | 🔄 设计中（已分配） |
| NFR-001 | P99 < 200ms | 各 HLD | 性能章节 | ✅ 已分配 |

### 覆盖率统计
- **功能需求**：X / Y 已分配 (Z%)
- **非功能需求**：X / Y 已分配 (Z%)
- **未分配需求**：[列出任何未分配的需求 ID] ⚠️

> **覆盖率计算口径**：需求已分配到任一 HLD 即计为覆盖，与设计是否完成无关
>
> ⚠️ **准出条件**：覆盖率必须达到 100%，任何未分配需求都是 P0 问题

## 跨 HLD 依赖

| 依赖方 HLD | 被依赖 HLD | 依赖内容 | 接口契约 |
|-----------|-----------|---------|---------|
| HLD-订单系统 | HLD-用户系统 | 用户鉴权 | 见 HLD-用户系统 4.1 |
| HLD-通知系统 | HLD-订单系统 | 订单事件 | 见 HLD-订单系统 5.2 |

## 跨 HLD 接口契约

当多个 HLD 之间存在依赖时，接口契约定义在**被依赖方 HLD** 中，依赖方引用。

| 接口 | 定义位置 | 使用方 |
|------|---------|-------|
| 用户鉴权 API | HLD-用户系统 4.1 | HLD-订单系统、HLD-通知系统 |
| 订单事件 Schema | HLD-订单系统 5.2 | HLD-通知系统 |

单个 HLD 的需求映射表（1:N 场景）

在 1:N 场景下，单个 HLD 的需求映射表只覆盖本 HLD 负责的部分，但必须明确标注：

### PRD↔HLD 需求映射表

**PRD 基线**：[PRD 路径] v[版本]
**本 HLD 覆盖范围**：用户系统（FR-001 ~ FR-010, NFR-001）
**索引文档**：[HLD-INDEX-xxx.md](路径)

| PRD 条目 | 验收标准 | HLD 章节 | 状态 |
|----------|---------|---------|------|
| FR-001 用户注册 | 支持邮箱/手机号 | 3.2 认证模块 | ✓ 已覆盖 |
| FR-002 密码重置 | 24h 内有效 | 3.2 认证模块 | ✓ 已覆盖 |
| NFR-001 响应时间 | P99 < 200ms | 5.1 性能策略 | ✓ 已覆盖 |

**不在本 HLD 范围内的需求**：FR-011 ~ FR-030（见 HLD-订单系统、HLD-通知系统）

1:N 场景审查要点

• 索引文档必须存在：没有索引文档 → P0
• 覆盖率必须 100%：任何 PRD 需求未分配到任何 HLD → P0（覆盖率按“已分配”计算）
• 跨 HLD 依赖必须声明：依赖未声明 → P1
• 接口契约必须明确：跨 HLD 接口无契约 → P1

工作流程

执行进度清单

执行时使用 TodoWrite 工具跟踪以下进度，完成一项后立即标记为 completed：

□ 阶段零：上下文收集
  □ 0.1 扫描项目文档
  □ 0.2 用户确认参考文档（PRD + API Contract 必须确认）
  □ 0.3 读取 PRD 和 API Contract（必读）
  □ 0.4 读取其他确认的文档
  □ 0.5 识别可复用资源
  □ 0.6 记录关键约束
  □ 0.7 执行 Guardrails trigger check
  □ 0.8 输出上下文收集报告
□ 阶段一：需求理解
  □ 分析 PRD，识别 HLD 类型
  □ 理解 API Contract 中的接口定义
  □ 确认技术选型偏好和约束
□ 阶段二：结构规划
  □ 读取对应 HLD 模板
  □ 规划文档大纲
□ 阶段三：内容撰写
  □ 填充各章节内容
  □ 接口部分引用 API Contract（不重新定义）
  □ 绘制架构图/时序图
  □ 确保决策有理由
□ 阶段四：强制审查
  □ 4.1 完整性检查
  □ 4.2 决策完整性检查
  □ 4.3 边界检查
  □ 4.4 契约一致性检查（HLD 接口引用与 API Contract 一致）
  □ 4.5 可落地检查
  □ 4.6 证据检查
  □ 4.7 Traceability Metadata 生成与校验

---

阶段零：上下文收集（强制）

写 HLD 前，必须先了解项目上下文。禁止跳过此阶段，禁止在未读取相关文档/代码的情况下猜测技术现状。

0.1 扫描项目文档（先扫描，不读取）

使用 Glob 工具广泛扫描以下类型的文档，只收集文件路径，暂不读取内容：

排除目录：扫描时必须排除以下目录，避免噪音：

• node_modules/, .git/, dist/, build/, .next/
• vendor/, target/, __pycache__/, .venv/, venv/
• 其他明显的依赖/构建产物目录

0.2 用户确认参考文档（必须执行）

扫描完成后，先进行初筛，再展示给用户确认：

初筛规则（Agent 自行执行，不展示低置信度结果）：

• 高置信度（展示给用户）：路径包含 docs/, spec/, design/, prd/, hld/, adr/ 等关键词，或文件名明确匹配
• 低置信度（默认不展示）：路径不明确、位于测试目录、或文件名过于通用
• 如果高置信度结果不足，可适当放宽条件

使用 AskUserQuestion 让用户确认：

我扫描到以下可能相关的文档，请确认哪些需要我仔细阅读：

**需求文档（PRD）**【必需】：
- [ ] path/to/prd-xxx.md
- ...

**API Contract**【必需】：
- [ ] path/to/api-contract-xxx.md
- [ ] path/to/openapi.yaml
- ...

**设计/架构文档**：
- [ ] path/to/hld-xxx.md
- [ ] path/to/architecture.md
- ...

**技术规范**：
- [ ] path/to/adr-xxx.md
- ...

**问题**：
1. 本次 HLD 对应的 PRD 是哪个？【必须确认】
2. 本次 HLD 对应的 API Contract 是哪个？【必须确认】
3. 以上其他文档中，哪些需要我参考？
4. 是否有我没扫描到但需要参考的重要文档？

门禁规则：PRD 和 API Contract 必须都确认后才能进入下一阶段。如果用户未提供 API Contract，提示用户先使用 /api-writer 生成。

注意：

• 只展示初筛后的高置信度结果，避免信息过载
• 这一步是为了避免读入过时/无关的文档，节省上下文
• 用户可能会排除一些过期文档，也可能补充遗漏的文档
• 只有用户确认后，才进入 0.3 阶段读取文档

0.3 读取 PRD 和 API Contract（必读）

根据用户在 0.2 中确认的文档列表：

• 优先读取 PRD：理解业务背景、功能需求、非功能目标
• 识别 PRD 中的"建议方案"，HLD 需要做最终决定
• 仔细读取 API Contract：明确接口边界、兼容性与错误契约
• 记录从 PRD 和 API Contract 中学到的关键信息

0.4 读取其他确认的文档

• 读取用户在 0.2 中确认的其他设计/规范/Guardrails/ADR
• 只提取与当前 HLD 决策直接相关的信息，避免把噪音带入上下文
• 记录从每个文档中学到的关键信息

0.5 识别可复用资源

• 基于已读取的文档，识别可复用的内部模块/共享服务
• 评估第三方成熟方案（优先复用，避免重复造轮子）
• 必须注明来源：从哪个文档/代码中识别到的

0.6 记录关键约束

• PRD 中的非功能需求（性能、安全目标）
• 技术栈限制
• 团队能力边界
• 已有 API/错误码契约（若有）

0.7 执行 Guardrails trigger check（强制）

在进入阶段一前，基于 ../../references/guardrails-trigger-check.md 执行一次 Guardrails trigger check：

• no_trigger：继续进入阶段一
• suggest_guardrails：在上下文收集报告中记录原因、影响域和推荐动作后继续
• require_guardrails_before_design：停止当前 HLD 写作，明确建议先运行 guardrails-writer

0.8 输出「上下文收集报告」（强制）

在进入阶段一之前，必须先输出以下报告：

## 上下文收集报告

### 已读取的文档（用户确认）
| 文档路径 | 文档类型 | 关键信息摘要 |
|---------|---------|-------------|
| [路径] | PRD/HLD/API/规范 | [从中学到的关键信息] |

### 识别的技术现状
- 技术栈：[从配置文件/代码识别]
- 现有架构：[从 HLD/代码识别]
- 已有 API 契约：[从 OpenAPI/代码识别]

### 可复用资源
| 资源 | 类型 | 与本需求关系 | 来源 |
|------|------|-------------|------|
| [资源名] | 内部模块/共享服务/第三方 | [关系描述] | [文档/代码路径] |

### Guardrails Trigger Check
- Decision: [no_trigger / suggest_guardrails / require_guardrails_before_design]
- Why: [一句话说明原因]
- Impacted domains: [API / Security / Data / Release / Observability ...]
- Guardrails status: [baseline exists / missing domain / outdated / drift]
- Recommended next action: [continue / update guardrails soon / run guardrails-writer first]

### 未找到信息的领域（需用户补充）
- [列出仍不确定的技术信息]

上下文收集报告无需用户再次确认，可直接进入阶段一。（因为文档选择已在 0.2 确认过；若 Guardrails trigger check = require_guardrails_before_design，则不得进入阶段一）

阶段一：需求理解

1. 分析 PRD，识别 HLD 类型 2. 使用 AskUserQuestion 确认：

• 技术选型偏好（如有）
• 性能/安全等非功能约束
• 已知的技术限制

阶段二：结构规划

1. 根据 HLD 类型读取对应模板 2. 规划文档大纲 3. 确认章节结构

模板文档路径：

• 新功能（有 UI）：assets/new-feature-ui.md
• 新功能（纯后端）：assets/new-feature-backend.md
• 第三方集成：assets/integration.md
• 重构方案：assets/refactoring.md
• 性能/安全优化：assets/optimization.md

阶段三：内容撰写

1. 按照模板结构填充内容 2. 使用 Mermaid 绘制架构图、时序图 3. 确保所有高成本决策都有明确结论 4. 标注"决策理由"

撰写规范：

• 默认使用中文（技术术语可保留英文）
• 架构图、时序图用 Mermaid
• 表格用于结构化信息
• 每个技术选型必须有"选型理由"

阶段四：强制审查

完成初稿后，必须进行以下审查：

4.1 完整性检查

• [ ] PRD↔HLD 需求映射表是否完整（每个 PRD 条目都有对应）
• [ ] 所有 PRD 中的功能需求是否都有技术方案
• [ ] 所有非功能目标是否都有达成策略
• [ ] 关键流程是否都有时序图或状态机

4.2 决策完整性

• [ ] PRD 中的"建议方案"是否都做了最终决定
• [ ] 每个技术选型是否都有理由
• [ ] 技术选型是否与现有技术栈对齐（偏离是否有充分理由）
• [ ] 是否优先复用了内部模块/共享服务
• [ ] 是否存在"待定"项需要澄清

4.3 边界检查（强制）

• [ ] 是否包含了函数签名、类设计？（不应该）
• [ ] 是否包含了具体参数（TTL、超时）？（不应该）
• [ ] 是否遗漏了跨团队约束的 API 契约？（不应该）

4.4 可落地检查

• [ ] 开发团队能否根据此文档开始 LLD/编码
• [ ] 是否有歧义或模糊的技术描述

4.5 证据检查（强制）

• [ ] 「复用盘点」表格中的每一行是否都有「来源」？（必须有）
• [ ] 技术现状描述是否有文档/代码依据？（必须有）
• [ ] 是否存在没有依据的猜测性描述？（不应该）
• [ ] 上下文收集报告是否已输出？（应该；注：报告本身无需用户确认，文档选择已在 0.2 确认过）

如果发现无依据的猜测性内容，必须删除或通过 AskUserQuestion 确认。

4.6 Traceability Metadata（强制）

产出的 HLD 必须内嵌 TRACEABILITY-METADATA block（格式见 ../../references/traceability-schema/traceability-schema-v1.md §11）。

要求：

• schema.profile = hld-profile-v1
• artifact.type = HLD
• artifact.source_documents 至少包含 PRD 和 API Contract 的 artifact ID
• entities.decisions[] 为每个架构决策建模（DEC-*），包含 decision 和 rationale
• entities.flows[] 为关键系统流程建模（FLOW-*），标注 kind
• 其余桶（requirements/risks/must_not_regress/external_behaviors/test_cases）保留空数组
• relations[] 使用 refines 将每个 DEC-*/FLOW-* 连回 REQ-*

参考示例：../../references/traceability-schema/hld-profile-v1.example.yaml

校验（写入文件后执行）：

python3 plugins/testany-eng/scripts/trace_lint.py --format json <HLD 路径>

若存在 blocking issue（error），必须修正后再输出完成结论。若 PRD 路径可用，额外执行：

python3 plugins/testany-eng/scripts/trace_build_rtm.py --format json <PRD 路径> <HLD 路径>

交互规范

必须使用 AskUserQuestion 的场景

1. PRD 中有多个"建议方案"需要最终选择 2. 非功能目标不明确（如"高性能"但无具体指标） 3. 技术选型存在多个可行方案 4. 涉及跨团队依赖需要确认

问题设计原则

问题：[清晰的技术问题]
选项：
- 选项 A：[方案描述 + 优劣势]
- 选项 B：[方案描述 + 优劣势]

禁止行为

关于猜测（严格禁止）：

• 禁止在未搜索/读取相关文档和代码的情况下描述技术现状
• 禁止猜测现有架构、技术栈、已有接口 — 必须有文档/代码依据
• 禁止在「复用盘点」中填写没有来源依据的内容
• 禁止假设技术约定 — 找不到就用 AskUserQuestion 确认

关于内容边界：

• 不要在 HLD 中写代码或伪代码
• 不要包含具体参数配置
• 不要遗漏 PRD 中已有的非功能约束
• 不要做 PRD 没有提及的需求假设
• 不要跳过阶段零的上下文收集

输出格式

最终输出的 HLD 必须：

1. 使用 Markdown 格式 2. 包含完整的元信息头部（关联 PRD、版本、作者） 3. 包含 PRD↔HLD 需求映射表（强制） 4. 章节编号清晰 5. 架构图使用 Mermaid 6. 技术选型附带理由 7. 跨团队 API/错误码有契约定义 8. 不包含 LLD 级别的实现细节

质量标准

一份合格的 HLD 应该：

• 完整：覆盖所有 PRD 需求的技术方案
• 可决策：所有高成本决策都有明确结论
• 可落地：开发团队可据此开始 LLD/编码
• 可追溯：关联 PRD，技术选型有理由
• 边界清晰：不越界到 LLD 领域

触发词

以下输入应触发此技能：

• "写 HLD"、"写技术设计文档"
• "帮我写技术方案"
• "HLD 模板"
• "技术设计"、"架构设计"
• "/hld-writer"

HLD Template: Third Party Integration

The following is the template content, copy it and fill it in according to the actual situation.

---

[Third Party Service] Integrated technical design

Meta information

PRD↔HLD requirements mapping table

Coverage of this HLD: [Scope] (required for 1:N scenario) Index document: [HLD-INDEX-xxx.md] (path) (required for 1:N scenario)

1. Integration Overview

1.1 Business Background

[Why you need to integrate this service]

1.2 Integration scope

1.3 Third-party service information

2. Technical architecture

2.1 Integrated architecture

graph LR
A[Business Service] --> B[Integrated Adaptation Layer]
B --> C [Third Party API]
B --> D[(local cache)]
B --> E[(callback processing)]

2.2 Reuse inventory

Description:

- Give priority to reusing existing adapters, open source SDKs, and internal packaging. Sufficient reasons must be given for self-development.

- "Source" column is required: You must indicate which document or code the candidate solution was identified from, and unfounded guessing is prohibited.

2.3 Adaptation layer design

[Why adaptation layer and adaptation layer responsibilities are needed]

3. Interface mapping

3.1 Call third party

3.2 Receive callback

4. Data mapping (cross-system contract)

Note: This section defines cross-system data contracts and falls under the category of HLD. Internal data table field design belongs to LLD.

4.1 Request mapping

4.2 Response mapping

4.3 Status Mapping

5. Authentication and Security

5.1 Authentication method

[API Key / OAuth / Signature, etc.]

5.2 Key Management

[Key storage, rotation strategy]

5.3 Data Security

[Sensitive data processing, transmission encryption]

6. Reliability design

6.1 Timeout and retry

6.2 Circuit breaker downgrade

[Circuit breaker conditions, downgrade plan]

6.3 Idempotent design

[Request deduplication, callback deduplication]

6.4 Reconciliation mechanism

[Regular reconciliation strategy]

7. Exception handling

7.1 Error code mapping

7.2 Abnormal scenarios

8. Testing strategy

8.1 Sandbox environment

8.2 Mock Strategy

[Local Mock, integration testing strategy]

9. Monitor alarms

9.1 Key Indicators

• Call success rate
• average latency
• Error distribution

9.2 Alarm rules

9.3 Buried points/monitoring design (accepting PRD success indicators)

10. Online plan

10.1 Grayscale strategy

[Grayscale ratio, grayscale conditions]

10.2 Rollback plan

[Rollback steps, scope of impact]

HLD 模板：第三方集成

以下为模板内容，复制后根据实际情况填写。

---

[第三方服务] 集成技术设计

元信息

PRD↔HLD 需求映射表

本 HLD 覆盖范围：[范围]（1:N 场景必填） 索引文档：HLD-INDEX-xxx.md（1:N 场景必填）

1. 集成概述

1.1 业务背景

[为什么需要集成此服务]

1.2 集成范围

1.3 第三方服务信息

2. 技术架构

2.1 集成架构

graph LR
    A[业务服务] --> B[集成适配层]
    B --> C[第三方 API]
    B --> D[(本地缓存)]
    B --> E[(回调处理)]

2.2 复用盘点

说明：

- 优先复用已有的适配器、开源 SDK、内部封装，自研需给出充分理由

- 「来源」列必填：必须注明从哪个文档或代码中识别到该候选方案，禁止无依据猜测

2.3 适配层设计

[为什么需要适配层、适配层职责]

3. 接口映射

3.1 调用第三方

3.2 接收回调

4. 数据映射（跨系统契约）

注意：此章节定义跨系统的数据契约，属于 HLD 范畴。内部数据表字段设计属于 LLD。

4.1 请求映射

4.2 响应映射

4.3 状态映射

5. 认证与安全

5.1 认证方式

[API Key / OAuth / 签名等]

5.2 密钥管理

[密钥存储、轮换策略]

5.3 数据安全

[敏感数据处理、传输加密]

6. 可靠性设计

6.1 超时与重试

6.2 熔断降级

[熔断条件、降级方案]

6.3 幂等设计

[请求去重、回调去重]

6.4 对账机制

[定期对账策略]

7. 异常处理

7.1 错误码映射

7.2 异常场景

8. 测试策略

8.1 沙箱环境

8.2 Mock 策略

[本地 Mock、集成测试策略]

9. 监控告警

9.1 关键指标

• 调用成功率
• 平均延迟
• 错误分布

9.2 告警规则

9.3 埋点/监控设计（承接 PRD 成功指标）

10. 上线计划

10.1 灰度策略

[灰度比例、灰度条件]

10.2 回滚方案

[回滚步骤、影响范围]

HLD Template: New Features (Pure Backend)

The following is the template content, copy it and fill it in according to the actual situation.

---

#[Function name] Technical design document

Meta information

PRD↔HLD requirements mapping table

Coverage of this HLD: [Scope] (required for 1:N scenario) Index document: [HLD-INDEX-xxx.md] (path) (required for 1:N scenario)

1. Background and goals

1.1 Business Background

[Brief description, citing PRD]

1.2 Technical Objectives

• [Target 1]
• [Target 2]

1.3 Non-functional goals

1.4 Technical status and changes (such as adding new functions to existing systems)

Affected technology components

Overview of architectural changes

[Describe the impact on the existing architecture. If it is a new system, it can be marked "not applicable"]

2. Technical architecture

2.1 System architecture

graph LR
A[upstream service] --> B[this service]
B --> C[(database)]
B --> D[(cache)]
B --> E[Downstream service]
B --> F [message queue]

2.2 Reuse inventory

Description:

- Prioritize the reuse of internal modules/shared services/third-party mature solutions, and sufficient reasons must be given for self-research

- "Source" column is required: You must indicate which document or code the candidate solution was identified from, and unfounded guessing is prohibited.

2.3 Technology Selection

3. API design

Note: If the project already has an OpenAPI/Swagger specification, give priority to citing the existing specification path to avoid repeated maintenance.

- Existing specifications: fill in "For details, see path/to/openapi.yaml#/paths/xxx"

- New interface: fill in the details according to the template below

3.1 Interface list

3.2 Interface details

Only fill in the details for new interface. For existing standardized interfaces, please refer to the canonical path.

POST /api/v1/xxx (new)

Request body:

{
  "field1": "string"
}

Response body:

{
  "code": 0,
  "data": {}
}

Error code:

4. Data design

4.1 Data Model (Conceptual Level)

Note: This is a conceptual model, the specific field types, lengths, etc. belong to LLD

4.2 Index strategy

4.3 Data life cycle

[Data retention policy, archiving policy]

5. Key processes

5.1 [Process Name]

sequenceDiagram
participant A as caller
participant B as this service
participant C as database
participant D as downstream

A->>B: Request
B->>C: Query
B->>D: call downstream
B-->>A: response

5.2 Exception handling

6. Non-functional design

6.1 Performance Strategy

• Cache: [Policy]
• Batch Processing: [Strategy]
• Asynchronous processing: [Strategy]

6.2 Reliability Strategy

• Idempotent design: [Strategy]
• Retry mechanism: [Strategy]
• Circuit breaker downgrade: [Strategy]

6.3 Observability

• Key indicators: [Indicator list]
• Alarm rules: [Rules]

7. Deployment and operation and maintenance

7.1 Deployment architecture

[Deployment method, number of instances]

7.2 Configuration Management

[Configuration center, environment differences]

7.3 Compatibility design (accepting PRD compatibility requirements)

7.4 Release Strategy

7.5 Buried points/monitoring design (accepting PRD success indicators)

8. Risks and Dependencies

HLD 模板：新功能（纯后端）

以下为模板内容，复制后根据实际情况填写。

---

[功能名称] 技术设计文档

元信息

PRD↔HLD 需求映射表

本 HLD 覆盖范围：[范围]（1:N 场景必填） 索引文档：HLD-INDEX-xxx.md（1:N 场景必填）

1. 背景与目标

1.1 业务背景

[简要描述，引用 PRD]

1.2 技术目标

• [目标 1]
• [目标 2]

1.3 非功能目标

1.4 技术现状与变更（如为已有系统新增功能）

受影响的技术组件

架构变更概述

[描述对现有架构的影响，如为全新系统可标注"不适用"]

2. 技术架构

2.1 系统架构

graph LR
    A[上游服务] --> B[本服务]
    B --> C[(数据库)]
    B --> D[(缓存)]
    B --> E[下游服务]
    B --> F[消息队列]

2.2 复用盘点

说明：

- 优先复用内部模块/共享服务/第三方成熟方案，自研需给出充分理由

- 「来源」列必填：必须注明从哪个文档或代码中识别到该候选方案，禁止无依据猜测

2.3 技术选型

3. API 设计

注意：若项目已有 OpenAPI/Swagger 规范，优先引用已有规范路径，避免重复维护。

- 已有规范：填写「详见 path/to/openapi.yaml#/paths/xxx」

- 新增接口：按下方模板填写详情

3.1 接口列表

3.2 接口详情

仅对新增接口填写详情，已有规范的接口请引用规范路径。

POST /api/v1/xxx（新增）

请求体：

{
  "field1": "string"
}

响应体：

{
  "code": 0,
  "data": {}
}

错误码：

4. 数据设计

4.1 数据模型（概念级）

注意：此处为概念模型，具体字段类型、长度等属于 LLD

4.2 索引策略

4.3 数据生命周期

[数据保留策略、归档策略]

5. 关键流程

5.1 [流程名称]

sequenceDiagram
    participant A as 调用方
    participant B as 本服务
    participant C as 数据库
    participant D as 下游

    A->>B: 请求
    B->>C: 查询
    B->>D: 调用下游
    B-->>A: 响应

5.2 异常处理

6. 非功能设计

6.1 性能策略

• 缓存：[策略]
• 批处理：[策略]
• 异步处理：[策略]

6.2 可靠性策略

• 幂等设计：[策略]
• 重试机制：[策略]
• 熔断降级：[策略]

6.3 可观测性

• 关键指标：[指标列表]
• 告警规则：[规则]

7. 部署与运维

7.1 部署架构

[部署方式、实例数]

7.2 配置管理

[配置中心、环境差异]

7.3 兼容性设计（承接 PRD 兼容性要求）

7.4 发布策略

7.5 埋点/监控设计（承接 PRD 成功指标）

8. 风险与依赖

HLD Template: new features (with UI)

The following is the template content, copy it and fill it in according to the actual situation.

---

#[Function name] Technical design document

Meta information

PRD↔HLD requirements mapping table

Coverage of this HLD: [Scope] (required for 1:N scenario) Index document: [HLD-INDEX-xxx.md] (path) (required for 1:N scenario)

1. Background and goals

1.1 Business Background

[Brief description of business background, citing PRD]

1.2 Technical Objectives

• [Technical Objective 1]
• [Technical Objective 2]

1.3 Non-functional goals

1.4 Technical status and changes (such as adding new functions to existing systems)

Affected technology components

Overview of architectural changes

[Describe the impact on the existing architecture. If it is a new system, it can be marked "not applicable"]

2. Technical architecture

2.1 Overall architecture

graph TB
subgraph front end
        A[Web App] --> B[API Gateway]
    end
subgraph backend
        B --> C[Service A]
        B --> D[Service B]
        C --> E[(Database)]
    end

2.2 Reuse inventory

Description:

- Prioritize the reuse of internal modules/shared services/third-party mature solutions, and sufficient reasons must be given for self-research

- "Source" column is required: You must indicate which document or code the candidate solution was identified from, and unfounded guessing is prohibited.

2.3 Technology Selection

3. Front-end design

3.1 Page structure

[Page level, routing design]

3.2 Status Management

[State Management Strategy]

3.3 Interacting with the backend

[API calling method, error handling strategy]

4. API design

Note: If the project already has an OpenAPI/Swagger specification, give priority to citing the existing specification path to avoid repeated maintenance.

- Existing specifications: fill in "For details, see path/to/openapi.yaml#/paths/xxx"

- New interface: fill in the details according to the template below

4.1 Interface list

4.2 Authentication and authorization

[Authentication method, authority control strategy]

4.3 Interface details

Only fill in the details for new interface. For existing standardized interfaces, please refer to the canonical path.

POST /api/v1/xxx (new)

Request body:

{
  "field1": "string",
  "field2": "number"
}

Response body:

{
  "code": 0,
  "data": {}
}

5. Data design

5.1 Data model (conceptual level)

erDiagram
    EntityA ||--o{ EntityB : contains
    EntityA ||--|| EntityC : references

Note: This is a conceptual model, the specific field types, lengths, etc. belong to LLD

5.2 Index strategy

5.3 Data migration strategy

[Whether migration is needed and migration strategy]

6. Key processes

6.1 [Core process name]

sequenceDiagram
participant U as user
participant F as front end
participant B as backend
participant D as database

U->>F: Operation
F->>B: API request
B->>D: query/write
D-->>B: Return
B-->>F: response
F-->>U: display results

7. Non-functional design

7.1 Performance Strategy

• Cache policy: [policy description]
• Pagination strategy: [strategy description]

7.2 Security Policy

• Authentication: [Policy]
• Data desensitization: [Strategy]

7.3 Observability

• Log: [Strategy]
• Monitor: [Key Indicators]
• Alarm: [Alarm Rules]

8. Deployment architecture

8.1 Deployment topology

[Deployment diagram or description]

8.2 Environment configuration

8.3 Compatibility design (accepting PRD compatibility requirements)

8.4 Release Strategy

8.5 Buried points/monitoring design (accepting PRD success indicators)

9. Risks and Dependencies

9.1 Technical Risks

9.2 External dependencies

10. Milestones

HLD 模板：新功能（有 UI）

以下为模板内容，复制后根据实际情况填写。

---

[功能名称] 技术设计文档

元信息

PRD↔HLD 需求映射表

本 HLD 覆盖范围：[范围]（1:N 场景必填） 索引文档：HLD-INDEX-xxx.md（1:N 场景必填）

1. 背景与目标

1.1 业务背景

[简要描述业务背景，引用 PRD]

1.2 技术目标

• [技术目标 1]
• [技术目标 2]

1.3 非功能目标

1.4 技术现状与变更（如为已有系统新增功能）

受影响的技术组件

架构变更概述

[描述对现有架构的影响，如为全新系统可标注"不适用"]

2. 技术架构

2.1 整体架构

graph TB
    subgraph 前端
        A[Web App] --> B[API Gateway]
    end
    subgraph 后端
        B --> C[Service A]
        B --> D[Service B]
        C --> E[(Database)]
    end

2.2 复用盘点

说明：

- 优先复用内部模块/共享服务/第三方成熟方案，自研需给出充分理由

- 「来源」列必填：必须注明从哪个文档或代码中识别到该候选方案，禁止无依据猜测

2.3 技术选型

3. 前端设计

3.1 页面结构

[页面层级、路由设计]

3.2 状态管理

[状态管理策略]

3.3 与后端交互

[API 调用方式、错误处理策略]

4. API 设计

注意：若项目已有 OpenAPI/Swagger 规范，优先引用已有规范路径，避免重复维护。

- 已有规范：填写「详见 path/to/openapi.yaml#/paths/xxx」

- 新增接口：按下方模板填写详情

4.1 接口列表

4.2 认证授权

[认证方式、权限控制策略]

4.3 接口详情

仅对新增接口填写详情，已有规范的接口请引用规范路径。

POST /api/v1/xxx（新增）

请求体：

{
  "field1": "string",
  "field2": "number"
}

响应体：

{
  "code": 0,
  "data": {}
}

5. 数据设计

5.1 数据模型（概念级）

erDiagram
    EntityA ||--o{ EntityB : contains
    EntityA ||--|| EntityC : references

注意：此处为概念模型，具体字段类型、长度等属于 LLD

5.2 索引策略

5.3 数据迁移策略

[是否需要迁移、迁移策略]

6. 关键流程

6.1 [核心流程名称]

sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant B as 后端
    participant D as 数据库

    U->>F: 操作
    F->>B: API 请求
    B->>D: 查询/写入
    D-->>B: 返回
    B-->>F: 响应
    F-->>U: 展示结果

7. 非功能设计

7.1 性能策略

• 缓存策略：[策略描述]
• 分页策略：[策略描述]

7.2 安全策略

• 认证：[策略]
• 数据脱敏：[策略]

7.3 可观测性

• 日志：[策略]
• 监控：[关键指标]
• 告警：[告警规则]

8. 部署架构

8.1 部署拓扑

[部署图或描述]

8.2 环境配置

8.3 兼容性设计（承接 PRD 兼容性要求）

8.4 发布策略

8.5 埋点/监控设计（承接 PRD 成功指标）

9. 风险与依赖

9.1 技术风险

9.2 外部依赖

10. 里程碑

HLD Template: Performance/Security Optimization

The following is the template content, copy it and fill it in according to the actual situation.

---

[Optimization Project] Technical Design Document

Meta information

PRD↔HLD requirements mapping table

1. Optimize background

1.1 Current situation analysis

1.2 Optimization goals

1.3 Constraints

• [Constraint 1: If the API contract cannot be changed]
• [Constraint 2: such as budget constraints]

2. Problem location

2.1 Performance bottleneck analysis (applicable to performance optimization)

graph LR
A[Request Entry] -->|Xms| B[Service A]
B -->|Xms| C[database]
B -->|Xms| D[cache]
C -->|Bottleneck| E[Slow Query]

2.2 Security risk analysis (security optimization applies)

2.3 Root cause analysis

[Root cause of problem]

3. Optimization plan

3.1 Solution Overview

3.2 Reuse inventory

Description:

- Optimization solutions give priority to existing component enhancements and mature third-party solutions

- "Source" column is required: You must indicate which document or code the candidate solution was identified from, and unfounded guessing is prohibited.

3.3 Plan details

Optimization point 1: [name]

status quo: [Current implementation]

Optimization Strategy: [Optimized implementation]

Architectural changes:

graph LR
subgraph before optimization
A1[component] --> B1[slow path]
    end
After subgraph optimization
A2[component] --> C2[cache]
C2 -.miss.-> B2[original path]
    end

Technical Selection:

Reason for selection: [Why choose this option]

3.3 Solutions not to be adopted

4. Scope of influence

4.1 Scope of code changes

4.2 Dependency changes

4.3 Configuration changes

5. Verification strategy

5.1 Performance verification (performance optimization applies)

5.2 Security verification (security optimization applies)

5.3 Regression testing

[Make sure not to introduce new problems]

6. Risks and Mitigations

7. Monitoring and Alarming

7.1 New monitoring

7.2 Observation period indicators

[Key indicators to observe after going online]

7.3 Buried points/monitoring design (accepting PRD success indicators)

8. Online plan

8.1 Grayscale strategy

8.2 Switch control

8.3 Rollback plan

[Rollback steps]

9. Subsequent optimization

9.1 Not doing it this time

9.2 Long-term planning

[Long-term optimization direction]

HLD 模板：性能/安全优化

以下为模板内容，复制后根据实际情况填写。

---

[优化项目] 技术设计文档

元信息

PRD↔HLD 需求映射表

1. 优化背景

1.1 现状分析

1.2 优化目标

1.3 约束条件

• [约束 1：如不能改变 API 契约]
• [约束 2：如预算限制]

2. 问题定位

2.1 性能瓶颈分析（性能优化适用）

graph LR
    A[请求入口] -->|Xms| B[服务A]
    B -->|Xms| C[数据库]
    B -->|Xms| D[缓存]
    C -->|瓶颈| E[慢查询]

2.2 安全风险分析（安全优化适用）

2.3 根因分析

[问题根本原因]

3. 优化方案

3.1 方案概述

3.2 复用盘点

说明：

- 优化方案优先考虑现有组件增强、成熟第三方方案

- 「来源」列必填：必须注明从哪个文档或代码中识别到该候选方案，禁止无依据猜测

3.3 方案详情

优化点 1：[名称]

现状： [当前实现方式]

优化策略： [优化后的实现方式]

架构变更：

graph LR
    subgraph 优化前
        A1[组件] --> B1[慢路径]
    end
    subgraph 优化后
        A2[组件] --> C2[缓存]
        C2 -.miss.-> B2[原路径]
    end

技术选型：

选型理由： [为什么选择此方案]

3.3 不采纳的方案

4. 影响范围

4.1 代码变更范围

4.2 依赖变更

4.3 配置变更

5. 验证策略

5.1 性能验证（性能优化适用）

5.2 安全验证（安全优化适用）

5.3 回归测试

[确保不引入新问题]

6. 风险与缓解

7. 监控与告警

7.1 新增监控

7.2 观察期指标

[上线后重点观察的指标]

7.3 埋点/监控设计（承接 PRD 成功指标）

8. 上线计划

8.1 灰度策略

8.2 开关控制

8.3 回滚方案

[回滚步骤]

9. 后续优化

9.1 本次不做

9.2 长期规划

[长期优化方向]

HLD Template: Refactoring plan

The following is the template content, copy it and fill it in according to the actual situation.

---

[Refactoring Project] Technical Design Document

Meta information

PRD↔HLD requirements mapping table

1. Reconstruct background

1.1 Current situation issues

1.2 Refactoring goals

• [Target 1]
• [Target 2]

1.3 Non-target (clearly not done)

• [Non-Target 1]

1.4 Success Indicators

2. Analysis of existing architecture

2.1 Existing architecture diagram

graph TB
subgraph existing architecture
A[Component A] --> B[Component B]
B --> C[component C]
    end

2.2 Problem location

[Which components/modules need to be refactored and why]

2.3 Dependency analysis

3. Target architecture

3.1 Target architecture diagram

graph TB
subgraph target architecture
A[new component A] --> B[new component B]
B --> C[component C]
    end

3.2 Reuse inventory

Description:

- During the reconstruction process, give priority to reusing existing modules to avoid reinventing the wheel.

- "Source" column is required: You must indicate which document or code the candidate solution was identified from, and unfounded guessing is prohibited.

3.3 Architecture change description

3.4 Changes in technology selection

4. Migration strategy

4.1 Migration method

• [ ] Big bang (one-time switch)
• [ ] Progressive (gradual migration)
• [ ] Strangler mode (old and new in parallel)

4.2 Migration steps

graph LR
A[Phase 1: Preparation] --> B[Phase 2: Double writing]
B --> C [Stage 3: Cutting Reading]
C --> D[Phase 4: Stop writing]
D --> E[Phase 5: Cleanup]

4.3 Data migration

[Data migration strategy, consistency guarantee]

5. Compatibility design

5.1 API compatible

5.2 Data Compatibility

[Compatible with old and new data formats]

5.3 Configuration compatibility

[Configuration changes, switch control]

6. Risks and Mitigations

6.1 Technical Risks

6.2 Business Risks

7. Rollback plan

7.1 Rollback trigger conditions

• [Condition 1]
• [Condition 2]

7.2 Rollback steps

1. [Step 1] 2. [Step 2]

7.3 Rollback verification

[How to verify rollback success]

8. Testing strategy

8.1 Test scope

8.2 Comparison test

[Comparative verification strategy between old and new systems]

9. Online plan

9.1 Grayscale strategy

9.2 Monitoring enhancement

[Additional monitoring measures during refactoring]

9.3 Buried points/monitoring design (accepting PRD success indicators)

10. Cleanup plan

10.1 Deprecated components

10.2 Technical Debt Cleanup

[Legacy Technical Debt Treatment Plan]

HLD 模板：重构方案

以下为模板内容，复制后根据实际情况填写。

---

[重构项目] 技术设计文档

元信息

PRD↔HLD 需求映射表

1. 重构背景

1.1 现状问题

1.2 重构目标

• [目标 1]
• [目标 2]

1.3 非目标（明确不做）

• [非目标 1]

1.4 成功指标

2. 现有架构分析

2.1 现有架构图

graph TB
    subgraph 现有架构
        A[组件A] --> B[组件B]
        B --> C[组件C]
    end

2.2 问题定位

[哪些组件/模块需要重构、为什么]

2.3 依赖分析

3. 目标架构

3.1 目标架构图

graph TB
    subgraph 目标架构
        A[新组件A] --> B[新组件B]
        B --> C[组件C]
    end

3.2 复用盘点

说明：

- 重构过程中优先复用已有模块，避免重复造轮子

- 「来源」列必填：必须注明从哪个文档或代码中识别到该候选方案，禁止无依据猜测

3.3 架构变更说明

3.4 技术选型变更

4. 迁移策略

4.1 迁移方式

• [ ] 大爆炸式（一次性切换）
• [ ] 渐进式（逐步迁移）
• [ ] 绞杀者模式（新旧并行）

4.2 迁移步骤

graph LR
    A[阶段1: 准备] --> B[阶段2: 双写]
    B --> C[阶段3: 切读]
    C --> D[阶段4: 停写]
    D --> E[阶段5: 清理]

4.3 数据迁移

[数据迁移策略、一致性保证]

5. 兼容性设计

5.1 API 兼容

5.2 数据兼容

[新旧数据格式兼容]

5.3 配置兼容

[配置变更、开关控制]

6. 风险与缓解

6.1 技术风险

6.2 业务风险

7. 回滚方案

7.1 回滚触发条件

• [条件 1]
• [条件 2]

7.2 回滚步骤

1. [步骤 1] 2. [步骤 2]

7.3 回滚验证

[如何验证回滚成功]

8. 测试策略

8.1 测试范围

8.2 对比测试

[新旧系统对比验证策略]

9. 上线计划

9.1 灰度策略

9.2 监控增强

[重构期间额外的监控措施]

9.3 埋点/监控设计（承接 PRD 成功指标）

10. 清理计划

10.1 废弃组件

10.2 技术债清理

[遗留技术债处理计划]