# 🏗️ System Design — 百万级并发企业数字化平台

> 填写本文档，为 AI Agent 提供系统架构上下文。

---

## 1. 技术栈

| 层级 | 技术 | 版本 |
|------|------|------|
| 前端框架 | Vue 3 + Vite | 3.5+ / 7.x |
| UI 库 (管理端) | Element Plus + Tailwind CSS | 2.x / 4.x |
| UI 库 (用户端) | Headless UI + Tailwind CSS | 1.x / 4.x |
| 状态管理 | Pinia | 3.x |
| 路由 | Vue Router | 4.x |
| HTTP 客户端 | Axios | 1.x |
| 后端框架 | Hyperf | 3.1 |
| 协程引擎 | Swoole | 5.0+ |
| 编程语言 | PHP | 8.1+ |
| 数据库 | MySQL | 8.1 |
| 缓存 | Redis | 7.x |
| 反向代理 | Nginx | 1.25+ |
| 容器化 | Docker + Docker Compose | - |

## 2. 架构总览

```
┌─────────────────────────────────────────────────────────────────┐
│                          用户层                                   │
│   PC 浏览器   │   移动端 (响应式)   │   平板   │   管理后台        │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌───────────────────────────────────────────────────────────────────┐
│                    CDN + WAF (可选)                                │
└───────────────────────────┬───────────────────────────────────────┘
                            │
                            ▼
┌───────────────────────────────────────────────────────────────────┐
│              Nginx 集群 (负载均衡 + SSL + 静态资源)                  │
│              - upstream hyperf_cluster                             │
│              - WebSocket proxy                                    │
└───────────────────────────┬───────────────────────────────────────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
       ┌──────────┐  ┌──────────┐  ┌──────────┐
       │ Hyperf-1 │  │ Hyperf-2 │  │ Hyperf-N │  (水平扩展)
       │ HTTP:9501│  │ HTTP:9501│  │ HTTP:9501│
       │ WS:9502  │  │ WS:9502  │  │ WS:9502  │
       └────┬─────┘  └────┬─────┘  └────┬─────┘
            │              │              │
            └──────┬───────┴──────┬───────┘
                   │              │
            ┌──────┴──────┐ ┌────┴────────┐
            │   Redis     │ │   MySQL     │
            │  Sentinel/  │ │  Master     │
            │  Cluster    │ │   ├─Slave 1 │
            │             │ │   └─Slave 2 │
            └─────────────┘ └─────────────┘
```

## 3. 分层架构

```
请求 → Nginx → Hyperf HTTP Server → 中间件链 → Controller
                                                    │
                                                    ▼
                                              Service 层
                                                    │
                                    ┌───────────────┼───────────────┐
                                    ▼               ▼               ▼
                              Repository        Redis Cache      Event Bus
                                    │                               │
                                    ▼                               ▼
                                  MySQL                       Async Queue
```

## 4. 核心模块

<!-- 根据实际项目填写 -->

| 模块 | 说明 | 关键接口 |
|------|------|---------|
| 用户认证 | JWT + RBAC 权限 | `/admin/auth/login`, `/admin/auth/refresh` |
| 权限管理 | 用户/角色/菜单/数据权限 | `/admin/users`, `/admin/roles`, `/admin/menus` |
| 生产管理 | 订单/子订单/发货/收款 | `/admin/production-orders`, `/admin/sub-orders` |
| 工作流 | 审批流程定义与执行 | `/admin/workflows`, `/admin/tasks` |
| 通知中心 | WebSocket + 站内消息 + 短信 | `/admin/notifications`, `ws://9502` |
| 客户管理 | 客户/平台/店铺 | `/admin/customers`, `/admin/platforms` |

## 5. 并发设计要点

| 设计要点 | 实现方式 |
|---------|---------|
| 无状态服务 | Session/Token 存 Redis，文件存对象存储 |
| 数据库高可用 | MySQL 主从 + 读写分离 + 连接池 |
| 缓存策略 | Cache-Aside + 穿透/击穿/雪崩防护 |
| 异步削峰 | Hyperf AsyncQueue (Redis 驱动) |
| 分布式锁 | Redis SET NX + Lua 脚本 |
| 限流 | 令牌桶 (API) + 滑动窗口 (用户) |
| 实时通信 | Swoole WebSocket + Redis Pub/Sub |
| 水平扩展 | Docker Compose → K8s HPA |

## 6. 部署拓扑

<!-- 根据实际部署环境填写 -->

### 开发环境
- 单机 Docker Compose (Nginx + Hyperf + MySQL + Redis)

### 生产环境
- Nginx 集群 (2+ 节点)
- Hyperf 应用 (4+ 实例)
- MySQL 主从 (1 写 + 2 读)
- Redis Sentinel (3 节点)

## 7. 决策记录

<!-- 重要架构决策记录在 docs/architecture/decisions/ -->

| 决策 | 选择 | 原因 |
|------|------|------|
| 后端框架 | Hyperf + Swoole | 协程高性能，连接池，与旧项目技术栈一致 |
| 数据库 | MySQL 8.1 | 成熟稳定，JSON 支持，与旧项目一致 |
| 缓存 | Redis 7 | 数据结构丰富，连接池，队列支持 |
| 前端框架 | Vue 3 + Vite | 生态成熟，与旧项目一致，Composition API |
| UI 库 | 管理端 Element Plus + Tailwind / 用户端 Headless UI + Tailwind | 管理端企业级组件 + 用户端轻量交互 |
| 部署 | Docker Compose → K8s | 渐进式扩展 |

---

*最后更新: YYYY-MM-DD*