/architecture-design

name: architect/architecture-design
description: 系统架构设计方法论，包含架构模式选择、系统分层、目录结构设计
version: 1.0.0
agent: architect
type: methodology
user-invocable: false
agent-invocable: true
dependencies:
- shared/tech-stack-detection
- architect/tech-research
  triggers:
- 技术调研完成后
- 需要设计系统架构时
- 需要定义项目结构时
  metadata:
  internal: true

系统架构设计方法论

适用场景

基于技术调研结论，设计完整的系统架构，包括：

• 架构模式选择（单体/前后端分离/微服务）
• 系统分层和模块划分
• 目录结构设计
• 数据模型设计
• API设计

架构设计流程

1. 架构模式选择

根据项目规模、团队规模、业务复杂度选择合适的架构模式：

| 架构模式 | 适用场景 | 优点 | 缺点 | 团队规模 | | -------------- | ---------------------------- | ---------------------------- | -------------------- | -------- | | **单体应用** | 小型项目、快速迭代、MVP | 简单、开发快、易部署 | 扩展性差、耦合高 | 1-3人 | | **前后端分离** | 中型项目、团队协作、多端支持 | 职责清晰、并行开发、技术独立 | 部署复杂、接口管理 | 3-10人 | | **微服务** | 大型项目、独立部署、高可用 | 独立扩展、技术异构、故障隔离 | 复杂度高、运维成本高 | 10+人 | | **Serverless** | 事件驱动、弹性伸缩、按需付费 | 免运维、自动扩展、成本优化 | 冷启动、供应商锁定 | 任意 |

**选择决策树**：

项目规模？
├─ 小型（< 10个页面）
│  └─ 单体应用 或 前后端分离（简化版）
├─ 中型（10-50个页面）
│  └─ 前后端分离
└─ 大型（> 50个页面）
   ├─ 业务模块独立？
   │  ├─ 是 → 微服务
   │  └─ 否 → 前后端分离
   └─ 流量波动大？
      └─ 是 → Serverless

2. 系统分层设计

经典三层架构

┌─────────────────────────────────┐
│      表现层 (Presentation)       │  ← 用户界面、API接口
├─────────────────────────────────┤
│       业务层 (Business)          │  ← 业务逻辑、流程控制
├─────────────────────────────────┤
│      数据层 (Data Access)        │  ← 数据库访问、ORM
└─────────────────────────────────┘

前后端分离架构

┌──────────────┐
│   前端应用    │  ← React/Vue/Angular
└──────┬───────┘
       │ HTTP/WebSocket
┌──────▼───────┐
│   API网关    │  ← 路由、认证、限流
└──────┬───────┘
       │
┌──────▼───────┐
│   后端服务    │  ← 业务逻辑
└──────┬───────┘
       │
┌──────▼───────┐
│   数据库     │  ← PostgreSQL/MongoDB
└──────────────┘

微服务架构

┌──────────┐
│  前端应用 │
└────┬─────┘
     │
┌────▼─────┐
│ API网关  │
└────┬─────┘
     │
     ├─────┬─────┬─────┐
     │     │     │     │
┌────▼┐ ┌─▼──┐ ┌▼───┐ ┌▼────┐
│用户 │ │订单│ │商品│ │支付 │
│服务│ │服务│ │服务│ │服务 │
└────┘ └────┘ └────┘ └─────┘
  │      │      │       │
  └──────┴──────┴───────┘
         │
    ┌────▼────┐
    │ 数据库  │
    └─────────┘

3. 系统架构图

使用 Mermaid 绘制系统架构图：

**前后端分离架构示例**：

