# 产品整体架构文档 — 道路救援企业培训系统

> 版本：V1.0
> 生成日期：2026-04-07
> 证据状态：✅ 已验证
> 证据来源：[SRC-FEAT-01] [SRC-SQL-01] [SRC-API-01] [SRC-CODE-01]

---

## 1. 产品定位

### 1.1 产品目标

为道路救援企业提供**一站式内部培训管理平台**，通过数字化方式替代口口相传的知识传承模式，实现知识沉淀、在线考核、培训过程管控三位一体。[SRC-FEAT-01]

### 1.2 核心价值

| 价值维度 | 解决的痛点 | 实现方式 |
|---------|---------|---------|
| 知识沉淀 | 知识依赖口口相传，无法沉淀 | 结构化知识库（文档+视频） |
| 高效考核 | 出题组卷效率低，纸质考试成本高 | 在线题库 + 自动/手动组卷 + 在线考试 |
| 培训管控 | 培训效果难追踪，进度不透明 | 培训计划+进度跟踪+成绩统计 |
| 标准化输出 | 服务标准参差不齐 | 统一平台 + 及格线控制 + 必考机制 |

### 1.3 目标用户

| 角色 | 人数 | 核心诉求 |
|------|------|---------|
| 管理员 | 3-5人 | 系统配置、人员管理、全平台数据可见 |
| 讲师（技师） | 30-50人 | 本部门知识上传、出题、发布考试、管理培训计划 |
| 学员 | ~450人 | 学习资料、参加考试、查看进度 |

[SRC-FEAT-01：二、用户画像]

### 1.4 使用场景

- **管理员场景**：系统初始化时维护组织架构；日常监控各部门培训完成情况。
- **讲师场景**：救援规范更新后，上传新手册并更新题库，发布新考试，关联到培训计划。
- **学员场景**：PC端浏览知识库预习、参加指定考试、查看自己的培训进度。
- **企业微信场景**：学员通过企业微信 H5 入口完成移动端学习和考试。

---

## 2. 系统整体架构

### 2.1 架构分层

| 层次 | 组件 | 职责 |
|-----|------|------|
| **表现层** | PC浏览器（管理员/讲师）、企业微信H5（学员）、移动端浏览器 | 用户交互，HTML+CSS+JS 原生技术栈 |
| **网关层** | Spring Boot 应用（JWT认证、权限拦截、日志、异常处理） | 请求入口，统一认证鉴权，全局异常处理 |
| **业务层** | 5个业务模块（auth / system / knowledge / exam / training） | 核心业务逻辑，按模块边界划分，禁止跨模块直接调用数据层 |
| **数据层** | MySQL 8.0（MyBatis Plus ORM）+ 文件存储（本地/MinIO/OSS） | 持久化业务数据和媒体文件 |

[SRC-FEAT-01：七、架构设计蓝图]

### 2.2 技术架构概览

| 技术选型 | 版本 | 用途 |
|---------|------|------|
| Spring Boot | 3.1.2 | 主框架 |
| MyBatis Plus | 3.5.3+ | ORM，简化CRUD |
| MySQL | 8.0 | 主数据库 |
| java-jwt | 4.4+ | JWT Token 签发与验证 |
| Spring Security | 6.x | BCrypt 密码加密 |
| weixin-java-cp | - | 企业微信 SDK（OAuth 登录） |
| Springdoc OpenAPI | 2.2+ | API 文档 |
| Spring @Scheduled | - | 考试超时自动交卷定时任务 |
| 文件存储 | - | V1 本地存储，V2 可扩展 MinIO/OSS |

[SRC-FEAT-01：7.3 技术选型]

### 2.3 系统依赖关系

```
外部系统依赖：
  企业微信API ←→ auth 模块（OAuth 换 userid）
  文件存储服务 ←→ knowledge 模块（上传/下载文件）
  文档预览服务（可选） ←→ knowledge 模块（在线预览）

内部模块依赖方向（单向，禁止逆向调用）：
  training → knowledge（引用知识内容、学习进度）
  training → exam（引用考试通过状态）
  knowledge / exam / training → system（查询用户/部门信息）
  所有模块 → auth（权限校验拦截器）
```

---

## 3. 业务架构图

