# 输出模板

设计文档的标准格式，确保输出结构完整、易于评审。

---

## 完整设计文档模板

```markdown
# [功能/项目名称] 设计文档

> 创建日期: YYYY-MM-DD
> 状态: 草稿 / 评审中 / 已确认

## 背景

[1-2段描述为什么要做这个，解决什么问题]

## 目标

### 核心目标
- [目标 1]
- [目标 2]

### 非目标
- [明确不在范围内的内容]

## 解决方案

### 方案概述
[一句话描述选定的方案]

### 方案对比
| 方案 | 优点 | 缺点 | 结论 |
|------|------|------|------|
| 方案 A | ... | ... | ✅ 选择 |
| 方案 B | ... | ... | ❌ 不选 |

### 选择理由
[解释为什么选择这个方案]

## 架构设计

### 整体架构
[架构图或文字描述]

```
┌─────────────┐     ┌─────────────┐
│   Client    │────▶│   Server    │
└─────────────┘     └─────────────┘
                          │
                          ▼
                    ┌─────────────┐
                    │  Database   │
                    └─────────────┘
```

### 核心组件
| 组件 | 职责 | 技术选型 |
|------|------|----------|
| 组件 A | ... | ... |
| 组件 B | ... | ... |

### 数据流
[描述数据如何在组件间流动]

## 数据模型

### 核心实体
[ER 图或实体定义]

```typescript
// 示例
interface User {
  id: string;
  name: string;
  createdAt: Date;
}
```

### 数据库 Schema
[表结构定义]

## API 设计

### 接口列表
| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/users | 获取用户列表 |
| POST | /api/users | 创建用户 |

### 接口详情

#### GET /api/users
**请求参数:**
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| page | int | 否 | 页码 |

**响应示例:**
```json
{
  "data": [...],
  "total": 100
}
```

## 错误处理

### 错误类型
| 错误码 | 描述 | 处理方式 |
|--------|------|----------|
| 400 | 参数错误 | 返回具体错误信息 |
| 401 | 未授权 | 跳转登录 |
| 500 | 服务器错误 | 记录日志，返回通用错误 |

### 错误响应格式
```json
{
  "error": {
    "code": "INVALID_PARAM",
    "message": "参数 xxx 不能为空"
  }
}
```

## 安全考虑

### 认证与授权
[描述认证机制]

### 数据安全
[敏感数据处理方式]

### 安全检查清单
- [ ] 输入验证
- [ ] SQL 注入防护
- [ ] XSS 防护
- [ ] CSRF 防护
- [ ] 敏感数据加密

## 测试策略

### 测试类型
| 类型 | 覆盖范围 | 工具 |
|------|----------|------|
| 单元测试 | 核心逻辑 | Jest |
| 集成测试 | API 接口 | Supertest |
| E2E 测试 | 关键流程 | Playwright |

### 测试用例
[关键测试场景]

## 性能考虑

### 性能目标
| 指标 | 目标值 |
|------|--------|
| 响应时间 | < 200ms |
| 并发用户 | 1000 |
| 可用性 | 99.9% |

### 优化策略
[缓存、索引、异步等]

## 实施计划

### 阶段划分
| 阶段 | 内容 | 预计时间 |
|------|------|----------|
| Phase 1 | MVP | 1 周 |
| Phase 2 | 完善 | 2 周 |
| Phase 3 | 优化 | 1 周 |

### 依赖
[外部依赖和前置条件]

## 风险与缓解

| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|----------|
| 风险 A | 高 | 中 | ... |

## 附录

### 参考资料
- [相关文档链接]

### 变更记录
| 日期 | 变更内容 | 作者 |
|------|----------|------|
| YYYY-MM-DD | 初稿 | XXX |
```

---

## 简化版模板（适用于小型功能）

```markdown
# [功能名称] 设计

## 问题
[描述要解决的问题]

## 方案
[描述解决方案]

## 实现
[关键实现要点]

## 测试
[如何验证]

## 风险
[潜在问题和应对]
```

---

## 架构决策记录 (ADR) 模板

```markdown
# ADR-[编号]: [决策标题]

## 状态
提议 / 已接受 / 已废弃

## 背景
[为什么需要做这个决策]

## 决策
[做出的决策是什么]

## 备选方案
[考虑过的其他方案]

## 后果
[这个决策的影响，包括正面和负面]
```

---

## 分段呈现顺序

当使用增量验证方式呈现设计时，按以下顺序分段：

1. **背景与目标** (5-10%)
   - 为什么要做
   - 要达成什么

2. **方案概述** (10-15%)
   - 选定方案简介
   - 为什么选这个

3. **架构设计** (20-25%)
   - 整体架构
   - 核心组件
   - 数据流

4. **数据模型** (15-20%)
   - 实体定义
   - 关系说明

5. **接口设计** (15-20%)
   - API 列表
   - 关键接口详情

6. **错误处理** (5-10%)
   - 错误类型
   - 处理方式

7. **测试与风险** (5-10%)
   - 测试策略
   - 风险缓解

每段呈现后询问：
```
这部分设计看起来对吗？有需要调整的地方吗？
```