初始化

2026-03-05 21:27:11 +08:00
commit 130de0fd5d
140 changed files with 21972 additions and 0 deletions
--- a/docs/architecture/system-design.md
+++ b/docs/architecture/system-design.md
@@ -0,0 +1,133 @@
+# 🏗️ 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*