ai-proj-helper/plugins/dev-arch-plugin/skills/SKILL.md

name, description

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

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

概述

本技能用于软件架构设计工作，包括：

• 系统架构设计与评审
• 技术选型与方案对比
• API 设计与文档
• 数据库设计
• 设计模式应用

---

架构设计流程

1. 需求分析

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

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

2. 概要设计

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

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

3. 详细设计

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

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

---

架构设计模板

系统设计文档模板

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

## 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}

响应格式

{
  "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

通用字段

-- 每个表必须包含的字段
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 集成

创建架构设计任务

# 创建架构设计任务
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>

关联设计文档

# 附加设计文档到任务
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 示例

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

---

参考资源

• 系统设计入门
• 微服务架构
• RESTful API 设计指南
• 数据库设计范式