chore(sync): 同步当前工作区全部变更（学员学号可编辑并留空自动生成等）
This commit is contained in:
buliping committed
1 parent
01e949093a
commit
ee629f2f3e
534 files changed
+72978
-2720
No files matched your search
@@ -0,0 +1,302 @@
|
||||
# 发送模块排队串行下发与失败重排设计方案
|
||||
|
||||
> 版本：v1.0
|
||||
> 适用模块：`ruoyi-iot` 门锁命令下发（MQTT 下行）
|
||||
> 说明：本文为设计文档，描述目标架构与关键决策，不涉及代码实现。
|
||||
|
||||
---
|
||||
|
||||
## 1. 方案概述与目标
|
||||
|
||||
### 1.1 背景与现状
|
||||
|
||||
当前人脸 / 门锁授权命令的下发链路为：
|
||||
|
||||
`/student/face` → 新建 `LockAuth` → `insertAuth` → `enqueue` 建 `LockCommand` → `send` 落库 → `afterCommit` 提交线程池 → `dispatch` → `publishCommand`（Paho MQTT，QoS=0）。
|
||||
|
||||
其并发特征是：
|
||||
|
||||
- 派发经 `threadPoolTaskExecutor`（core=50 / max=200 / queue=1000）**并行执行**；
|
||||
- `dispatch` 仅对**单条命令**做行锁（`selectCommandByIdForUpdate(commandId)`），不同命令互不阻塞；
|
||||
- `publishCommand` 直接调用 Paho `publish`，**无队列、无串行、无“成功后再发下一条”**；
|
||||
- QoS=0 为“至多一次”，仅代表已交给 broker，**不代表设备生效**；
|
||||
- 每 2s 的 `LockCommandRetryTask` 负责超时判定与重试补偿。
|
||||
|
||||
结果：并发人脸命令无序、并行下发，同一设备/同一主题上的消息可能交错或乱序，且失败与后续互不阻塞。
|
||||
|
||||
### 1.2 目标
|
||||
|
||||
1. **排队**：命令按先进先出（FIFO）进入队列；
|
||||
2. **串行下发**：同一目标（Lane）内严格串行，前一条到达“完成门”后才发下一条；
|
||||
3. **失败重排**：按策略退避重试，耗尽后进入死信/人工；
|
||||
4. **可恢复**：进程重启后队列与状态可续；
|
||||
5. **可观测**：排队、重试、失败、时延全程可追踪与告警。
|
||||
|
||||
### 1.3 范围与非目标
|
||||
|
||||
- **范围**：仅改造“命令生成之后的下发调度层”，叠加在现有 `LockCommand` 模型与 MQTT 通道之上。
|
||||
- **非目标**：不改变 Ydlink 协议、不改变命令与授权业务模型、不引入 broker 级 QoS 语义变更（仍以 QoS=0 为传输基础）。
|
||||
|
||||
### 1.4 术语表
|
||||
|
||||
| 术语 | 含义 |
|
||||
|---|---|
|
||||
| Lane（通道 / 泳道） | 串行化单元，通常为 `deviceSn`（或 `groupCode` / `topic`）。同一 Lane 内串行，不同 Lane 可并行 |
|
||||
| Task（队列任务） | 指向一条 `command_id` 的排队项，携带 Lane、优先级、序号、可见时间等 |
|
||||
| 完成门（Completion Gate） | 判定“本条算发送完成、可推进下一条”的条件（传输成功 / 设备 ACK 确认） |
|
||||
| 队头（Head-of-Lane） | 某 Lane 中当前应被取出执行的最小 `(priority, seq)` 任务 |
|
||||
| 租约（Lease） | 多实例下某实例对某 Lane/任务的临时独占权，带过期时间 |
|
||||
| 死信（DEAD） | 重试耗尽或不可重试后进入的终态，保留现场供人工处理 |
|
||||
| 结果未知 | QoS=0 下 `publish` 抛异常但无法确认是否已达设备 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 系统架构与模块划分
|
||||
|
||||
### 2.1 总体架构
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ 业务入口（如 /student/face） │
|
||||
└───────────────────────────┬──────────────────────────────┘
|
||||
│ ① 事务内落库 LockCommand(READY) + 入队
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ 队列协调器 QueueCoordinator │
|
||||
│ 去重 / 优先级 / 容量控制 / Lane 内 seq 分配 │
|
||||
└───────────────────────────┬──────────────────────────────┘
|
||||
│ ② 写入持久队列
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ 持久队列 lock_dispatch_task（MySQL） │
|
||||
└───────────────────────────┬──────────────────────────────┘
|
||||
│ ③ 取队头（SKIP LOCKED + 租约）
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ 通道调度器 LaneScheduler │
|
||||
│ 每 Lane 单执行者（串行）/ 全局或每目标策略 │
|
||||
└───────────────────────────┬──────────────────────────────┘
|
||||
│ ④ 单条执行
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ 下发执行器 DispatchExecutor │
|
||||
│ dispatch → publishCommand / 完成门判定 │
|
||||
└───────┬───────────────────────────────────┬──────────────┘
|
||||
成功 │ │ 失败 / 超时
|
||||
▼ ▼
|
||||
┌───────────────┐ ┌───────────────────────┐
|
||||
│ DONE（成功） │ │ 重试与死信 RetryManager │
|
||||
└───────────────┘ └───────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ 可观测模块 Metrics / Logging / Tracing │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2.2 模块划分与职责
|
||||
|
||||
| 模块 | 职责 | 关键点 |
|
||||
|---|---|---|
|
||||
| **队列协调器 QueueCoordinator** | 入队、去重、优先级、容量控制、Lane 内 `seq` 分配 | 与业务落库同事务，保证“有命令必有任务” |
|
||||
| **持久队列 lock_dispatch_task** | 持久化 FIFO，支撑重启恢复与多实例 | 状态与顺序以 DB 为准，内存队列仅作唤醒加速 |
|
||||
| **通道调度器 LaneScheduler** | 按 Lane 取队头、租约、串行执行者管理 | 每 Lane 同时仅一个执行者；不同 Lane 并行 |
|
||||
| **下发执行器 DispatchExecutor** | 调用现有 `dispatch/publishCommand`，执行完成门判定 | 复用现有派发与安全校验逻辑，不重复实现 |
|
||||
| **重试与死信 RetryManager** | 失败分类、退避重排、死信沉淀 | 可重试 vs 不可重试；结果未知不自动重放 |
|
||||
| **状态存储** | 任务状态与命令状态持久化、乐观锁 | 复用 `LockCommand`，扩展队列表 |
|
||||
| **补偿任务** | 超时判定、僵尸租约回收、重试唤醒 | 改造/替代现有 `LockCommandRetryTask`（每 2s） |
|
||||
| **可观测模块** | 日志、指标、告警、链路追踪 | 以 `intentKey/commandId` 为关联 ID |
|
||||
|
||||
### 2.3 部署拓扑
|
||||
|
||||
- **单实例**：每 Lane 使用进程内单线程执行器（`SerialExecutor`）或 `Semaphore(1)` 保证串行；持久队列用于重启恢复。
|
||||
- **多实例**：在 DB 层用 `SELECT ... FOR UPDATE SKIP LOCKED` + 租约（`lease_owner/lease_expire_at`）保证同一 Lane 同一时刻只有一个实例持有并执行；备选方案为按 Lane 的 Redis 分布式锁。
|
||||
- **决策**：优先 **DB 租约**，避免额外中间件依赖，且与持久队列同源；多依赖 Redis 时再切换。
|
||||
|
||||
### 2.4 可观测性设计
|
||||
|
||||
- **日志（结构化）**：在 `enqueue / dequeue / start / publish / ack / retry / dead / drop` 节点各打一条，统一携带 `laneKey, taskId, commandId, intentKey, attempt, at`；记录时间轴 `enqueueAt→startAt→publishAt→ackAt→retryAt`。
|
||||
- **指标**：
|
||||
- 队列：`queue_depth{lane}`、`global_depth`、`in_flight_count`、`enqueue_rate`、`dequeue_rate`；
|
||||
- 质量：`success_rate`、`failure_rate{reason}`、`retry_count` 分布、`retry_success_rate`、`dead_letter_count`；
|
||||
- 时延：`time_in_queue`、`dispatch_latency`、`end_to_end_latency`；
|
||||
- 健康：`lane_busy_time`、`head_of_line_blocked_ms`、`lease_expired_count`。
|
||||
- **告警**：队列积压（超阈值/持续增长）、失败率/重试率/死信增长、端到端或排队时延超阈值、单实例长期持锁（疑似僵死）、连接断开。
|
||||
- **追踪**：以 `intentKey/commandId` 为 correlation id，贯通“请求→入队→派发→MQTT→设备 ACK→补偿重试”。
|
||||
|
||||
---
|
||||
|
||||
## 3. 关键流程与数据说明
|
||||
|
||||
### 3.1 数据结构（`lock_dispatch_task`）
|
||||
|
||||
| 字段 | 说明 |
|
||||
|---|---|
|
||||
| `task_id` | 任务主键 |
|
||||
| `lane_key` | 目标标识（`deviceSn` / `groupCode` / `topic`） |
|
||||
| `command_id` | 关联命令（FK），**一条命令至多一个在途任务** |
|
||||
| `intent_key` | 幂等键，用于去重 |
|
||||
| `priority` | 越小越优先（撤销/删除=0，新增=1） |
|
||||
| `seq` | Lane 内单调递增序号（决定 FIFO） |
|
||||
| `state` | 任务状态（见 §3.2） |
|
||||
| `attempts` | 已尝试次数 |
|
||||
| `next_visible_at` | 可见时间（退避用），此前不被取走 |
|
||||
| `lease_owner` / `lease_expire_at` | 多实例租约 |
|
||||
| `version` | 乐观锁 |
|
||||
| `last_error` | 最近错误摘要（截断存储） |
|
||||
| `created_at` / `updated_at` | 审计与排障 |
|
||||
|
||||
索引建议：`(lane_key, state, priority, seq)`、`(state, next_visible_at)`、唯一 `(command_id)`。
|
||||
|
||||
### 3.2 状态机
|
||||
|
||||
```
|
||||
PENDING(待发送) ──取队头──▶ IN_FLIGHT(发送中) ──完成门──▶ DONE(成功)
|
||||
▲ │
|
||||
│ ├─可重试失败/超时─▶ RETRY_WAIT(失败待重试) ──next_visible_at──▶ PENDING
|
||||
│ ├─不可重试/超 maxRetry─▶ DEAD(丢弃/死信)
|
||||
│ └─结果未知(QoS0)─▶ MANUAL_REVIEW(人工对账, 不自动重放)
|
||||
└──────────────── 重启回收：IN_FLIGHT 且租约过期 ─▶ PENDING / MANUAL_REVIEW
|
||||
```
|
||||
|
||||
与现有 `executionState / commandStatus` 的映射：
|
||||
|
||||
| 本方案状态 | 现有映射 |
|
||||
|---|---|
|
||||
| PENDING | `executionState=READY`，`commandStatus=pending` |
|
||||
| IN_FLIGHT | `executionState=DISPATCHING`，`commandStatus=pending` |
|
||||
| RETRY_WAIT | `executionState=READY` + `nextVisibleTime` 未来 |
|
||||
| DONE | `AWAITING_ACK`（模式 A）/ `CONFIRMED`（模式 B） |
|
||||
| DEAD / 丢弃 | `MANUAL_REVIEW` / `QUARANTINED`，`commandStatus=fail/timeout` |
|
||||
|
||||
### 3.3 入队流程
|
||||
|
||||
1. 命令在**同一事务**内落库为 `READY`，同时写入 `lock_dispatch_task`；
|
||||
2. 计算 `lane_key`、`priority`、`seq`（Lane 内 `MAX(seq)+1`）；
|
||||
3. 唯一约束 `(command_id)` 与 `intent_key` 保证幂等，重复入队被忽略；
|
||||
4. 可选“合并”策略：同一设备同一学员重复上传时，旧任务置 `DEAD/drop`，新任务入队（以最新为准）。
|
||||
|
||||
### 3.4 出队与串行下发流程
|
||||
|
||||
1. 调度器按 `(priority, seq)` 选出各 Lane 队头；
|
||||
2. `SELECT ... FOR UPDATE SKIP LOCKED` 抢占，`state→IN_FLIGHT`，写 `lease_owner/expire`；
|
||||
3. 投递到该 Lane 的**单执行者**串行执行；Lane 在任务到终态前不再取下一个；
|
||||
4. 执行内容复用现有 `dispatch → publishCommand`（含安全校验与 `requirePersistedDispatch`）。
|
||||
|
||||
### 3.5 完成门与推进
|
||||
|
||||
- **模式 A（默认，QoS=0）**：`publish` 未抛异常即视为传输成功，推进下一条。低延迟，但仅表示已交 broker。
|
||||
- **模式 B（强一致，可配置）**：命令进入 `AWAITING_ACK` 后，等待设备业务 ACK → `CONFIRMED` 才推进；ACK 超时按失败重排或转人工。
|
||||
- **决策**：默认 A；对“增删互斥 / 强顺序敏感”的 Lane 启用 B。文档需明确“发送成功 ≠ 设备生效”的语义。
|
||||
|
||||
### 3.6 失败重排流程
|
||||
|
||||
1. **失败分类**：可重试（连接断开、`MqttException`、ACK 超时）与不可重试（策略拦截 `POLICY_BLOCKED`、载荷/身份不一致、安全拒绝、方向非法）。
|
||||
2. **不可重试**：直接 `DEAD` / `MANUAL_REVIEW`，不重排。
|
||||
3. **可重试**：`attempts++`，`next_visible_at = now + delay`，`state→RETRY_WAIT`；退避采用 `min(cap, base·2^attempts)·(1±jitter)`（`base≈2s`，`cap≈30min`）。
|
||||
4. **重排位置**（关键决策）：
|
||||
- **严格（默认）**：任务留在队头（`RETRY_WAIT`），同 Lane 后续等待；达 `maxRetry`/超时限后转 `DEAD/MANUAL_REVIEW` 并释放队头，推进下一条。
|
||||
- **宽松（可配置）**：失败任务让出队头、移入延迟/队尾，后续先发；吞吐好但可能改变 Lane 内相对顺序。
|
||||
5. **结果未知（QoS=0）**：不自动重放，转 `MANUAL_REVIEW` 人工对账，避免设备重复执行。
|
||||
|
||||
### 3.7 重启恢复流程
|
||||
|
||||
1. 启动扫描 `lock_dispatch_task` 与命令状态；
|
||||
2. `IN_FLIGHT` 且租约过期 → 视为结果未知：转 `MANUAL_REVIEW`（或按配置重排）；
|
||||
3. `PENDING` / `RETRY_WAIT` → 依据 `next_visible_at` 恢复为队头候选；
|
||||
4. 幂等键防止重复入队。
|
||||
|
||||
### 3.8 去重、优先级与幂等
|
||||
|
||||
- **去重**：唯一 `(command_id)`；`intent_key` 作为跨重复上传的幂等键。
|
||||
- **优先级**：`(priority ASC, seq ASC)` 决定 Lane 内先后（控制类优先于新增）；优先级不跨 Lane 抢占；可加“优先级老化”防低优先级饥饿。
|
||||
- **幂等**：重试复用同一 `command_id`，不产生新业务副作用。
|
||||
|
||||
---
|
||||
|
||||
## 4. 接口与依赖
|
||||
|
||||
### 4.1 内部接口（设计契约）
|
||||
|
||||
| 接口 | 说明 |
|
||||
|---|---|
|
||||
| `enqueue(commandId, laneKey, priority, intentKey)` | 事务内写入队列，返回 `taskId`；幂等 |
|
||||
| `claimHead(laneKey, leaseMs)` | 抢占队头（`SKIP LOCKED` + 租约），返回任务或空 |
|
||||
| `markInflight(taskId, leaseOwner)` | 状态置 `IN_FLIGHT`，续租 |
|
||||
| `complete(taskId, outcome)` | 置 `DONE` / `RETRY_WAIT` / `DEAD`，推进队头 |
|
||||
| `reschedule(taskId, delayMs, error)` | 退避重排，写 `next_visible_at` |
|
||||
| `recoverOnStartup()` | 启动恢复：回收僵尸 `IN_FLIGHT`、恢复可见任务 |
|
||||
|
||||
### 4.2 外部依赖
|
||||
|
||||
- **MySQL**：持久队列与状态存储；`FOR UPDATE SKIP LOCKED` 需 MySQL 8.0+（不满足时退回乐观锁 + 租约轮询）。
|
||||
- **Paho MQTT（QoS=0）**：现有传输通道，无 broker 级确认，完成门语义受其限制。
|
||||
- **调度器**：Spring `@Scheduled`（改造现有 `LockCommandRetryTask`）。
|
||||
- **可选 Redis**：按 Lane 的分布式锁（DB 租约的替代方案）。
|
||||
|
||||
### 4.3 与现有实现的对接点
|
||||
|
||||
- 复用 `LockCommand`（`intentKey`、`executionState`、`commandStatus`、`retryCount`、`maxRetry`、`nextVisibleTime`、`attemptStartedAt`）。
|
||||
- 复用 `LockExecutionTransactions`（`required` / `committed`）处理事务边界。
|
||||
- 复用 `dispatch` 内的安全校验（`requirePayloadAndIdentity`、`requireDispatchAllowed`、`requirePersistedDispatch`）。
|
||||
- 用“入队”替代现有 `afterCommit → taskExecutor.execute` 的并行派发；由 Lane 串行执行器驱动。
|
||||
|
||||
---
|
||||
|
||||
## 5. 约束与风险
|
||||
|
||||
### 5.1 约束
|
||||
|
||||
- 串行粒度上限为 Lane（`deviceSn` / `topic`），跨 Lane 不保证顺序。
|
||||
- QoS=0 无 broker 确认，“传输成功”不等于“设备生效”。
|
||||
- `SKIP LOCKED` 依赖 MySQL 8.0+；旧版本需降级实现。
|
||||
- 必须保持 `intentKey` 幂等与现有安全校验链不变。
|
||||
- 授权类命令为安全敏感操作，不允许静默丢弃。
|
||||
|
||||
### 5.2 风险与应对
|
||||
|
||||
| 风险 | 影响 | 应对 |
|
||||
|---|---|---|
|
||||
| 队头阻塞（严格策略） | 单条失败拖住同 Lane 后续 | 设最大重试/最大滞留时限强推；或切宽松策略 |
|
||||
| 吞吐下降（串行） | 单 Lane 吞吐受限于一条在发 | 每目标 Lane 并行；仅必要时全局单 Lane |
|
||||
| 多实例双消费 | 同任务被重复执行 | `SKIP LOCKED` + 租约心跳 + 幂等 |
|
||||
| 结果未知重复发送 | 设备重复增删 | QoS=0 结果未知不自动重放，转人工 |
|
||||
| 队列满背压 | 影响业务受理 | 授权类显式报错；可选降级直存待重试 |
|
||||
| 时钟漂移/惊群 | 大量任务同刻复活 | `next_visible_at` 用 DB 时间 + 退避抖动 |
|
||||
| 重启遗留 `IN_FLIGHT` | 僵尸任务 | 租约过期回收 + 启动扫描 |
|
||||
|
||||
### 5.3 异常与边界处理
|
||||
|
||||
| 场景 | 处理设计 |
|
||||
|---|---|
|
||||
| 队列满 | 有界队列（全局 + 单 Lane）；授权类拒绝并显式报错（背压），不静默丢；非关键可配丢最旧 |
|
||||
| 发送超时 | `IN_FLIGHT` 超阈值（如 30s）标记超时；QoS=0 结果未知转 `MANUAL_REVIEW`；模式 B 按 ACK 超时重排 |
|
||||
| 重复失败 | 达 `maxRetry` → `DEAD` + 告警；死信保留现场；禁止无限重试 |
|
||||
| 进程重启 | 按 §3.7 扫描恢复；僵尸 `IN_FLIGHT` 转人工或重排 |
|
||||
| 多实例 | `SKIP LOCKED` + 租约；处理幂等 |
|
||||
| 设备离线 | 连接/ACK 失败按可重试退避；超上限转 `DEAD` 并告警 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 待确认事项
|
||||
|
||||
1. **Lane 粒度**：以 `deviceSn`、`groupCode` 还是 `topic` 作为串行单元？（影响并发度与顺序语义）
|
||||
2. **完成门选型**：默认“传输成功即推进”，还是“设备 ACK 确认才推进”？哪些 Lane/命令需强一致？
|
||||
3. **重排策略**：默认严格（阻塞队头）还是宽松（让出队头）？是否按命令类型区分？
|
||||
4. **队列满策略**：拒绝（背压）、降级直存，还是丢最旧？哪些命令允许丢弃？
|
||||
5. **是否需全局串行**：跨设备全局有序是否为硬需求（若否，保持每 Lane 串行）？
|
||||
6. **多实例部署**：是否多实例部署？租约时长、续租心跳、`SKIP LOCKED` 的 MySQL 版本支持情况？
|
||||
7. **重试参数**：`maxRetry`、`base`、`cap`、最大滞留时限、`IN_FLIGHT` 超时阈值的具体取值。
|
||||
8. **死信处理流程**：`DEAD` 的人工对账/重推入口与 SLA。
|
||||
9. **重复上传语义**：同一学员同一设备重复上传是“以最新为准合并”还是“各自排队”？
|
||||
10. **数据保留**：`DONE`/`DEAD` 的保留期与归档清理策略。
|
||||
|
||||
---
|
||||
|
||||
## 附录：落地阶段建议
|
||||
|
||||
1. **阶段一（正确性）**：DB 持久队列 + 每 Lane 串行 + 严格重排（完成门模式 A），打通排队与顺序。
|
||||
2. **阶段二（强一致）**：按需开启模式 B（ACK 门控）与失败分类精细化。
|
||||
3. **阶段三（吞吐与治理）**：宽松重排、优先级老化、死信流程、可观测看板与告警完善。
|
||||
|
||||
> 全方案不改变 Ydlink 协议与现有命令模型，仅在命令之上叠加调度层。
|
||||
@@ -0,0 +1,918 @@
|
||||
# 铁路房建学员管理系统 · 外部实训系统数据接口设计
|
||||
|
||||
> 文档类型：接口与数据表设计（本阶段不含代码实现）
|
||||
> 依据文档：《铁路房建学员管理系统-外部实训系统数据接口规范》（文内版本 V1.2，文件标题 V1.0，5 个接口）
|
||||
> 适用系统：VR 实训 / 3D 巡检 / 实操实训 / 帽石考核 / 其他实训考核系统
|
||||
> 设计范围：平台侧（学员管理系统）对外提供的 5 个接口所需的数据表、约束、接口契约与实现方案
|
||||
> 技术基线：RuoYi-Vue（Spring Boot 4.1 / Java 17 / MyBatis / Redis / PageHelper），数据库 **MySQL 5.7**
|
||||
> 审查状态：已完成框架与数据库兼容性审查，结论与修订建议见第 11 章
|
||||
|
||||
---
|
||||
|
||||
## 1. 业务场景与功能范围
|
||||
|
||||
### 1.1 业务场景
|
||||
|
||||
外部实训系统（VR、3D 巡检、实操、帽石考核等）在实训考核过程中产生成绩，需要：
|
||||
|
||||
1. 考前从平台拉取当期在训学员名单，作为本地考核名单（**不得自行新增学员**）；
|
||||
2. 考核结束后实时上报成绩，或按周期（默认 30 分钟）批量补报；
|
||||
3. 上报失败时按 1/5/15 分钟重试，仍失败转本地缓存，恢复后以 `resend=true` 补传（窗口 90 天）；
|
||||
4. 通过对账接口查询逐条上报结果，处理"学员无法匹配（待认领）""已归档锁定"等异常。
|
||||
|
||||
平台侧承担：学员与班级主数据、考试科目字典、成绩接收与匹配、成绩归集与归档、应用授权与配额管理。
|
||||
|
||||
### 1.2 功能范围
|
||||
|
||||
| 编号 | 功能 | 对应接口 | 平台侧职责 |
|
||||
|---|---|---|---|
|
||||
| F1 | 应用登录换取令牌 | 3.1 `POST /api/open/v1/auth/token` | 校验 appId/appSecret，签发 7200s 令牌，旧令牌立即失效 |
|
||||
| F2 | 在训学员查询 | 3.2 `GET /api/open/v1/student/list` | 按班级过滤、分页返回在训学员，敏感字段掩码 |
|
||||
| F3 | 考试成绩批量上报 | 3.3 `POST /api/open/v1/exam/report` | 整批校验、整批写入，按 `batchId`/`reportId` 幂等，返回汇总 |
|
||||
| F4 | 实时成绩上报 | 3.4 `POST /api/open/v1/exam/report/realtime` | 1–20 条即时接收，按 `reportId` 幂等，返回汇总 |
|
||||
| F5 | 上报结果查询 | 3.5 `GET /api/open/v1/exam/result` | 按 batchId / reportId / 时间窗查询逐条状态，用于对账 |
|
||||
|
||||
**不在本期范围**：外部系统的账号体系与页面、考核过程数据（题目、操作轨迹）解析、成绩的人工评分、外部系统的本地缓存实现。平台仅原样存储 `content` JSON，不解析业务字段。
|
||||
|
||||
### 1.3 设计依据的业务约束（来自规范，必须满足）
|
||||
|
||||
| # | 约束 | 设计落点 |
|
||||
|---|---|---|
|
||||
| C1 | 平台为服务端，全部调用由外部系统发起 | 仅提供出站（平台对外）HTTP 接口，无回调 |
|
||||
| C2 | 一个外部系统一个 `appId`；多实例共用一个 `appId`、一个令牌、一份配额 | 令牌以 `appId` 为粒度唯一（新令牌使旧令牌失效）；限流按 `appId` 计数 |
|
||||
| C3 | 学员身份以平台 `studentId` 为准 | 匹配键固定为 `train_student.s_id`；名单接口返回该值 |
|
||||
| C4 | 报文 UTF-8、`application/json;charset=UTF-8`，单条 ≤ 1 MB | 请求体大小网关 + 应用双层校验 |
|
||||
| C5 | 批量 ≤ 200 条/批，实时 ≤ 20 条/次 | 请求体数组长度校验 |
|
||||
| C6 | 调用频率 ≤ 20 次/秒/appId，超限 3002 | Redis 滑动窗口限流 |
|
||||
| C7 | 除 3.1 外均需 `Authorization: Bearer {accessToken}`，有效期 7200 秒，剩余 10 分钟重新登录 | 令牌 TTL 7200s；响应头回传剩余有效期 |
|
||||
| C8 | 时间一律 int64 毫秒时间戳（东八区），禁止格式化字符串 | 入参校验为 long；内部换算为 `TIMESTAMP` 存储 |
|
||||
| C9 | `reportId` 永久幂等，重复上报忽略、保留首次内容 | `report_id` 全局唯一 + 幂等处理 |
|
||||
| C10 | 同一 `batchId` 重复提交返回首次结果 | `(app_id, batch_id)` 唯一 + 首次汇总回放 |
|
||||
| C11 | 补传窗口 90 天，`resend=true` | 时间窗校验分支 |
|
||||
| C12 | 实时上报时间窗：`examEndTime ≤ now+10min` 且 `≥ now-24h`；`resend=true` 放宽至 90 天 | 校验分支（码 3004） |
|
||||
| C13 | 批量时间窗：每条 `examEndTime ∈ [periodStart, periodEnd)`，单次考试跨度 ≤ 24h | 校验（码 3004） |
|
||||
| C14 | 分数 `0 ≤ score ≤ fullScore`，`fullScore` 默认 100，两位小数 | 校验 + `NUMERIC(7,2)` |
|
||||
| C15 | `retake=true` 时 `retakeNo` 必填且从 1 递增 | 校验（码 3001） |
|
||||
| C16 | `content` 必须为 JSON **对象**且 ≤ 32 KB，不得含身份证/手机号/人脸 | 对象校验 + 体积校验（3005）+ 敏感信息扫描 |
|
||||
| C17 | 平台是成绩归集与归档方，成绩状态 RECEIVED → ARCHIVED，可 LOCKED | `score_status` 状态机 + 归档任务 |
|
||||
| C18 | `matchStatus=UNMATCHED` 需平台管理员认领后转 MATCHED | 待认领池 + 认领操作（后台） |
|
||||
| C19 | 业务结果用 `code` 表达，不依赖 HTTP 状态码 | 业务响应统一 HTTP 200 + code |
|
||||
|
||||
### 1.4 待评审确认的假设
|
||||
|
||||
| # | 事项 | 本设计取值 | 说明 |
|
||||
|---|---|---|---|
|
||||
| A1 | "在训"口径 | `train_enrollment.enrollment_status ∈ (1 已报到, 2 请假)` 且学员 `del_flag='0'`、`status=1` | 已结业(4)、退训(3)、待报到(0) 不返回；如需含待报到，仅调整白名单 |
|
||||
| A2 | `studentNo` 来源 | `train_student.person_no`，为空回退 `s_id` | 平台无独立"学号"字段 |
|
||||
| A3 | `idCard` 返回形式 | 默认掩码（保留前 6 后 4）；可配置返回明文 | 依据规范"身份证号或掩码" |
|
||||
| A4 | 科目字典形态 | 新建 `train_exam_subject` 表（而非复用 `sys_dict_data`） | 需承载"应用-科目授权""科目→考核项映射" |
|
||||
| A5 | 归档映射 | `train_exam_subject.score_item_id` 优先，其次按 `train_score_item.plan_id + item_name` 匹配 | 无法映射则保持 RECEIVED，不阻塞上报 |
|
||||
| A6 | 实时上报是否启用 | 按应用级开关 `realtime_enabled` | 规范：与平台约定开启 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 核心实体与关系
|
||||
|
||||
### 2.1 实体清单
|
||||
|
||||
| 实体 | 说明 | 新增/复用 |
|
||||
|---|---|---|
|
||||
| 外部应用 | 接入方身份（appId/appSecret/类型/状态/配额） | 新增 |
|
||||
| 应用授权范围 | 应用可见的班级 / 科目 | 新增 |
|
||||
| 访问令牌 | 应用调用凭证（审计与吊销） | 新增 |
|
||||
| 考试科目字典 | `subjectCode` / `subjectName`，归档映射 | 新增 |
|
||||
| 上报批次 | 批量上报的批次头与汇总 | 新增 |
|
||||
| 成绩上报记录 | 单条成绩（幂等键 `reportId`），含匹配/归档状态 | 新增 |
|
||||
| 接口调用日志 | `reqId` 追踪与审计 | 新增 |
|
||||
| 学员主档 | `studentId`、姓名、性别、单位、证件 | 复用 `train_student` |
|
||||
| 参训登记 | 学员与班级关系、"在训"判定 | 复用 `train_enrollment` |
|
||||
| 培训班 | `classId` / `className` | 复用 `train_class_plan` |
|
||||
| 考核项 | 归档落库目标配置 | 复用 `train_score_item` |
|
||||
| 学员得分 | 归档后的平台成绩 | 复用 `train_student_score` |
|
||||
|
||||
### 2.2 关系说明
|
||||
|
||||
```
|
||||
train_open_app (PK app_id)
|
||||
├─1:N─ train_open_app_scope (app_id)
|
||||
├─1:N─ train_open_token (app_id)
|
||||
├─1:N─ train_exam_report_batch (app_id)
|
||||
│ └─1:N─ train_exam_report (batch_pk)
|
||||
├─1:N─ train_open_api_log (app_id)
|
||||
└─1:N─ train_exam_report (app_id)
|
||||
|
||||
train_exam_report
|
||||
├─N:1─ train_student (student_id → s_id，匹配后)
|
||||
├─N:1─ train_enrollment (matched_enrollment_id，匹配后)
|
||||
├─N:1─ train_class_plan (matched_plan_id，匹配后)
|
||||
├─N:1─ train_exam_subject (subject_code，可空)
|
||||
└─1:1─ train_student_score (归档后：source_system=app_id AND source_event_id=report_id)
|
||||
|
||||
train_exam_subject
|
||||
├─N:1─ train_class_plan (plan_id，可空表示全局科目)
|
||||
└─N:1─ train_score_item (score_item_id，归档映射，可空)
|
||||
```
|
||||
|
||||
### 2.3 关键约束汇总
|
||||
|
||||
| 约束 | 内容 | 目的 |
|
||||
|---|---|---|
|
||||
| U1 | `train_open_app.app_id` 唯一 | 应用身份唯一 |
|
||||
| U2 | `train_open_app_scope (app_id, scope_type, scope_value)` 唯一 | 授权不重复 |
|
||||
| U3 | `train_open_token.token_hash` 唯一 | 令牌可精确校验/吊销 |
|
||||
| U4 | `train_exam_subject.subject_code` 唯一 | 科目编码唯一，避免同科目多名称 |
|
||||
| U5 | `train_exam_report_batch (app_id, batch_id)` 唯一 | 整批幂等 |
|
||||
| U6 | `train_exam_report.report_id` 唯一 | 单条永久幂等 |
|
||||
| U7 | `train_student_score (enrollment_id, score_item_id)` 唯一（既有） | 归档不重复落分 |
|
||||
| C1 | `train_exam_report`：`exam_end_time > exam_start_time`、`score >= 0`、`score <= full_score`、`retake_no >= 0` | 数据合法性兜底 |
|
||||
| C2 | 状态枚举检查：`match_status ∈ (MATCHED, UNMATCHED)`、`score_status ∈ (RECEIVED, ARCHIVED, LOCKED)`、`report_channel ∈ (REALTIME, PERIODIC)` | 状态机可控 |
|
||||
| C3 | 外键：`app_id → train_open_app.app_id`；`batch_pk → train_exam_report_batch.batch_pk`；`matched_enrollment_id → train_enrollment.enrollment_id` | 引用完整 |
|
||||
|
||||
> C1/C2 在 MySQL 5.7 中**无法由 `CHECK` 强制执行**（5.7 解析但忽略），必须在 DTO 校验 + Service 层兜底；U1–U7 由唯一索引保证，是并发幂等的最终防线。
|
||||
|
||||
---
|
||||
|
||||
## 3. 数据表设计清单
|
||||
|
||||
> 本项目主库为 **MySQL 5.7**，下表类型为方言中立写法，落地映射见 3.9：`BIGINT IDENTITY` → `BIGINT AUTO_INCREMENT`，`TIMESTAMP`（审计字段）→ `DATETIME`，`NUMERIC(7,2)` → `DECIMAL(7,2)`。业务时间统一 `BIGINT`（毫秒）以贴合报文，规避 5.7 `TIMESTAMP` 的 2038 上限与时区转换。
|
||||
|
||||
### 3.1 `train_open_app` 外部应用注册表（新增）
|
||||
|
||||
用途：登记接入方身份、类型、密钥散列、状态与配额。
|
||||
|
||||
| 字段 | 类型 | 空 | 默认 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `app_id` | VARCHAR(64) | N | — | 应用标识，主键；报文 `appId` |
|
||||
| `app_name` | VARCHAR(100) | N | — | 应用名称，如「VR 安全实训系统」 |
|
||||
| `app_type` | VARCHAR(16) | N | — | `VR` / `INSPECT3D` / `PRACTICE` / `CAPSTONE` / `OTHER` |
|
||||
| `org_name` | VARCHAR(100) | Y | NULL | 归属单位，登录响应回显 |
|
||||
| `app_secret_hash` | VARCHAR(128) | N | — | `appSecret` 的 BCrypt 散列（明文不落库） |
|
||||
| `app_secret_masked` | VARCHAR(16) | Y | NULL | 密钥掩码（展示后 4 位） |
|
||||
| `contact_name` | VARCHAR(50) | Y | NULL | 联系人 |
|
||||
| `contact_phone` | VARCHAR(20) | Y | NULL | 联系电话 |
|
||||
| `rate_limit` | INT | N | 20 | 每秒请求上限（默认 20，规范值） |
|
||||
| `realtime_enabled` | SMALLINT | N | 1 | 是否启用 3.4 实时上报（1 启用） |
|
||||
| `status` | SMALLINT | N | 1 | 1 启用 / 0 停用（停用返回 1004） |
|
||||
| `remark` | VARCHAR(500) | Y | NULL | 备注 |
|
||||
| `create_by` | VARCHAR(64) | Y | NULL | 创建人 |
|
||||
| `create_time` | TIMESTAMP | N | CURRENT_TIMESTAMP | 创建时间 |
|
||||
| `update_by` | VARCHAR(64) | Y | NULL | 更新人 |
|
||||
| `update_time` | TIMESTAMP | Y | NULL | 更新时间 |
|
||||
|
||||
- 主键：`pk_train_open_app (app_id)`
|
||||
- 索引建议：`idx_open_app_status (status)`
|
||||
- 关联：1:N `train_open_app_scope`、`train_open_token`、`train_exam_report_batch`、`train_exam_report`
|
||||
|
||||
### 3.2 `train_open_app_scope` 应用授权范围表（新增）
|
||||
|
||||
用途：限定应用可访问的班级 / 科目（越权返回 2001）。
|
||||
|
||||
| 字段 | 类型 | 空 | 默认 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `scope_id` | BIGINT IDENTITY | N | — | 主键 |
|
||||
| `app_id` | VARCHAR(64) | N | — | 外键 → `train_open_app.app_id` |
|
||||
| `scope_type` | VARCHAR(16) | N | — | `CLASS` 班级 / `SUBJECT` 科目 |
|
||||
| `scope_value` | VARCHAR(64) | N | — | 班级 `plan_id` 或科目 `subject_code` |
|
||||
| `create_by` | VARCHAR(64) | Y | NULL | 创建人 |
|
||||
| `create_time` | TIMESTAMP | N | CURRENT_TIMESTAMP | 创建时间 |
|
||||
|
||||
- 主键：`pk_open_app_scope (scope_id)`
|
||||
- 唯一键：`uk_open_app_scope (app_id, scope_type, scope_value)`
|
||||
- 外键：`fk_scope_app (app_id) → train_open_app(app_id)`
|
||||
- 索引建议：`idx_scope_value (scope_type, scope_value)`（按班级/科目反查应用）
|
||||
|
||||
### 3.3 `train_open_token` 访问令牌表（新增）
|
||||
|
||||
用途：令牌审计、吊销与重启恢复。运行期以 Redis 为主存储（`train:open:token:{appId}`，TTL 7200s）。
|
||||
|
||||
| 字段 | 类型 | 空 | 默认 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `token_id` | BIGINT IDENTITY | N | — | 主键 |
|
||||
| `app_id` | VARCHAR(64) | N | — | 外键 → `train_open_app.app_id` |
|
||||
| `token_hash` | VARCHAR(64) | N | — | 令牌的 SHA-256（不存明文），唯一 |
|
||||
| `issued_time` | TIMESTAMP | N | CURRENT_TIMESTAMP | 签发时间 |
|
||||
| `expire_time` | TIMESTAMP | N | — | 过期时间（签发 + 7200s） |
|
||||
| `status` | SMALLINT | N | 1 | 1 有效 / 0 已失效（被新令牌替换或手动吊销） |
|
||||
| `client_ip` | VARCHAR(64) | Y | NULL | 签发来源 IP（审计） |
|
||||
| `user_agent` | VARCHAR(255) | Y | NULL | 客户端标识 |
|
||||
| `create_time` | TIMESTAMP | N | CURRENT_TIMESTAMP | 创建时间 |
|
||||
|
||||
- 主键：`pk_open_token (token_id)`
|
||||
- 唯一键：`uk_open_token_hash (token_hash)`
|
||||
- 外键：`fk_token_app (app_id) → train_open_app(app_id)`
|
||||
- 索引建议：`idx_token_app_status (app_id, status)`、`idx_token_expire (expire_time)`（清理任务）
|
||||
|
||||
### 3.4 `train_exam_subject` 考试科目字典表（新增）
|
||||
|
||||
用途：统一 `subjectCode` / `subjectName`，承载科目授权与归档映射。
|
||||
|
||||
| 字段 | 类型 | 空 | 默认 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `subject_id` | BIGINT IDENTITY | N | — | 主键 |
|
||||
| `subject_code` | VARCHAR(32) | N | — | 科目编码（如 `VR-SAFE`），唯一 |
|
||||
| `subject_name` | VARCHAR(100) | N | — | 科目名称（如「高处作业隐患排查」），唯一 |
|
||||
| `plan_id` | VARCHAR(32) | Y | NULL | 外键 → `train_class_plan.plan_id`；空表示全局科目 |
|
||||
| `score_item_id` | BIGINT | Y | NULL | 外键 → `train_score_item.score_item_id`；归档落分目标 |
|
||||
| `status` | SMALLINT | N | 1 | 1 启用 / 0 停用 |
|
||||
| `sort_no` | INT | N | 0 | 展示顺序 |
|
||||
| `remark` | VARCHAR(200) | Y | NULL | 备注 |
|
||||
| `create_by` / `create_time` / `update_by` / `update_time` | VARCHAR(64)/TIMESTAMP/… | Y | — | 审计字段 |
|
||||
|
||||
- 主键：`pk_exam_subject (subject_id)`
|
||||
- 唯一键：`uk_exam_subject_code (subject_code)`、`uk_exam_subject_name (subject_name)`
|
||||
- 外键：`fk_subject_plan (plan_id) → train_class_plan(plan_id)`、`fk_subject_score_item (score_item_id) → train_score_item(score_item_id)`
|
||||
- 索引建议：`idx_subject_plan (plan_id, status)`
|
||||
|
||||
### 3.5 `train_exam_report_batch` 上报批次表（新增）
|
||||
|
||||
用途：批量上报的批次头、首个汇总结果回放、`batchId` 幂等。
|
||||
|
||||
| 字段 | 类型 | 空 | 默认 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `batch_pk` | BIGINT IDENTITY | N | — | 主键（内部） |
|
||||
| `app_id` | VARCHAR(64) | N | — | 外键 → `train_open_app.app_id` |
|
||||
| `batch_id` | VARCHAR(64) | N | — | 报文 `batchId` |
|
||||
| `report_time` | BIGINT | N | — | 报文 `reportTime`（毫秒） |
|
||||
| `period_start` | BIGINT | N | — | 覆盖窗口开始（含），毫秒 |
|
||||
| `period_end` | BIGINT | N | — | 覆盖窗口结束（不含），毫秒 |
|
||||
| `resend` | SMALLINT | N | 0 | 补传标记 1/0 |
|
||||
| `total` | INT | N | 0 | 本批记录数 |
|
||||
| `accepted` | INT | N | 0 | 校验通过并入库 |
|
||||
| `duplicated` | INT | N | 0 | `reportId` 已存在被忽略 |
|
||||
| `unmatched` | INT | N | 0 | 学员无法匹配（待认领） |
|
||||
| `received_time` | BIGINT | N | — | 平台接收时间（毫秒） |
|
||||
| `req_id` | VARCHAR(64) | Y | NULL | 处理该批次的请求标识 |
|
||||
| `create_time` | TIMESTAMP | N | CURRENT_TIMESTAMP | 创建时间 |
|
||||
|
||||
- 主键：`pk_exam_report_batch (batch_pk)`
|
||||
- 唯一键：`uk_batch_app_batch (app_id, batch_id)`
|
||||
- 外键：`fk_batch_app (app_id) → train_open_app(app_id)`
|
||||
- 索引建议：`idx_batch_received (app_id, received_time)`、`idx_batch_period (period_start, period_end)`
|
||||
|
||||
### 3.6 `train_exam_report` 成绩上报记录表（新增，核心）
|
||||
|
||||
用途：保存每条上报成绩原文、匹配结果与归档状态；`reportId` 为永久幂等键。
|
||||
|
||||
| 字段 | 类型 | 空 | 默认 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `report_pk` | BIGINT IDENTITY | N | — | 主键（内部） |
|
||||
| `report_id` | VARCHAR(64) | N | — | 报文 `reportId`，全局唯一幂等键 |
|
||||
| `app_id` | VARCHAR(64) | N | — | 外键 → `train_open_app.app_id` |
|
||||
| `batch_pk` | BIGINT | Y | NULL | 外键 → `train_exam_report_batch.batch_pk`；实时上报为 NULL |
|
||||
| `batch_id` | VARCHAR(64) | Y | NULL | 批次号冗余（实时上报为 NULL），便于按批查询 |
|
||||
| `report_channel` | VARCHAR(16) | N | — | `REALTIME` / `PERIODIC` |
|
||||
| `biz_type` | VARCHAR(16) | N | 'PRACTICE' | 成绩类型，固定实训成绩 |
|
||||
| `student_id` | VARCHAR(32) | N | — | 报文 `studentId`（匹配键，原文保留） |
|
||||
| `student_name` | VARCHAR(50) | Y | NULL | 上报姓名，供人工认领核对 |
|
||||
| `id_card_masked` | VARCHAR(32) | Y | NULL | 上报证件号掩码（明文不落库，仅存比对结果） |
|
||||
| `id_card_md5` | CHAR(32) | Y | NULL | 上报证件号 MD5，用于与平台档案交叉校验 |
|
||||
| `matched_enrollment_id` | BIGINT | Y | NULL | 外键 → `train_enrollment.enrollment_id`，匹配成功时写入 |
|
||||
| `matched_plan_id` | VARCHAR(32) | Y | NULL | 匹配到的培训班 `plan_id`（冗余） |
|
||||
| `match_status` | VARCHAR(16) | N | 'UNMATCHED' | `MATCHED` / `UNMATCHED` |
|
||||
| `score_status` | VARCHAR(16) | N | 'RECEIVED' | `RECEIVED` / `ARCHIVED` / `LOCKED` |
|
||||
| `subject_code` | VARCHAR(32) | Y | NULL | 科目编码，须与字典一致（可空） |
|
||||
| `subject_name` | VARCHAR(100) | N | — | 科目名称（必填） |
|
||||
| `exam_start_time` | BIGINT | N | — | 考试开始（毫秒） |
|
||||
| `exam_end_time` | BIGINT | N | — | 考试结束（毫秒） |
|
||||
| `duration_seconds` | INT | Y | NULL | 用时（`exam_end_time - exam_start_time` 换算秒，写入时计算） |
|
||||
| `score` | NUMERIC(7,2) | N | — | 分数（两位小数） |
|
||||
| `full_score` | NUMERIC(7,2) | N | 100.00 | 满分 |
|
||||
| `pass_flag` | SMALLINT | N | — | 是否通过 1/0（报文 `pass`） |
|
||||
| `retake` | SMALLINT | N | 0 | 是否重考 1/0 |
|
||||
| `retake_no` | INT | N | 0 | 重考序号，`retake=0` 时为 0 |
|
||||
| `station` | VARCHAR(64) | N | — | 考试工位 |
|
||||
| `content` | TEXT | N | — | 考试内容原始 JSON（对象，≤32 KB，原样存储） |
|
||||
| `content_size` | INT | Y | NULL | 内容 UTF-8 字节数 |
|
||||
| `content_md5` | CHAR(32) | Y | NULL | 内容摘要，用于重复上报的内容一致性判断 |
|
||||
| `remark` | VARCHAR(500) | Y | NULL | 备注 |
|
||||
| `report_time` | BIGINT | Y | NULL | 报文 `reportTime`，实时上报缺省为接收时间 |
|
||||
| `received_time` | BIGINT | N | — | 平台接收时间（毫秒） |
|
||||
| `resend` | SMALLINT | N | 0 | 补传标记 1/0 |
|
||||
| `claim_by` | VARCHAR(64) | Y | NULL | 认领操作人（UNMATCHED → MATCHED） |
|
||||
| `claim_time` | TIMESTAMP | Y | NULL | 认领时间 |
|
||||
| `archive_time` | TIMESTAMP | Y | NULL | 归档时间（写入 `train_student_score`） |
|
||||
| `lock_time` | TIMESTAMP | Y | NULL | 锁定时间（结课/人工锁定） |
|
||||
| `lock_reason` | VARCHAR(200) | Y | NULL | 锁定原因 |
|
||||
| `data_version` | INT | N | 0 | 乐观锁版本（归档/认领并发保护） |
|
||||
| `create_time` / `update_time` | TIMESTAMP | Y | CURRENT_TIMESTAMP | 审计字段 |
|
||||
|
||||
- 主键：`pk_exam_report (report_pk)`
|
||||
- 唯一键：`uk_exam_report_id (report_id)`
|
||||
- 外键：
|
||||
- `fk_report_app (app_id) → train_open_app(app_id)`
|
||||
- `fk_report_batch (batch_pk) → train_exam_report_batch(batch_pk)`
|
||||
- `fk_report_enrollment (matched_enrollment_id) → train_enrollment(enrollment_id)`
|
||||
- 检查约束（**MySQL 5.7 仅语法解析、不生效**，下列规则必须由应用层校验兜底，Kingbase 侧可按此 DDL 建约束）：
|
||||
- `chk_report_time_range CHECK (exam_end_time > exam_start_time)`
|
||||
- `chk_report_score CHECK (score >= 0 AND score <= full_score)`
|
||||
- `chk_report_retake_no CHECK (retake_no >= 0)`
|
||||
- `chk_report_match_status CHECK (match_status IN ('MATCHED','UNMATCHED'))`
|
||||
- `chk_report_score_status CHECK (score_status IN ('RECEIVED','ARCHIVED','LOCKED'))`
|
||||
- `chk_report_channel CHECK (report_channel IN ('REALTIME','PERIODIC'))`
|
||||
- 索引建议：
|
||||
- `idx_report_app_time (app_id, received_time)`：按应用对账
|
||||
- `idx_report_app_batch (app_id, batch_id)`：3.5 按批次查询
|
||||
- `idx_report_student (app_id, student_id, exam_end_time)`：学员成绩回溯
|
||||
- `idx_report_status (match_status, score_status)`：认领与归档任务扫描
|
||||
- `idx_report_exam_end (exam_end_time)`：时间窗查询（3.5）
|
||||
- 容量与归档：单应用日均 1 万条估算，`content` 平均 2–8 KB；**MySQL 5.7 不做分区**（唯一键 `report_id` 与分区列约束冲突），改为"热表保留 12 个月 + 按 `received_time` 归档到 `train_exam_report_his`（同结构）"，列表查询不读取 `content` 列。
|
||||
|
||||
### 3.7 `train_open_api_log` 接口调用日志表（新增）
|
||||
|
||||
用途：`reqId` 排障、审计与配额统计（异步写入，失败不影响主流程）。
|
||||
|
||||
| 字段 | 类型 | 空 | 默认 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `log_id` | BIGINT IDENTITY | N | — | 主键 |
|
||||
| `req_id` | VARCHAR(64) | N | — | 请求标识（响应同值） |
|
||||
| `app_id` | VARCHAR(64) | Y | NULL | 应用（登录失败时可能为空） |
|
||||
| `api_path` | VARCHAR(128) | N | — | 请求路径 |
|
||||
| `http_method` | VARCHAR(8) | N | — | GET / POST |
|
||||
| `biz_key` | VARCHAR(128) | Y | NULL | 业务键：`batchId` / `reportId` / `classId` |
|
||||
| `code` | INT | N | — | 业务返回码 |
|
||||
| `msg` | VARCHAR(500) | Y | NULL | 返回描述（截断） |
|
||||
| `cost_ms` | INT | Y | NULL | 耗时（毫秒） |
|
||||
| `client_ip` | VARCHAR(64) | Y | NULL | 调用方 IP |
|
||||
| `create_time` | TIMESTAMP | N | CURRENT_TIMESTAMP | 记录时间 |
|
||||
|
||||
- 主键：`pk_open_api_log (log_id)`
|
||||
- 索引建议：`idx_open_log_req (req_id)`、`idx_open_log_app_time (app_id, create_time)`
|
||||
- 保留策略：默认 90 天，按 `create_time` 定期清理。
|
||||
|
||||
### 3.8 复用的既有表（不新增字段，仅映射）
|
||||
|
||||
| 表 | 关键字段 | 在接口中的用途 | 映射/说明 |
|
||||
|---|---|---|---|
|
||||
| `train_student` | `s_id`、`s_name`、`s_gender`、`s_phone`、`id_card_ciphertext`/`id_card_hash`/`id_card_last4`、`dept_name`、`card_no`、`status`、`del_flag` | 3.2 名单来源；3.3/3.4 匹配 | `studentId ← s_id`；`gender`：男→`MALE`、女→`FEMALE`；`orgName ← dept_name`；`studentNo ← card_no`（空回退 `s_id`） |
|
||||
| `train_enrollment` | `enrollment_id`、`plan_id`、`student_id`、`enrollment_status`、`join_time`、`complete_time` | 3.2 在训过滤；3.3/3.4 定位 `enrollment_id` | 在训口径见 A1 |
|
||||
| `train_class_plan` | `plan_id`、`plan_name` | 3.2 班级过滤与 `className` | `classId ← plan_id` |
|
||||
| `train_score_item` | `score_item_id`、`plan_id`、`item_name`、`full_score` | 归档时定位考核项 | 与 `train_exam_subject.score_item_id` 配合 |
|
||||
| `train_student_score` | `enrollment_id`、`score_item_id`、`score`、`source_type`、`source_system`、`source_event_id` | 归档落分 | `source_type=4`（外部导入）；`source_system=appId`；`source_event_id=reportId`；`(enrollment_id, score_item_id)` 唯一，归档用 UPSERT |
|
||||
|
||||
### 3.9 数据库方言与 MySQL 5.7 落地约定（本项目主库为 MySQL 5.7）
|
||||
|
||||
> 本节按「MySQL 5.7 为主、Kingbase 兼容为辅」修订；MySQL 5.7 的差异已计入字段类型与实现方式。
|
||||
|
||||
| 设计项 | MySQL 5.7 写法与约束 | 说明 |
|
||||
|---|---|---|
|
||||
| 自增主键 | `BIGINT NOT NULL AUTO_INCREMENT` | 不支持 `GENERATED ... AS IDENTITY`；MyBatis 需 `useGeneratedKeys="true"` |
|
||||
| 审计时间 | `DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP` | 避免 `TIMESTAMP` 的 2038 上限与时区隐式转换；与 RuoYi 既有表一致 |
|
||||
| 分数 | `DECIMAL(7,2)` | `NUMERIC` 仅为同义词，DDL 统一写 `DECIMAL` |
|
||||
| 列注释 | 列定义内 `COMMENT '...'` | 不支持独立 `COMMENT ON COLUMN` |
|
||||
| `content` 存储 | `TEXT NOT NULL`（**不用 `JSON`**） | MySQL 5.7 的 `JSON` 会重排键、去空白、强制校验，破坏"原样存储"与 `content_md5` 语义；`TEXT`（65,535 字节）足以容纳 32 KB |
|
||||
| 枚举/状态 | `VARCHAR(16)` + 应用层枚举校验 | MySQL 5.7 **解析但不强制执行 `CHECK`**，唯一/非空之外只能靠应用校验 |
|
||||
| 字符集 | `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci` | 需与 `train_student` 等既有表一致，避免 JOIN 隐式转换导致索引失效 |
|
||||
| 长索引 | `VARCHAR(100)` 唯一键（utf8mb4 400 字节） | 5.7 默认 `innodb_large_prefix=ON`，3072 字节上限内安全 |
|
||||
| 哈希列 | `CHAR(32) CHARACTER SET ascii` | 证件号/内容摘要仅 ASCII，节省空间并避免大小写/重音排序干扰 |
|
||||
| 迁移脚本 | 无 `ADD COLUMN IF NOT EXISTS`、无 `CREATE INDEX IF NOT EXISTS` | 用 `information_schema` 判断后 `PREPARE/EXECUTE`，脚本须可重复执行 |
|
||||
| SQL 能力 | 无窗口函数、无 CTE（`WITH`） | "取最新在训记录"用 `ORDER BY join_time DESC LIMIT 1`；统计用子查询，不写 `ROW_NUMBER()` |
|
||||
| 分区 | **本期不分区** | 5.7 要求所有唯一键包含分区列，`report_id` 全局唯一与分区互斥；改用"热表 + 定期归档冷数据" |
|
||||
| JDBC 连接 | 现有 URL 为 `characterEncoding=utf8` | 如需完整 4 字节字符支持，改为 `characterEncoding=utf8mb4` 并确认服务端 `utf8mb4`（现网中文场景可保持现状） |
|
||||
|
||||
---
|
||||
|
||||
## 4. 接口设计方案
|
||||
|
||||
### 4.1 分层与落点（仅设计说明）
|
||||
|
||||
| 层 | 职责 | 建议落点 |
|
||||
|---|---|---|
|
||||
| 接入层 | 令牌校验、限流、`reqId` 生成、请求体大小限制、应用上下文注入 | `ruoyi-admin`：`/api/open/v1/**` 过滤器 + 统一异常处理 |
|
||||
| 控制层 | 5 个接口的入参/出参、参数格式校验 | `com.ruoyi.web.controller.open.OpenExamApiController`（按接口再拆分为 Auth/Student/Exam 三个 Controller） |
|
||||
| 服务层 | 令牌签发、名单查询、上报校验与幂等、匹配、归档、认领 | `ruoyi-train`：`ITrainOpenAppService`、`IOpenExamReportService`、`IOpenStudentQueryService` |
|
||||
| 持久层 | 上述新表 CRUD 与幂等插入 | MyBatis Mapper |
|
||||
| 任务层 | 归档任务、令牌清理、日志清理 | 定时任务（参照现有 quartz 任务） |
|
||||
| 存储层 | 令牌、限流计数、应用配置缓存 | Redis |
|
||||
|
||||
**统一响应模型** `OpenApiResponse<T>`：`code`、`msg`、`data`、`reqId`、`ts`；HTTP 恒为 200（业务错误也用 code 表达），网关层超限（如 Nginx 413）除外。
|
||||
|
||||
> **与 RuoYi 的兼容性说明（重要）**
|
||||
> - 不能直接复用 `AjaxResult`：其成功码为 `HttpStatus.SUCCESS`(=200)，`isSuccess()` 按 200 判定，而本规范要求 `code=0`；额外还需要 `reqId`/`ts`。故新建 `OpenApiResponse`（`code/msg/data/reqId/ts`）+ `OpenApiResponse.success(data)`/`error(code,msg)`，仅本包使用。
|
||||
> - 不能复用 `TableDataInfo`（字段为 `total/rows/code/msg`）与 `BaseController.getDataTable()`，分页数据按规范输出 `{total,pageNo,pageSize,list}`。
|
||||
> - 不能复用全局 `GlobalExceptionHandler`：其对 `ServiceException`/校验异常统一返回 `AjaxResult.error(...)`（code=500，无 `reqId`）。需新增 `@RestControllerAdvice`（`basePackages` 限定 open 包、`@Order` 高于全局）把异常映射到 1001/1002/3003/3005/4000。
|
||||
> - 鉴权放行用框架既有机制：Controller 标注 `@Anonymous`（`PermitAllUrlProperties` 自动收集并 permitAll），再由自有 Servlet Filter（参照 `OpenApiAuthFilter`）做令牌校验；不改动 `SecurityConfig` 中既有 matcher 列表。
|
||||
> - 必须把 `/api/open/**` 加入 `xss.excludes`：RuoYi `XssFilter` 对 POST/PUT 的 JSON 会逐字符串转义，会破坏 `content` 的"原样存储"与 `content_md5`。
|
||||
> - 令牌读写统一用 `RedisCache`（`setCacheObject(key, val, 7200, TimeUnit.SECONDS)`），键前缀 `open:token:{appId}`，与框架登录令牌 `login_tokens:*` 隔离。
|
||||
> - 外部调用无登录上下文：禁止调用 `SecurityUtils.getUsername()`（会抛异常），审计操作人固定为 `openapi`。
|
||||
|
||||
### 4.2 接口一：登录获取访问令牌
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 名称 | 登录获取访问令牌 |
|
||||
| 路径 / 方法 | `POST /api/open/v1/auth/token` |
|
||||
| 鉴权 | 无（白名单），仅校验 appId + appSecret |
|
||||
| 对应表 | `train_open_app`、`train_open_token`、`train_open_api_log` |
|
||||
|
||||
**入参**
|
||||
|
||||
| 字段 | 类型 | 必填 | 校验 |
|
||||
|---|---|---|---|
|
||||
| `appId` | string(64) | 是 | 非空；长度 ≤ 64 |
|
||||
| `appSecret` | string(128) | 是 | 非空；长度 ≤ 128 |
|
||||
|
||||
**出参 `data`**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `accessToken` | string | 不透明令牌（256 位随机），Redis 与 `train_open_token.token_hash` 存散列 |
|
||||
| `tokenType` | string | 固定 `Bearer` |
|
||||
| `expiresIn` | int | 固定 `7200` |
|
||||
| `app.appId` | string | 应用标识 |
|
||||
| `app.appName` | string | 应用名称 |
|
||||
| `app.appType` | string | 应用类型枚举 |
|
||||
| `app.orgName` | string | 归属单位 |
|
||||
|
||||
> 规范示例中的令牌形如 JWT 仅为示意；平台采用不透明随机串（调用方无需解析），如需与既有系统统一，也可改为 HS256 JWT，载荷仅含 `appId`、`iat`、`exp`，并同样在 Redis 维护"单应用单令牌"。
|
||||
|
||||
**业务逻辑**
|
||||
|
||||
1. 参数非空校验，失败 → `1001`；
|
||||
2. 按 `app_id` 查应用：不存在 → `1003`；`status=0` → `1004`；
|
||||
3. BCrypt 校验 `appSecret`，失败 → `1005`（同一应用连续失败 5 次锁定 10 分钟，防爆破）；
|
||||
4. 生成令牌（SecureRandom 32 字节，Base64URL），计算 SHA-256；
|
||||
5. 旧令牌失效：将 Redis `train:open:token:{appId}` 指向新散列并重置 TTL；`train_open_token` 中该应用 `status=1` 记录置 0；
|
||||
6. 写入新令牌记录（`issued_time`、`expire_time=now+7200s`、`client_ip`），Redis 写入 `appId → tokenHash`，TTL 7200s；
|
||||
7. 记录调用日志；返回令牌与应用信息。
|
||||
|
||||
**边界与错误码**：`1001`/`1003`/`1004`/`1005`/`4000`。
|
||||
|
||||
### 4.3 接口二：在训学员查询
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 名称 | 在训学员查询 |
|
||||
| 路径 / 方法 | `GET /api/open/v1/student/list` |
|
||||
| 鉴权 | Bearer；需 `CLASS` 范围（传 `classId` 时校验） |
|
||||
| 对应表 | `train_student`、`train_enrollment`、`train_class_plan`、`train_open_app_scope`、`train_open_api_log` |
|
||||
|
||||
**入参（Query）**
|
||||
|
||||
| 字段 | 类型 | 必填 | 校验 |
|
||||
|---|---|---|---|
|
||||
| `classId` | string(32) | 否 | 传则须存在且在该应用 `CLASS` 授权内 |
|
||||
| `pageNo` | int | 否 | ≥ 1，默认 1 |
|
||||
| `pageSize` | int | 否 | 1–200，默认 50 |
|
||||
|
||||
**出参 `data`**：`{ total, pageNo, pageSize, list[] }`
|
||||
|
||||
`list[]` 字段：`studentId`、`studentName`、`gender`（MALE/FEMALE）、`phone`（掩码）、`idCard`（掩码）、`classId`、`className`、`studentNo`、`orgName`。
|
||||
|
||||
**业务逻辑**
|
||||
|
||||
1. 令牌校验通过，`appId` 由过滤器注入；
|
||||
2. `classId` 存在性校验 → 不存在 `2002`；`CLASS` 授权校验 → 未授权 `2001`；
|
||||
3. 组装查询：`train_enrollment e JOIN train_student s JOIN train_class_plan p`；
|
||||
- `s.del_flag='0' AND s.status=1`；
|
||||
- `e.enrollment_status IN (1,2)`（在训口径 A1）；
|
||||
- 传 `classId` 时 `e.plan_id = #{classId}`；
|
||||
- 同一学员多班时按班展开（每人每班一行）。
|
||||
4. 固定排序：`p.plan_name ASC, e.student_id ASC`（保证翻页稳定）；
|
||||
5. 分页返回；手机号中间 4 位掩码，证件号按 A3 掩码；`gender` 枚举转换；
|
||||
6. 记录调用日志（`biz_key=classId`）。
|
||||
|
||||
**边界与错误码**：`1002`（分页参数非法）、`2001`、`2002`、`1006`、`3002`、`4000`。
|
||||
|
||||
### 4.4 接口三：考试成绩批量上报
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 名称 | 考试成绩批量上报 |
|
||||
| 路径 / 方法 | `POST /api/open/v1/exam/report` |
|
||||
| 鉴权 | Bearer；`SUBJECT` 范围校验（带 `subjectCode` 时）；`realtime_enabled` 无关 |
|
||||
| 对应表 | `train_exam_report_batch`、`train_exam_report`、`train_open_app_scope`、`train_exam_subject`、`train_student`、`train_enrollment`、`train_open_api_log` |
|
||||
|
||||
**入参（Body）**
|
||||
|
||||
批次级：`batchId`(string64,必填)、`reportTime`(int64,必填)、`periodStart`(int64,必填)、`periodEnd`(int64,必填)、`resend`(boolean,可选，默认 false)、`reports`(object[],必填，1–200)。
|
||||
|
||||
`reports[]`：`reportId`(string64,必填)、`studentId`(string32,必填)、`idCard`(string64,可选)、`studentName`(string50,可选)、`subjectCode`(string32,可选)、`subjectName`(string100,必填)、`examStartTime`(int64,必填)、`examEndTime`(int64,必填)、`score`(decimal,必填)、`fullScore`(decimal,可选，默认 100)、`pass`(boolean,必填)、`retake`(boolean,必填)、`retakeNo`(int,条件)、`station`(string64,必填)、`content`(object,必填)、`remark`(string500,可选)。
|
||||
|
||||
**出参 `data`**：`batchId`、`total`、`accepted`、`duplicated`、`unmatched`、`receivedTime`（满足 `accepted + duplicated + unmatched = total`）。
|
||||
|
||||
**业务逻辑**
|
||||
|
||||
1. **请求级校验**：`Content-Length ≤ 1 MB` → 否则 `3003`；JSON 结构/类型 → `1002`；必填缺失 → `1001`；
|
||||
2. **批次校验**：`batchId` ≤ 64；`periodEnd > periodStart` → 否则 `3004`；`reports` 1–200 → 否则 `3003`；批内 `reportId` 重复 → `3001`；
|
||||
3. **批次幂等**：查 `(app_id, batch_id)`：
|
||||
- 已存在且批次元数据（`reportTime`/`periodStart`/`periodEnd`/`resend`/记录数）一致 → 直接回放首次汇总，不重复入库；
|
||||
- 已存在但元数据不一致 → `2003`；
|
||||
4. **逐条字段校验**（整批校验，任一不合法整批拒绝 `3001`）：
|
||||
- `reportId` ≤ 64 且非空；`studentId` 非空 ≤ 32；`subjectName` 非空；
|
||||
- `examEndTime > examStartTime` 且跨度 ≤ 24h，`examEndTime ∈ [periodStart, periodEnd)` → 否则 `3004`；
|
||||
- `0 ≤ score ≤ fullScore`，`fullScore` 缺省 100，小数位 ≤ 2 → 否则 `3001`；
|
||||
- `retake=true` 时 `retakeNo ≥ 1`，`retake=false` 时 `retakeNo` 缺省 0；
|
||||
- `content` 为 JSON 对象且序列化 ≤ 32 KB → 否则 `3005`；命中身份证/手机号模式 → `3005`；
|
||||
- `subjectCode` 传值时须存在于 `train_exam_subject`（启用）→ 否则 `3001`；不在应用 `SUBJECT` 授权内 → `2001`；
|
||||
5. **写入批次头**（`total` 先落，汇总置 0，事务内更新）；
|
||||
6. **逐条处理**（`reportId` 分块预查 + 唯一键冲突兜底）：
|
||||
- `report_id` 已存在 → `duplicated++`（保持首次内容；若 `content_md5` 不同仅记差异日志，不覆盖）；
|
||||
- 学员匹配（见 4.7）：成功 → `match_status=MATCHED` 并写 `matched_enrollment_id`/`matched_plan_id`；失败 → `UNMATCHED`、`unmatched++`；
|
||||
- 入库 `train_exam_report`（`report_channel='PERIODIC'`，`resend`、`report_time`、`received_time` 落库）；
|
||||
- 成功入库 → `accepted++`；
|
||||
7. 汇总更新批次头，返回汇总；记录调用日志（`biz_key=batchId`）。
|
||||
8. 事务与并发：批次头 + 明细在同一事务，每 100 条一批 `INSERT`；唯一键冲突捕获后按 `duplicated` 处理；跨实例并发同 `batchId` 由唯一键保证只成功一次，另一请求回放首次结果。
|
||||
|
||||
**边界与错误码**：`1001`、`1002`、`2001`、`2003`、`3001`、`3002`、`3003`、`3004`、`3005`、`4000`。
|
||||
|
||||
### 4.5 接口四：实时成绩上报
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 名称 | 实时成绩上报 |
|
||||
| 路径 / 方法 | `POST /api/open/v1/exam/report/realtime` |
|
||||
| 鉴权 | Bearer；应用需 `realtime_enabled=1` |
|
||||
| 对应表 | `train_exam_report`、`train_exam_subject`、`train_student`、`train_enrollment`、`train_open_app_scope`、`train_open_api_log` |
|
||||
|
||||
**入参**：`reports`(object[], 必填, 1–20，字段同 3.3 的 `reports[]`)、`reportTime`(int64, 可选，缺省取平台接收时间)。不带 `batchId`/`periodStart`/`periodEnd`。
|
||||
|
||||
**出参**：`{ total, accepted, duplicated, unmatched, receivedTime }`（无 `batchId`）。
|
||||
|
||||
**业务逻辑**
|
||||
|
||||
1. 请求体 ≤ 1 MB → 否则 `3003`；`reports` 1–20 → 否则 `3003`；同一请求内 `reportId` 重复 → `3001`；
|
||||
2. 逐条字段校验（同 3.3 第 4 步），时间窗改为：`examEndTime ≤ now + 10min` 且 `≥ now - 24h`；`resend=true` 时下限放宽至 90 天 → 违反 `3004`；
|
||||
3. 幂等：`report_id` 唯一键冲突 → `duplicated++`；
|
||||
4. 匹配与入库：`report_channel='REALTIME'`、`batch_pk=NULL`、`batch_id=NULL`；匹配失败同样入待认领池并计入 `unmatched`；
|
||||
5. **即时可见**：匹配成功的记录同步触发归档（见 4.8），使成绩查询与班牌即时可见；归档失败不回滚上报，仅置 `RECEIVED` 由定时任务补归档；
|
||||
6. 返回汇总；记录日志。
|
||||
|
||||
**边界与错误码**：`1001`、`1002`（含未开启实时上报时按 `2001` 返回）、`2001`、`3001`、`3002`、`3003`、`3004`、`3005`、`4000`。
|
||||
|
||||
> 失败兜底由调用方完成：超时（5s）或非 0 → 本地持久化，并入下一周期 3.3（`resend=true`），同一 `reportId` 不会重复入库。
|
||||
|
||||
### 4.6 接口五：上报结果查询
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 名称 | 上报结果查询 |
|
||||
| 路径 / 方法 | `GET /api/open/v1/exam/result` |
|
||||
| 鉴权 | Bearer |
|
||||
| 对应表 | `train_exam_report_batch`、`train_exam_report`、`train_open_api_log` |
|
||||
|
||||
**入参（Query）**
|
||||
|
||||
| 字段 | 类型 | 必填 | 校验 |
|
||||
|---|---|---|---|
|
||||
| `batchId` | string(64) | 条件 | 与 `reportId` 二选一；同时传 → `1002` |
|
||||
| `reportId` | string(64) | 条件 | 与 `batchId` 二选一 |
|
||||
| `periodStart` / `periodEnd` | int64 | 否 | 两者均未传 `batchId`/`reportId` 时必填；跨度 ≤ 31 天 |
|
||||
| `pageNo` / `pageSize` | int | 否 | 默认 1 / 50，`pageSize ≤ 200` |
|
||||
|
||||
**出参 `data`**：`batchId`、`reportTime`、`periodStart`、`periodEnd`、`total`、`accepted`、`duplicated`、`unmatched`、`list[]`
|
||||
|
||||
`list[]`：`reportId`、`subjectName`、`studentId`、`matchStatus`、`scoreStatus`、`score`、`pass`、`retake`、`retakeNo`、`examStartTime`、`examEndTime`、`receivedTime`。
|
||||
|
||||
**业务逻辑**
|
||||
|
||||
1. 参数互斥/必填校验 → `1001`/`1002`；
|
||||
2. 按 `batchId`：查批次头（不存在 → `2002`），分页查明细（`app_id + batch_id`）；
|
||||
3. 按 `reportId`：查单条（不存在或不属于本应用 → `2002`），返回 `total=1`；
|
||||
4. 按时间窗：`received_time ∈ [periodStart, periodEnd)`，分页查明细；汇总按窗口内 `total/accepted/duplicated/unmatched` 统计；
|
||||
5. 固定排序：`exam_end_time ASC, report_id ASC`（规范：平台按考试结束时间排序）；
|
||||
6. 只返回必要字段，不返回 `content`、`idCard`、`station` 等敏感/大字段；
|
||||
7. 记录调用日志。
|
||||
|
||||
**边界与错误码**：`1001`、`1002`、`1006`、`2002`、`3002`、`4000`。
|
||||
|
||||
### 4.7 学员匹配与待认领规则
|
||||
|
||||
| 场景 | 判定 | 结果 |
|
||||
|---|---|---|
|
||||
| `studentId` 存在、在训 | `train_student.s_id` 命中 + `train_enrollment` 在训（A1） | `MATCHED`，写 `matched_enrollment_id/plan_id` |
|
||||
| `studentId` 不存在 | 主档无记录 | `UNMATCHED`（待认领池） |
|
||||
| `studentId` 存在但无在训记录 | 已结业/退训/未入班 | `UNMATCHED` |
|
||||
| 传 `idCard` 且与平台档案不一致 | MD5 比对不一致 | `UNMATCHED`（交叉校验不通过） |
|
||||
| 多班在训 | 取 `join_time` 最新且 `enrollment_status=1` 的一条 | `MATCHED` |
|
||||
| 认领 | 管理员指定学员 + 参训记录 | `UNMATCHED → MATCHED`，记 `claim_by/claim_time`，随后进入归档 |
|
||||
|
||||
> 批量/实时接口对 `UNMATCHED` **不返回逐条错误**，只计入 `unmatched`；单条状态通过 3.5 查询（`matchStatus`）。
|
||||
|
||||
### 4.8 归档与锁定规则
|
||||
|
||||
| 环节 | 规则 |
|
||||
|---|---|
|
||||
| 归档对象 | `match_status=MATCHED AND score_status=RECEIVED` |
|
||||
| 归档映射 | `train_exam_subject.score_item_id` 优先；否则按 `train_score_item.plan_id = matched_plan_id AND item_name = subject_name` 匹配 |
|
||||
| 落库 | UPSERT `train_student_score`：`enrollment_id`、`score_item_id`、`score`、`source_type=4`、`source_system=app_id`、`source_event_id=report_id` |
|
||||
| 状态迁移 | 落库成功 → `ARCHIVED` + `archive_time`；映射缺失 → 保持 `RECEIVED` 并告警，待配置后重跑 |
|
||||
| 锁定 | 培训班结课（`plan_status=2`）或管理员手工锁定 → `LOCKED` + `lock_time`；锁定后同一 `reportId` 内容变更重传 → `2005` |
|
||||
| 幂等 | 归档以 `(enrollment_id, score_item_id)` 唯一键 UPSERT，重复执行不重复计分 |
|
||||
| 执行方式 | 实时上报同步归档；周期批次由定时任务（建议 1 分钟）批量归档 |
|
||||
|
||||
### 4.9 考试内容（content）约定
|
||||
|
||||
| 项目 | 平台侧设计与校验 |
|
||||
|---|---|
|
||||
| 类型 | 必须是 JSON 对象（`{}`），数组/字符串/null → `3005`（解析后用 `JsonNode.isObject()` 判断） |
|
||||
| 大小 | UTF-8 序列化后 ≤ 32 KB → 否则 `3005`；同时记录 `content_size` |
|
||||
| 结构 | 平台不解析业务字段，原样入库（`content` TEXT）；增删字段无需平台改造 |
|
||||
| 敏感信息 | 扫描身份证（18 位）、手机号（11 位）等模式 → `3005`，提示改用 `studentId` 关联 |
|
||||
| 变更 | 结构变更走线下报备；平台按上报时间保留历史内容，`content_md5` 用于识别同 `reportId` 内容差异 |
|
||||
| 展示 | 详情页转义输出，禁止 `innerHTML` 直出，防 XSS |
|
||||
|
||||
### 4.10 接口间依赖关系
|
||||
|
||||
```
|
||||
3.1 登录 ──签发令牌──► 3.2 / 3.3 / 3.4 / 3.5（均需 Bearer）
|
||||
3.2 在训名单 ──提供 studentId──► 3.3 / 3.4（成绩匹配键）
|
||||
3.3 批量上报 ─┐
|
||||
3.4 实时上报 ─┴─写──► train_exam_report ──归档──► train_student_score
|
||||
3.3 / 3.4 ──失败兜底──► 3.3（resend=true，同一 reportId 幂等）
|
||||
3.5 结果查询 ──读──► train_exam_report(_batch)（对账 / 问题定位）
|
||||
科目字典 train_exam_subject ──约束──► 3.3 / 3.4（subjectCode）──映射──► 归档
|
||||
应用授权 train_open_app_scope ──约束──► 3.2（CLASS）/ 3.3、3.4（SUBJECT）
|
||||
```
|
||||
|
||||
### 4.11 表与接口对应关系
|
||||
|
||||
| 数据表 | 3.1 令牌 | 3.2 名单 | 3.3 批量上报 | 3.4 实时上报 | 3.5 结果查询 |
|
||||
|---|---|---|---|---|---|
|
||||
| `train_open_app` | ● 读 | ○ 鉴权 | ○ 鉴权 | ○ 鉴权 | ○ 鉴权 |
|
||||
| `train_open_app_scope` | — | ● 读 | ● 读 | ● 读 | — |
|
||||
| `train_open_token` | ● 写 | ● 读 | ● 读 | ● 读 | ● 读 |
|
||||
| `train_exam_subject` | — | — | ● 读 | ● 读 | ○ 展示 |
|
||||
| `train_exam_report_batch` | — | — | ● 写 | — | ● 读 |
|
||||
| `train_exam_report` | — | — | ● 写 | ● 写 | ● 读 |
|
||||
| `train_open_api_log` | ● 写 | ● 写 | ● 写 | ● 写 | ● 写 |
|
||||
| `train_student` | — | ● 读 | ● 读 | ● 读 | — |
|
||||
| `train_enrollment` | — | ● 读 | ● 读 | ● 读 | — |
|
||||
| `train_class_plan` | — | ● 读 | ○ 归档 | ○ 归档 | — |
|
||||
| `train_score_item` | — | — | ○ 归档 | ○ 归档 | — |
|
||||
| `train_student_score` | — | — | ○ 归档写 | ○ 归档写 | — |
|
||||
|
||||
> ● 直接读写；○ 间接依赖（鉴权、归档、展示）。
|
||||
|
||||
---
|
||||
|
||||
## 5. 通用规范
|
||||
|
||||
### 5.1 分页
|
||||
|
||||
- 入参 `pageNo ≥ 1`（默认 1）、`pageSize ∈ [1,200]`（默认 50）；超范围 → `1002`；
|
||||
- 响应统一 `{ total, pageNo, pageSize, list }`；`total` 为满足过滤条件的总条数；
|
||||
- 深分页（`pageNo` 过大）由索引 + `ORDER BY` 保证稳定；导出类需求不在本期。
|
||||
- **与 RuoYi 分页机制的对接方式**（不使用 `BaseController.startPage()`）：
|
||||
- 框架的 `startPage()` 读取 `pageNum`/`pageSize`/`orderByColumn`/`isAsc` 并交给 PageHelper，而本规范是 `pageNo` 且**不开放自定义排序**，直接复用会读不到页码、并引入 `orderBy` 注入面；
|
||||
- 改为在 Service/Mapper 查询前显式 `PageHelper.startPage(pageNo, pageSize)`（不传 orderBy），查询后用 `new PageInfo<>(list)` 取 `total`，再映射为 `{total, pageNo, pageSize, list}`；
|
||||
- PageHelper 为 ThreadLocal，必须在 `finally` 中 `PageUtils.clearPage()`（或 `PageHelper.clearPage()`），避免线程复用时污染后续查询；
|
||||
- 3.5 按时间窗统计（`total/accepted/duplicated/unmatched`）需单独 `COUNT` 查询，不能依赖分页拦截器生成。
|
||||
|
||||
### 5.2 排序
|
||||
|
||||
| 接口 | 固定排序 |
|
||||
|---|---|
|
||||
| 3.2 学员 | `plan_name ASC, student_id ASC` |
|
||||
| 3.5 结果查询 | `exam_end_time ASC, report_id ASC`（符合规范"按考试结束时间排序"） |
|
||||
|
||||
> 本期不开放自定义排序字段，避免索引失控与注入风险。
|
||||
|
||||
### 5.3 过滤
|
||||
|
||||
- 3.2 仅支持 `classId` 精确过滤；
|
||||
- 3.5 支持 `batchId`、`reportId`、时间窗三类，且互斥/组合规则如 4.6；
|
||||
- 时间窗跨度上限：3.5 为 31 天；3.3 批次窗口由调用方定义（单次考试 ≤ 24h）。
|
||||
|
||||
### 5.4 时间与数值
|
||||
|
||||
- 入参/出参时间统一 `int64` 毫秒（东八区）；业务时间库内 `BIGINT` 毫秒，审计字段用 `DATETIME`（MySQL 5.7 的 `TIMESTAMP` 有 2038 上限且受时区影响）；
|
||||
- 分数 `DECIMAL(7,2)`（Java `BigDecimal`，统一 `setScale(2, RoundingMode.HALF_UP)`）；JSON 中 `86.50` 与 `86.5` 数值等价，尾随 0 不作为契约要求，展示层格式化；
|
||||
- 布尔字段报文用 `true/false`，库内 `SMALLINT 1/0`（MySQL 用 `TINYINT(1)` 会被驱动映射为 Boolean，故统一 `SMALLINT`，避免实体类型不一致）；
|
||||
- 文本列统一 `utf8mb4`；如需支持 4 字节字符（emoji），JDBC 需 `characterEncoding=utf8mb4`（现网配置为 `utf8`）。
|
||||
|
||||
### 5.5 幂等与重试
|
||||
|
||||
| 场景 | 幂等键 | 处理 |
|
||||
|---|---|---|
|
||||
| 单条成绩 | `reportId` | 唯一键 + 冲突按 `duplicated`，保留首次内容 |
|
||||
| 整批 | `(appId, batchId)` | 唯一键；同批重提回放首次汇总；元数据不一致 `2003` |
|
||||
| 令牌 | `appId` | 新令牌覆盖旧令牌，旧令牌立即失效 |
|
||||
| 归档 | `(enrollment_id, score_item_id)` | UPSERT，不重复计分 |
|
||||
|
||||
调用方重试策略：3 次，间隔 1/5/15 分钟；仍失败转本地缓存，恢复后 `resend=true` 补传（90 天）。
|
||||
|
||||
### 5.6 限流
|
||||
|
||||
- 维度：`appId`，默认 20 次/秒（`train_open_app.rate_limit` 可调）；
|
||||
- 实现：Redis 滑动窗口（Lua 原子计数），超限 → `3002`；
|
||||
- **不能直接复用框架 `@RateLimiter`**：其 `getCombineKey()` 只支持 `LimitType.IP`（追加客户端 IP）或全局，无 `appId` 维度；且超限抛 `ServiceException`，经全局异常处理返回 `code=500`，与 `3002` 契约不符。本设计自建 `OpenApiRateLimiter`（Servlet Filter 或 AOP），复用框架已有的 `RedisScript<Long> limitScript` bean，key 为 `open:rate:{appId}`，超限直接写 `OpenApiResponse.error(3002, ...)`；
|
||||
- 登录接口额外独立限流（同 IP 10 次/分钟）防爆破（可用框架 `@RateLimiter(limitType=IP)` 实现，但需单独映射错误码）。
|
||||
|
||||
---
|
||||
|
||||
## 6. 鉴权与权限控制
|
||||
|
||||
| 项 | 设计 |
|
||||
|---|---|
|
||||
| 认证方式 | `appId` + `appSecret` 换取出站令牌，后续请求 `Authorization: Bearer {accessToken}` |
|
||||
| 密钥存储 | 仅存 BCrypt 散列 + 掩码；页面只在新增/重置时展示一次明文 |
|
||||
| 令牌 | 256 位随机不透明串；Redis 存 `appId → sha256(token)`，TTL 7200s；DB 冗余审计 |
|
||||
| 令牌失效 | 同 `appId` 重新登录 → 旧令牌立即失效；管理员停用应用 → 该应用全部令牌失效 |
|
||||
| 校验流程 | 过滤器解析 Bearer → 查 Redis → 比对散列 → 校验应用状态 → 注入 `appId` 到请求上下文 |
|
||||
| 令牌提醒 | 响应头 `X-Token-Remaining`（剩余秒数），剩余 ≤ 600s 时提示重新登录 |
|
||||
| 权限范围 | `train_open_app_scope`：`CLASS` 限制 3.2 可查班级；`SUBJECT` 限制 3.3/3.4 可报科目；越权 `2001` |
|
||||
| 数据隔离 | 所有查询/写入强制带 `app_id` 条件；`reportId` 跨应用不可见（`2002`） |
|
||||
| 免鉴权白名单 | 仅 `POST /api/open/v1/auth/token` |
|
||||
| 停用应用 | `status=0` → `1004`（登录）或 `1006`（存量令牌失效） |
|
||||
| 框架放行方式 | Controller 标注 `@Anonymous`（`PermitAllUrlProperties` 自动收集 → `permitAll`），无需改动 `SecurityConfig`；`JwtAuthenticationTokenFilter` 按 `login_tokens:{token}` 查 Redis，未命中时 `loginUser` 为 null 且不抛异常，请求继续下传，由自有过滤器接管鉴权 |
|
||||
| 过滤器实现 | 参照 `ruoyi-iot` 的 `OpenApiAuthFilter`：`implements Filter` + `@Component`，按路径前缀 `/api/open/` 判定，非本前缀直接放行；校验失败按规范返回 HTTP 200 + `code`（与既有 `OpenApiAuthFilter` 的 401 风格不同，需在文档中显式声明） |
|
||||
| 上下文传递 | 校验通过后将 `appId`、`tokenHash` 写入 `request.setAttribute`，Controller 通过参数或 `RequestContextHolder` 读取；不写入 Spring Security 上下文 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 错误码与异常处理
|
||||
|
||||
### 7.1 错误码（与规范 2.1 一致）
|
||||
|
||||
| code | 含义 | 触发场景 | 返回位置 |
|
||||
|---|---|---|---|
|
||||
| 0 | 成功 | 正常处理（含 `unmatched>0` 的汇总） | 全部 |
|
||||
| 1001 | 缺少必填参数 | 必填字段缺失 | 全部 |
|
||||
| 1002 | 参数格式错误 | 类型/长度/枚举/分页/互斥参数错误 | 全部 |
|
||||
| 1003 | 应用未注册 | `appId` 不存在 | 3.1 |
|
||||
| 1004 | 应用已停用 | `status=0` | 3.1 |
|
||||
| 1005 | 应用密钥错误 | BCrypt 校验失败 | 3.1 |
|
||||
| 1006 | 令牌无效或已过期 | 缺失/不匹配/过期 | 3.2–3.5 |
|
||||
| 2001 | 无权限访问该资源 | 班级/科目不在授权范围；实时上报未开启 | 3.2/3.3/3.4 |
|
||||
| 2002 | 数据不存在 | `batchId`/`reportId` 无记录 | 3.5 |
|
||||
| 2003 | 数据冲突 | 同 `batchId` 元数据不一致 | 3.3 |
|
||||
| 2004 | 学员不存在或不在训 | 单条查询/认领场景提示 | 3.5（单条语义） |
|
||||
| 2005 | 成绩已归档锁定 | 锁定后内容变更重传 | 3.3/3.4 |
|
||||
| 3001 | 上报数据校验失败 | 字段业务规则不满足（含批内 `reportId` 重复） | 3.3/3.4 |
|
||||
| 3002 | 调用频率超限 | 超过 `rate_limit` | 全部 |
|
||||
| 3003 | 消息体超过大小限制 | > 1 MB；批量 > 200；实时 > 20 | 3.3/3.4 |
|
||||
| 3004 | 考试时间超出允许范围 | 时间窗/跨度/先后关系不合法 | 3.3/3.4 |
|
||||
| 3005 | 考试内容 JSON 不合法 | 非对象 / > 32 KB / 含敏感信息 | 3.3/3.4 |
|
||||
| 4000 | 服务端内部错误 | 未预期异常、DB 异常 | 全部 |
|
||||
| 4001 | 下游系统不可达 | 平台依赖服务不可用（预留，本期无下游依赖） | 全部 |
|
||||
|
||||
### 7.2 HTTP 语义
|
||||
|
||||
- 业务错误一律 HTTP 200 + `code`；`reqId` 同时返回并落日志；
|
||||
- 仅网关/容器层限制返回非 200（如 Nginx 413 请求体过大），此时调用方按 `3003` 处理；
|
||||
- 禁止用 HTTP 4xx/5xx 表达业务结果（避免调用方误判重试策略）。
|
||||
|
||||
### 7.3 异常处理
|
||||
|
||||
| 异常类型 | 处理 |
|
||||
|---|---|
|
||||
| JSON 解析失败 / 类型不符 | `1002`，不回显原始报文 |
|
||||
| 参数校验（Bean Validation + 业务校验） | 首个错误返回对应 code，`msg` 指明字段与原因 |
|
||||
| 唯一键冲突 | 3.3/3.4 按 `duplicated` 计入；批次头冲突按首次结果回放 |
|
||||
| 数据库异常/超时 | 事务回滚，返回 `4000`，日志带 `reqId`、`appId`、`bizKey` |
|
||||
| 归档失败 | 不影响上报结果，保留 `RECEIVED`，定时任务重试并告警 |
|
||||
| 幂等重放 | 不重复入库，返回首次汇总（`duplicated` 口径一致） |
|
||||
|
||||
### 7.4 事务边界
|
||||
|
||||
- 3.3：批次头 + 明细同一事务；分块插入（每 100 条）；
|
||||
- 3.4：明细批量插入同一事务；归档在事务外异步/同步独立处理；
|
||||
- 3.1：令牌写入（Redis + DB）先 DB 后 Redis，Redis 失败则整体失败返回 `4000`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 性能与容量
|
||||
|
||||
| 项 | 设计 |
|
||||
|---|---|
|
||||
| 索引 | 见第 3 章；覆盖 `(app_id, received_time)`、`(app_id, batch_id)`、`report_id` 唯一索引、状态扫描索引 |
|
||||
| 大字段 | `content` 不参与列表查询；详情单独查询 |
|
||||
| 批量写入 | 明细 `INSERT` 每 100 条一批；批次汇总最后一次性更新 |
|
||||
| 幂等预查 | 按 `reportId` 分块 `IN` 预查，减少逐条 SELECT |
|
||||
| 缓存 | 应用配置（含限流值、回调开关）Redis 缓存 60s；令牌 O(1) 校验 |
|
||||
| 分页 | 限制 `pageSize ≤ 200`，避免深分页与全表扫描 |
|
||||
| 异步化 | 调用日志、归档、告警异步执行，不阻塞主链路 |
|
||||
| 估算 | 单应用日均 1 万条、峰值 20 次/秒；`train_exam_report` 年增量约 365 万行（含 content），按月分区可控制单表规模 |
|
||||
| 归档任务 | 1 分钟扫描 `MATCHED + RECEIVED`，每次 ≤ 500 条，失败重试 3 次并告警 |
|
||||
| 慢查询 | 开启慢 SQL 日志（> 500ms），对 `3.5` 时间窗查询重点监控 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 安全设计
|
||||
|
||||
| 项 | 措施 |
|
||||
|---|---|
|
||||
| 传输 | 仅 HTTPS；禁用 HTTP 明文入口 |
|
||||
| 密钥 | `appSecret` 仅存 BCrypt 散列；新增/重置仅展示一次；支持轮换；连续失败锁定 |
|
||||
| 令牌 | 不透明随机串（非可预测 JWT 载荷）、2h 过期、单应用单令牌、可即时吊销 |
|
||||
| 越权 | 全链路 `app_id` 过滤；班级/科目授权校验；跨应用 `reportId` 一律 `2002` |
|
||||
| 注入 | MyBatis `#{}` 参数绑定；排序/过滤字段白名单，不拼接用户输入 |
|
||||
| 请求体 | 1 MB 上限（Nginx + 应用）；`content` 32 KB；批量条数上限 |
|
||||
| 敏感数据 | 名单接口手机号掩码、证件号掩码；证件号只存 MD5/Hash 与掩码；日志不记录证件号、手机号、`content` |
|
||||
| `content` 合规 | 强制 JSON 对象；扫描身份证/手机号模式拒绝（3005）；页面展示转义，防 XSS |
|
||||
| 限流与防刷 | 应用级 20 次/秒；登录接口 IP 级 10 次/分钟 |
|
||||
| 重放 | `reportId`/`batchId` 幂等键天然防重放；令牌有效期短 |
|
||||
| 审计 | `train_open_api_log` 记录 `reqId`、`appId`、路径、业务键、返回码、耗时、IP；保留 90 天 |
|
||||
| 权限分离 | 平台后台"应用授权"仅管理员可见；密钥重置留操作日志 |
|
||||
|
||||
---
|
||||
|
||||
## 10. 评审确认清单
|
||||
|
||||
| # | 待确认项 | 影响 |
|
||||
|---|---|---|
|
||||
| 1 | "在训"是否包含待报到（`enrollment_status=0`） | 3.2 名单范围 |
|
||||
| 2 | `studentNo` 的权威字段（`card_no` 还是 `s_id`） | 3.2 输出 |
|
||||
| 3 | `idCard` 是否允许返回明文（当前默认掩码） | 3.2 输出与合规 |
|
||||
| 4 | 科目字典由平台后台维护还是沿用 `sys_dict_data` | 表结构与页面 |
|
||||
| 5 | 归档映射规则（科目 → 考核项）与未映射时的处理 | 归档覆盖率 |
|
||||
| 6 | 成绩锁定触发点（结课自动锁定 or 人工） | 状态机与 2005 |
|
||||
| 7 | 是否需要 IP 白名单（规范未要求） | 安全加固项 |
|
||||
| 8 | `train_exam_report` 是否按月分区/冷热分离 | 容量与运维 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 兼容性审查与修改建议（RuoYi-Vue 3.9.2 + MySQL 5.7）
|
||||
|
||||
> 审查基准：本仓库实际代码与配置（Spring Boot 4.1.0 / Java 17 / MyBatis / Druid / Redis / PageHelper；数据库按 MySQL 5.7），以及规范《外部实训系统数据接口规范》。
|
||||
> 结论：**接口契约（路径、字段、错误码）无需变更**；但返回结构、分页、鉴权放行、异常映射 4 处必须按框架实际能力调整，数据层有 6 处需按 MySQL 5.7 修正（已在第 2/3/4/5/6 章同步修订）。
|
||||
|
||||
### 11.1 框架兼容性问题（R1–R10）
|
||||
|
||||
| 编号 | 问题 | 证据（仓库实际） | 影响 | 修改建议 | 优先级 | 文档落点 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| R1 | 直接复用 `AjaxResult` 会返回 `code=200` 而非 `0`，且缺少 `reqId`/`ts` | `AjaxResult` 成功码取 `HttpStatus.SUCCESS`（=200），`isSuccess()` 按 200 判定 | 调用方按 `code!=0` 判失败，所有成功请求被误判 | 新增 `OpenApiResponse<T>{code,msg,data,reqId,ts}`，`code=0` 表成功；不复用 `AjaxResult` | P0 | 4.1（已修订） |
|
||||
| R2 | 复用 `TableDataInfo`/`getDataTable()` 会输出 `rows` 而非 `list`，且无 `pageNo/pageSize` | `TableDataInfo` 字段为 `total/rows/code/msg` | 3.2、3.5 响应结构不符合规范 | 自定义 `OpenApiPage{total,pageNo,pageSize,list}`，由 `PageInfo` 映射 | P0 | 3.x/4.3/4.6/5.1（已修订） |
|
||||
| R3 | `BaseController.startPage()` 读 `pageNum`/`orderByColumn`/`isAsc`，与规范 `pageNo` 且固定排序冲突 | `PageUtils`/`TableSupport` 按 `pageNum` 解析，`orderBy` 由请求参数控制 | 页码取不到（永远第 1 页）；排序参数形成注入面 | 显式 `PageHelper.startPage(pageNo, pageSize)`（不传 orderBy）+ `new PageInfo<>(list)`；`finally` 中 `PageUtils.clearPage()` | P0 | 5.1（已修订） |
|
||||
| R4 | 全局异常处理器把校验错误映射为 `code=500`，且无 `reqId`；不含 `HttpMessageNotReadableException` 处理 | `GlobalExceptionHandler`：`ServiceException`/`BindException`/`MethodArgumentNotValidException` 均返回 `AjaxResult.error(...)` | 参数错误返回 500，调用方按"服务端错误"重试 | 新增 openapi 专用 `@RestControllerAdvice(basePackages="...open")` + `@Order`：`MethodArgumentNotValid/Bind/HttpMessageNotReadable/TypeMismatch` → 1001/1002，`MaxUploadSizeExceeded` → 3003，`DuplicateKeyException` → 按幂等处理，其它 → 4000 | P0 | 4.1/7.3（已修订） |
|
||||
| R5 | `/api/open/v1/**` 未放行时会被 Spring Security 拦截并返回框架 401 结构 | `SecurityConfig` 逐个 matcher 放行（`/api/iot/v1/**`、`/api/lock/v1/**` 等） | 未放行 → 直接 401，且响应体不是规范结构 | Controller 标注 `@Anonymous`（`PermitAllUrlProperties` 自动收集），或显式追加 matcher；**禁止**改造 `JwtAuthenticationTokenFilter` | P0 | 6（已修订） |
|
||||
| R6 | 限流注解不支持 `appId` 维度，且超限码不符合规范 | `RateLimiterAspect.getCombineKey()` 仅 `LimitType.IP`/全局；超限抛 `ServiceException` | 多实例共用 appId 时按 IP 计数不准确；返回 code=500 | 自建 `OpenApiRateLimiter`（Filter/AOP），复用 `RedisScript<Long> limitScript`，key `open:rate:{appId}`，超限返回 3002 | P1 | 5.6（已修订） |
|
||||
| R7 | XSS 过滤器会改写 JSON 请求体，破坏 `content` 原样存储与 `content_md5` | `XssFilter` 对 POST/PUT 包装 `XssHttpServletRequestWrapper`，逐字符串转义 | `content` 入库内容与外部系统原文不一致，幂等内容比对失效 | `application.yml` 的 `xss.excludes` 增加 `/api/open/**` | P0 | 4.1（已修订） |
|
||||
| R8 | 无登录上下文，`SecurityUtils.getUsername()`/`@Log` 不可用 | `@Log` 依赖登录用户写 `sys_oper_log`；`SecurityUtils` 无认证时抛异常 | 审计字段写入失败或抛异常 | 操作人固定 `openapi`；审计落 `train_open_api_log`（异步），不使用 `@Log` | P1 | 4.1/3.7（已修订） |
|
||||
| R9 | 实体与后台管理页需遵循框架约定 | 现有实体继承 `BaseEntity`（`createBy/createTime/updateBy/updateTime/remark/params`）；列表页用 `@PreAuthorize("@ss.hasPermi(...)")` + `@Excel` | 与既有后台风格不一致，导出/权限缺失 | 实体继承 `BaseEntity`；后台菜单权限键 `train:openApp:*`、`train:examSubject:*`、`train:examReport:*`；字段加 `@Excel`；枚举用 `sys_dict_data` 供 `dict-tag` 渲染 | P1 | 3.x、10（待补充评审） |
|
||||
| R10 | Redis 访问方式不统一 | 框架提供 `RedisCache`（序列化、TTL 封装）；登录令牌键前缀 `login_tokens:` | 直接使用 `RedisTemplate` 易出现序列化/键冲突 | 令牌、限流、应用缓存统一走 `RedisCache`，键前缀 `open:` | P1 | 6（已修订） |
|
||||
|
||||
### 11.2 MySQL 5.7 兼容性问题（D1–D10）
|
||||
|
||||
| 编号 | 问题 | MySQL 5.7 事实 | 影响 | 修改建议 | 优先级 | 文档落点 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| D1 | `CHECK` 约束不生效 | 5.7 解析但忽略 `CHECK` | 时间/分数/枚举非法值可直接写入 | 应用层（DTO 校验 + Service 兜底）实现全部检查；DDL 保留仅作其他方言兼容 | P0 | 2.3/3.6（已修订） |
|
||||
| D2 | `content` 使用 `JSON` 会破坏"原样存储" | `JSON` 列会规范化键序、空白并强制合法性 | 与外部原文不一致，`content_md5` 比对失真 | 统一 `TEXT NOT NULL`（32 KB < 65,535 字节），应用层 `JsonNode.isObject()` 校验 | P0 | 3.6/3.9（已修订） |
|
||||
| D3 | `TIMESTAMP` 2038 上限与时区隐式转换 | `TIMESTAMP` 范围 1970–2038，受 `time_zone` 影响 | 审计/过期时间长期不可用，跨时区显示偏差 | 审计字段 `DATETIME DEFAULT CURRENT_TIMESTAMP`；业务时间用 `BIGINT` 毫秒 | P1 | 3.x/5.4（已修订） |
|
||||
| D4 | `ADD COLUMN IF NOT EXISTS`、`CREATE INDEX IF NOT EXISTS` 不支持 | 5.7 无该语法 | 迁移脚本重复执行报错 | `information_schema` 判断 + `PREPARE/EXECUTE`（参照 `sql/train/v2/022b_*.sql`） | P1 | 3.9（已修订） |
|
||||
| D5 | 无窗口函数、无 CTE | 5.7 不支持 `ROW_NUMBER()`、`WITH` | "取最新在训记录"等实现方式不可用 | `ORDER BY join_time DESC LIMIT 1`；统计用子查询/两次聚合 | P1 | 4.7/3.9（已修订） |
|
||||
| D6 | 分区与唯一键冲突 | 5.7 要求唯一键包含分区列 | 按 `received_time` 分区将无法保留 `report_id` 全局唯一 | **本期不分区**；热表 12 个月 + 归档表 `train_exam_report_his` | P1 | 3.6（已修订） |
|
||||
| D7 | 字符集/排序规则需与既有表一致 | 既有表 `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`；连接串 `characterEncoding=utf8` | JOIN 隐式转换导致索引失效；emoji 写入失败 | 新表显式 `CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci`；跨表 `student_id/plan_id` 同字符集；需要 4 字节时调整连接串 | P1 | 3.9/5.4（已修订） |
|
||||
| D8 | `TINYINT(1)` 被 JDBC 映射为 Boolean | `tinyInt1isBit` 默认 true | `pass`/`retake`/`status` 实体类型随驱动变化 | 统一 `SMALLINT` + Java `Integer`，不使用 `TINYINT(1)` | P2 | 3.5/3.6/5.4（已修订） |
|
||||
| D9 | 索引长度与哈希列膨胀 | utf8mb4 单字符 4 字节；`CHAR(32)` 哈希列占 128 字节 | 空间浪费、唯一索引偏大 | 哈希列 `CHAR(32) CHARACTER SET ascii`；`VARCHAR` 长度按业务收紧（已 ≤100） | P2 | 3.6/3.9（已修订） |
|
||||
| D10 | `JSON` 函数/类型别名与 `NUMERIC` 写法 | `NUMERIC` 为 `DECIMAL` 同义词；`JSON_TABLE` 不存在 | DDL 风格不统一 | DDL 统一 `DECIMAL`；不使用 `JSON_TABLE` | P2 | 3.9（已修订） |
|
||||
|
||||
### 11.3 参数校验、异常与安全性完整性（V1–V8）
|
||||
|
||||
| 编号 | 问题 | 影响 | 修改建议 | 优先级 |
|
||||
|---|---|---|---|---|
|
||||
| V1 | 3.3/3.4 未定义"校验失败是否部分入库"的明确边界（文档仅写整批校验整批写入） | 歧义：实现可能边校验边插入 | 明确：**格式/业务校验失败 → 整批回滚（3001/3004/3005）**；`duplicated`/`unmatched` 属正常计数，不算失败 | P0 |
|
||||
| V2 | 未约定请求体超限在网关被拦截时的响应形态 | 调用方收到 413 HTML，无法解析 | 网关 `client_max_body_size 2m` + 应用层 `Content-Length` 预检返回 3003；文档注明 413 按 3003 处理 | P1 |
|
||||
| V3 | `idCard` 明文传输与落库风险 | 违反"平台不存明文"的最小化原则 | 只用于交叉校验：入参即算 `MD5`，仅存 `id_card_md5` + 掩码；日志与 `content` 中禁止出现 | P1 |
|
||||
| V4 | 缺少请求链路标识的统一规范 | 排障困难 | `reqId` 由过滤器生成（`RQ-yyyyMMdd-8位`），响应体、响应头 `X-Request-Id`、`train_open_api_log` 三处一致；下游调用透传 | P1 |
|
||||
| V5 | 令牌校验对"已停用应用/已轮换密钥"的存量令牌失效时机未定义 | 停用后仍可调用 2 小时内有效 | 过滤器每次校验都读应用状态（Redis 缓存 60s）；停用/重置密钥时主动删除 `open:token:{appId}` | P1 |
|
||||
| V6 | 3.5 未限制 `reportId` 跨应用访问的响应差异 | 可能探测他人 `reportId` 是否存在 | 统一返回 2002（不区分"不存在"与"不属于本应用"），并记录审计日志 | P1 |
|
||||
| V7 | 未定义重复 `batchId` 但 `reports` 内容不同的判定口径 | 可能重复入库或静默丢弃 | 明确：仅比对批次元数据（`reportTime/periodStart/periodEnd/resend/reports.length`）；一致→回放首次汇总，不一致→2003；明细差异由 `reportId` 幂等兜底 | P0 |
|
||||
| V8 | 归档与锁定缺少并发保护说明 | 定时任务与实时归档并发重复落分 | 归档使用 `data_version` 乐观锁 + `train_student_score` 唯一键 UPSERT；锁定时校验 `score_status!=LOCKED` | P1 |
|
||||
|
||||
### 11.4 本仓库证据索引（便于评审核对）
|
||||
|
||||
| 主题 | 文件 |
|
||||
|---|---|
|
||||
| 成功码/响应结构 | `ruoyi-common/src/main/java/com/ruoyi/common/core/domain/AjaxResult.java`、`.../core/page/TableDataInfo.java` |
|
||||
| 分页 | `ruoyi-common/src/main/java/com/ruoyi/common/core/controller/BaseController.java`、`.../utils/PageUtils.java` |
|
||||
| 全局异常 | `ruoyi-framework/src/main/java/com/ruoyi/framework/web/exception/GlobalExceptionHandler.java` |
|
||||
| 安全放行 | `ruoyi-framework/src/main/java/com/ruoyi/framework/config/SecurityConfig.java`（100–118 行）、`.../config/properties/PermitAllUrlProperties.java` |
|
||||
| 限流 | `ruoyi-framework/src/main/java/com/ruoyi/framework/aspectj/RateLimiterAspect.java`（76–88 行） |
|
||||
| 开放接口鉴权先例 | `ruoyi-iot/src/main/java/com/ruoyi/iot/openapi/filter/OpenApiAuthFilter.java` |
|
||||
| XSS | `ruoyi-common/src/main/java/com/ruoyi/common/filter/XssFilter.java` 及 `application.yml` 的 `xss.excludes` |
|
||||
| 数据源/字符集 | `ruoyi-admin/src/main/resources/application-druid.yml`（`characterEncoding=utf8`） |
|
||||
| MySQL DDL 风格 | `sql/train/v2/019_signage.sql`（`ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`）、`sql/train/v2/022b_add_accommodation_lock_result_mysql.sql`（幂等 DDL） |
|
||||
|
||||
### 11.5 修订实施顺序（建议）
|
||||
|
||||
| 阶段 | 内容 | 关联项 |
|
||||
|---|---|---|
|
||||
| 第一步（P0，编码前必须定稿） | 响应模型、分页映射、异常映射、鉴权放行、XSS 排除、CHECK 兜底、`content` 改 `TEXT` | R1–R5、R7、D1、D2、V1、V7 |
|
||||
| 第二步（P1） | 限流自建、审计与操作人、归档/锁定并发、令牌失效策略、时间类型、迁移脚本、字符集 | R6、R8、R10、D3–D7、V2–V6、V8 |
|
||||
| 第三步（P2） | 哈希列 ascii、`SMALLINT` 统一、后台菜单与字典、导出注解 | R9、D8–D10 |
|
||||
|
||||
---
|
||||
|
||||
## 附录 A：接口清单
|
||||
|
||||
| 序号 | 接口名称 | 方法 | 路径 | 鉴权 | 主要表 |
|
||||
|---|---|---|---|---|---|
|
||||
| 3.1 | 登录获取访问令牌 | POST | `/api/open/v1/auth/token` | 无 | `train_open_app`、`train_open_token` |
|
||||
| 3.2 | 在训学员查询 | GET | `/api/open/v1/student/list` | Bearer | `train_student`、`train_enrollment`、`train_class_plan` |
|
||||
| 3.3 | 考试成绩批量上报 | POST | `/api/open/v1/exam/report` | Bearer | `train_exam_report_batch`、`train_exam_report` |
|
||||
| 3.4 | 实时成绩上报 | POST | `/api/open/v1/exam/report/realtime` | Bearer | `train_exam_report` |
|
||||
| 3.5 | 上报结果查询 | GET | `/api/open/v1/exam/result` | Bearer | `train_exam_report_batch`、`train_exam_report` |
|
||||
|
||||
## 附录 B：数据字典
|
||||
|
||||
| 字段 | 取值 |
|
||||
|---|---|
|
||||
| `appType` | `VR` / `INSPECT3D` / `PRACTICE` / `CAPSTONE` / `OTHER` |
|
||||
| `gender` | `MALE` / `FEMALE` |
|
||||
| `matchStatus` | `MATCHED` / `UNMATCHED` |
|
||||
| `scoreStatus` | `RECEIVED` / `ARCHIVED` / `LOCKED` |
|
||||
| `bizType` | `PRACTICE` |
|
||||
| `reportChannel` | `REALTIME` / `PERIODIC` |
|
||||
| `retake` / `resend` | `true` / `false`（库内 1/0） |
|
||||
| `scopeType` | `CLASS` / `SUBJECT` |
|
||||
@@ -0,0 +1,687 @@
|
||||
# 报到机接口 API 文档
|
||||
|
||||
| 项目 | 内容 |
|
||||
|---|---|
|
||||
| 控制器 | `com.ruoyi.web.controller.api.TrainRegisterApiController` |
|
||||
| 源文件 | `ruoyi-admin/src/main/java/com/ruoyi/web/controller/api/TrainRegisterApiController.java` |
|
||||
| BasePath | `/api/register/v1` |
|
||||
| 接口数量 | 12（8 个 GET + 4 个 POST） |
|
||||
| 鉴权 | Spring Security 已放行 `/api/register/v1/**`（`permitAll`）；仅 `/report/reset` 内部取登录用户，需携带 RuoYi Bearer Token |
|
||||
| 统一响应 | `AjaxResult`（`code` / `msg` / `data`） |
|
||||
| 日期格式 | `yyyy-MM-dd HH:mm:ss`（`spring.jackson.date-format`，时区 GMT+8） |
|
||||
| 文档更新 | 2026-11-09（新增宿舍布局接口） |
|
||||
| 编写依据 | 控制器源码逐行核对，与当前实现一致 |
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
- [1. 通用约定](#1-通用约定)
|
||||
- [1.1 鉴权说明](#11-鉴权说明)
|
||||
- [1.2 统一响应结构](#12-统一响应结构)
|
||||
- [1.3 状态码与错误提示](#13-状态码与错误提示)
|
||||
- [1.4 公共数据结构](#14-公共数据结构)
|
||||
- [2. 接口总览](#2-接口总览)
|
||||
- [3. 学员信息](#3-学员信息)
|
||||
- [3.1 获取学员信息列表](#31-获取学员信息列表)
|
||||
- [3.2 获取学员详情](#32-获取学员详情)
|
||||
- [3.3 获取学员基础信息](#33-获取学员基础信息)
|
||||
- [3.4 获取学员关联资源](#34-获取学员关联资源)
|
||||
- [4. 教师信息](#4-教师信息)
|
||||
- [4.1 获取教师信息列表](#41-获取教师信息列表)
|
||||
- [4.2 获取教师基础信息](#42-获取教师基础信息)
|
||||
- [5. 班级名单](#5-班级名单)
|
||||
- [5.1 获取进行中班级的学员名单](#51-获取进行中班级的学员名单)
|
||||
- [6. 人脸照片上传](#6-人脸照片上传)
|
||||
- [6.1 上传学员人脸照片](#61-上传学员人脸照片)
|
||||
- [6.2 上传教师人脸照片](#62-上传教师人脸照片)
|
||||
- [6.3 上传人脸照片（统一入口）](#63-上传人脸照片统一入口)
|
||||
- [7. 报到业务](#7-报到业务)
|
||||
- [7.1 报到重置](#71-报到重置)
|
||||
- [8. 宿舍布局](#8-宿舍布局)
|
||||
- [8.1 获取宿舍布局信息](#81-获取宿舍布局信息)
|
||||
- [9. 附录](#9-附录)
|
||||
- [9.1 典型调用流程](#91-典型调用流程)
|
||||
- [9.2 调用示例](#92-调用示例)
|
||||
|
||||
---
|
||||
|
||||
## 1. 通用约定
|
||||
|
||||
### 1.1 鉴权说明
|
||||
|
||||
- 源代码类注释声明“其余接口复用 RuoYi Bearer 鉴权”，但当前 `SecurityConfig` 中已配置：
|
||||
|
||||
```110:110:ruoyi-framework/src/main/java/com/ruoyi/framework/config/SecurityConfig.java
|
||||
.requestMatchers("/api/register/v1/**").permitAll();
|
||||
```
|
||||
|
||||
即 **整个 `/api/register/v1/**` 路径实际为匿名可访问**，查询类与人脸上传接口不强制 Token。
|
||||
|
||||
- 例外：`POST /report/reset` 内部通过 `SecurityUtils.getUsername()` 写入操作人，无登录态时该方法会抛 `ServiceException("获取用户账户异常", 401)`。因此该接口**必须携带** `Authorization: Bearer {token}`。
|
||||
- 控制器注释提到的 `X-Signature` / `X-Nonce`（HMAC）验签目前**未在本控制器内实现**，`DeviceHmacFilter` 仅对 `/api/iot/v1/device/login` 生效。
|
||||
|
||||
### 1.2 统一响应结构
|
||||
|
||||
所有接口返回 `AjaxResult`：
|
||||
|
||||
```json
|
||||
{ "code": 200, "msg": "操作成功", "data": {} }
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `code` | number | 业务状态码，见 1.3 |
|
||||
| `msg` | string | 提示信息；成功时通常为 `操作成功` |
|
||||
| `data` | object / array | 业务数据，无数据时该字段不出现 |
|
||||
|
||||
### 1.3 状态码与错误提示
|
||||
|
||||
| code | 含义 | 触发来源 |
|
||||
|---|---|---|
|
||||
| 200 | 成功 | 正常返回 |
|
||||
| 401 | 未认证 / 无登录上下文 | `SecurityUtils` 抛出的 `ServiceException` |
|
||||
| 500 | 参数缺失、图片解析失败、目标记录不存在等业务失败 | 控制器内 `AjaxResult.error(...)` |
|
||||
|
||||
> 除框架级 401/404 外，业务失败统一为 `code=500`，调用方需读取 `msg` 区分原因。
|
||||
|
||||
### 1.4 公共数据结构
|
||||
|
||||
#### StudentItemVO（学员列表项，`/student/list`）
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `sId` | string | 学员ID（业务主键） |
|
||||
| `sName` | string | 学员姓名 |
|
||||
| `personNo` | string | 人员编号 |
|
||||
| `sGender` | string | 性别 |
|
||||
| `sBirth` | string | 出生日期，`yyyy-MM-dd` |
|
||||
| `deptName` | string | 所属部门名称 |
|
||||
| `cardNo` | string | 卡号 |
|
||||
| `sPhone` | string | 手机号 |
|
||||
| `sEmail` | string | 邮箱 |
|
||||
| `idCardMasked` | string | 证件号掩码 |
|
||||
| `idCardLast4` | string | 证件号后 4 位 |
|
||||
| `sourceType` | number | 数据来源类型 |
|
||||
| `status` | number | 状态 |
|
||||
| `avatar` | string | 头像访问路径（如 `/profile/upload/...png`） |
|
||||
| `dutyLevel` | number | 职务级别 |
|
||||
| `extractStatus` / `extractTime` / `extractMsg` | string / string / string | 人脸特征提取状态、时间、描述 |
|
||||
| `photoMd5` | string | 人脸照片 MD5 |
|
||||
| `featureData` / `featureMd5` / `featureAlgoVersion` / `featureSize` | string / string / string / number | 人脸特征数据及元信息 |
|
||||
| `id` | number | 主键 |
|
||||
| `deptId` | number | 部门ID |
|
||||
| `enrollmentStatus` | number | 报到状态：0 待报到、1 已报到、2 请假、3 放弃、4 已完成 |
|
||||
| `joinTime` | string | 报到/入学时间 |
|
||||
|
||||
#### 门锁入住结果 lockCheckin（`LockStayCheckinResult`）
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `success` | boolean | 是否成功 |
|
||||
| `status` | string | 处理状态 |
|
||||
| `bizNo` | string | 门锁业务流水号 |
|
||||
| `httpStatus` | number | 下游 HTTP 状态 |
|
||||
| `code` | string | 下游业务码 |
|
||||
| `message` | string | 下游提示信息 |
|
||||
| `rawBody` | string | 下游原始响应体 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 接口总览
|
||||
|
||||
| 序号 | 分组 | 方法 | 路径 | 功能说明 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | 学员信息 | GET | `/api/register/v1/student/list` | 获取全部学员列表（含报到状态） |
|
||||
| 2 | 学员信息 | GET | `/api/register/v1/student/{sId}` | 获取单个学员详情（含账号绑定信息） |
|
||||
| 3 | 学员信息 | GET | `/api/register/v1/student/{sId}/base` | 获取学员基础信息（个人信息/开班/宿舍/教室/实训场地） |
|
||||
| 4 | 学员信息 | GET | `/api/register/v1/student/{sId}/resources` | 获取学员关联资源（基础信息 + 课程 + 课表） |
|
||||
| 5 | 教师信息 | GET | `/api/register/v1/teacher/list` | 获取全部教师列表（结构同学员列表） |
|
||||
| 6 | 教师信息 | GET | `/api/register/v1/teacher/{tId}/base` | 获取教师基础信息（个人信息/宿舍/授课课表） |
|
||||
| 7 | 班级名单 | GET | `/api/register/v1/class/student` | 获取进行中班级及其未报到学员名单 |
|
||||
| 8 | 人脸照片 | POST | `/api/register/v1/student/face` | 上传学员人脸照片并同步人脸设备、办理报到 |
|
||||
| 9 | 人脸照片 | POST | `/api/register/v1/teacher/face` | 上传教师人脸照片并同步人脸设备 |
|
||||
| 10 | 人脸照片 | POST | `/api/register/v1/face` | 按 `employeeId` 后缀统一分发到学员/教师上传 |
|
||||
| 11 | 报到业务 | POST | `/api/register/v1/report/reset` | 报到重置（解绑人脸、清门锁授权、状态回退） |
|
||||
| 12 | 宿舍布局 | GET | `/api/register/v1/dormitory/layout` | 按楼栋/楼层/房间返回宿舍布局及已分配床位数 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 学员信息
|
||||
|
||||
### 3.1 获取学员信息列表
|
||||
|
||||
- **接口路径**：`/api/register/v1/student/list`
|
||||
- **请求方法**：`GET`
|
||||
- **功能说明**：读取学员主档列表（`train_student`），并按 `sId` 反查 `train_enrollment` 报名记录，用第一条记录的报到状态与报到时间补齐 `enrollmentStatus`、`joinTime`。
|
||||
|
||||
**请求参数**：无（无分页、无过滤条件，返回全量）
|
||||
|
||||
**返回结果说明**：
|
||||
|
||||
- `data`：`StudentItemVO` 数组，字段见 [1.4](#14-公共数据结构)。
|
||||
- 学员无报名记录时，`enrollmentStatus` 与 `joinTime` 为 `null`。
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": [
|
||||
{
|
||||
"sId": "S0001",
|
||||
"sName": "张三",
|
||||
"personNo": "P1001",
|
||||
"sGender": "1",
|
||||
"sBirth": "2000-01-01",
|
||||
"deptName": "供电段",
|
||||
"sPhone": "13800000000",
|
||||
"status": 1,
|
||||
"avatar": "/profile/upload/2026/11/05/xxxx.png",
|
||||
"enrollmentStatus": 1,
|
||||
"joinTime": "2026-11-05 09:12:33"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.2 获取学员详情
|
||||
|
||||
- **接口路径**：`/api/register/v1/student/{sId}`
|
||||
- **请求方法**：`GET`
|
||||
- **功能说明**：按学员ID查询详情，并在基础字段上补充账号绑定信息（`userId`、`userName`、`nickName`、`accountBindingStatus`）。
|
||||
|
||||
**请求参数**
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `sId` | path | string | 是 | 学员ID，如 `S0001` |
|
||||
|
||||
**返回结果说明**：
|
||||
|
||||
- `data` 为 `StudentAdminVO`，继承 `StudentDetailVO` ← `StudentItemVO`。
|
||||
- 在 [1.4 StudentItemVO](#14-公共数据结构) 字段基础上，追加：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `faceRef` | string | 人脸引用 |
|
||||
| `remark` | string | 备注 |
|
||||
| `createBy` / `createTime` | string / string | 创建人 / 创建时间 |
|
||||
| `userId` | number | 绑定的系统用户ID |
|
||||
| `userName` | string | 登录账号 |
|
||||
| `nickName` | string | 用户昵称 |
|
||||
| `accountBindingStatus` | number | 账号绑定状态：1 已绑定，0 未绑定 |
|
||||
|
||||
- 学员不存在时返回 `{"code":200,"msg":"操作成功","data":null}`。
|
||||
|
||||
---
|
||||
|
||||
### 3.3 获取学员基础信息
|
||||
|
||||
- **接口路径**：`/api/register/v1/student/{sId}/base`
|
||||
- **请求方法**：`GET`
|
||||
- **功能说明**：按 `sId` 聚合该学员的个人信息、所属开班计划、宿舍、教室、实训场地，供报到机首屏展示。开班 planId 取值优先取最新报到记录，缺失时从报名关系兜底。
|
||||
|
||||
**请求参数**
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `sId` | path | string | 是 | 学员ID |
|
||||
|
||||
**返回结果说明**：`data` 为对象（字段可能为 `null`）：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `studInfo` | object | 学员基础信息：`sId`、`sName`、`sPhone`、`sGender`、`deptName`、`personNo` |
|
||||
| `classPlan` | object | 开班信息：`planId`、`planName`、`startTime`、`endTime` |
|
||||
| `dormitory` | object | 宿舍信息：`dormId`、`bedNo`、`dormBuilding`、`dormRoom` |
|
||||
| `classroom` | object | 教室信息（取自本计划首个带教室的课次）：`classRoomId`、`roomLocation`、`roomName` |
|
||||
| `trainingSite` | object | 实训场地信息（取自本计划首个带场地的课次）：`siteId`、`siteLocation`、`siteName`、`major` |
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {
|
||||
"studInfo": { "sId": "S0001", "sName": "张三", "sPhone": "13800000000", "sGender": "1", "deptName": "供电段", "personNo": "P1001" },
|
||||
"classPlan": { "planId": "P2026001", "planName": "2026年第一期", "startTime": "2026-11-01 08:00:00", "endTime": "2026-11-30 18:00:00" },
|
||||
"dormitory": { "dormId": "D01", "bedNo": "3", "dormBuilding": "1号楼", "dormRoom": "101" },
|
||||
"classroom": { "classRoomId": "R01", "roomLocation": "教学楼2层", "roomName": "201" },
|
||||
"trainingSite": { "siteId": "T01", "siteLocation": "实训楼1层", "siteName": "接触网实训场", "major": "接触网" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 注意：本接口**不返回** `courses` 与 `lesson`（源码中已注释），需要课表请使用 3.4。
|
||||
|
||||
---
|
||||
|
||||
### 3.4 获取学员关联资源
|
||||
|
||||
- **接口路径**：`/api/register/v1/student/{sId}/resources`
|
||||
- **请求方法**：`GET`
|
||||
- **功能说明**：在 3.3 的基础上额外返回本计划课程列表与课次（含课程名），供报到机展示课表。
|
||||
|
||||
**请求参数**
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `sId` | path | string | 是 | 学员ID |
|
||||
|
||||
**返回结果说明**：`data` 在 3.3 全部字段之外，追加：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `courses` | array | 本计划课程：`cId`（计划课程主键）、`cName`（课程名称） |
|
||||
| `lesson` | array | 课次列表：`startTime`、`endTime`、`planCourseId`、`cName` |
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {
|
||||
"studInfo": { "sId": "S0001", "sName": "张三" },
|
||||
"classPlan": { "planId": "P2026001", "planName": "2026年第一期" },
|
||||
"courses": [ { "cId": 1001, "cName": "接触网巡视" } ],
|
||||
"lesson": [ { "startTime": "2026-11-06 08:00:00", "endTime": "2026-11-06 10:00:00", "planCourseId": 1001, "cName": "接触网巡视" } ],
|
||||
"dormitory": { "dormId": "D01", "bedNo": "3" },
|
||||
"classroom": { "classRoomId": "R01", "roomName": "201" },
|
||||
"trainingSite": { "siteId": "T01", "siteName": "接触网实训场" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 教师信息
|
||||
|
||||
### 4.1 获取教师信息列表
|
||||
|
||||
- **接口路径**：`/api/register/v1/teacher/list`
|
||||
- **请求方法**：`GET`
|
||||
- **功能说明**：读取教师主档（`train_teacher`），按**与学员列表完全一致的结构**返回，便于报到机统一处理。转换规则：
|
||||
- `sId` = `tId + "_teacher"`（与人脸库教师 `employee_id` 口径一致）
|
||||
- `sName` = `tName`，其余字段一一映射
|
||||
- 教师无报名记录，`enrollmentStatus`、`joinTime` 恒为 `null`
|
||||
|
||||
**请求参数**：无
|
||||
|
||||
**返回结果说明**：`data` 为 `StudentItemVO` 数组，实际填充字段：`sId`、`sName`、`personNo`、`sGender`、`sBirth`、`deptName`、`cardNo`、`sPhone`、`sEmail`、`status`、`avatar`、`id`。
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": [
|
||||
{
|
||||
"sId": "T0001_teacher",
|
||||
"sName": "李老师",
|
||||
"personNo": "P2001",
|
||||
"sGender": "1",
|
||||
"sPhone": "13900000000",
|
||||
"deptName": "供电段",
|
||||
"status": 1,
|
||||
"avatar": null,
|
||||
"enrollmentStatus": null,
|
||||
"joinTime": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.2 获取教师基础信息
|
||||
|
||||
- **接口路径**：`/api/register/v1/teacher/{tId}/base`
|
||||
- **请求方法**：`GET`
|
||||
- **功能说明**：按教师工号聚合个人信息、宿舍信息与授课课表。兼容传入 `tId + "_teacher"` 口径：路径参数以 `_teacher` 结尾时会自动去除后缀再查询。
|
||||
|
||||
**请求参数**
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `tId` | path | string | 是 | 教师工号；可传 `T0001` 或 `T0001_teacher` |
|
||||
|
||||
**返回结果说明**：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `teacherInfo` | object | 教师信息：`tId`、`tName`、`tPhone`、`tGender`、`deptName`、`personNo`、`avatar`；教师不存在时为 `null` |
|
||||
| `dormitory` | object | `dormId`、`bedNo`、`dormBuilding`、`dormRoom`（无有效住宿时 `dormId` 为 `null`） |
|
||||
| `lesson` | array | 授课课次（按开始时间升序，不传日期范围即全部）；字段：`lessonId`、`planCourseId`、`courseName`、`tId`、`teacherName`、`startTime`、`endTime`、`venueType`、`classRoomId`、`classRoomName`、`siteId`、`siteName`、`venueName`、`boardSn`、`remark` |
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {
|
||||
"teacherInfo": { "tId": "T0001", "tName": "李老师", "tPhone": "13900000000", "tGender": "1", "deptName": "供电段", "personNo": "P2001", "avatar": null },
|
||||
"dormitory": { "dormId": "D02", "bedNo": "1", "dormBuilding": "2号楼", "dormRoom": "205" },
|
||||
"lesson": [
|
||||
{ "lessonId": 9001, "courseName": "接触网巡视", "tId": "T0001", "teacherName": "李老师", "startTime": "2026-11-06 08:00:00", "endTime": "2026-11-06 10:00:00", "classRoomId": "R01", "classRoomName": "201", "venueName": "教学楼201" }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 班级名单
|
||||
|
||||
### 5.1 获取进行中班级的学员名单
|
||||
|
||||
- **接口路径**：`/api/register/v1/class/student`
|
||||
- **请求方法**：`GET`
|
||||
- **功能说明**：查询所有**进行中**（`planStatus = 1`）的开班计划，并按计划取报名记录中**未报到**（`enrollmentStatus = 0`）的学员，学员列表作为班级属性 `students` 一并返回。单个学员主档缺失时用报名记录的冗余字段兜底，不会中断整体返回。
|
||||
|
||||
**请求参数**：无
|
||||
|
||||
**返回结果说明**：`data` 为班级数组：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `planId` | string | 开班计划ID |
|
||||
| `planName` | string | 开班计划名称 |
|
||||
| `classId` | string | 班级ID |
|
||||
| `className` | string | 班级名称 |
|
||||
| `students` | array | 未报到学员：`sId`、`sName`、`deptId`、`deptName` |
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": [
|
||||
{
|
||||
"planId": "P2026001",
|
||||
"planName": "2026年第一期",
|
||||
"classId": "C01",
|
||||
"className": "接触网一班",
|
||||
"students": [
|
||||
{ "sId": "S0001", "sName": "张三", "deptId": 103, "deptName": "供电段" }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 人脸照片上传
|
||||
|
||||
> 三个接口均为 `POST` + `application/json`，`faceImage` 支持**纯 base64** 或 **data URI**（`data:image/png;base64,....`）两种形式；服务端统一解码并转码为 PNG 落盘，路径形如 `/profile/upload/yyyy/MM/dd/{uuid}.png`，随后写回对应主档的 `avatar` 字段。
|
||||
|
||||
### 6.1 上传学员人脸照片
|
||||
|
||||
- **接口路径**：`/api/register/v1/student/face`
|
||||
- **请求方法**：`POST`
|
||||
- **功能说明**：保存学员人脸照片到 `train_student.avatar`，同步人脸识别设备（`employee_id = sId`），并按住宿记录办理报到：
|
||||
1. 更新报名记录 `enrollmentStatus = 1`、`joinTime = 当前时间`（存在报名记录时）；
|
||||
2. 若学员有有效住宿记录（按 `create_time` 降序首条且 `dormId` 非空），生成门锁业务流水号并调用入住接口 `/openapi/iot/stay/checkin`。
|
||||
|
||||
**请求参数**（JSON Body）
|
||||
|
||||
| 名称 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `sId` | string | 是 | 学员ID |
|
||||
| `faceImage` | string | 是 | 人脸图片 base64，可带 `data:image/xxx;base64,` 前缀 |
|
||||
|
||||
**返回结果说明**：`data` 字段：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `sId` | string | 学员ID |
|
||||
| `avatar` | string | 头像访问路径 |
|
||||
| `faceSync` | string | 设备同步状态：`success` / `failed` / `skipped` |
|
||||
| `faceMsg` | string | 同步失败原因（仅失败时存在） |
|
||||
| `faceData` | any | 设备返回的非 Map 数据（成功时可能追加） |
|
||||
| `lockCheckin` | object | 门锁入住结果，结构见 [1.4 lockCheckin](#14-公共数据结构)（有住宿时返回） |
|
||||
| `lockAuthId` | string | 门锁授权ID，当前固定为空串（有住宿时返回） |
|
||||
| `joinTime` | string | 报到时间（有住宿时返回） |
|
||||
|
||||
**失败场景**（`code=500`）：
|
||||
|
||||
| msg | 触发条件 |
|
||||
|---|---|
|
||||
| `参数缺失：sId 与 faceImage 均为必填` | 任一参数为 `null` |
|
||||
| `sId 不能为空` | `sId` 为空串 |
|
||||
| `图片解析失败：...` | base64 非法 / 非图片 / 无法编码为 PNG |
|
||||
| `创建存储目录失败` | 落盘目录创建失败 |
|
||||
| `图片写入失败：...` | 文件写入 IO 异常 |
|
||||
| `学员不存在或更新失败` | 更新 `train_student` 影响行数为 0 |
|
||||
|
||||
> 人脸设备同步失败不影响接口成功返回，仅通过 `faceSync=failed` + `faceMsg` 体现。
|
||||
|
||||
---
|
||||
|
||||
### 6.2 上传教师人脸照片
|
||||
|
||||
- **接口路径**：`/api/register/v1/teacher/face`
|
||||
- **请求方法**：`POST`
|
||||
- **功能说明**：保存教师人脸照片到 `train_teacher.avatar`，以 `employee_id = tId + "_teacher"` 同步人脸识别设备。教师无报名记录，**不处理报到状态**；若教师已有有效住宿且已生成门锁流水号，则补发一次入住授权（有效期 15 天）。
|
||||
|
||||
**请求参数**（JSON Body）
|
||||
|
||||
| 名称 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `teacherId` | string | 是 | 教师工号（`train_teacher.t_id`），不含 `_teacher` 后缀 |
|
||||
| `faceImage` | string | 是 | 人脸图片 base64，可带 data URI 前缀 |
|
||||
|
||||
**返回结果说明**：`data` 字段：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `tId` | string | 教师工号 |
|
||||
| `avatar` | string | 头像访问路径 |
|
||||
| `faceSync` | string | 设备同步状态：`success` / `failed` / `skipped` |
|
||||
| `faceMsg` | string | 同步失败原因（仅失败时存在） |
|
||||
| `lockCheckin` | object | 补发入住授权结果（教师有住宿且已生成 `lockApiBizNo` 时返回） |
|
||||
| `lockAuthId` | string | 当前固定为空串（补发授权时返回） |
|
||||
|
||||
**失败场景**（`code=500`）：
|
||||
|
||||
| msg | 触发条件 |
|
||||
|---|---|
|
||||
| `参数缺失：teacherId 与 faceImage 均为必填` | 任一参数为 `null` |
|
||||
| `teacherId 不能为空` | `teacherId` 为空串 |
|
||||
| `图片解析失败：...` / `创建存储目录失败` / `图片写入失败：...` | 同 6.1 |
|
||||
| `教师不存在或更新失败` | 更新 `train_teacher` 影响行数为 0 |
|
||||
|
||||
---
|
||||
|
||||
### 6.3 上传人脸照片（统一入口）
|
||||
|
||||
- **接口路径**：`/api/register/v1/face`
|
||||
- **请求方法**：`POST`
|
||||
- **功能说明**：按 `employeeId` 后缀分发到 6.1 / 6.2，返回被调用方法的原样结果：
|
||||
- `employeeId` 以 `_teacher` 结尾 → 去掉后缀作为 `teacherId`，转 6.2；
|
||||
- 其他情况 → `employeeId` 即 `sId`，转 6.1。
|
||||
- 后缀匹配**区分大小写**且不做 `trim`（`_TEACHER` 会被当作学员ID）。
|
||||
|
||||
**请求参数**（JSON Body）
|
||||
|
||||
| 名称 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `employeeId` | string | 是 | 人脸库人员ID：学员 `sId` 或教师 `tId + "_teacher"` |
|
||||
| `faceImage` | string | 是 | 人脸图片 base64，可带 data URI 前缀 |
|
||||
|
||||
**返回结果说明**：与分发目标接口完全一致（见 6.1 / 6.2 的 `data` 说明）。
|
||||
|
||||
**失败场景**（`code=500`）：
|
||||
|
||||
| msg | 触发条件 |
|
||||
|---|---|
|
||||
| `参数缺失：employeeId 与 faceImage 均为必填` | 任一参数为 `null` |
|
||||
| `employeeId 不能为空` | `employeeId` 为空串 |
|
||||
| `employeeId 非法：教师工号（tId）不能为空` | `employeeId` 仅由 `_teacher` 组成 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 报到业务
|
||||
|
||||
### 7.1 报到重置
|
||||
|
||||
- **接口路径**：`/api/register/v1/report/reset`
|
||||
- **请求方法**：`POST`
|
||||
- **功能说明**：用于“误点他人信息导致人脸错绑”的补救。按顺序执行 4 步，任一关键步骤失败即中止并返回原因：
|
||||
1. 解绑人脸（复用 `TrainFaceApiController.deleteEmployee`，`employee_id = studentId`）；
|
||||
2. 清除门锁入住授权（复用 `TrainLockApiController.checkout`），**住宿分配记录保留**；
|
||||
3. 参训状态重置为未报到 `0`（备注保持不变）；
|
||||
4. 清空学员头像（`train_student.avatar` 置 NULL）。
|
||||
|
||||
**请求参数**（Query / Form，`@RequestParam`，非 JSON Body）
|
||||
|
||||
| 名称 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `planId` | string | 是 | 开班计划ID（`train_enrollment.plan_id`） |
|
||||
| `studentId` | string | 是 | 学员ID（`train_enrollment.student_id`） |
|
||||
|
||||
**返回结果说明**：`data` 字段：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `planId` | string | 开班计划ID |
|
||||
| `studentId` | string | 学员ID |
|
||||
| `enrollmentId` | number | 参训记录主键 |
|
||||
| `previousStatus` | number | 重置前的报到状态 |
|
||||
| `faceUnbind` | string | 人脸解绑结果，成功为 `success` |
|
||||
| `lockCheckout` | string | 门锁授权清除结果：`success` / `skipped: 无有效住宿记录` / `skipped: 缺少门锁业务流水号与宿舍信息` |
|
||||
| `lockApiBizNo` | string | 门锁业务流水号（清除成功时返回） |
|
||||
| `currentStatus` | number | 重置后状态，固定 `0` |
|
||||
| `alreadyReset` | boolean | 重置前是否已是未报到 |
|
||||
| `accommodationKept` | boolean | 是否保留了住宿记录 |
|
||||
| `avatarCleared` | boolean | 头像是否已清空（成功路径） |
|
||||
| `avatarSId` | string | 清空头像的学员ID（成功路径） |
|
||||
|
||||
**失败场景**（`code=500`）：
|
||||
|
||||
| msg | 触发条件 |
|
||||
|---|---|
|
||||
| `planId 和 studentId 不能为空` | 任一参数为空 |
|
||||
| `未找到学员[xxx]在班级[yyy]的参训记录` | 报名记录不存在 |
|
||||
| `学员已放弃培训，不允许重置报到状态` | `previousStatus = 3` |
|
||||
| `学员已结训，不允许重置报到状态` | `previousStatus = 4` |
|
||||
| `步骤1 人脸解绑失败：...；参训状态未变更` | 人脸解绑未返回 200 |
|
||||
| `步骤2 门锁授权清除响应解析失败：...；人脸已解绑，参训状态未变更` | 下游响应非法 JSON |
|
||||
| `步骤2 门锁授权清除失败：...；人脸已解绑，参训状态未变更` | 下游返回非 200 |
|
||||
| `步骤3 参训状态重置失败；人脸与门锁授权已解除，请人工核对后重试` | 状态更新影响行数为 0 |
|
||||
| `报到重置已完成，但未找到有效学员档案[xxx]，avatar 未清空` | 主档缺失（`data` 仍返回已完成信息） |
|
||||
| `报到重置已完成，但清空学员头像失败：...` | 头像更新异常（`data` 仍返回已完成信息） |
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "报到重置成功",
|
||||
"data": {
|
||||
"planId": "P2026001",
|
||||
"studentId": "S0001",
|
||||
"enrollmentId": 5001,
|
||||
"previousStatus": 1,
|
||||
"faceUnbind": "success",
|
||||
"lockCheckout": "success",
|
||||
"lockApiBizNo": "STAY20261105001",
|
||||
"currentStatus": 0,
|
||||
"alreadyReset": false,
|
||||
"accommodationKept": true,
|
||||
"avatarCleared": true,
|
||||
"avatarSId": "S0001"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 宿舍布局
|
||||
|
||||
### 8.1 获取宿舍布局信息
|
||||
|
||||
- **接口路径**：`/api/register/v1/dormitory/layout`
|
||||
- **请求方法**：`GET`
|
||||
- **功能说明**：查询 `train_dormitory_info`（仅未删除房间），依次按 `dorm_building`（楼栋）→ `dorm_floor`（楼层）→ `dorm_room`（房间号）分组；并左关联 `train_accommodation` 统计每个房间的已分配床位数（住宿状态 `0 预分配` / `1 已入住` 计入，`2 已退宿` 不计），总床位数取房间核定容量 `capacity`。
|
||||
|
||||
**请求参数**：无
|
||||
|
||||
**返回结果说明**：
|
||||
|
||||
- `data` 为三层嵌套对象，键依次为「楼栋名称 → 楼层 → 房间号」，每间房的值包含：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `id` | number | 宿舍自增编号（`train_dormitory_info.id`） |
|
||||
| `dorm_room` | string | 房间号 |
|
||||
| `accommodation` | string | 已分配床位数/总床位数，如 `"2/4"` |
|
||||
|
||||
- 楼栋、楼层、房间均按数据库升序排列（`dorm_building, dorm_floor, dorm_room`），嵌套对象使用有序 Map 输出，顺序稳定。
|
||||
- 无房间数据时 `data` 为空对象 `{}`。
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {
|
||||
"1号楼": {
|
||||
"1": {
|
||||
"101": { "id": 1, "dorm_room": "101", "accommodation": "2/4" },
|
||||
"102": { "id": 2, "dorm_room": "102", "accommodation": "0/4" }
|
||||
},
|
||||
"2": {
|
||||
"201": { "id": 5, "dorm_room": "201", "accommodation": "4/6" }
|
||||
}
|
||||
},
|
||||
"2号楼": {
|
||||
"1": {
|
||||
"101": { "id": 9, "dorm_room": "101", "accommodation": "1/2" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 说明：同一楼栋内房间号唯一（约束 `uq_dorm_building_room`），因此以房间号作为楼层下的键不会冲突；楼层为空时键为 `未标注楼层`。
|
||||
|
||||
---
|
||||
|
||||
## 9. 附录
|
||||
|
||||
### 9.1 典型调用流程
|
||||
|
||||
1. `GET /student/list` 或 `GET /class/student` —— 报到机展示待报到人员。
|
||||
2. `GET /teacher/list` —— 展示教师名单（`sId` 形如 `T0001_teacher`）。
|
||||
3. 人员点击后：`GET /student/{sId}/resources`（或 `/base`）—— 展示开班、宿舍、教室、课表。
|
||||
4. 采集人脸后：`POST /face`（统一入口，传 `employeeId` + `faceImage`）—— 完成照片入库、设备下发、报到登记、门锁入住。
|
||||
5. 宿舍看板：`GET /dormitory/layout` —— 按楼栋/楼层/房间展示床位占用情况。
|
||||
6. 误绑时：`POST /report/reset?planId=...&studentId=...` —— 回退报到与人脸/门锁授权。
|
||||
|
||||
### 9.2 调用示例
|
||||
|
||||
```bash
|
||||
# 学员列表
|
||||
curl "http://localhost:8096/api/register/v1/student/list"
|
||||
|
||||
# 学员关联资源
|
||||
curl "http://localhost:8096/api/register/v1/student/S0001/resources"
|
||||
|
||||
# 教师基础信息（tId 可带 _teacher 后缀）
|
||||
curl "http://localhost:8096/api/register/v1/teacher/T0001_teacher/base"
|
||||
|
||||
# 统一人脸上传
|
||||
curl -X POST "http://localhost:8096/api/register/v1/face" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"employeeId":"S0001","faceImage":"data:image/jpeg;base64,/9j/4AAQSkZJRg..."}'
|
||||
|
||||
# 报到重置（需登录态）
|
||||
curl -X POST "http://localhost:8096/api/register/v1/report/reset?planId=P2026001&studentId=S0001" \
|
||||
-H "Authorization: Bearer {token}"
|
||||
|
||||
# 宿舍布局
|
||||
curl "http://localhost:8096/api/register/v1/dormitory/layout"
|
||||
```
|
||||
|
||||
### 9.3 与源码注释的差异说明
|
||||
|
||||
| 位置 | 注释/声明 | 实际实现 |
|
||||
|---|---|---|
|
||||
| 类注释 | 登录接口需 HMAC 签名（`X-Signature`/`X-Nonce`） | 控制器内未实现；`DeviceHmacFilter` 仅覆盖 `/api/iot/v1/device/login` |
|
||||
| `SecurityConfig` 注释 | `/api/register/v1/**` 走 Bearer 鉴权 | 已配置 `permitAll`，除 `/report/reset` 外不校验 Token |
|
||||
| `/student/{sId}/base` | 注释称返回“课表、实训场地” | 实际不返回 `courses`、`lesson`，需调用 `/student/{sId}/resources` |
|
||||
@@ -0,0 +1,612 @@
|
||||
# 电子班牌接口 API 文档
|
||||
|
||||
| 项目 | 内容 |
|
||||
|---|---|
|
||||
| 控制器 | `com.ruoyi.web.controller.api.TrainBoardApiController` |
|
||||
| 源文件 | `ruoyi-admin/src/main/java/com/ruoyi/web/controller/api/TrainBoardApiController.java` |
|
||||
| BasePath | `/api/board/v1` |
|
||||
| 接口数量 | 7（4 个查询类 + 1 个签到上报 + 2 个新增能力） |
|
||||
| 鉴权 | RuoYi Bearer Token（`Authorization: Bearer {token}`） |
|
||||
| 文档更新 | 2026-11-03 |
|
||||
| 编写依据 | 控制器源码逐行核对，与当前实现一致 |
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
- [1. 通用约定](#1-通用约定)
|
||||
- [1.1 鉴权](#11-鉴权)
|
||||
- [1.2 统一响应结构](#12-统一响应结构)
|
||||
- [1.3 状态码](#13-状态码)
|
||||
- [1.4 列表数据包装](#14-列表数据包装)
|
||||
- [1.5 字段类型说明](#15-字段类型说明)
|
||||
- [2. 接口总览](#2-接口总览)
|
||||
- [3. 接口详情](#3-接口详情)
|
||||
- [3.1 查询教室信息](#31-查询教室信息)
|
||||
- [3.2 查询指定教室当天课程](#32-查询指定教室当天课程)
|
||||
- [3.3 查询指定班级在指定教室的座位](#33-查询指定班级在指定教室的座位)
|
||||
- [3.4 查询班级学员卡号](#34-查询班级学员卡号)
|
||||
- [3.5 上报签到数据](#35-上报签到数据)
|
||||
- [3.6 查询本节课签到记录](#36-查询本节课签到记录)
|
||||
- [3.7 查询座位布局](#37-查询座位布局)
|
||||
- [4. 异常与错误汇总](#4-异常与错误汇总)
|
||||
- [5. 调用示例](#5-调用示例)
|
||||
- [6. 附录](#6-附录)
|
||||
|
||||
---
|
||||
|
||||
## 1. 通用约定
|
||||
|
||||
### 1.1 鉴权
|
||||
|
||||
- 所有接口均需携带 `Authorization: Bearer {token}`，Token 由平台登录接口签发。
|
||||
- 未携带或 Token 失效时，返回 **HTTP 200** + 响应体 `code=401`：
|
||||
|
||||
```json
|
||||
{ "code": 401, "msg": "请求访问：/api/board/v1/signageService/selectClassroom，认证失败，无法访问系统资源" }
|
||||
```
|
||||
|
||||
> 本控制器未使用 `@PreAuthorize` 数据权限注解，因此不存在 `403` 业务场景。
|
||||
|
||||
### 1.2 统一响应结构
|
||||
|
||||
所有接口返回 `AjaxResult`：
|
||||
|
||||
```json
|
||||
{ "code": 200, "msg": "操作成功", "data": {} }
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `code` | number | 业务状态码，见 1.3 |
|
||||
| `msg` | string | 提示信息；成功固定为 `操作成功` |
|
||||
| `data` | object / array | 业务数据，无数据时字段不出现 |
|
||||
|
||||
### 1.3 状态码
|
||||
|
||||
| code | 含义 | HTTP 状态 | 触发来源 |
|
||||
|---|---|---|---|
|
||||
| 200 | 成功 | 200 | 正常返回 |
|
||||
| 401 | 未认证 / Token 无效 | **200** | `AuthenticationEntryPointImpl` |
|
||||
| 404 | 接口路径不存在 | 404 | `NoResourceFoundException` |
|
||||
| 500 | 参数缺失、参数格式错误、数据校验失败、控制器内业务拦截、系统异常 | 200 | `GlobalExceptionHandler` / 控制器返回值 |
|
||||
| 40080 / 40081 / 40085 / 40086 / 40087 | 考勤业务码（计划不一致 / 课次不存在 / 未报到 / 已放弃 / 已结训） | 200 | `ServiceException`（`AttendanceErrorCode`） |
|
||||
|
||||
> **调用方必须判断响应体 `code`**：除 404 外，失败场景的 HTTP 状态码仍是 200。
|
||||
|
||||
### 1.4 列表数据包装
|
||||
|
||||
除 `3.1 查询教室信息`（`data` 直接是数组）外，其余查询接口的 `data` 为：
|
||||
|
||||
```json
|
||||
{ "total": 2, "rows": [ ... ] }
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `total` | number | 本次返回的记录数（非分页总数） |
|
||||
| `rows` | array | 数据列表，无数据时为 `[]` |
|
||||
|
||||
### 1.5 字段类型说明
|
||||
|
||||
类注释约定 `id / classId / classroomId / courseId / teacherId / stuId / studentId` 为 Long，
|
||||
但本系统相关表以业务编码为主键（字符串），因此这些字段**返回字符串**；
|
||||
仅 `lessonId(id)`、`enrollmentId`、`zoneId`、`seatId`、`capacity`、`classHour` 等为数值。
|
||||
|
||||
---
|
||||
|
||||
## 2. 接口总览
|
||||
|
||||
| # | 接口名称 | 方法 | 路径 | 用途 |
|
||||
|---|---|---|---|---|
|
||||
| 3.1 | 查询教室信息 | GET | `/api/board/v1/signageService/selectClassroom` | 返回全部教学教室与实训场地 |
|
||||
| 3.2 | 查询指定教室当天课程 | GET | `/api/board/v1/signageService/coursesInClassroom` | 按教室与日期范围返回排课 |
|
||||
| 3.3 | 查询指定班级在指定教室的座位 | GET | `/api/board/v1/signageService/studentInClassroom` | 返回座位网格（含学员姓名） |
|
||||
| 3.4 | 查询班级学员卡号 | GET | `/api/board/v1/signageService/studentCard` | 刷卡校验用卡号与班级信息 |
|
||||
| 3.5 | 上报签到数据 | POST | `/api/board/v1/signageService/checkin/upload` | JSON 上报签到并落库 |
|
||||
| 3.6 | 查询本节课签到记录 | GET | `/api/board/v1/signageService/checkin/list` | 按课次返回签到流水与学员姓名 |
|
||||
| 3.7 | 查询座位布局 | GET | `/api/board/v1/signageService/seatLayout` | 仅读 `train_class_seat` 的座位布局 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 接口详情
|
||||
|
||||
### 3.1 查询教室信息
|
||||
|
||||
**用途**：返回全部教学教室 + 实训场地（`train_classroom_info` UNION `train_training_site`），供班牌后台定位终端绑定教室。
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| HTTP 方法 | `GET` |
|
||||
| 请求路径 | `/api/board/v1/signageService/selectClassroom` |
|
||||
| 鉴权 | 需要 |
|
||||
|
||||
**请求参数**：无。
|
||||
|
||||
**请求体**：无。
|
||||
|
||||
**响应结构**：`data` 为数组（**不是** `{total, rows}` 包装）。
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `id` | string | 教室ID（`class_room_id`）或场地ID（`site_id`） |
|
||||
| `name` | string | 教室/场地名称 |
|
||||
| `campus` | string | 校区/位置 |
|
||||
| `capacity` | number | 容量 |
|
||||
| `outside` | number | `0`=教室，`1`=实训场地 |
|
||||
| `category` | string | `教室` / `实训场地` |
|
||||
|
||||
**成功示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": [
|
||||
{ "id": "CR01", "name": "多媒体教室01", "campus": "一号教学楼3层", "capacity": 60, "outside": 0, "category": "教室" },
|
||||
{ "id": "SITE01", "name": "信号实训场", "campus": "实训楼1层", "capacity": 40, "outside": 1, "category": "实训场地" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**异常说明**：未认证 → `code=401`；无数据 → `data: []`。
|
||||
|
||||
---
|
||||
|
||||
### 3.2 查询指定教室当天课程
|
||||
|
||||
**用途**：按教室/场地与日期范围（含首尾日期）返回排课列表。文档约定 `beginDate=endDate=当天`，接口本身不限制两者相等。
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| HTTP 方法 | `GET` |
|
||||
| 请求路径 | `/api/board/v1/signageService/coursesInClassroom` |
|
||||
| 鉴权 | 需要 |
|
||||
|
||||
**请求参数（Query String）**
|
||||
|
||||
| 名称 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `classroomId` | string | 是 | 无 | 教室ID（`class_room_id`）或场地ID（`site_id`），SQL 同时匹配两列 |
|
||||
| `beginDate` | string | 是 | 无 | 开始日期 `yyyy-MM-dd`，条件 `start_time >= beginDate` |
|
||||
| `endDate` | string | 是 | 无 | 结束日期 `yyyy-MM-dd`，条件 `start_time < endDate + 1 天`（含当天） |
|
||||
|
||||
**请求体**：无。
|
||||
|
||||
**响应结构**：`data = { total, rows[] }`
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `id` | number | 排课ID（`train_lesson.lesson_id`），**即 3.5 的 `lessonId`** |
|
||||
| `courseId` | string | 课程主数据ID（`train_course.c_id`） |
|
||||
| `classId` | string | 班级ID（`train_class_plan.plan_id`） |
|
||||
| `classroomId` | string | 教室ID或场地ID（`COALESCE(class_room_id, site_id)`） |
|
||||
| `courseName` | string | 课程名称 |
|
||||
| `couresName` | string | 兼容旧拼写的课程名称（与 `courseName` 同值） |
|
||||
| `courseTime` | string | 上课时间 `yyyy-MM-dd HH:mm:ss` |
|
||||
| `classHour` | number | 时长（分钟） |
|
||||
| `className` | string | 班级名称 |
|
||||
| `teacherId` | string | 教师ID（`train_lesson.t_id`） |
|
||||
| `teacherName` | string | 教师姓名，未排教师为 `null` |
|
||||
| `courseIntro` | string | 课程简介（`train_course.teaching_objective`） |
|
||||
| `isPublic` | number | 固定 `0` |
|
||||
|
||||
**成功示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {
|
||||
"total": 1,
|
||||
"rows": [
|
||||
{
|
||||
"id": 1001, "courseId": "CR01", "classId": "PLAN_A", "classroomId": "CR01",
|
||||
"courseName": "电子班牌数字化实务", "couresName": "电子班牌数字化实务",
|
||||
"courseTime": "2026-11-02 09:00:00", "classHour": 90,
|
||||
"className": "2026年第一期培训班", "teacherId": "T101", "teacherName": "张三",
|
||||
"courseIntro": "班牌设备安装与配置", "isPublic": 0
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**异常说明**
|
||||
|
||||
| 场景 | 响应 |
|
||||
|---|---|
|
||||
| 缺少 `classroomId` | `{"code":500,"msg":"Required request parameter 'classroomId' for method parameter type String is not present"}` |
|
||||
| 无排课 | `{"code":200,"msg":"操作成功","data":{"total":0,"rows":[]}}` |
|
||||
|
||||
---
|
||||
|
||||
### 3.3 查询班级学员卡号
|
||||
|
||||
**用途**：按班级返回学员卡号与班级、住宿信息，用于班牌刷卡校验。仅返回参训状态非“已放弃(3)”的学员。
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| HTTP 方法 | `GET` |
|
||||
| 请求路径 | `/api/board/v1/signageService/studentCard` |
|
||||
| 鉴权 | 需要 |
|
||||
|
||||
**请求参数（Query String）**
|
||||
|
||||
| 名称 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `classId` | string | 是 | 无 | 班级ID（`train_enrollment.plan_id`） |
|
||||
|
||||
**请求体**：无。
|
||||
|
||||
**响应结构**：`data = { total, rows[] }`
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `cardNo` | string | 卡号（`train_student.card_no`，保留前导零） |
|
||||
| `studentId` | string | 学员ID（`s_id`） |
|
||||
| `classId` | string | 班级ID |
|
||||
| `studentName` | string | 学员姓名 |
|
||||
| `className` | string | 班级名称 |
|
||||
| `id` | number | 参训档案ID（`enrollment_id`，**不是学员ID**） |
|
||||
| `roomId` | string | 宿舍ID，未分配为 `null` |
|
||||
| `bedType` | string | 床位类型（预留，固定 `null`） |
|
||||
| `seatNumber` | string | 床位号，未分配为 `null` |
|
||||
|
||||
**成功示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {
|
||||
"total": 1,
|
||||
"rows": [
|
||||
{ "cardNo": "00012345", "studentId": "STU_1", "classId": "PLAN_A", "studentName": "王五", "className": "2026年第一期培训班", "id": 201, "roomId": "DORM-101", "bedType": null, "seatNumber": "1" }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**异常说明**：缺少 `classId` → `code=500`；无数据 → `{total:0, rows:[]}`。
|
||||
|
||||
---
|
||||
|
||||
### 3.4 上报签到数据
|
||||
|
||||
**用途**：班牌上报学员签到。服务端按 `studentId` 在课次所属培训班内查询 `train_enrollment` 得到 `enrollmentId`，写入 `train_student_checkin`（`student_id`、`board_id`、`lesson_id`、`sign_in_time` 一并落库）。
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| HTTP 方法 | `POST` |
|
||||
| 请求路径 | `/api/board/v1/signageService/checkin/upload` |
|
||||
| 鉴权 | 需要 |
|
||||
| Content-Type | **必须 `application/json`** |
|
||||
| 文件上传 | 无 |
|
||||
|
||||
**请求参数**：无 Query 参数，全部字段在请求体中。
|
||||
|
||||
**请求体结构**（`BoardCheckinUploadRequest`）
|
||||
|
||||
| 名称 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `studentId` | string | 是 | 无 | 学员ID（`train_student.s_id`），首尾空格会被去除 |
|
||||
| `boardId` | string | 否 | `null` | 门牌（班牌）ID，写入 `train_student_checkin.board_id`；空串按 `null` 处理 |
|
||||
| `lessonId` | number(long) | 是 | 无 | 课程（课次）ID，对应 `train_student_checkin.lesson_id`，取值来自 3.2 的 `id` |
|
||||
| `signInTime` | string | 否 | 服务器当前时间 | 签到时间，格式 `yyyy-MM-dd HH:mm:ss`；格式非法直接报错，不静默改写 |
|
||||
|
||||
```json
|
||||
{
|
||||
"studentId": "STU_1",
|
||||
"boardId": "BP001",
|
||||
"lessonId": 1001,
|
||||
"signInTime": "2026-11-02 08:30:00"
|
||||
}
|
||||
```
|
||||
|
||||
**响应结构**（`data` 为单对象）
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `checkinId` | number | 考勤记录ID |
|
||||
| `studentId` | string | 学员ID（库中 `student_id`，为空时回填请求值） |
|
||||
| `enrollmentId` | number | 参训档案ID（由 `studentId` + 班次推导） |
|
||||
| `lessonId` | number | 课次ID |
|
||||
| `boardId` | string | 班牌ID，未传为 `null` |
|
||||
| `signInTime` | string | 实际落库的签到时间 `yyyy-MM-dd HH:mm:ss` |
|
||||
|
||||
**成功示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {
|
||||
"checkinId": 9001, "studentId": "STU_1", "enrollmentId": 201,
|
||||
"lessonId": 1001, "boardId": "BP001", "signInTime": "2026-11-02 08:30:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**异常与错误说明**
|
||||
|
||||
| 场景 | code | 响应 msg |
|
||||
|---|---|---|
|
||||
| `studentId` 为空 | 500 | `studentId 不能为空` |
|
||||
| `lessonId` 为空 | 500 | `lessonId 不能为空` |
|
||||
| `signInTime` 格式错误 | 500 | `signInTime 格式不正确，应为 yyyy-MM-dd HH:mm:ss` |
|
||||
| 课次不存在 | 500 | `课程(课次)不存在: 1001` |
|
||||
| 课次未关联有效培训计划 | 500 | `课程(课次)[1001]未关联有效的培训计划` |
|
||||
| 学员无该班参训记录 | 500 | `未找到学员[STU_1]在班级[PLAN_A]的参训记录` |
|
||||
| 非 JSON / 空请求体 | 500 | Spring 反序列化异常信息（如 `Content-Type 'text/plain' is not supported`） |
|
||||
| 未认证 | 401 | `请求访问：/api/board/v1/signageService/checkin/upload，认证失败，无法访问系统资源` |
|
||||
| 学员未报到 / 已放弃 / 已结训 | 40085 / 40086 / 40087 | 对应中文提示（见 `AttendanceErrorCode`） |
|
||||
| 课次所属计划与参训计划不一致 | 40080 | `业务不变量校验失败：考勤学员与课次所属培训班不一致` |
|
||||
|
||||
**业务规则**
|
||||
|
||||
1. **幂等**：同一 `enrollmentId + lessonId` 已有签到记录（`sign_in_time` 非空）时返回已有记录，不覆盖首次签到时间。
|
||||
2. **生命周期**：仅“已报到(1)”“请假(2)”状态允许签到。
|
||||
3. **计划一致性**：学员参训档案所属培训班必须与课次所属培训班一致。
|
||||
4. **打卡方式**：固定按设备打卡 `checkinWay=1` 落库。
|
||||
|
||||
---
|
||||
|
||||
### 3.5 查询本节课签到记录
|
||||
|
||||
**用途**：按 `lessonId` 返回 `train_student_checkin` 签到流水，并按 `studentId` 关联 `train_student` 返回学员姓名（`s_name`）。
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| HTTP 方法 | `GET` |
|
||||
| 请求路径 | `/api/board/v1/signageService/checkin/list` |
|
||||
| 鉴权 | 需要 |
|
||||
|
||||
**请求参数（Query String）**
|
||||
|
||||
| 名称 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `lessonId` | number(long) | 是 | 无 | 课程（课次）ID；非数字时返回参数类型不匹配错误 |
|
||||
|
||||
**请求体**：无。
|
||||
|
||||
**响应结构**：`data = { total, rows[] }`，`rows[]` 为 `TrainStudentCheckin`：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `checkinId` | number | 考勤记录ID |
|
||||
| `enrollmentId` | number | 参训档案ID |
|
||||
| `lessonId` | number | 课次ID |
|
||||
| `studentId` | string | 学员ID（优先取 `train_student_checkin.student_id`，为空取参训档案的 `student_id`） |
|
||||
| `studentName` | string | 学员姓名（`train_student.s_name`） |
|
||||
| `planId` | string | 培训班ID |
|
||||
| `planName` | string | 培训班名称 |
|
||||
| `className` | string | 班级名称 |
|
||||
| `courseName` | string | 课程名称 |
|
||||
| `boardId` | string | 打卡班牌ID |
|
||||
| `boardSn` | string | 班牌序列号 |
|
||||
| `boardName` | string | 班牌名称 |
|
||||
| `checkinWay` | number | 打卡方式：1 人脸/设备，2 刷卡，3 扫码，4 教师代签 |
|
||||
| `signInTime` | string | 签到时间 `yyyy-MM-dd HH:mm:ss`，未签到为 `null` |
|
||||
| `signOutTime` | string | 签退时间 `yyyy-MM-dd HH:mm:ss`，未签退为 `null` |
|
||||
| `attendanceStatus` | number | 考勤结论：0 缺勤，1 正常，2 迟到，3 早退，4 请假 |
|
||||
| `manualFlag` | number | 是否人工修正：0 否，1 是 |
|
||||
| `createBy` / `createTime` / `updateBy` / `updateTime` / `remark` | string | 审计字段（时间格式 `yyyy-MM-dd HH:mm:ss`） |
|
||||
|
||||
> `params` 为空时不输出；`searchValue` 始终不输出。
|
||||
|
||||
**成功示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {
|
||||
"total": 1,
|
||||
"rows": [
|
||||
{
|
||||
"checkinId": 9001, "enrollmentId": 201, "lessonId": 1001,
|
||||
"studentId": "STU_1", "studentName": "张三",
|
||||
"planId": "PLAN_A", "planName": "2026年第一期培训班", "className": "一班",
|
||||
"courseName": "电子班牌数字化实务",
|
||||
"boardId": "BP001", "boardSn": "BP001", "boardName": "1号班牌",
|
||||
"checkinWay": 1, "signInTime": "2026-11-02 08:30:00", "signOutTime": null,
|
||||
"attendanceStatus": 1, "manualFlag": 0,
|
||||
"createBy": "board_device", "createTime": "2026-11-02 08:30:01",
|
||||
"updateBy": null, "updateTime": null, "remark": null
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**异常与错误说明**
|
||||
|
||||
| 场景 | 响应 |
|
||||
|---|---|
|
||||
| 缺少 `lessonId` | `{"code":500,"msg":"Required request parameter 'lessonId' for method parameter type Long is not present"}` |
|
||||
| `lessonId` 非数字 | `{"code":500,"msg":"请求参数类型不匹配，参数[lessonId]要求类型为：'java.lang.Long'，但输入值为：'abc'"}` |
|
||||
| 课次无签到记录 | `{"code":200,"msg":"操作成功","data":{"total":0,"rows":[]}}` |
|
||||
|
||||
---
|
||||
|
||||
### 3.6 查询座位布局
|
||||
|
||||
**用途**：按班级与教室查询座位布局，**仅读取 `train_class_seat` 单表**，不关联学员、教室、班级表；不校验班级是否删除、学员是否存在。
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| HTTP 方法 | `GET` |
|
||||
| 请求路径 | `/api/board/v1/signageService/seatLayout` |
|
||||
| 鉴权 | 需要 |
|
||||
|
||||
**请求参数（Query String）**
|
||||
|
||||
| 名称 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `planId` | string | 是 | 无 | 班级ID，对应 `train_class_seat.plan_id` |
|
||||
| `classroomId` | string | 是 | 无 | 教室ID，对应 `train_class_seat.classroom_id` |
|
||||
|
||||
**请求体**：无。
|
||||
|
||||
**响应结构**：`data = { total, rows[] }`
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `seatId` | number | 座位主键（`seat_id`） |
|
||||
| `planId` | string | 班级ID（`plan_id`） |
|
||||
| `classroomId` | string | 教室ID（`classroom_id`） |
|
||||
| `rowIndex` | number | 行号，从 1 开始 |
|
||||
| `colIndex` | number | 列号，从 1 开始 |
|
||||
| `seatCode` | string | 物理座位标识（`seat_code`） |
|
||||
| `canceled` | number | `0`=正常，`1`=取消位置（**不做过滤，原样返回**） |
|
||||
| `studentId` | string | 占用座位学员ID，空座为 `null` |
|
||||
| `zoneId` | number | 区域ID |
|
||||
| `deptDetail` | string | 部门 |
|
||||
| `job` | string | 职务 |
|
||||
|
||||
排序：`row_index, col_index` 升序。
|
||||
|
||||
**成功示例**
|
||||
|
||||
```json
|
||||
http://localhost:8096/api/board/v1/signageService/seatLayout?classroomId=afcf21a8bd99488cb19638d285f157a8&planId=f70ec13a651942e8a704ee4cc010c95e
|
||||
|
||||
{
|
||||
"msg": "操作成功",
|
||||
"code": 200,
|
||||
"data": {
|
||||
"total": 2,
|
||||
"rows": [
|
||||
{
|
||||
"canceled": 0,
|
||||
"classroomId": "afcf21a8bd99488cb19638d285f157a8",
|
||||
"colIndex": 5,
|
||||
"deptDetail": null,
|
||||
"job": null,
|
||||
"planId": "f70ec13a651942e8a704ee4cc010c95e",
|
||||
"rowIndex": 2,
|
||||
"seatCode": "2-5",
|
||||
"seatId": 29,
|
||||
"studentId": "c78c425e66384104bf37d150519fc5d3",
|
||||
"zoneId": null
|
||||
},
|
||||
{
|
||||
"canceled": 0,
|
||||
"classroomId": "afcf21a8bd99488cb19638d285f157a8",
|
||||
"colIndex": 9,
|
||||
"deptDetail": null,
|
||||
"job": null,
|
||||
"planId": "f70ec13a651942e8a704ee4cc010c95e",
|
||||
"rowIndex": 3,
|
||||
"seatCode": "3-9",
|
||||
"seatId": 30,
|
||||
"studentId": "63d889e8be2c4d61900d09b51b2108a5",
|
||||
"zoneId": null
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**异常与错误说明**
|
||||
|
||||
| 场景 | 响应 |
|
||||
|---|---|
|
||||
| 缺少 `planId` 或 `classroomId` | `code=500`，`msg` 为 Spring 缺参提示 |
|
||||
| 该班该教室无座位数据 | `{"code":200,"msg":"操作成功","data":{"total":0,"rows":[]}}` |
|
||||
| 表 `train_class_seat` 不存在 | `code=500`，`msg` 含 `Table 'xxx.train_class_seat' doesn't exist`（需先执行 `sql/train/v2/019_signage.sql`） |
|
||||
|
||||
---
|
||||
|
||||
## 4. 异常与错误汇总
|
||||
|
||||
| 类型 | 返回形式 | 说明 |
|
||||
|---|---|---|
|
||||
| 未认证 | HTTP 200，`code=401` | Token 缺失、过期、伪造 |
|
||||
| 路径不存在 | HTTP 404，`code=404`，`msg=接口不存在或未启用` | 路由未匹配 |
|
||||
| 缺少必填 Query 参数 | HTTP 200，`code=500` | `Required request parameter 'xxx' ... is not present` |
|
||||
| 参数类型不匹配 | HTTP 200，`code=500` | `请求参数类型不匹配，参数[lessonId]要求类型为：'java.lang.Long'，但输入值为：'abc'` |
|
||||
| 请求方法不支持 | HTTP 200，`code=500` | `Request method 'GET' is not supported` |
|
||||
| 请求体非 JSON | HTTP 200，`code=500` | `Content-Type 'xxx' is not supported` |
|
||||
| 控制器内业务拦截 | HTTP 200，`code=500` | 见 3.5 异常表 |
|
||||
| 考勤业务异常 | HTTP 200，`code=40080/40081/40085/40086/40087` | `AttendanceErrorCode` |
|
||||
|
||||
`AttendanceErrorCode` 常用码：
|
||||
|
||||
| code | 含义 |
|
||||
|---|---|
|
||||
| 40080 | 考勤学员与课次所属培训班不一致 |
|
||||
| 40081 | 课次不存在 |
|
||||
| 40085 | 学员尚未完成开班报到，禁止录入课次考勤 |
|
||||
| 40086 | 学员已放弃培训 |
|
||||
| 40087 | 学员已结训 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 调用示例
|
||||
|
||||
```bash
|
||||
# 登录获取 token（按平台实际登录接口调整）
|
||||
TOKEN=$(curl -s -X POST 'http://192.168.106.24:8096/login' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"username":"admin","password":"admin123"}' | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')
|
||||
|
||||
# 3.1 教室信息
|
||||
curl -s 'http://192.168.106.24:8096/api/board/v1/signageService/selectClassroom' \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# 3.2 指定教室当天课程
|
||||
curl -s 'http://192.168.106.24:8096/api/board/v1/signageService/coursesInClassroom?classroomId=CR01&beginDate=2026-11-02&endDate=2026-11-02' \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# 3.3 指定班级在指定教室的座位
|
||||
curl -s 'http://192.168.106.24:8096/api/board/v1/signageService/studentInClassroom?classroomId=CR01&classId=PLAN_A' \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# 3.4 班级学员卡号
|
||||
curl -s 'http://192.168.106.24:8096/api/board/v1/signageService/studentCard?classId=PLAN_A' \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# 3.5 上报签到（JSON 请求体）
|
||||
curl -s -X POST 'http://192.168.106.24:8096/api/board/v1/signageService/checkin/upload' \
|
||||
-H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" \
|
||||
-d '{"studentId":"STU_1","boardId":"BP001","lessonId":1001,"signInTime":"2026-11-02 08:30:00"}'
|
||||
|
||||
# 3.6 本节课签到记录
|
||||
curl -s 'http://192.168.106.24:8096/api/board/v1/signageService/checkin/list?lessonId=1001' \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# 3.7 座位布局
|
||||
curl -s 'http://192.168.106.24:8096/api/board/v1/signageService/seatLayout?planId=P2026001&classroomId=CR-001' \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 附录
|
||||
|
||||
### 6.1 数据来源
|
||||
|
||||
| 接口 | 主要数据表 |
|
||||
|---|---|
|
||||
| 3.1 | `train_classroom_info`、`train_training_site` |
|
||||
| 3.2 | `train_lesson`、`train_plan_course`、`train_course`、`train_class_plan`、`train_teacher` |
|
||||
| 3.3 | `train_class_seat`、`train_class_plan`、`train_student` |
|
||||
| 3.4 | `train_enrollment`、`train_student`、`train_class_plan`、`train_accommodation`、`train_dormitory_info` |
|
||||
| 3.5 | `train_lesson`、`train_plan_course`、`train_enrollment`、`train_student_checkin` |
|
||||
| 3.6 | `train_student_checkin`、`train_enrollment`、`train_student`、`train_class_plan`、`train_plan_course`、`train_course`、`train_electronic_board` |
|
||||
| 3.7 | `train_class_seat`（单表） |
|
||||
|
||||
### 6.2 Swagger
|
||||
|
||||
Swagger UI：`/swagger-ui/index.html`，分组 `电子班牌接口`。
|
||||
若 3.5 的 Request body 显示为 query 参数，说明部署的是旧包（当前实现为 `@RequestBody`）。
|
||||
|
||||
### 6.3 已知约束
|
||||
|
||||
1. `lessonId` 是**课次ID（`train_lesson.lesson_id`，数值）**，不是课程编码（`c_id`，如 `CR01`）；班牌须先调用 3.2 获取 `id`。
|
||||
2. 3.5 只接受 JSON 请求体，query/form 写法无效。
|
||||
3. 3.5 依赖 `train_student_checkin.student_id` 列；报 `Unknown column 'a.student_id'` 时需执行 `sql/train/v2/020b_add_checkin_student_id_mysql.sql`（MySQL）或 `sql/train/v2/020_add_checkin_student_id.sql`（KingbaseES/PostgreSQL）。
|
||||
4. 3.3 与 3.7 的区别：3.3 关联 `train_student` 返回姓名并过滤已删除班级；3.7 严格单表返回，含 `canceled=1` 的座位，不做班级有效性校验。
|
||||
5. 所有查询接口的 `total` 为本次返回条数，不是分页总数。
|
||||
Reference in new issue
Block a user