# Tech Spec

> 【技术方案】根据需求文档输出技术方案设计，包含架构设计、模块划分、接口定义、数据模型、技术选型、风险评估。 触发时机： - 用户要求"写技术方案"、"技术设计"、"系统设计" - 需求评审后需要技术实现方案 - 重构前需要技术方案论证 输出格式为 Markdown，可直接用于技术评审。

- Skill: `afine907/tech-spec` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add afine907/tech-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/afine907/tech-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: afine907 (https://skillmd.com/u/afine907)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/afine907/tech-spec

---


# Tech Spec — 技术方案设计技能

根据需求文档输出结构化技术方案，用于技术评审和团队对齐。


## Goal

根据需求文档输出技术方案设计，包含架构设计、模块划分、接口定义、数据模型、技术选型、风险评估

## Trigger

- 用户要求"写技术方案"、"技术设计"、"系统设计"
  - 需求评审后需要技术实现方案
  - 重构前需要技术方案论证

## 工作流程

```
需求分析 → 方案设计 → 技术选型 → 详细设计 → 风险评估 → 输出文档
```

## 输出文档结构

```markdown
# [功能名称] 技术方案

## 一、需求概述
### 1.1 业务背景
{为什么要做这个功能}

### 1.2 核心需求
- {需求点1}
- {需求点2}

### 1.3 约束条件
- 性能要求：{QPS、延迟、并发}
- 数据规模：{数据量、增长速度}
- 兼容性：{需要兼容的系统/版本}

## 二、方案设计

### 2.1 整体架构
{架构图描述或 Mermaid 图}

### 2.2 核心流程
{关键业务流程的时序图}

### 2.3 模块划分
| 模块 | 职责 | 技术栈 | 负责人 |
|------|------|--------|--------|
| 模块A | {职责} | {技术} | {人} |

### 2.4 接口定义
#### API-1: {接口名称}
- Method: POST /api/v1/xxx
- Request: {Schema}
- Response: {Schema}
- Error Codes: {错误码列表}

### 2.5 数据模型
```sql
CREATE TABLE xxx (
    id BIGINT PRIMARY KEY,
    ...
);
```

### 2.6 缓存设计
| 缓存 key | 数据来源 | 过期策略 | 更新方式 |
|-----------|----------|----------|----------|
| user:{id} | DB | 30min | Cache-Aside |

### 2.7 消息设计（如涉及）
| Topic | 生产者 | 消费者 | 消息格式 |
|-------|--------|--------|----------|
| order.created | 订单服务 | 库存服务 | JSON |

## 三、技术选型

| 组件 | 选型 | 理由 | 备选方案 |
|------|------|------|----------|
| 数据库 | MySQL 8.0 | {理由} | PostgreSQL |
| 缓存 | Redis 7 | {理由} | Memcached |
| 消息队列 | Kafka | {理由} | RabbitMQ |
| 搜索引擎 | Elasticsearch | {理由} | MeiliSearch |

## 四、详细设计

### 4.1 核心算法
{复杂业务逻辑的算法描述}

### 4.2 状态机
{状态流转图}

### 4.3 幂等设计
{如何保证接口幂等}

### 4.4 分布式事务（如涉及）
{采用的分布式事务方案：Saga/TCC/最终一致性}

## 五、非功能需求

### 5.1 性能
| 场景 | 目标 | 方案 |
|------|------|------|
| 读接口 | < 50ms P99 | 缓存 + 索引 |
| 写接口 | < 200ms P99 | 异步 + 批量 |

### 5.2 可用性
- SLA 目标：{99.9%}
- 降级方案：{功能降级策略}
- 熔断策略：{熔断阈值}

### 5.3 监控告警
| 指标 | 阈值 | 告警渠道 |
|------|------|----------|
| 接口延迟 P99 | > 500ms | 钉钉/飞书 |
| 错误率 | > 1% | 钉钉/飞书 |

## 六、风险评估

| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| {风险1} | 高/中/低 | 高/中/低 | {措施} |

## 七、里程碑

| 阶段 | 时间 | 交付物 | 验收标准 |
|------|------|--------|----------|
| 设计评审 | {日期} | 本文档 | 评审通过 |
| 开发 | {日期} | 代码 | 单元测试通过 |
| 联调 | {日期} | 接口联调 | 集成测试通过 |
| 上线 | {日期} | 灰度发布 | 监控无异常 |

## 八、待确认事项
- [ ] {待确认项1}
- [ ] {待确认项2}
```

## 设计原则

1. **简单优先** — 能用简单方案解决的不要过度设计
2. **可扩展** — 设计时考虑未来3-6个月的扩展
3. **可观测** — 关键路径必须有日志、指标、链路追踪
4. **容错设计** — 外部依赖必须有超时、重试、降级
5. **安全第一** — 认证、授权、加密、审计缺一不可

## Example

```
# 从需求文档生成技术方案
根据以下需求设计技术方案：[粘贴需求]

# 设计特定功能的技术方案
设计一个用户权限系统的技术方案

# 审查现有技术方案
审查以下技术方案，指出问题：[粘贴方案]

# 方案对比
对比以下两种技术方案的优劣：[方案A] vs [方案B]
```

## 参考资料

- 技术方案模板: [references/template.md](references/template.md)
- 架构决策记录: [references/adr-template.md](references/adr-template.md)