# 整体架构图

本章从全局视角阐述系统的整体技术架构，涵盖前端、后端、数据库及基础设施等核心组成部分。

## 架构总览

```
┌─────────────────────────────────────────────────────────────────────────┐
│                    Browser (Vue3 + ElementPlus)                         │
│                    Axios HTTP Request / Vite Dev Proxy                  │
└──────────────────────────────┬──────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    Nginx (反向代理)                                      │
│                    静态资源 / SSL 终止 / 负载均衡 / gzip 压缩            │
└──────────────────────────────┬──────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    Tornado Application                                  │
│                                                                         │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ Handler 生命周期                                                    │  │
│  │ set_default_headers() → prepare() → handler_method() → on_finish()│  │
│  │ CORS + trace_id    JWT 认证    权限+日志+业务逻辑   释放DB会话     │  │
│  └───────────────────────────────┬───────────────────────────────────┘  │
│                                  ▼                                      │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ Service Layer (业务逻辑层)                                          │  │
│  │ BaseService / 自定义 Service                                        │  │
│  │ 唯一性校验 · 字段组装 · 序列化 · 文件处理                           │  │
│  └───────────────────────────────┬───────────────────────────────────┘  │
│                                  ▼                                      │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ Repository Layer (数据访问层)                                       │  │
│  │ BaseRepository                                                     │  │
│  │ CRUD · 软删除 · 分页 · 等值查询 · 原始条件查询                      │  │
│  └───────────────────────────────┬───────────────────────────────────┘  │
│                                  ▼                                      │
│  ┌─────────────────────┐  ┌──────────────────────────────────────────┐  │
│  │ SQLAlchemy 2.0      │  │ Redis (同步客户端)                        │  │
│  │ ORM → SQL 生成      │  │ Token 黑名单 · 登录锁 · 字典缓存 · 权限缓存│  │
│  └──────────┬──────────┘  └──────────────────────────────────────────┘  │
└─────────────┼───────────────────────────────────────────────────────────┘
              ▼
┌─────────────────────────────────────────────────────────────────────────┐
│              Database (MySQL / PostgreSQL / SQL Server / SQLite / Oracle)│
│              表前缀: tornado_ · 软删除: is_delete                        │
└─────────────────────────────────────────────────────────────────────────┘
```

## 架构特征

### 1. 前后端分离

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

### 2. 分层架构

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

| 层次 | 目录 | 职责 |
|:---:|:---:|:---|
| HTTP 层 | `modules/{module}/handlers.py` | 路由定义、权限装饰器、操作日志、响应返回 |
| 业务层 | `modules/{module}/service.py` | 业务逻辑、校验规则、序列化加工 |
| 数据层 | `modules/{module}/repository.py` | 数据库 CRUD、查询条件组装 |
| 模型层 | `modules/{module}/models.py` | 表结构定义、字段映射 |

### 3. 模板方法模式

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

### 4. Handler 生命周期

Tornado 通过 Handler 生命周期方法实现横切关注点：

```python
# src/core/base_handler.py
class BaseHandler(tornado.web.RequestHandler):
    def set_default_headers(self):
        """① 设置 CORS 头 + trace_id"""
        cros_required(self)
        apply_trace_id(self)

    @login_required
    def prepare(self):
        """② JWT 认证（白名单 URL 跳过）"""
        pass

    def on_finish(self):
        """④ 请求结束后释放数据库会话"""
        db.close()

    def write_error(self, status_code, **kwargs):
        """⑤ 异常统一响应"""
        ...
```

Handler 方法中通过装饰器实现权限/演示模式/操作日志：

```python
class PositionAddHandler(BaseHandler):
    @permission_required("sys:position:add")  # RBAC 权限校验
    @check_demo                                 # 演示模式拦截
    @operation_log("岗位管理", "添加")           # 操作日志记录
    async def post(self):
        return await position_service.add(self)
```

### 5. 全局异常处理

`BaseHandler.write_error()` 统一捕获异常并返回标准响应：

