# 整体架构图

本章从全局视角阐述系统的整体技术架构，涵盖前端、后端、数据库及基础设施等核心组成部分，旨在帮助开发者快速建立对系统全貌的清晰认知，为后续的开发和运维工作奠定基础。

## 架构总览

下图展示了从用户浏览器发起请求到最终返回响应的完整链路：

```
┌─────────────────────────────────────────────────────────────────────────┐
│ Browser (Vue3 + ElementPlus)                                          │
│ Axios HTTP Request / Vite Dev Proxy                                    │
└──────────────────────────────┬──────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Nginx (反向代理)                                                        │
│ 静态资源 / SSL 终止 / 负载均衡 / gzip 压缩                              │
└──────────────────────────────┬──────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Flask Application                                                      │
│ ┌───────────────────────────────────────────────────────────────────┐  │
│ │ Middleware Chain (请求/响应钩子)                                    │  │
│ │ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌───────┐     │  │
│ │ │ CORS │→│ Redis │→│ RateLimit │→│ DBSession│→│OpLog │     │  │
│ │ │ 跨域处理 │ │ 上下文 │ │ 滑动窗口 │ │ 会话管理 │ │操作日志│     │  │
│ │ └─────────┘ └─────────┘ └──────────┘ └─────────┘ └───────┘     │  │
│ └───────────────────────────────┬───────────────────────────────────┘  │
│                                 ▼                                      │
│ ┌───────────────────────────────────────────────────────────────────┐  │
│ │ Blueprint Router (路由分发)                                        │  │
│ │ ┌─────────────┐ ┌──────────────┐ ┌──────────────────────────┐   │  │
│ │ │login_required│→│check_permis- │→│ Router (HTTP 层)         │   │  │
│ │ │ JWT 认证 │ │ sion RBAC    │ │ @blueprint.route()       │   │  │
│ │ │ │ │ 鉴权 │ │ WTForms 校验 │   │  │
│ │ └─────────────┘ └──────────────┘ └────────────┬─────────────┘   │  │
│ └───────────────────────────────────────────────────┼───────────────┘  │
│                                                     ▼                  │
│ ┌───────────────────────────────────────────────────────────────────┐  │
│ │ Service Layer (业务逻辑层)                                         │  │
│ │ BaseService / 自定义 Service                                      │  │
│ │ 唯一性校验 · 字段组装 · 序列化 · 文件处理 · 缓存管理              │  │
│ └───────────────────────────────┬───────────────────────────────────┘  │
│                                 ▼                                      │
│ ┌───────────────────────────────────────────────────────────────────┐  │
│ │ Repository Layer (数据访问层)                                      │  │
│ │ BaseRepository                                                    │  │
│ │ CRUD · 软删除 · 分页 · 等值查询 · 原始条件查询                   │  │
│ └───────────────────────────────┬───────────────────────────────────┘  │
│                                 ▼                                      │
│ ┌─────────────────────┐ ┌──────────────────────────────────────────┐  │
│ │ SQLAlchemy 2.0      │ │ Redis                                    │  │
│ │ ORM → SQL 生成      │ │ Token 黑名单 · 登录锁 · 缓存            │  │
│ └──────────┬──────────┘ └──────────────────────────────────────────┘  │
└─────────────┼───────────────────────────────────────────────────────────┘
              ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Database (MySQL / PostgreSQL / SQL Server / SQLite / Oracle)            │
│ 表前缀: flask_ · 软删除: is_delete                                      │
└─────────────────────────────────────────────────────────────────────────┘
```

## 架构特征

:::tip 核心设计原则
遵循以下架构设计原则，确保系统在长期演进中保持高质量和可维护性：
:::

### 1. 前后端分离

前端 Vue3 应用通过 HTTP API 调用后端 Flask 服务，两者独立开发、独立部署。前端开发阶段通过 Vite 的 `proxy` 配置将 `/api` 请求代理到后端 `http://127.0.0.1:8021`，生产环境由 Nginx 统一反向代理。

