154 lines
8.4 KiB
Markdown
154 lines
8.4 KiB
Markdown
# SYFJGYD学员管理系统（融合演示版）— Clean Demo Candidate 运行与演示说明书
|
||
|
||
## 一、系统概况
|
||
|
||
本工程为 **SYFJGYD学员管理系统** 的隔离融合演示候选版本（Clean Demo Candidate），集成了 **Java 21 + Spring Boot 4** 架构升级、培训管理业务（学员、班级、住宿全周期）与智能门锁 IoT 协同授权中枢。
|
||
|
||
### 核心演示原则
|
||
- **数据源隔离**：严格运行于独立研发 QA 数据库（`railwaysystem_fusion_qa_20261013`），采用最小权限应用账号连接，与共享试用库（`training`）及生产环境完全隔离。
|
||
- **仿真受控运行**：IoT 底层采用仿真受控模式，物理 MQTT 硬件与实体门锁处于安全隔离状态，防止误触发真实硬件动作。
|
||
- **真实完整业务闭环**：前端 UI、后端业务逻辑、Kingbase 事务状态流转均为 100% 真实执行。
|
||
|
||
---
|
||
|
||
## 二、系统访问与前置准备
|
||
|
||
### 1. 访问地址
|
||
- **前端 Web 控制台**：`http://127.0.0.1:8088`
|
||
- **默认演示账号**：`admin` / `admin123`
|
||
- **后端 API 服务**：`http://127.0.0.1:8096`（由前端通过 `/prod-api` 自动反向代理）
|
||
|
||
### 2. 演示前服务状态核验
|
||
在启动系统前，请确保研发数据库 SSH 隧道处于连通状态：
|
||
- **隧道端口**：`127.0.0.1:14321`
|
||
- **若隧道未连通**，请在终端执行：
|
||
```bash
|
||
ssh -N -L 127.0.0.1:14321:192.168.139.218:4321 -o ServerAliveInterval=15 wzbmatebook
|
||
```
|
||
- **安全凭据文件**：系统启动依赖受限目录下的环境变量配置（`~/.railwaysystem-qa.env`），密码由启动脚本安全注入，无需人工输入。
|
||
|
||
---
|
||
|
||
## 三、一键启停操作指南
|
||
|
||
系统提供了平滑、健壮的一键管理脚本，支持自动端口清理与就绪健康探测：
|
||
|
||
### 1. 启动系统
|
||
在工程根目录下执行：
|
||
```bash
|
||
./start_demo.sh
|
||
```
|
||
**启动脚本自动完成：**
|
||
1. 校验环境变量与凭据完整性；
|
||
2. 探测数据库 SSH 隧道连通性（未连通时给出明确操作指引并安全终止）；
|
||
3. 自动释放 8096 与 8088 端口历史旧进程；
|
||
4. 启动 Spring Boot 4 后端，轮询 `/captchaImage` 验证就绪（约 4~6 秒）；
|
||
5. 启动前端反向代理服务并验证 HTTP 200 就绪；
|
||
6. 打印就绪提示与访问入口。
|
||
|
||
### 2. 停止系统
|
||
在演示结束或需要重置时执行：
|
||
```bash
|
||
./stop_demo.sh
|
||
```
|
||
**停止脚本自动完成：**
|
||
1. 优雅停止前端反向代理进程（释放端口 8088）；
|
||
2. 优雅停止后端 Spring Boot 进程（释放端口 8096）；
|
||
3. 清理 Headless Chrome 测试残留进程；
|
||
4. 确认所有演示端口已完全释放。
|
||
|
||
---
|
||
|
||
## 四、建议的五分钟核心业务演示路线
|
||
|
||
建议按照培训学员入宿、门锁授权、调宿换锁、退宿撤权的标准业务生命周期进行演示：
|
||
|
||
```
|
||
[1. 管理员登录]
|
||
↓
|
||
[2. 住宿管理：查询预分配学员] ──> 点击【入住】办理 ──> 状态流转为【在住】
|
||
↓
|
||
[3. 智能门锁：授权管理] ──> 查看自动生成的人脸授权意图 (待下发/待回执)
|
||
↓
|
||
[4. 仿真回执确认] ──> 受控驱动网关与门锁回执 ──> 页面刷新为【已生效/下发成功】
|
||
↓
|
||
[5. 住宿管理：办理调房] ──> 选择新宿舍 (致远楼 102) 提交 ──> 触发新门锁建权与旧门锁撤权
|
||
↓
|
||
[6. 住宿管理：办理退宿] ──> 点击【退宿】确认 ──> 状态更新为【已退宿】，授权彻底清除
|
||
↓
|
||
[7. 履历与流水核查] ──> 查看【住宿履历】对话框 & 【命令记录】指令流水
|
||
```
|
||
|
||
### 步骤详解：
|
||
|
||
1. **登录系统**：
|
||
- 打开浏览器访问 `http://127.0.0.1:8088`，输入账号 `admin`，密码 `admin123`，点击登录，进入系统仪表盘首页。
|
||
2. **查询并办理入住**：
|
||
- 点击左侧菜单【培训管理】->【住宿安排】（或访问 `/train/accommodation`）；
|
||
- 在学号输入框输入演示学员学号（例如 `S_DEMO_20261013`），点击【搜索】；
|
||
- 找到处于“预分配”状态的学员记录，点击操作列的【入住】按钮；
|
||
- 在弹出的确认对话框中点击【确定】；
|
||
- 页面提示“入住办理成功”，学员住宿状态实时刷新为绿色的【在住】标签。
|
||
3. **核查门锁授权意图**：
|
||
- 点击左侧菜单【门禁管理】->【授权管理】（或访问 `/iot/auth`）；
|
||
- 看到系统已根据学员的人脸特征与所分配的宿舍房间（致远楼 101），自动建立门锁授权意图记录。
|
||
4. **演示仿真回执确认生效**：
|
||
- 在仿真环境下，系统调用受控 Mock 回执端点驱动状态；
|
||
- 在授权管理页面点击【搜索】刷新，授权同步状态变更为【已生效】（或【下发成功】），展示端到端联动效果。
|
||
5. **办理学员调房**：
|
||
- 返回【住宿安排】页面，点击学员右侧的【调房】按钮；
|
||
- 在弹出的【办理学员调房】对话框中，目标宿舍选择“致远楼 102”，输入床位号“2号床”，点击【确认调房】；
|
||
- 系统执行调房事务：原宿舍记录流转为“已退宿”，新宿舍记录建立并流转为“在住”；
|
||
- 后台自动向旧门锁下发撤权指令，向新门锁下发建权指令。
|
||
6. **办理退宿**：
|
||
- 在【住宿安排】页面中，点击学员所在行的【退宿】按钮，在确认框中点击【确定】；
|
||
- 提示“退宿办理成功”，住宿状态更新为红色的【已退宿】标签。
|
||
7. **查看历史履历与指令流水**：
|
||
- 点击该行操作列的【住宿履历】按钮，弹出【学员历史住宿记录】对话框，清晰展示从预分配、调房退宿到最终退宿的完整时间轴；
|
||
- 点击左侧菜单【门禁管理】->【命令记录】（或访问 `/iot/command`），查看全流程自动生成的授权下发（0011）与清除授权（0012）指令流水，证明全链路具备完整审计溯源能力。
|
||
|
||
---
|
||
|
||
## 五、真实业务流程 vs 仿真（Mock）环节说明
|
||
|
||
为了确保演示的真实性与合规性，系统严格区分业务逻辑与硬件模拟：
|
||
|
||
| 业务环节 | 实现方式 | 状态说明 |
|
||
| :--- | :--- | :--- |
|
||
| **管理员鉴权与 RBAC 权限** | 真实数据库与 Spring Security | 100% 真实执行 |
|
||
| **学员基本信息与班级档案** | 真实 Kingbase QA 数据库表 | 100% 真实执行 |
|
||
| **住宿全生命周期状态机** | 真实业务 Service 与事务 | 100% 真实执行（预分配/在住/退宿） |
|
||
| **住宿调房多阶段事务** | 真实业务 Service | 100% 真实执行（旧记退宿 + 新建在住） |
|
||
| **门锁授权意图关联生成** | 真实 IoT 业务桥接器 | 100% 真实执行（自动解析人脸与房间锁映射） |
|
||
| **指令流水与审计日志** | 真实 Kingbase `iot_command` 表 | 100% 真实执行，全链路持久化 |
|
||
| **前端交互与响应** | 真实 Vue SPA 页面与 Element UI | 100% 真实执行，无静态伪造 |
|
||
| **MQTT 指令双端回执** | Mock 仿真驱动（`iot.mqtt.mock=true`） | 仿真模拟网关与门锁硬件回执，隔绝物理设备 |
|
||
| **人脸识别特征提取** | 仿真服务 | 仿真特征向量映射，未连接物理人脸终端 |
|
||
| **实体门锁物理开锁/状态** | 物理隔离（未接入） | **BLOCKED / HARDWARE_PENDING** |
|
||
|
||
---
|
||
|
||
## 六、常见问题排查与快速恢复
|
||
|
||
### 1. 启动脚本提示 `[BLOCKED] 数据库 SSH 隧道未连接`
|
||
- **原因**：本地 14321 端口无法连接到 Kingbase 研发服务器。
|
||
- **排查方法**：
|
||
1. 检查 SSH 隧道进程：`ps aux | grep 14321`；
|
||
2. 重新建立隧道：`ssh -N -L 127.0.0.1:14321:192.168.139.218:4321 wzbmatebook`；
|
||
3. 验证端口连通：`nc -z 127.0.0.1 14321`。
|
||
|
||
### 2. 页面访问提示 502 Bad Gateway
|
||
- **原因**：后端 Spring Boot 正在启动中或由于数据库超时启动失败。
|
||
- **排查方法**：
|
||
1. 查看后端日志：`tail -n 50 backend.log`；
|
||
2. 检查是否有 Druid 数据源连接超时异常；
|
||
3. 确认后执行 `./stop_demo.sh && ./start_demo.sh` 重启。
|
||
|
||
### 3. 演示过程中需要重置测试数据
|
||
- **方法**：
|
||
可直接在工程根目录下执行演示数据预置脚本：
|
||
```bash
|
||
java -cp RuoYi-Vue-master/ruoyi-admin/target/test-classes:RuoYi-Vue-master/ruoyi-admin/target/ruoyi-admin.jar com.ruoyi.train.PrepareDemoData
|
||
```
|
||
该命令将自动重置学员 `S_DEMO_20261013` 为初始的“预分配”住宿状态，并清理门锁历史旧授权，无需重启系统即可开始下一轮完整演示。
|