| 异常类型 | 触发场景 | 响应 |
|:---|:---|:---|
| `AuthError` | JWT 过期 / 未登录 | `{"code": 401, "msg": "登录过期"}` |
| `PermissionDeniedError` | 权限不足 | `{"code": 403, "msg": "权限不足"}` |
| `BusinessError` | 业务逻辑错误 | `{"code": 1, "msg": "..."}` |
| `ValidationError` | Pydantic 校验失败 | `{"code": 1, "msg": "field: message"}` |
| `NotFoundError` | 记录不存在 | `{"code": 404, "msg": "记录不存在"}` |
| `Exception` | 未捕获异常 | `{"code": 500, "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. 事务管理

数据库事务由 Repository 层的 `create()` / `update()` / `batch_delete()` 方法内部 `db.commit()` 管理。Service 层的 `try/finally` 块确保 `repo.close()` 释放会话。`BaseHandler.on_finish()` 兜底关闭会话，避免长连接泄漏。

### 9. 多数据库驱动

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

### 10. 应用启动流程

```python
# app.py（入口）→ bootstrap.py（启动引导）→ src/app.py（应用工厂）
# 启动流程：
#   1. bootstrap.main() 解析 --port 参数
#   2. create_app() 构建 Application（路由、模板、静态目录）
#   3. register_extensions() 初始化扩展（SQLAlchemy、Redis）
#   4. HTTPServer.listen(port) 开始监听
#   5. init_scheduler() 启动定时任务调度器
#   6. 注册 SIGINT/SIGTERM 信号实现优雅关闭
#   7. ioloop.start() 启动事件循环
```

## 技术分层图

```
┌──────────────────────────────────────────────────────────────┐
│                    Frontend (Vue3)                            │
│            ElementPlus · Pinia · Vue Router · Axios           │
└──────────────────────────┬───────────────────────────────────┘
                           │ HTTP / JSON
┌──────────────────────────┴───────────────────────────────────┐
│                    Tornado Application                        │
│                                                               │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────────────┐  │
│  │ Handler     │  │ Router      │  │ Exception Handler    │  │
│  │ ─────────  │  │ ─────────  │  │ ─────────────────   │  │
│  │ CORS        │  │ auth        │  │ BaseAppError         │  │
│  │ trace_id    │  │ v1 (login   │  │ write_error()        │  │
│  │ login_      │  │ required)   │  │ 统一 {code,data,msg} │  │
│  │ required    │  │             │  │                      │  │
│  └─────────────┘  └─────────────┘  └──────────────────────┘  │
│                                                               │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │ Handlers (modules/{module}/handlers.py)                   │ │
│  │ @permission_required · @check_demo · @operation_log      │ │
│  └──────────────────────────────────────────────────────────┘ │
│                          │                                     │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │ Services (modules/{module}/service.py)                    │ │
│  │ BaseService · 自定义 Service                               │ │
│  └──────────────────────────────────────────────────────────┘ │
│                          │                                     │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │ Repositories (modules/{module}/repository.py)             │ │
│  │ BaseRepository · 自定义 Repository                         │ │
│  └──────────────────────────────────────────────────────────┘ │
│                          │                                     │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │ Models (modules/{module}/models.py)                       │ │
│  │ BaseModel → SQLAlchemy ORM                                │ │
│  └──────────────────────────────────────────────────────────┘ │
└──────────────────────────┬───────────────────────────────────┘
                           │
              ┌────────────┴────────────┐
              ▼                         ▼
       ┌────────────┐          ┌─────────────┐
       │ Database   │          │ Redis       │
       │ (MySQL等)  │          │ (同步客户端) │
       └────────────┘          └─────────────┘
```

## 总结

系统采用经典的前后端分离 + 分层架构设计，通过 Handler 生命周期方法和装饰器实现横切关注点（认证、权限、日志），通过基类模板方法消除重复 CRUD 代码，通过 Pydantic 实现请求参数的声明式校验。整体架构在保持简洁的同时，具备良好的可扩展性和可维护性。