```mermaid
graph TD
    subgraph 客户端
        PC[PC浏览器<br>管理员/讲师]
        WX[企业微信H5<br>学员]
        MB[移动端浏览器<br>学员]
    end

    subgraph 后端服务
        subgraph 网关层
            GW[JWT认证 / 权限拦截 / 异常处理]
        end

        subgraph 业务域
            AUTH[认证模块<br>auth]
            SYS[系统管理<br>system]
            KM[知识库模块<br>knowledge]
            EX[考试模块<br>exam]
            TR[培训模块<br>training]
        end
    end

    subgraph 数据层
        DB[(MySQL 8.0)]
        FS[文件存储<br>本地/MinIO]
    end

    subgraph 外部服务
        WXAPI[企业微信API]
        PREVIEW[文档预览服务<br>可选]
    end

    PC --> GW
    WX --> GW
    MB --> GW
    GW --> AUTH
    GW --> SYS
    GW --> KM
    GW --> EX
    GW --> TR

    AUTH --> WXAPI
    KM --> FS
    KM --> PREVIEW

    TR --> KM
    TR --> EX
    KM --> SYS
    EX --> SYS
    TR --> SYS

    AUTH --> DB
    SYS --> DB
    KM --> DB
    EX --> DB
    TR --> DB
```

---

## 4. 核心业务流程说明

### 4.1 用户主流程（学员）

```mermaid
sequenceDiagram
    participant 学员
    participant 前端
    participant 后端
    participant 企业微信

    学员->>前端: 点击企业微信登录
    前端->>企业微信: 跳转 OAuth 授权
    企业微信-->>前端: 返回 code
    前端->>后端: code 换 Token
    后端->>企业微信: code → userid
    后端->>后端: 查 sys_user 匹配
    alt 用户已录入
        后端-->>前端: JWT Token + 用户信息
        前端->>学员: 进入工作台
    else 用户未录入
        后端-->>前端: 错误：联系管理员
    end

    学员->>前端: 查看培训计划
    前端->>后端: GET /api/student/training
    后端-->>前端: 计划列表 + 进度

    学员->>前端: 参加考试
    前端->>后端: POST /api/student/exam/{id}/start
    后端->>后端: 校验时间窗口 + 剩余次数
    后端-->>前端: 试题 + 考试时长
    学员->>前端: 答题 + 交卷
    前端->>后端: POST /api/student/exam/{id}/submit
    后端->>后端: 自动判分
    后端-->>前端: 成绩 + 排名 + 答案解析
```

### 4.2 管理流程（讲师）

```mermaid
flowchart LR
    A[上传知识<br>DRAFT] --> B[发布知识<br>PUBLISHED]
    B --> C{有培训计划?}
    C -->|是| D[关联到培训计划]
    C -->|否| E[学员自由学习]

    F[创建题目<br>DRAFT] --> G[发布题目<br>PUBLISHED]
    G --> H[组卷<br>手动/自动]
    H --> I[发布试卷<br>PUBLISHED]
    I --> J[创建考试<br>设置时间/次数]
    J --> K[指定考试对象<br>部门/小组/个人]
    D --> L[创建培训计划]
    J --> L
    L --> M[分配学员<br>部门/小组/个人]
    M --> N[发布培训计划]
```

### 4.3 数据流转流程

```mermaid
flowchart TB
    subgraph 内容生产
        KM_CREATE[知识创建<br>km_knowledge DRAFT]
        KM_PUBLISH[发布知识<br>PUBLISHED]
        QS_CREATE[题目创建<br>ex_question DRAFT]
        QS_PUBLISH[发布题目<br>PUBLISHED]
        PP_CREATE[组卷<br>ex_paper + ex_paper_question]
        EX_CREATE[创建考试<br>ex_exam + ex_exam_target]
        TR_CREATE[培训计划<br>tr_plan + tr_plan_knowledge<br>+ tr_plan_exam + tr_plan_target]
    end

    subgraph 学员消费
        LEARN[学习知识<br>→ km_knowledge_progress UPSERT]
        EXAM[参加考试<br>→ ex_exam_record 创建/更新]
        PROGRESS[进度计算<br>必修知识完成数 + 必考通过数]
    end

    KM_CREATE --> KM_PUBLISH --> LEARN
    QS_CREATE --> QS_PUBLISH --> PP_CREATE --> EX_CREATE --> EXAM
    TR_CREATE --> LEARN
    TR_CREATE --> EXAM
    LEARN --> PROGRESS
    EXAM --> PROGRESS
```

---

## 5. 数据架构

### 5.1 核心数据实体（共19张表）

