jcgl/docs/05-数据模型.md

05 数据模型

数据库为 KingbaseES 8，默认 schema gygl。表名大小写混用（GY_JCXX、gy_rooms、GYGL_JLXX），SQL 中需按现有写法保持一致。 本文只列核心表与关键字段；完整字段以 src/main/resources/mapper/**/*.xml 为准。

1. 核心关系图

erDiagram
    GY_YKT_RY ||--o{ GY_JCXX : "ryid/card_id"
    GY_JCXX }o--|| GY_ROOMS : "gyid + fjh"
    GY_JCXX ||--o{ GYGL_LY_EVENT : "jcid"
    GY_JCXX }o--o| GYGL_JLXX : "jlid"
    GY_JCXX ||--o| GY_JCXX_HIS : "归档"
    GY_YKT_RY ||--o| GY_YKT_REMAINDER : "ryid"
    GY_YKT_REMAINDER ||--o{ GY_YKT_ALLOWANCE : "补助"
    GY_YKT_REMAINDER ||--o{ GY_YKT_CONSUME : "消费"
    GY_YKT_REMAINDER ||--o{ GY_YKT_XJCZJL : "现金充值"
    GY_YKT_CASH_REQUEST ||--o| GY_YKT_XJCZJL : "完成充值"
    GY_SYN_JCXX }o--|| GY_SYN_JCXX_STATUS : "同步状态"
    GY_GYZD ||--o{ GY_ROOMS : "gyid"
    GY_GYZD ||--o{ GY_SB : "gyid"
    GY_SB ||--o| GY_SB_XT : "devicecode"

2. 住宿与叫乘

2.1 GY_JCXX（当前在寓/叫乘记录，核心表）

分组	字段	说明
主键	jcid	入住记录 ID
人员	ryid、card_id、rymc、rydw、gzzh、depotid	人员工号/卡号/姓名/单位/工资账号
公寓	gyid、gymc	公寓
房间	fjh	房间号（与 GY_ROOMS.room_no 对应）
交路	jlid、cc、jch、cclx、qd、ddcc、ddsj	交路 ID、车次、机车号、接车方式、起点、到达车次/时间
时间	kcsj、jcsj、fjsj、jcbjsj	开车、叫乘、复叫、叫乘结束（计划）
实际时间	jcsj_s、fjsj_s、jcbjsj_s、hjxysj、lybjsj	实际叫乘/复叫/报警/应答/离寓报警
入住离寓	yrysj、sjrysj、ylysj、sjlysj	预定/实际入住、预定/实际离寓
状态	ryzt、finish_jc、finish_ly、stoped、jllx	见状态字典
报警	is_jcbj、is_lybj、alarm_event_key	叫乘/离寓报警标记、报警事件键
通知去重	route_notice_key、call_timeout_notice_key、missed_call_notice_key	防止重复提醒
离寓证据	leave_type、leave_event_id、leave_remark、leave_snapshot_url	冗余自 GYGL_LY_EVENT，便于查询
其他	is_yaxx、yappsj、is_tempCall、recordfile、cblx、cbje、sfffcb	运安匹配标记、临时叫乘、录音文件、补助标识

有效在寓判定：finish_ly='0' AND sjlysj IS NULL。

2.2 GY_JCXX_HIS

与 GY_JCXX 同构的历史归档表；另有 ly_event_id 等证据字段。归档条件：已离寓且 sjlysj <= sysdate - 7。

2.3 GY_ROOMS

字段	说明
gyid、room_no	公寓 + 房间号（联合定位）
room_floor、room_dir、room_face、is_edge、is_next_floor、next_floor	楼层/朝向/相邻关系（用于推荐与排序）
room_status	房态，见下表
bed_numbers	床位数
room_type、room_dept、room_order	房型/所属部门/排序
live_person、person_name	当前人数/姓名串（实时重算）
sip_account	房间 SIP 账号（叫乘呼叫用）
bjkssj	保洁开始时间

room_status	含义
1	空闲
2	住满
3	待清扫
4	不能入住
5	未满
6	保洁中

2.4 GYGL_LY_EVENT（离寓事件证据）

字段	说明
id	事件 ID
jcid、gyid、ryid、fjh	关联入住记录
leave_type	FACE / MANUAL 等
device_code、device_event_id	设备与事件号（device_code + device_event_id 幂等）
snapshot_url、remark、operator_id、operator_name	抓拍、备注、操作人
occurred_at、received_at	发生/接收时间

2.5 GYGL_JLXX（交路模板）

id、jch、cc、qd、kcsj、jcsj、cclx、ddcc、ddsj、rysj、lysj、sfpc、bz、qr_fcd、qr_gy、lrsj、gyid、gymc、flag_send、bzje。

关联：

• GYGL_JLXX_TY：交路停运/调整时间段（gyid、cc、kssj、jssj）。
• GYGL_JLXX_LOGS：交路操作日志。
• 交路叫乘时刻不单独建表：getJlXxJcsjList 由 GYGL_JLXX 的 kcsj（开车时刻）、jcsj（叫乘时刻）、lysj（离寓时刻）结合传入的开车日期 kcrq 计算得出，fjsj = jcsj + 10 分钟、jcbjsj = jcsj + 15 分钟。

3. 运安同步

3.1 GY_SYN_JCXX（运安计划快照）

字段	说明
id	计划 ID（`jobid
ryid、ryxm、sfzh、sjh	司机工号/姓名/身份证/手机
jch、cx、cc	机车号、车型、车次
kcsj	开车时间（匹配后据此本地计算叫乘时间）
jhxl、jhcqdd、jcfs	计划线路、机车缺勤地点、接车方式
h1	派班室/公寓辅助字段
write_time	写入时间

3.2 GY_SYN_JCXX_STATUS

单行/少量行状态表，表示快照是否可用于匹配：0 未同步/同步中，1 同步完成。

3.3 GY_SYN_JCXX_HIS

同步快照历史（按需保留/排查用）。

3.4 GY_CALL_DUTY_MATCH_LOCK

交路抓取/推送/匹配的协调锁表。使用固定协调行（如 __SYNC_JCXX__）持有租约，避免多实例/多线程同时 TRUNCATE 与匹配。

3.5 JWDATA_SYNC_LOG / 同步日志

记录运安抓取、推送、匹配结果与异常，页面 /jwDataLog/* 查询。

4. 人员与卡务

4.1 GY_YKT_RY（人员）

ryid、card_id、gzzh、xm、dw、depotid、gwmc、gzmcnew、sjh、sfzh、xb、mz、zm、deleted、gxsj、photoUrl。

• deleted='1' 为逻辑删除，查询普遍带 nvl(deleted,'0') != '1'。
• gzmcnew 是岗位归类，用于补助规则与“内部人员”判断。

4.2 GY_YKT_RY_ZP

人员照片（ryid + photoBase64 BLOB）。

4.3 GY_YKT_REMAINDER（卡余额）

ryid、xm、xjye（现金余额）、knye（卡内余额/可用余额）、xfze（消费总额）、bzze（补助总额）、xfxjje（现金消费额）、xfbzje（补助消费额）。

4.4 GY_YKT_ALLOWANCE（补助明细）

ryid、gyid、cblx（补助类型）、cbje（金额）、sfffcb、ryzt、fjh、jlid、yrysj、sjrysj、ylysj 等。

4.5 GY_YKT_CONSUME（消费明细）

tid（交易号）、ryid、xm、xfje、xfsj、gyid、knye、xjye、xfze、bzze、xfxjje、xfbzje、deviceCode、xfly（消费来源）、is_jrxf（节假日消费）。

4.6 GY_YKT_XJCZJL（现金充值记录）

充值流水，关联现金充值申请。

4.7 GY_YKT_CASH_REQUEST（现金充值申请）

字段	说明
id	申请 ID
ryid、gyid、device_code	人员/公寓/设备
request_state	PENDING / CANCELLED / COMPLETED
created_at、updated_at	创建/更新时间

申请表本身不存金额；金额由设备/值班端在处理时传入，校验后写入充值流水与余额。

状态流转：PENDING → COMPLETED（值班端处理）或 PENDING → CANCELLED（设备取消），两者通过条件更新互斥。

4.8 GY_YKT_BTJS / GY_YKT_BTBJ

补助结算/补助报警相关表，配合补助统计与异常检查。

5. 设备

5.1 GY_SB（设备）

DEVICECODE、GYID、LX（类型）、jrsj、gxsj、ip、fjh（房间号）。

5.2 GY_SB_XT（设备心跳/系统信息）

devicecode、版本、deviceType、ip、deviceUpdateState、lastUserUpdateTime、lastDeviceConfigUpdateTime、心跳时间等。

5.3 GY_SB_ZL（设备指令/版本）

id、devicecode、updateState、generatedTime、apkurl、deleted。

• 业务代码写入指令后，设备心跳时按 devicecode + deleted='0' 取最新一条返回，并置 deleted='1'。
• 因此一次心跳只消费一条指令；多条指令会随多次心跳依次下发。

6. 基础资料与统计

表	说明
GY_GYZD	公寓字典（gyid、gymc、ip 等）
GY_GZZD	工种字典
GY_JRB	节假日日历
GY_JBXX	基本/班次信息
GY_SJGZ	时间规则：lysjgz、zjjcsjgz、kjjcsjgz（按公寓 + 单位）
GY_BJCSTJ、GY_BJXX	报警次数/报警信息
GYGL_JGXX	叫乘/离寓警示记录（gyid、fssj、xx_cc、xx_sj、xx_ryid、xx_ry、xxlx、xxms）
GY_JDQKHZ	进出情况汇总
GY_RTJB、GY_YTJB	日报/月报
GY_LOGS、GL_LOGS	业务/登录日志
GY_ZBY	值班员信息

7. 权限与用户

GL_YH（用户）、GL_JS（角色）、GL_QX（权限）、GL_CD（菜单）、GL_YH_JS（用户-角色）、GL_JS_QX（角色-权限）；另有 SYS_USER、SYS_USER_ROLE（历史/兼容）。

8. 库存扩展（kcgl）

GYGL_KCGL_*：仓库、供应商、物料、成品、入库单/出库单、盘点单、领料单、价格系数等；与叫乘主线弱相关。

9. 状态字典汇总

字段	取值
GY_JCXX.ryzt	0 待叫乘；1 叫乘中；2 叫乘报警；3 已应答待离寓；4 离寓报警；5 通话中；-1 查询合成
GY_JCXX.finish_jc	0 未结束；1 已结束
GY_JCXX.finish_ly	0 在寓；1 已离寓
GY_JCXX.jllx	0 按交路；1 非标准/便乘/驻在/人工修改
GY_ROOMS.room_status	1 空闲；2 住满；3 待清扫；4 不能入住；5 未满；6 保洁中
GY_YKT_CASH_REQUEST.request_state	PENDING / CANCELLED / COMPLETED
GY_JCXX.leave_type	FACE / MANUAL 等
同步状态	0 未完成；1 完成

10. 升级脚本

yktgl/src/main/resources/db/manual/ 下为手工执行的 Kingbase 脚本，按文件名日期顺序执行：

脚本	作用
V20260921_01__leave_snapshot_evidence_kingbase.sql	离寓抓拍证据字段/表
V20260922_01__call_duty_notice_dedup_kingbase.sql	叫乘提醒去重键
V20261008_01__syn_jcxx_write_time_kingbase.sql	快照写入时间
V20261008_02__call_duty_match_lock_kingbase.sql	匹配锁表与协调行
V20261009_01__jcxx_history_archive_kingbase.sql	历史归档字段/索引
V20261023_01__cash_request_state_kingbase.sql	现金充值申请状态
V20261029_01__reconcile_tlxc_room_occupancy.sql	通辽公寓房间占用校对（含 preview 版本）

另有 db/GY_SYN_JCXX_STATUS.sql 初始化同步状态表。

这些脚本不在应用启动时自动执行，升级需人工按序执行并校验。执行前务必备份。