### 2. 分层架构

后端严格分为三层，每层职责单一、依赖单向：

| 层次 | 目录 | 职责 |
|:---:|:---:|:---|
| HTTP 层 | `modules/{group}/{name}/router.py` | 路由定义、权限装饰器、参数接收、响应返回 |
| 业务层 | `modules/{group}/{name}/service.py` | 业务逻辑、校验规则、序列化加工 |
| 数据层 | `modules/{group}/{name}/repository.py` | 数据库 CRUD、查询条件组装 |

### 3. 模板方法模式

通过 `BaseRepository` 和 `BaseService` 基类，将通用 CRUD 流程固化为模板方法。子类只需声明差异点（过滤字段、排序规则、唯一性校验等），即可获得完整的增删改查能力，极大减少重复代码。

### 4. 中间件链式处理

请求处理采用 Flask 的 `before_request` / `after_request` 钩子，形成链式处理。中间件在 `src/app.py` 的 `create_app()` 中按以下顺序注册：

```python
# src/app.py - create_app() 中间件注册顺序
CORS(app, ...)                        # CORS（最外层）
ProxyFix(app.wsgi_app, ...)           # 可信代理
register_operation_log(app)           # 操作日志记录
register_transaction(app)             # AOP 事务管理
register_v1(app)                      # 路由注册
register_extends(app)                 # 扩展初始化
register_middleware(app)              # 认证中间件
register_v1(app)                      # 路由注册
register_exception(app)               # 全局异常处理
```

外层中间件（CORS）先拦截，内层中间件（DB 会话、Redis 注入）后处理，响应沿反向链返回。

### 5. 全局异常处理

`register_exception(app)` 在 `src/app.py` 中注册全局异常处理器，所有异常均返回 HTTP 200 状态码，通过 `code` 字段区分业务成功（0）与失败（1）：

| 异常类型 | 触发场景 | 响应格式 |
|:---|:---|:---|
| `BizError` | 业务逻辑错误 | `{"code": 1, "msg": "..."}` |
| `ValidationError` | WTForms 校验失败 | `{"code": 1, "msg": "field: message/..."}` |
| `Exception` | 未捕获异常 | `{"code": 1, "msg": "服务器内部错误"}` |

### 6. 统一响应格式

所有 API 端点返回统一的 JSON 结构：

```json
{
  "code": 0,
  "data": {},
  "msg": "操作成功",
  "ok": true
}
```

成功响应 `code=0`，失败响应 `code=1`，前端无需针对不同接口做差异化解析。

### 7. 软删除策略

所有业务表通过 `is_delete` 字段实现软删除（0=正常，1=已删除）。`BaseRepository` 的等值查询方法自动追加 `is_delete=0` 过滤，业务代码无需关心已删除数据。

### 8. AOP 事务管理

数据库事务由 `src/middleware/transaction.py` 的 `register_transaction` 统一管理：`before_request` 标记事务活跃，`after_request` 在 POST/PUT/DELETE/PATCH 请求且 HTTP 2xx 且 `code==0` 时自动 commit，否则 rollback，`teardown_request` 在异常时自动 rollback。业务代码只需调用 `model.save()` 完成 `add + flush`，无需手动提交事务。

```python
# src/middleware/transaction.py 核心逻辑
def register_transaction(app):
    @app.before_request
    def _transaction_begin():
        g.transaction_active = True

    @app.after_request
    def _transaction_commit(response):
        if request.method in ('POST', 'PUT', 'DELETE', 'PATCH'):
            if response.status_code == 200:
                body = response.get_json()
                if body and body.get('code') == 0:
                    db.session.commit()
                else:
                    db.session.rollback()
        return response

    @app.teardown_request
    def _transaction_rollback(exception):
        if exception:
            db.session.rollback()
```

### 9. 多数据库驱动

