01 系统总览

1. 业务定位

yktgl 是铁路行车公寓的叫乘（叫班）管理系统。公寓为值乘机车的乘务员提供住宿，系统负责把“入住—叫乘—出乘—离寓”串起来，并对接机务运安系统的乘务计划，确保乘务员按时出乘。

核心业务闭环：

乘务员到寓，在设备或值班端完成入寓登记，分配房间与床位，读取/生成叫乘计划（开车时间、叫乘时间、复叫时间、叫乘结束时间）。
到点自动叫乘：通过电话/广播（Asterisk 会议桥 + TTS）呼叫房间和值班台；未应答触发复叫，仍未应答触发报警。
乘务员应答后记录应答时间，结束本次叫乘。
乘务员离寓（刷卡/人脸/值班端操作），释放房间床位，写离寓时间与归档标记。
卡务侧完成补助发放、余额、消费、现金充值；管理端提供房间、人员、交路、统计报表、设备心跳与指令。

2. 使用角色

角色	使用入口	主要动作
公寓值班员	Web 管理端（`YktVue`）	入寓/离寓登记、叫乘监控与人工干预、换房、房间状态、充值审核
公寓管理员	Web 管理端	人员、交路、房间、设备、报表、用户权限
乘务员	公寓设备（叫乘屏/签到机/房间屏/消费机/售货机）	自助登记、查询、应答、消费、充值
保洁人员	房间设备/管理端	开始/结束保洁
运安系统	SOAP / HTTP	下发乘务计划、人员资料
中心服务器	HTTP	汇总公寓人员、财务数据

3. 运行形态

系统同时支持两种部署语义，但代码是同一套：

公寓端：每套公寓一套服务（或同一服务按 IP 区分公寓），连接本地 Asterisk、串口控制台、各类设备。
中心/汇总端：通过 /synData/*、/excel/* 提供人员与财务数据汇总；部分环境由中心下发交路。

flowchart LR
    subgraph 公寓现场
      DEV[叫乘屏/签到机/房间屏/消费机/售货机]
      WEB[值班员浏览器 YktVue]
      PHONE[电话/广播终端]
      CONSOLE[串口控制台]
    end

    subgraph 应用服务器
      APP[Spring Boot yktgl<br/>context /yktgl :8081]
      WS[WebSocket 服务]
      QZ[Quartz / @Scheduled]
      REDIS[(Redis Session)]
      DB[(KingbaseES gygl)]
    end

    subgraph 外部系统
      AST[Asterisk AMI / Conf-01]
      BYXX[机务运安 SOAP]
      CENTER[中心服务器 HTTP]
    end

    DEV -->|HTTP 心跳/业务| APP
    WEB -->|HTTP + WebSocket| APP
    APP --- WS
    APP --- QZ
    APP --- REDIS
    APP --- DB
    QZ -->|呼叫| AST
    AST --> PHONE
    AST --> CONSOLE
    APP -->|WSDL PbResource| BYXX
    APP <-->|人员/财务| CENTER

4. 技术栈

层次	选型	说明
运行时	Java 8、Spring Boot 2.6.13	继承 `spring-boot-starter-parent`；`pom.xml` 未声明 packaging（默认 jar），入口继承 `SpringBootServletInitializer`，也可改为 WAR 部署到外部 Tomcat
Web	Spring MVC、Spring WebSocket	`@ServerEndpoint` + `ServerEndpointExporter`
持久化	MyBatis-Plus 3.1.0、PageHelper 1.4.1	Mapper XML 位于 `classpath:mapper/*/.xml`
数据库	KingbaseES 8（`kingbase8` 8.6.0）	URL 形如 `jdbc:kingbase8://host:54321/gygl?currentSchema=gygl`；SQL 大量使用 Oracle 兼容写法（`TO_DATE`、`NVL`、`ROWNUM`、`MERGE`、`LISTAGG`、`sysdate`）
缓存/会话	Redis + Spring Session	`@EnableRedisHttpSession`，默认 30 分钟
调度	Quartz（内存模式）+ Spring `@Scheduled`	叫乘任务用 Quartz，补偿/清理用 `@Scheduled`
电话	asterisk-java `3.38.0-zfjia` + jSerialComm	AMI 控制会议桥，串口控制广播/话机
文档	Springfox Swagger 2.9.2	仅扫描 `jlgl.controller`
报表	Apache POI 4.1.2	`/excel/*` 导出
其他	fastjson2、Guava、Reflections、JNA	JSON、工具、类扫描、本地库调用

注意：pom.xml 中 spring-boot-starter-web 显式写了 3.5.4、spring-boot-starter-data-redis 写了 3.3.1，与 Boot 2.6.13 / Java 8 不匹配。见 09-迭代指引与风险清单.md。

5. 多公寓识别（重要约束）

同一套后端服务多个公寓时，公寓身份由请求来源 IP 决定：

入口：ZdwhService.getUniqueGyByIp(request) / getGyIdByIp(request)。
解析顺序：设备表（GY_SB）中的 IP → 公寓字典 GY_GYZD.ip。
若同一 IP 命中多个公寓，直接拒绝，避免写错公寓数据。
业务代码中 gyid 不能信任前端传入；入住、房间、充值等写操作均由服务端重新解析或校验。

相关配置：baseConfig.gyid、baseConfig.gymc 作为单公寓/默认值兜底；各 Profile 不同。

6. 关键设计约束（迭代时不要破坏）

房间占用以有效在寓明细为准：live_person、person_name 由 GY_JCXX 中 finish_ly='0' AND sjlysj IS NULL 的记录实时重算，不能仅做 ±1 计数。
交路快照与匹配分离：运安计划先整表落到 GY_SYN_JCXX（快照），再由匹配流程写入 GY_JCXX；匹配有全局锁和状态位，避免抓取/推送并发写坏数据。
叫乘任务可恢复：Quartz 任务按 ryid + 类型 建键，应用重启后由 WakeupJobRecoveryRunner 从库中恢复未来任务。
设备指令一次性投递：指令写入设备指令表，心跳时下发，下发后置 deleted=1。
事务内不做外部副作用：WebSocket 推送、创建 Quartz 任务等放在事务提交后（afterCurrentTransactionCommits）。
离寓有证据链：人脸离寓会保存抓拍快照、写 GYGL_LY_EVENT，并以 deviceEventId 做幂等。

7. 与前端/设备的关系

Web 管理端 YktVue 通过 /yktgl/* 接口与 WebSocket 交互；后端也会把旧构建产物放在 src/main/resources/static 下（历史遗留，见风险清单）。
设备通过各自的心跳接口注册，通过业务接口上报事件；服务端通过 WebSocket 向值班端推送刷新与人员信息。
叫乘执行不经过设备，而是直接走 Asterisk 电话/广播链路。

6.2 KiB Raw Permalink Blame History Unescape Escape