# xgy-c/tlias architecture

> Architecture diagram of the GitHub repository xgy-c/tlias, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xgy-c/tlias
- Repository: https://github.com/xgy-c/tlias

## Overview

##### 项目类型与目的
- 这是一个基于 Spring Boot 和 MyBatis 的单体 Web 管理系统，提供部门（Dept）和员工（Emp）之类的增删改查接口，并集成了登录校验、操作日志记录、文件上传（Aliyun OSS）等功能。
- 主要面向初学者，示范典型的 MVC 分层架构、AOP 记录日志、Filter/Interceptor 做登录校验、JWT 认证、静态资源托管等常见 Web 开发模块。

##### 文件结构分析
- src/main/java/com/xgy
- controller：HTTP 接口层（DeptController、EmpController、LoginController、UploadController）
- service & service/impl：业务逻辑层
- mapper (+ resources/com/xgy/mapper/*.xml)：MyBatis 数据访问层
- pojo：领域模型／DTO
- config：Spring MVC 和静态资源等通用配置
- filter & interceptor：登录校验请求拦截
- anno & aop：自定义 @Log 注解和日志切面 LogAspect，自动记录操作日志到 OperateLogMapper／DeptLogMapper
- utils：JWT 工具类、AliOSS 配置与工具
- exception：全局异常处理器
- src/main/resources
- application.yml：环境配置
- static：HTML 页面（upload.html）
- mapper XML：SQL 映射文件
- pom.xml + mvnw：Maven 构建与依赖管理

##### 如何绘制系统设计图
a. 确定主要参与者和组件
- Client (浏览器或 Postman)
- Spring Boot 内嵌 Tomcat（HTTP 服务器）
- Controller 层：DeptController、EmpController、LoginController、UploadController
- Service 层：DeptService、EmpService、DeptLogService
- DAO 层(MyBatis)：DeptMapper、EmpMapper、OperateLogMapper、DeptLogMapper + 对应 XML
- 数据库：MySQL（或其他 RDBMS）
- 外部文件存储：Aliyun OSS
- 横切关注点：
- Filter（LoginCheckFilter）– 请求进入时做 Token 校验
- Interceptor（LoginCheckInterceptor）– MVC 层面再校验
- AOP（LogAspect + @Log）– 在服务／控制器方法执行前后记录操作日志
- 配置与工具：JwtUtils、AliOSSUtils、WebConfig、GlobalExceptionHandler

b. 组件关系与交互流程
1. 客户端发起 HTTP 请求 → Spring Boot (Tomcat)
2. **Filter**：LoginCheckFilter 拦截检查 JWT token
3. **Interceptor**：进一步做基于 URL／方法级的权限检查
4. **Controller** 接收请求，调用对应 Service
5. **AOP 切面**：在带 @Log 的方法上记录操作日志，调用 OperateLogMapper/DeptLogMapper 持久化
6. **Service** 层执行业务，调用 Mapper
7. **MyBatis Mapper** 执行 SQL 操作，访问数据库
8. 若是 UploadController，Service 层会调用 AliOSSUtils 将文件推送到 Aliyun OSS
9. Controller 返回 JSON（包装在 Result/ PageBean 中）给客户端

c. 重要架构模式与设计原则
- 分层架构 (MVC + Service + DAO)
- 依赖注入 (Spring IoC)
- AOP 横切关注点 (日志)
- 责任链 / 拦截器模式 (Filter + HandlerInterceptor)
- 外部化配置 (application.yml)
- RESTful API 设计

d. 关键技术栈
- Spring Boot (Web, AOP, MVC, DI)
- MyBatis (+ XML 映射)
- JWT (JwtUtils)
- Aliyun OSS SDK (AliOSSUtils)
- Maven 构建
- SLF4J/Logback（日志）
- 全局异常处理 (ControllerAdvice)

##### 绘制指南与要点
- 在顶层画出客户端（浏览器 / REST 客户端）和外部服务（MySQL 数据库、Aliyun OSS）。
- 将服务器模块画成一个大容器，内部再细分：
- 入口层：Filter → Interceptor → Controller
- 业务层：Service
- 数据层：Mapper + DB
- 横切关注点：AOP 日志模块独立标注
- 工具/配置：JWT 模块、OSS 模块、Exception Handler
- 用箭头标明调用／数据流向：
- 客户端 → HTTP 接口 → Filter → Interceptor → Controller → Service → Mapper → DB
- UploadController → AliOSSUtils → Aliyun OSS
- LogAspect → Mapper → DB(日志表)
- 使用不同形状/颜色区分：
- 矩形：模块／组件
- 箭头：同步调用／数据流
- 颜色：
– 蓝色：核心业务流（Controller/Service/Mapper/DB）
– 绿色：安全/认证（Filter/Interceptor/JWT）
– 橙色：日志 AOP
– 紫色：外部资源（Aliyun OSS）
- 标注清晰的组件名和交互协议（HTTP、JDBC、OSS SDK）
- 如果需要，也可在旁边补充各层使用的技术（Spring MVC, MyBatis, JWT, AOP）

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    Client["Client (Browser/Postman)"]:::external
    DB[(MySQL Database)]:::external
    OSS[(Aliyun OSS)]:::external

    %% Server Container
    subgraph "Spring Boot Server" 
        direction TB

        %% Entry Point
        App["TliasWebManagementApplication"]:::entry
        click App "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/TliasWebManagementApplication.java"

        %% Security & Filters
        subgraph "Security & Auth" 
            direction TB
            Filter["LoginCheckFilter"]:::security
            click Filter "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/filter/LoginCheckFilter.java"
            Interceptor["LoginCheckInterceptor"]:::security
            click Interceptor "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/interceptor/LoginCheckInterceptor.java"
            Jwt["JwtUtils"]:::security
            click Jwt "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/utils/JwtUtils.java"
        end

        %% Controllers
        subgraph "Controller Layer" 
            direction TB
            DeptCtrl["DeptController"]:::core
            click DeptCtrl "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/controller/DeptController.java"
            EmpCtrl["EmpController"]:::core
            click EmpCtrl "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/controller/EmpController.java"
            LoginCtrl["LoginController"]:::core
            click LoginCtrl "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/controller/LoginController.java"
            UploadCtrl["UploadController"]:::core
            click UploadCtrl "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/controller/UploadController.java"
        end

        %% Service Layer
        subgraph "Service Layer" 
            direction TB
            DeptSvcI["DeptService"]:::core
            click DeptSvcI "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/service/DeptService.java"
            EmpSvcI["EmpService"]:::core
            click EmpSvcI "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/service/EmpService.java"
            DeptLogSvcI["DeptLogService"]:::core
            click DeptLogSvcI "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/service/DeptLogService.java"
            DeptSvcImpl["DeptServiceImpl"]:::core
            click DeptSvcImpl "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/service/impl/DeptServiceImpl.java"
            EmpSvcImpl["EmpServiceImpl"]:::core
            click EmpSvcImpl "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/service/impl/EmpServiceImpl.java"
            DeptLogSvcImpl["DeptLogServiceImpl"]:::core
            click DeptLogSvcImpl "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/service/impl/DeptLogServiceImpl.java"
        end

        %% MyBatis Layer
        subgraph "Data Access (MyBatis)" 
            direction TB
            DeptMap["DeptMapper"]:::core
            click DeptMap "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/mapper/DeptMapper.java"
            EmpMap["EmpMapper"]:::core
            click EmpMap "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/mapper/EmpMapper.java"
            OpLogMap["OperateLogMapper"]:::core
            click OpLogMap "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/mapper/OperateLogMapper.java"
            DeptLogMap["DeptLogMapper"]:::core
            click DeptLogMap "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/mapper/DeptLogMapper.java"
        end

        %% AOP Logging
        subgraph "AOP Logging" 
            direction TB
            LogAnno["@Log Annotation"]:::aop
            click LogAnno "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/anno/Log.java"
            LogAspect["LogAspect"]:::aop
            click LogAspect "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/aop/LogAspect.java"
        end

        %% File Upload Utils
        subgraph "File Upload & OSS" 
            direction TB
            OSSProp["AliOSSProperties"]:::util
            click OSSProp "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/utils/AliOSSProperties.java"
            OSSUtil["AliOSSUtils"]:::util
            click OSSUtil "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/utils/AliOSSUtils.java"
        end

        %% Configuration & Exception
        subgraph "Config & Exception" 
            direction TB
            WebCfg["WebConfig"]:::config
            click WebCfg "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/config/WebConfig.java"
            GlobEx["GlobalExceptionHandler"]:::config
            click GlobEx "https://github.com/xgy-c/tlias/blob/master/src/main/java/com/xgy/exception/GlobalExceptionHandler.java"
            AppYml["application.yml"]:::config
            click AppYml "https://github.com/xgy-c/tlias/blob/master/src/main/resources/application.yml"
        end

        %% Static Resource
        Static["upload.html"]:::static
        click Static "https://github.com/xgy-c/tlias/blob/master/src/main/resources/static/upload.html"
    end

    %% Flow Arrows
    Client -->|HTTP Request| App
    App --> Filter --> Interceptor --> DeptCtrl
    Interceptor --> EmpCtrl
    Interceptor --> LoginCtrl
    Interceptor --> UploadCtrl

    DeptCtrl -->|calls| DeptSvcImpl
    EmpCtrl -->|calls| EmpSvcImpl
    LoginCtrl -->|calls JwtUtils| Jwt
    UploadCtrl -->|calls| OSSUtil

    DeptSvcImpl -->|uses| DeptMap
    EmpSvcImpl -->|uses| EmpMap
    DeptLogSvcImpl -.->|logs via| DeptLogMap
    DeptSvcImpl -.->|logs via| OpLogMap

    DeptMap -->|JDBC| DB
    EmpMap -->|JDBC| DB
    OpLogMap -->|JDBC| DB
    DeptLogMap -->|JDBC| DB

    UploadCtrl -->|upload| OSSUtil -->|SDK| OSS

    %% AOP weaving
    LogAspect --> DeptSvcImpl
    LogAspect --> DeptLogSvcImpl
    LogAspect --> DeptCtrl
    LogAspect --> EmpCtrl
    LogAspect --> LoginCtrl
    LogAspect --> UploadCtrl

    %% Static Resource Flow
    Client -->|GET upload.html| Static

    %% Styles
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef entry fill:#AEDFF7,stroke:#036A8E,stroke-width:2px;
    classDef security fill:#C8E6C9,stroke:#256029,stroke-width:1px;
    classDef core fill:#BBDEFB,stroke:#0D47A1,stroke-width:1px;
    classDef aop fill:#FFE0B2,stroke:#E65100,stroke-width:1px;
    classDef util fill:#E1BEE7,stroke:#6A1B9A,stroke-width:1px;
    classDef config fill:#F0F4C3,stroke:#827717,stroke-width:1px;
    classDef static fill:#FFF9C4,stroke:#F57F17,stroke-width:1px;
```