通过 `DB_DRIVER` 环境变量切换数据库驱动（MySQL / PostgreSQL / SQL Server / SQLite / Oracle），`SQLAlchemy` 的方言层屏蔽了底层差异，业务代码无需修改。

### 10. 应用生命周期管理

`src/app.py` 通过 `create_app()` 管理应用启动和关闭流程：

```python
# src/app.py
def create_app():
    app = Flask(__name__)
    # 1. 验证配置
    validate_config()
    # 2. CORS + ProxyFix
    CORS(app, ...)
    app.wsgi_app = ProxyFix(app.wsgi_app, ...)
    # 3. 注册中间件
    register_operation_log(app)
    register_transaction(app)
    register_v1(app)
    register_extends(app)
    register_middleware(app)
    register_error_handlers(app)
    # 4. 依赖注入
    register_v1(app)
    # 5. 注册异常处理
    register_exception(app)
    # 6. 初始化定时任务
    init_scheduler(app)
    return app
```

启动顺序：`validate_config()` → `register_extends()` → 中间件注册 → 路由注册 → 异常处理 → 定时任务初始化。

## 技术分层图

```
┌──────────────────────────────────────────────────────────────┐
│ Frontend (Vue3)                                              │
│ ElementPlus · Pinia · Vue Router · Axios                    │
└──────────────────────────┬───────────────────────────────────┘
                           │ HTTP / JSON
┌──────────────────────────┴───────────────────────────────────┐
│ Flask Application                                            │
│                                                              │
│ ┌─────────────┐ ┌─────────────┐ ┌──────────────────────┐    │
│ │ Middleware   │ │ Router      │ │ Exception Handler    │    │
│ │ ───────── │ │ ───────── │ │ ───────────────── │    │
│ │ CORS        │ │ auth        │ │ BizError             │    │
│ │ Redis       │ │ v1 (login   │ │ ValidationError      │    │
│ │ RateLimit   │ │ required)   │ │ HTTP                 │    │
│ │ DBSession   │ │             │ │ Generic              │    │
│ │ OpLog       │ │             │ │                      │    │
│ └─────────────┘ └─────────────┘ └──────────────────────┘    │
│                                                              │
│ ┌──────────────────────────────────────────────────────────┐│
│ │ Routers (modules/{group}/{name}/router.py)               ││
│ │ @check_permission · @check_demo · WTForms Form           ││
│ └──────────────────────────────────────────────────────────┘│
│ │                                                          ││
│ ┌──────────────────────────────────────────────────────────┐│
│ │ Services (modules/{group}/{name}/service.py)             ││
│ │ BaseService · 自定义 Service                             ││
│ └──────────────────────────────────────────────────────────┘│
│ │                                                          ││
│ ┌──────────────────────────────────────────────────────────┐│
│ │ Repositories (modules/{group}/{name}/repository.py)      ││
│ │ BaseRepository · 自定义 Repository                       ││
│ └──────────────────────────────────────────────────────────┘│
│ │                                                          ││
│ ┌──────────────────────────────────────────────────────────┐│
│ │ Models (modules/{group}/{name}/models.py)                ││
│ │ BaseModel + BaseDB → SQLAlchemy ORM                      ││
│ └──────────────────────────────────────────────────────────┘│
└──────────────────────────┬───────────────────────────────────┘
                           │
           ┌───────────────┴───────────────┐
           ▼                               ▼
    ┌────────────┐                  ┌─────────────┐
    │ Database   │                  │ Redis       │
    │ (MySQL等)  │                  │             │
    └────────────┘                  └─────────────┘
```

## 总结

项目采用经典的前后端分离 + 三层架构设计，通过中间件链实现横切关注点（认证、日志、事务）的统一处理，通过基类模板方法消除重复 CRUD 代码，通过 WTForms 实现请求参数的声明式校验。整体架构在保持简洁的同时，具备良好的可扩展性和可维护性，适合企业级后台管理系统的快速开发与长期演进。