[SRC-SQL-01] [SRC-SQL-02]

| 数据域 | 表名 | 核心字段 | 说明 |
|-------|------|---------|------|
| **系统** | sys_center | id, name | 中心（最高层级） |
| **系统** | sys_department | id, name, center_id | 部门（隶属中心） |
| **系统** | sys_group | id, name, department_id | 小组（隶属部门） |
| **系统** | sys_user | id, wx_userid, role(0/1/2), department_id, group_id, status | 用户（ADMIN/LECTURER/STUDENT） |
| **知识库** | km_category | id, name, parent_id, department_id | 知识分类（多级树） |
| **知识库** | km_knowledge | id, title, type(0文档/1视频), file_url, department_id, status(0/1/2) | 知识内容 |
| **知识库** | km_knowledge_progress | id, user_id, knowledge_id, status, progress, duration, video_position, source, plan_id | 学习进度 |
| **考试** | ex_question_category | id, name, parent_id, department_id | 题目分类 |
| **考试** | ex_question | id, type(0/1/2), content, options(JSON), answer, analysis, status | 题目 |
| **考试** | ex_paper | id, title, total_score, duration, pass_score, status | 试卷 |
| **考试** | ex_paper_question | paper_id, question_id, score, sort_order | 试卷-题目关联 |
| **考试** | ex_exam | id, title, paper_id, start_time, end_time, max_attempts, status(0/1/2) | 考试 |
| **考试** | ex_exam_target | exam_id, target_type(0部门/1小组/2个人), target_id | 考试对象 |
| **考试** | ex_exam_record | id, exam_id, user_id, attempt_no, score, passed, answers(JSON), status, version | 考试记录（含乐观锁） |
| **培训** | tr_plan | id, title, start_date, end_date, department_id, status(0/1/2) | 培训计划 |
| **培训** | tr_plan_knowledge | plan_id, knowledge_id, required, sort_order | 计划-知识关联 |
| **培训** | tr_plan_exam | plan_id, exam_id, required, sort_order | 计划-考试关联（V1.0.1） |
| **培训** | tr_plan_target | plan_id, target_type, target_id | 计划-对象 |
| **培训** | tr_plan_progress | plan_id, user_id, knowledge_id, completed, complete_time | 旧版进度（已被 km_knowledge_progress 替代）|

### 5.2 实体关系图

```mermaid
erDiagram
    sys_center ||--o{ sys_department : "中心下辖多个部门"
    sys_department ||--o{ sys_group : "部门下辖多个小组"
    sys_department ||--o{ sys_user : "用户属于部门"
    sys_group ||--o{ sys_user : "用户可归属小组"

    sys_department ||--o{ km_category : "按部门隔离"
    km_category ||--o{ km_knowledge : "知识归属分类"
    sys_user ||--o{ km_knowledge_progress : "学员学习进度"
    km_knowledge ||--o{ km_knowledge_progress : "知识对应进度"

    sys_department ||--o{ ex_question_category : "按部门隔离"
    ex_question_category ||--o{ ex_question : "题目归属分类"
    ex_paper ||--o{ ex_paper_question : "试卷包含多道题"
    ex_question ||--o{ ex_paper_question : "题目被多张试卷引用"
    ex_paper ||--|| ex_exam : "考试使用某试卷"
    ex_exam ||--o{ ex_exam_target : "考试指定对象"
    ex_exam ||--o{ ex_exam_record : "考试产生记录"
    sys_user ||--o{ ex_exam_record : "学员的考试记录"

    tr_plan ||--o{ tr_plan_knowledge : "计划包含多个知识"
    tr_plan ||--o{ tr_plan_exam : "计划关联多场考试"
    tr_plan ||--o{ tr_plan_target : "计划分配给对象"
    km_knowledge ||--o{ tr_plan_knowledge : "知识被计划引用"
    ex_exam ||--o{ tr_plan_exam : "考试被计划引用"
```

### 5.3 数据生命周期

| 数据类型 | 创建 | 有效态 | 失效态 | 删除方式 |
|---------|------|-------|-------|---------|
| 知识/题目/试卷 | DRAFT | PUBLISHED | OFFLINE | 逻辑删除（deleted=1） |
| 考试 | NOT_STARTED | IN_PROGRESS | ENDED | 逻辑删除 |
| 培训计划 | NOT_STARTED | IN_PROGRESS | ENDED | 逻辑删除 |
| 考试记录 | IN_PROGRESS | SUBMITTED | 永久保留（取最高分） | 不删除 |
| 学习进度 | NOT_STARTED | IN_PROGRESS | COMPLETED | UPSERT更新 |

