---
title: 设计文档模板
summary: 记录一个功能/模块的设计方案、权衡与落地计划（建议配套 ADR）。
owners:
  - team: <team>
reviewers:
  - <name-or-team>
status: draft
date: 2026-01-03
version: 0.1.0
related:
  - adr: docs/architecture/adr-xxxx-<slug>.md
  - pr: <link>
  - issue: <link>
---

# 设计文档：<标题>

## 1. 背景（Context）

- 当前问题是什么？为什么现在要做？
- 相关现状：已有模块/接口/数据模型（附链接）
- 约束：技术栈、部署方式、团队边界、时间/人力

## 2. 目标（Goals）

- [ ] 目标 1（可验证）
- [ ] 目标 2（可验证）

## 3. 非目标（Non-goals）

- 不做什么（防止范围膨胀）

## 4. 需求与范围（Requirements & Scope）

- 用户/角色：谁会用？（例如：管理员、开发者、CI runner）
- 功能需求：
  - R1:
  - R2:
- 非功能需求：性能、可用性、可维护性、可观测性

## 5. 方案概览（High-level Design）

- 用 5-10 行描述整体方案（模块、数据流、调用链）
- 关键选择：为什么选这个方案？

## 6. 详细设计（Detailed Design）

### 6.1 接口/API 设计

- 新增/变更端点（路径、方法、权限、请求/响应示例）
- 错误码与错误语义（与 `BusinessError` 对齐）

### 6.2 数据模型/数据库

- Prisma model 变更（字段、索引、迁移策略）
- 数据一致性与幂等策略（例如：重试/重复提交）

### 6.3 任务/队列/异步处理（如有）

- 队列模型：入队、出队、并发、重试、死信/失败处理
- 状态机：状态枚举与迁移

### 6.4 配置与环境变量

- 新增 env（默认值、是否敏感、是否需要重启）

### 6.5 可观测性

- 日志：关键日志点、traceId/requestId（如有）
- 指标：成功率、延迟、队列长度、失败原因分布
- 告警：P0/P1 触发条件

### 6.6 安全与权限

- 认证：是否要求登录（session）
- 授权：角色/资源权限（项目级、流水线级）
- 数据安全：敏感信息、token、日志脱敏

## 7. 影响与权衡（Trade-offs）

- 性能影响
- 运维影响
- 对现有接口/调用方的影响
- 技术债与后续演进

## 8. 兼容性与迁移（Compatibility & Migration）

- 是否 breaking change？
- 迁移步骤（DB、配置、数据回填）
- 回滚策略

## 9. 测试计划（Test Plan）

- 单测：覆盖哪些模块
- 集成测试：关键链路（如：创建部署 -> 入队 -> 执行 -> 状态更新）
- 手工验证：步骤清单

## 10. 发布计划（Rollout Plan）

- 分阶段：灰度/开关/逐步放量（如有）
- 监控指标与验收标准

## 11. 备选方案（Alternatives Considered）

- 方案 A：为什么不用
- 方案 B：为什么不用

## 12. 风险与开放问题（Risks & Open Questions）

- 风险 1
- 问题 1（需要谁来决定/何时决定）

## 13. 附录（Appendix）

- 相关链接：控制器、DTO、Prisma schema、PR 等