---
name: dev-arch
description: 软件架构设计技能。用于系统设计、技术选型、架构评审、设计文档编写。当用户提到架构设计、系统设计、技术方案、API 设计相关任务时自动激活。
---

# 软件架构设计 Skill (dev-arch)

## 概述

本技能用于软件架构设计工作，包括：
- 系统架构设计与评审
- 技术选型与方案对比
- API 设计与文档
- 数据库设计
- 设计模式应用

---

## 架构设计流程

### 1. 需求分析

```
输入：
- 业务需求文档
- 非功能性需求（性能、安全、可用性）
- 技术约束条件

输出：
- 需求清单
- 约束条件列表
```

### 2. 概要设计

```
内容：
- 系统边界定义
- 模块划分
- 技术栈选择
- 部署架构

输出：
- 架构图
- 技术方案文档
```

### 3. 详细设计

```
内容：
- API 接口设计
- 数据模型设计
- 核心流程设计
- 异常处理设计

输出：
- API 文档
- ER 图
- 时序图
```

---

## 架构设计模板

### 系统设计文档模板

```markdown
# [系统名称] 技术设计文档

## 1. 概述
### 1.1 背景
[项目背景和目标]

### 1.2 范围
[系统边界和功能范围]

### 1.3 术语定义
| 术语 | 定义 |
|------|------|
| ... | ... |

## 2. 系统架构
### 2.1 整体架构图
[架构图]

### 2.2 模块说明
| 模块 | 职责 | 技术栈 |
|------|------|--------|
| ... | ... | ... |

### 2.3 部署架构
[部署图]

## 3. 技术选型
### 3.1 技术栈
| 类别 | 选择 | 理由 |
|------|------|------|
| 后端框架 | ... | ... |
| 数据库 | ... | ... |
| 缓存 | ... | ... |
| 消息队列 | ... | ... |

### 3.2 技术对比
[备选方案对比分析]

## 4. 数据设计
### 4.1 ER 图
[ER 图]

### 4.2 核心表设计
[表结构说明]

### 4.3 索引策略
[索引设计]

## 5. API 设计
### 5.1 API 规范
[RESTful 规范说明]

### 5.2 核心接口
[接口定义]

## 6. 非功能性设计
### 6.1 性能设计
- 响应时间目标
- 吞吐量目标
- 优化策略

### 6.2 安全设计
- 认证授权
- 数据安全
- 日志审计

### 6.3 可用性设计
- 容错机制
- 监控告警
- 备份恢复

## 7. 风险评估
| 风险 | 影响 | 概率 | 应对措施 |
|------|------|------|----------|
| ... | ... | ... | ... |

## 8. 附录
- 参考资料
- 变更历史
```

---

## 常用架构模式

### 分层架构

```
┌─────────────────────────────────┐
│        表现层 (Presentation)      │
├─────────────────────────────────┤
│        业务层 (Business)          │
├─────────────────────────────────┤
│        数据层 (Data Access)       │
├─────────────────────────────────┤
│        基础设施 (Infrastructure)   │
└─────────────────────────────────┘
```

### 微服务架构

```
┌─────┐  ┌─────┐  ┌─────┐
│ API │  │ API │  │ API │
│ GW  │──│ SVC │──│ SVC │
└──┬──┘  └──┬──┘  └──┬──┘
   │        │        │
   └────────┴────────┘
         │
    ┌────┴────┐
    │ Message │
    │  Queue  │
    └─────────┘
```

### 六边形架构 (端口-适配器)

```
           ┌─────────────────┐
    ┌──────│    Adapters     │──────┐
    │      │   (Inbound)     │      │
    │      └────────┬────────┘      │
    │               │               │
┌───┴───┐    ┌──────┴──────┐   ┌────┴────┐
│ REST  │    │    Core     │   │  Repo   │
│ API   │────│  Business   │───│  Impl   │
└───────┘    │   Domain    │   └─────────┘
             └─────────────┘
```

---

## API 设计规范

### RESTful 规范

| 方法 | 用途 | 示例 |
|------|------|------|
| GET | 查询资源 | `GET /users/{id}` |
| POST | 创建资源 | `POST /users` |
| PUT | 全量更新 | `PUT /users/{id}` |
| PATCH | 部分更新 | `PATCH /users/{id}` |
| DELETE | 删除资源 | `DELETE /users/{id}` |

### 响应格式

```json
{
  "code": 0,
  "message": "success",
  "data": {},
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}
```