---

## 6. 权限与角色体系

### 6.1 角色定义

[SRC-FEAT-01：4.1 权限规则] [SRC-SQL-01：sys_user.role]

| 角色 | 枚举值（DB） | 数据范围 | 
|------|------------|---------|
| 管理员 ADMIN | role=0 | 全平台（无部门隔离） |
| 讲师 LECTURER | role=1 | 本部门（department_id匹配） |
| 学员 STUDENT | role=2 | 本部门（只读；自己的进度/成绩） |

### 6.2 权限分层（按功能菜单）

| 菜单/功能 | ADMIN | LECTURER | STUDENT |
|---------|-------|---------|---------|
| 组织架构管理 | ✅ 全部 | ❌ | ❌ |
| 员工管理 | ✅ 全部 | 👁️ 本部门只读 | ❌ |
| 知识库-分类管理 | ✅ 全部 | ✅ 本部门 | ❌ |
| 知识库-知识列表 | ✅ 全部 | ✅ 本部门（含草稿） | 👁️ 本部门已发布 |
| 考题管理-题库分类 | ✅ | ✅ 本部门 | ❌ |
| 考题管理-题目列表 | ✅ | ✅ 本部门 | ❌ |
| 试卷管理 | ✅ | ✅ 本部门 | ❌ |
| 考试管理 | ✅ | ✅ 本部门发布 | 👁️ 我的考试 |
| 培训计划 | ✅ | ✅ 本部门创建/管理 | 👁️ 我的培训 |
| 系统设置 | ✅ | ❌ | ❌ |
| 工作台 | ✅ | ✅ | ✅（学员视图） |

[SRC-FEAT-01：8.1 角色菜单权限对照表]

### 6.3 控制逻辑

**认证层**：JWT Token 携带 userId + role，每次请求由 AuthInterceptor 解析验证。[SRC-CODE-01：common/interceptor/AuthInterceptor.java]

**授权层**：
- 接口级：`@PreAuthorize` / SecurityConfig 按角色匹配路径（`/api/student/**` 仅 STUDENT）
- 数据级：Service 层注入 `department_id` 过滤，讲师/学员查询一律追加 `WHERE department_id = ?`

**隔离规则**：
- 4类数据（知识库、题库、试卷/考试、培训计划）均按 `department_id` 隔离
- 管理员不注入部门过滤，讲师注入本部门，学员额外限制只查 PUBLISHED 状态

---

## 7. 系统扩展点分析

### 7.1 可扩展模块

| 扩展点 | 当前状态 | V2+ 扩展方向 |
|-------|---------|------------|
| 文件存储 | 本地文件系统 | 抽象 `FileStorageService` 接口 → MinIO/OSS 实现切换 |
| 认证方式 | 企业微信 OAuth（账号密码作备选） | 可接入 SSO/LDAP |
| 定时任务 | Spring @Scheduled（单机） | 可替换为 XXL-Job/SchedulerX 支持集群 |
| 统计报表 | 无（V2规划） | 新增 `statistics` 模块，不影响现有模块 |
| 通知 | 无（V2规划） | 可插入企业微信消息推送 |

### 7.2 可插拔能力

- **文档预览**：kkFileView / OnlyOffice 作为可选外部服务，knowledge 模块通过 URL 调用，可随时替换
- **视频播放器**：video.js 为前端组件，与后端解耦，可替换
- **批量导入**：EasyExcel 依赖已选型，可随时为题目/用户管理添加 Excel 导入功能

### 7.3 易变业务点

| 易变点 | 变化方向 | 影响范围 |
|-------|---------|---------|
| 培训完成判定逻辑（当前：必修知识+必考通过） | V2 可能增加签到、线下课时 | `TrainingProgressService.calculateProgress()` |
| 知识学习完成判定（视频90%/文档时长） | 可能改为100%或按章节 | `KnowledgeLearningService.isCompleted()` |
| 考试排名计算口径（当前：最高分排名 DENSE_RANK） | 可能改为平均分/最后一次 | SQL窗口函数，需同步修改 |
| 组织架构层级（当前：中心→部门→小组三级） | 可能增减层级 | system 模块全面影响 |