vibe_coding/docs/architecture/system-design.md

🏗️ 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. 决策记录

决策	选择	原因
后端框架	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