8.4 KiB
8.4 KiB
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 - 若隧道未连通，请在终端执行：
ssh -N -L 127.0.0.1:14321:192.168.139.218:4321 -o ServerAliveInterval=15 wzbmatebook - 安全凭据文件：系统启动依赖受限目录下的环境变量配置（
~/.railwaysystem-qa.env），密码由启动脚本安全注入，无需人工输入。
三、一键启停操作指南
系统提供了平滑、健壮的一键管理脚本，支持自动端口清理与就绪健康探测：
1. 启动系统
在工程根目录下执行：
./start_demo.sh
启动脚本自动完成：
- 校验环境变量与凭据完整性；
- 探测数据库 SSH 隧道连通性（未连通时给出明确操作指引并安全终止）；
- 自动释放 8096 与 8088 端口历史旧进程；
- 启动 Spring Boot 4 后端，轮询
/captchaImage验证就绪（约 4~6 秒）； - 启动前端反向代理服务并验证 HTTP 200 就绪；
- 打印就绪提示与访问入口。
2. 停止系统
在演示结束或需要重置时执行：
./stop_demo.sh
停止脚本自动完成：
- 优雅停止前端反向代理进程（释放端口 8088）；
- 优雅停止后端 Spring Boot 进程（释放端口 8096）；
- 清理 Headless Chrome 测试残留进程；
- 确认所有演示端口已完全释放。
四、建议的五分钟核心业务演示路线
建议按照培训学员入宿、门锁授权、调宿换锁、退宿撤权的标准业务生命周期进行演示：
[1. 管理员登录]
↓
[2. 住宿管理：查询预分配学员] ──> 点击【入住】办理 ──> 状态流转为【在住】
↓
[3. 智能门锁：授权管理] ──> 查看自动生成的人脸授权意图 (待下发/待回执)
↓
[4. 仿真回执确认] ──> 受控驱动网关与门锁回执 ──> 页面刷新为【已生效/下发成功】
↓
[5. 住宿管理：办理调房] ──> 选择新宿舍 (致远楼 102) 提交 ──> 触发新门锁建权与旧门锁撤权
↓
[6. 住宿管理：办理退宿] ──> 点击【退宿】确认 ──> 状态更新为【已退宿】，授权彻底清除
↓
[7. 履历与流水核查] ──> 查看【住宿履历】对话框 & 【命令记录】指令流水
步骤详解：
- 登录系统：
- 打开浏览器访问
http://127.0.0.1:8088，输入账号admin，密码admin123，点击登录，进入系统仪表盘首页。
- 打开浏览器访问
- 查询并办理入住：
- 点击左侧菜单【培训管理】->【住宿安排】（或访问
/train/accommodation）； - 在学号输入框输入演示学员学号（例如
S_DEMO_20261013），点击【搜索】； - 找到处于“预分配”状态的学员记录，点击操作列的【入住】按钮；
- 在弹出的确认对话框中点击【确定】；
- 页面提示“入住办理成功”，学员住宿状态实时刷新为绿色的【在住】标签。
- 点击左侧菜单【培训管理】->【住宿安排】（或访问
- 核查门锁授权意图：
- 点击左侧菜单【门禁管理】->【授权管理】（或访问
/iot/auth）； - 看到系统已根据学员的人脸特征与所分配的宿舍房间（致远楼 101），自动建立门锁授权意图记录。
- 点击左侧菜单【门禁管理】->【授权管理】（或访问
- 演示仿真回执确认生效：
- 在仿真环境下，系统调用受控 Mock 回执端点驱动状态；
- 在授权管理页面点击【搜索】刷新，授权同步状态变更为【已生效】（或【下发成功】），展示端到端联动效果。
- 办理学员调房：
- 返回【住宿安排】页面，点击学员右侧的【调房】按钮；
- 在弹出的【办理学员调房】对话框中，目标宿舍选择“致远楼 102”，输入床位号“2号床”，点击【确认调房】；
- 系统执行调房事务：原宿舍记录流转为“已退宿”，新宿舍记录建立并流转为“在住”；
- 后台自动向旧门锁下发撤权指令，向新门锁下发建权指令。
- 办理退宿：
- 在【住宿安排】页面中，点击学员所在行的【退宿】按钮，在确认框中点击【确定】；
- 提示“退宿办理成功”，住宿状态更新为红色的【已退宿】标签。
- 查看历史履历与指令流水：
- 点击该行操作列的【住宿履历】按钮，弹出【学员历史住宿记录】对话框，清晰展示从预分配、调房退宿到最终退宿的完整时间轴；
- 点击左侧菜单【门禁管理】->【命令记录】（或访问
/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 研发服务器。
- 排查方法：
- 检查 SSH 隧道进程：
ps aux | grep 14321； - 重新建立隧道：
ssh -N -L 127.0.0.1:14321:192.168.139.218:4321 wzbmatebook； - 验证端口连通：
nc -z 127.0.0.1 14321。
- 检查 SSH 隧道进程：
2. 页面访问提示 502 Bad Gateway
- 原因：后端 Spring Boot 正在启动中或由于数据库超时启动失败。
- 排查方法：
- 查看后端日志：
tail -n 50 backend.log； - 检查是否有 Druid 数据源连接超时异常；
- 确认后执行
./stop_demo.sh && ./start_demo.sh重启。
- 查看后端日志：
3. 演示过程中需要重置测试数据
- 方法：
可直接在工程根目录下执行演示数据预置脚本：
该命令将自动重置学员
java -cp RuoYi-Vue-master/ruoyi-admin/target/test-classes:RuoYi-Vue-master/ruoyi-admin/target/ruoyi-admin.jar com.ruoyi.train.PrepareDemoDataS_DEMO_20261013为初始的“预分配”住宿状态，并清理门锁历史旧授权，无需重启系统即可开始下一轮完整演示。