Arch Doc Generation

---
name: arch-doc-generation
description: 架构文档生成 — 生成架构设计说明书、技术方案文档、API设计文档、部署架构文档
agent_created: true
---

# 架构文档生成

## 概述

生成结构化的软件架构文档，包括架构设计说明书、技术方案文档、API 设计文档、部署架构文档等。支持 Markdown 输出。

**⚠ PDF输出:** 此技能负责文档内容的组织与模板。如果需要将文档输出为 PDF，请另外加载 `chinese-pdf-generation` 技能（它会处理 fpdf2 的字形、分页、跨页表格等底层问题），或者直接告知用户以 Markdown 形式交付。

## 触发条件

当用户需要：
- "写一份架构设计文档"
- "生成技术方案"
- "写API设计文档"
- "写部署架构文档"
- "输出架构文档"
- 任何需要生成正式架构文档的场景

## 文档类型

### 1. 架构设计说明书

标准架构设计文档，包含以下章节：

```markdown
# {{系统名称}} 架构设计说明书

## 1. 文档概述
- 版本: v1.0
- 作者: {{作者}}
- 日期: {{YYYY-MM-DD}}
- 状态: 草稿/评审中/已定稿

## 2. 项目背景
- 业务目标
- 项目范围
- 关键约束

## 3. 架构设计原则
- 原则1: {{原则}}（理由：{{理由}}）
- 原则2: {{原则}}（理由：{{理由}}）

## 4. 系统架构概览
- 架构模式（微服务/单体/事件驱动）
- 系统上下文图（C4 Level 1）
- 容器图（C4 Level 2）

## 5. 核心模块设计
### 5.1 {{模块1}}
- 职责
- 核心接口
- 依赖关系

### 5.2 {{模块2}}
- 职责
- 核心接口
- 依赖关系

## 6. 数据架构
- 数据库选型
- 数据模型
- 缓存策略
- 数据流

## 7. 部署架构
- 部署拓扑
- 高可用方案
- 容灾策略
- 监控告警

## 8. 安全架构
- 认证授权方案
- 数据加密
- 网络安全

## 9. 非功能性设计
- 性能设计
- 可扩展性
- 可用性
- 安全性

## 10. 架构决策记录
- ADR-001: {{决策}}
- ADR-002: {{决策}}

## 11. 附录
- 术语表
- 参考文献
- 变更历史
```

### 2. 技术方案文档

```markdown
# {{项目名称}} 技术方案

## 1. 背景与目标
{{业务背景、技术目标}}

## 2. 技术选型
| 技术领域 | 选型 | 理由 |
|----------|------|------|
| 后端框架 | {{选型}} | {{理由}} |
| 数据库 | {{选型}} | {{理由}} |
| 消息队列 | {{选型}} | {{理由}} |
| 缓存 | {{选型}} | {{理由}} |
| 部署 | {{选型}} | {{理由}} |

## 3. 系统架构
{{架构图 + 说明}}

## 4. 核心流程
### 4.1 {{流程1}}
{{流程图 + 说明}}

### 4.2 {{流程2}}
{{流程图 + 说明}}

## 5. 接口设计
### 5.1 REST API
| 方法 | 路径 | 说明 | 请求体 | 响应 |
|------|------|------|--------|------|
| GET | /api/v1/{{资源}} | 列表查询 | - | {{响应}} |
| POST | /api/v1/{{资源}} | 创建 | {{请求体}} | {{响应}} |

### 5.2 消息队列
| Topic | 生产者 | 消费者 | 消息格式 |
|-------|--------|--------|----------|
| {{topic}} | {{服务}} | {{服务}} | {{格式}} |

## 6. 实施计划
- 阶段1（{{时间}}）：{{内容}}
- 阶段2（{{时间}}）：{{内容}}
- 阶段3（{{时间}}）：{{内容}}

## 7. 风险评估
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| {{风险}} | 高/中/低 | 高/中/低 | {{措施}} |
```

### 3. API设计文档

```markdown
# {{系统名称}} API设计文档

## 1. 概述
- 协议: HTTP/REST / gRPC
- 基础URL: {{base_url}}
- 认证方式: {{认证方案}}
- 版本策略: {{版本策略}}

## 2. 接口规范
### 通用规范
- 请求/响应格式: JSON
- 分页: page, size, sort
- 错误响应格式: {code, message, details}
- 状态码规范

## 3. API列表

### 3.1 {{资源名}}
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/{{资源}} | 列表查询 |
| POST | /api/v1/{{资源}} | 创建 |
| GET | /api/v1/{{资源}}/{id} | 详情 |
| PUT | /api/v1/{{资源}}/{id} | 更新 |
| DELETE | /api/v1/{{资源}}/{id} | 删除 |

### 3.2 请求/响应示例
```json
// 请求
POST /api/v1/orders
{
  "userId": "u123",
  "items": [{"productId": "p456", "quantity": 2}]
}

// 响应
{
  "id": "ord-789",
  "status": "CREATED",
  "totalAmount": 199.99
}
```

## 4. 错误码
| 状态码 | 错误码 | 说明 |
|--------|--------|------|
| 400 | INVALID_REQUEST | 请求参数错误 |
| 401 | UNAUTHORIZED | 未认证 |
| 403 | FORBIDDEN | 无权限 |
| 404 | NOT_FOUND | 资源不存在 |
| 500 | INTERNAL_ERROR | 服务端错误 |
```