### 错误码设计

| 范围 | 类型 | 示例 |
|------|------|------|
| 10000-19999 | 系统错误 | 10001 内部错误 |
| 20000-29999 | 参数错误 | 20001 参数缺失 |
| 30000-39999 | 业务错误 | 30001 用户不存在 |
| 40000-49999 | 权限错误 | 40001 未授权 |

---

## 数据库设计

### 命名规范

| 类型 | 规范 | 示例 |
|------|------|------|
| 表名 | 小写下划线，复数 | `user_accounts` |
| 字段 | 小写下划线 | `created_at` |
| 主键 | id | `id` |
| 外键 | 表名_id | `user_id` |
| 索引 | idx_表名_字段 | `idx_users_email` |

### 通用字段

```sql
-- 每个表必须包含的字段
id          BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
created_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
deleted_at  DATETIME DEFAULT NULL  -- 软删除
```

### 索引策略

- 主键索引：每表必须
- 唯一索引：业务唯一字段
- 普通索引：高频查询字段
- 联合索引：遵循最左前缀原则

---

## 技术选型参考

### 后端框架

| 语言 | 框架 | 适用场景 |
|------|------|----------|
| Go | Gin, Echo | 高并发 API |
| Java | Spring Boot | 企业应用 |
| Python | FastAPI, Django | 快速开发 |
| Node.js | NestJS, Express | 全栈/实时 |

### 数据库选型

| 类型 | 选项 | 适用场景 |
|------|------|----------|
| 关系型 | MySQL, PostgreSQL | 事务型业务 |
| 文档型 | MongoDB | 灵活结构 |
| 键值型 | Redis | 缓存/会话 |
| 时序 | InfluxDB | 监控/IoT |
| 搜索 | Elasticsearch | 全文检索 |

### 消息队列

| 选项 | 特点 | 适用场景 |
|------|------|----------|
| Redis | 简单快速 | 轻量级队列 |
| RabbitMQ | 可靠传递 | 企业集成 |
| Kafka | 高吞吐 | 日志/流处理 |
| NATS | 轻量级 | 微服务通信 |

---

## 架构评审检查清单

### 功能性检查
- [ ] 需求覆盖完整
- [ ] 边界条件处理
- [ ] 异常情况处理
- [ ] 数据一致性保证

### 非功能性检查
- [ ] 性能目标明确
- [ ] 安全措施到位
- [ ] 可扩展性设计
- [ ] 可维护性考虑

### 运维检查
- [ ] 监控指标定义
- [ ] 日志规范
- [ ] 部署方案
- [ ] 回滚机制

---

## 与 ai-proj 集成

### 创建架构设计任务

```bash
# 创建架构设计任务
ai-proj task create --title "[系统名称] 架构设计"

# 创建子任务
ai-proj task create --title "需求分析" --parent-id <parentId>
ai-proj task create --title "概要设计" --parent-id <parentId>
ai-proj task create --title "详细设计" --parent-id <parentId>
ai-proj task create --title "架构评审" --parent-id <parentId>
```

### 关联设计文档

```bash
# 附加设计文档到任务
ai-proj task append-doc --id <taskId> --content "设计文档内容 (Markdown)"
```

---

## 最佳实践

1. **KISS 原则** - 保持简单，避免过度设计
2. **YAGNI 原则** - 不要预测未来需求
3. **DRY 原则** - 避免重复代码
4. **SOLID 原则** - 面向对象设计原则
5. **关注点分离** - 模块职责单一
6. **高内聚低耦合** - 模块独立性

---

## 文档工具

### 架构图工具

- **draw.io** - 在线免费绘图
- **PlantUML** - 代码生成图
- **Mermaid** - Markdown 内嵌图
- **Excalidraw** - 手绘风格

### Mermaid 示例

```mermaid
sequenceDiagram
    Client->>API Gateway: Request
    API Gateway->>Auth Service: Validate Token
    Auth Service-->>API Gateway: Valid
    API Gateway->>Business Service: Forward Request
    Business Service->>Database: Query
    Database-->>Business Service: Result
    Business Service-->>API Gateway: Response
    API Gateway-->>Client: Response
```

---

## 参考资源

- [系统设计入门](https://github.com/donnemartin/system-design-primer)
- [微服务架构](https://microservices.io/)
- [RESTful API 设计指南](https://restfulapi.net/)
- [数据库设计范式](https://www.guru99.com/database-normalization.html)