graph TB
    subgraph 客户端
        Web[Web 应用]
        Mobile[移动端]
    end

    subgraph 接入层
        CDN[CDN]
        LB[负载均衡]
    end

    subgraph 应用层
        subgraph 前端服务
            FE[前端应用]
        end

        subgraph 后端服务
            API[API 网关]
            Auth[认证服务]
            BIZ[业务服务]
        end
    end

    subgraph 数据层
        DB[(主数据库)]
        Cache[(缓存)]
        MQ[消息队列]
    end

    subgraph 基础设施
        Log[日志系统]
        Monitor[监控告警]
    end

    Web --> CDN
    Mobile --> LB
    CDN --> LB
    LB --> FE
    FE --> API
    API --> Auth
    API --> BIZ
    BIZ --> DB
    BIZ --> Cache
    BIZ --> MQ
    BIZ --> Log

4. 目录结构设计

**重要原则**： 1. **遵循框架惯例**：使用检测到的框架的标准目录结构 2. **关注点分离**：业务逻辑、数据访问、API层清晰分离 3. **测试并置**：测试文件与源码在同层或专用tests目录 4. **配置集中**：环境配置统一管理

Next.js App Router 项目结构

project/
├── app/                    # Next.js App Router
│   ├── (auth)/            # 路由组：认证相关页面
│   │   ├── login/
│   │   └── register/
│   ├── (dashboard)/       # 路由组：仪表板
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── api/               # API Routes
│   │   ├── auth/
│   │   └── users/
│   ├── layout.tsx         # 根布局
│   └── page.tsx           # 首页
├── components/            # React组件
│   ├── ui/               # UI组件
│   └── features/         # 功能组件
├── lib/                   # 工具库
│   ├── db.ts             # 数据库连接
│   ├── auth.ts           # 认证逻辑
│   └── utils.ts          # 工具函数
├── prisma/               # Prisma ORM
│   └── schema.prisma
├── public/               # 静态资源
├── tests/                # 测试
└── package.json

Express + React 前后端分离结构

project/
├── client/               # 前端
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── hooks/
│   │   └── App.tsx
│   ├── public/
│   └── package.json
├── server/               # 后端
│   ├── src/
│   │   ├── routes/      # 路由
│   │   ├── controllers/ # 控制器
│   │   ├── services/    # 业务逻辑
│   │   ├── models/      # 数据模型
│   │   ├── middleware/  # 中间件
│   │   └── app.ts       # 入口
│   ├── tests/
│   └── package.json
├── shared/              # 共享代码
│   └── types/          # TypeScript类型
└── docker-compose.yml

Python FastAPI 项目结构

project/
├── app/
│   ├── api/             # API路由
│   │   ├── v1/
│   │   │   ├── endpoints/
│   │   │   └── router.py
│   │   └── deps.py      # 依赖注入
│   ├── core/            # 核心配置
│   │   ├── config.py
│   │   └── security.py
│   ├── models/          # 数据模型
│   ├── schemas/         # Pydantic schemas
│   ├── services/        # 业务逻辑
│   └── main.py          # 入口
├── tests/
├── alembic/             # 数据库迁移
├── requirements.txt
└── pyproject.toml

Go 标准项目结构

project/
├── cmd/                 # 主程序入口
│   └── api/
│       └── main.go
├── internal/            # 私有代码
│   ├── handler/        # HTTP处理器
│   ├── service/        # 业务逻辑
│   ├── repository/     # 数据访问
│   └── model/          # 数据模型
├── pkg/                 # 公共库
│   └── utils/
├── api/                 # API定义
│   └── openapi.yaml
├── migrations/          # 数据库迁移
├── tests/
├── go.mod
└── go.sum

5. 技术栈总览

输出完整的技术栈清单：

| 层级 | 技术 | 版本 | 说明 | | ------------ | ------------------ | ---- | -------------- | | **前端** | | | | | 框架 | Next.js | 14.x | App Router模式 | | UI库 | React | 18.x | | | 样式 | Tailwind CSS | 3.x | 原子化CSS | | 状态管理 | Zustand | 4.x | 轻量级状态管理 | | **后端** | | | | | 运行时 | Node.js | 20.x | LTS版本 | | 框架 | Next.js API Routes | 14.x | 与前端一体 | | ORM | Prisma | 5.x | 类型安全ORM | | **数