jcgl-dev/docs/README.md

# 叫乘管理系统 梳理文档

本目录是对既有代码的结构化梳理，目的是为后续迭代提供统一的“地图”：知道每个业务落在哪个包/页面、数据怎么流转、接口和外部系统怎么对接、改动时应该看哪些文件。

> 后端：`yktgl/`；前端：`YktVue/`，见 [frontend/](./frontend/README.md)。
> 梳理基准：`main` 分支提交 `135a192`（2026-11-07）。

## 文档索引

| 文档 | 内容 | 适用场景 |
| --- | --- | --- |
| [01-系统总览.md](./01-系统总览.md) | 业务定位、角色、运行形态、技术栈、关键设计约束 | 新人入门、方案评审 |
| [02-工程结构与分层.md](./02-工程结构与分层.md) | 目录/包结构、分层约定、启动流程、公共组件 | 找代码、定落点 |
| [03-业务模块地图.md](./03-业务模块地图.md) | 各业务模块职责、控制器、服务、依赖关系 | 评估改动影响面 |
| [04-核心业务流程.md](./04-核心业务流程.md) | 入住、叫乘、复叫、报警、应答、离寓、房间、交路同步、卡务 | 改业务逻辑前必读 |
| [05-数据模型.md](./05-数据模型.md) | 核心表、字段语义、状态码、归档与锁 | 写 SQL / 改表 / 排查数据 |
| [06-接口清单.md](./06-接口清单.md) | Web 接口与设备接口清单、协议枚举 | 联调、接口扩展 |
| [07-外部集成与定时任务.md](./07-外部集成与定时任务.md) | Asterisk AMI、运安 SOAP、中心 HTTP、WebSocket、Quartz/@Scheduled | 排障、集成改造 |
| [08-部署与配置.md](./08-部署与配置.md) | Profile、数据库/Redis、资源目录、升级脚本 | 部署、环境切换 |
| [09-迭代指引与风险清单.md](./09-迭代指引与风险清单.md) | 技术债、改动落点速查、待确认问题、迭代建议 | 排期、评审 |
| [10-架构优化方案-三端拆分.md](./10-架构优化方案-三端拆分.md) | 平台端/公寓端/应用端拆分：现状评估、目标架构、职责边界、模块与数据归属、接口契约、设备接入、部署与迁移路径；含公寓端细化（RuoYi-Vue + MySQL 技术基线、应用端复用实现、语音域 Asterisk/AMI/分机/录音与配置收敛对账）及 KingbaseES→MySQL 选型与迁移 | 架构评审、重构设计 |
| [11-既有数据库结构分析.md](./11-既有数据库结构分析.md) | 实测库级参数、40 表清单与规模、零主键零索引等结构缺陷、数据质量实证、表归属矩阵、类型归一与拆表建议 | 库设计评审、迁移改造 |
| [12-三端功能规划与应用端值班台设计.md](./12-三端功能规划与应用端值班台设计.md) | v4 三端功能范围 / 模块划分 / 职责边界 / 协作关系；应用端「1 台 + 2 层」信息架构与四区值班台；交互与状态反馈、异常与容错、8 类 28 项现场及中老年适配检查项 | 界面重构评审、前端交付与验收走查 |
| [13-值班员端功能补全与常驻盯控导航设计.md](./13-值班员端功能补全与常驻盯控导航设计.md) | v5 增量：六个功能模块（换乘 / 叫乘历史查询 / 交路管理 / 房间管理 / 交班日志 / 系统告警）、统一入口与导航、常驻盯控骨架与跨模块实时告警、范围变更登记与 41 项验收 | 界面补全评审、前端实现与走查 |
| [14-叫乘功能入口整合与房间维度展示调整.md](./14-叫乘功能入口整合与房间维度展示调整.md) | v6 形态增量：六入口并入顶部按钮操作区（排在「记录与自检」之后）、六模块全部弹出窗口化且主控区不变、紧急处置区显示全部报警 / 正在执行房间、叫乘信息以房间为单位（2~4 人/房间、1~2 房间/交路）、54 项验收 | 界面整合评审、前端实现与走查 |
| [15-原系统功能对照与逐页落点.md](./15-原系统功能对照与逐页落点.md) | v7 功能增量：以 `JcXx.vue` 全文 5295 行为事实源建立追溯矩阵；补齐主台四维查询、详情原系统字段与时刻口径、六模块原系统筛选与功能对照条、吸底值班条口径；10 项原系统缺陷明确不继承；43 项验收 | 功能对齐评审、前端实现与走查 |

## 前端文档

前端梳理独立成册，入口见 [frontend/README.md](./frontend/README.md)：

| 文档 | 内容 |
| --- | --- |
| [frontend/01-前端总览与技术栈.md](./frontend/01-前端总览与技术栈.md) | 四类界面、运行拓扑、技术栈、全局变量 |
| [frontend/02-工程结构与请求链路.md](./frontend/02-工程结构与请求链路.md) | 启动装配、登录守卫、axios、API 与后端映射 |
| [frontend/03-路由与页面职责.md](./frontend/03-路由与页面职责.md) | 13 条路由、入口关系、遗留页面 |
| [frontend/04-核心页面拆解-JcXx.md](./frontend/04-核心页面拆解-JcXx.md) | 值班台布局、状态、操作、时间规则、轮询 |
| [frontend/05-实时通信与语音告警.md](./frontend/05-实时通信与语音告警.md) | WebSocket/SIP、消息协议、告警与 TTS 队列 |
| [frontend/06-食堂与自助终端模块.md](./frontend/06-食堂与自助终端模块.md) | 自助登记、点餐/结算/后厨/保洁、选房与房间维护 |
| [frontend/07-构建部署与风险清单.md](./frontend/07-构建部署与风险清单.md) | 构建、环境、部署要点、测试基线、P0/P1/P2 风险 |

## 界面效果图与原型（docs/UI）

| 文件 | 说明 |
| --- | --- |
| [UI/](./UI/) | 效果图：v4 主台 12 张（A01~A13）+ v5 补全 16 张（B01~B06）+ v6 形态 18 张（`V6-` 前缀）+ **v7 当前版 20 张（`V7-` 前缀）** |
| [UI/_src/duty-console-v7.html](./UI/_src/duty-console-v7.html) | **当前版**原型：v6 形态冻结 + 按 `JcXx.vue` 补齐四维查询 / 详情字段 / 六模块功能对照 / A14 追溯矩阵；`?mod=B01~B06&ref=1&v=A14` 等参数 |
| [UI/_src/shoot-v7.cjs](./UI/_src/shoot-v7.cjs) | v7 出图 + 43 项断言（功能对照 + v4/v5/v6 全量形态回归） |
| [UI/_src/duty-console-v6.html](./UI/_src/duty-console-v6.html) | 上一版原型（v6 形态基线，保留对照 / 可复跑）；`?mod=B01~B06` 等参数 |
| [UI/_src/shoot-v6.cjs](./UI/_src/shoot-v6.cjs) | v6 出图 + 54 项断言（入口排序 / 弹窗范围 / 紧急区条件 / 房间维度 + v4/v5 回归） |
| [UI/_src/duty-console-v5.html](./UI/_src/duty-console-v5.html) | 上一版原型（并列工作区，保留对照 / 可复跑）；`?mod=B01~B06` 等参数 |
| [UI/_src/shoot-v5.cjs](./UI/_src/shoot-v5.cjs) | v5 出图 + 41 项断言（21 项 v4 基线回归 + 20 项常驻盯控约束） |
| [UI/_src/duty-console-v4.html](./UI/_src/duty-console-v4.html) | 上一版单文件原型（保留可复跑）；URL `?v=&mode=&layout=&dlg=` 切页 / 切版本 / 切布局 / 开弹层 |
| [UI/_src/shoot-v4.cjs](./UI/_src/shoot-v4.cjs) | 批量出图 + 21 项渲染 / 交互 / 适配断言（字号、对比度、点击区、焦点、回退、降级、时钟） |
| [12-三端功能规划与应用端值班台设计.md](./12-三端功能规划与应用端值班台设计.md) | 配套规划与验收依据 |
| [14-叫乘功能入口整合与房间维度展示调整.md](./14-叫乘功能入口整合与房间维度展示调整.md) | 当前版界面形态与验收依据（v7 冻结不变） |
| [15-原系统功能对照与逐页落点.md](./15-原系统功能对照与逐页落点.md) | 当前版功能口径与逐页落点依据 |

> 旧稿归档不删除：`UI/_v1-archive/`（v1 12 张）、`UI/_v2-archive/`（v2/v3/D12 共 20 张）。

## 三端功能设计修订（CR-02，2026-11-09）

> 依据 [公寓端/00-公寓端主要功能设计.md](./公寓端/00-公寓端主要功能设计.md) 对公寓端功能的重新规划，结合 `backend/`（既有后端梳理）与 `frontend/`（既有前端梳理），对平台端 / 公寓端 / 应用端（值班员界面）三端功能设计做了整体修订。**权威文档**：[设计变更/03-三端功能设计修订（CR-02）.md](./设计变更/03-三端功能设计修订（CR-02）.md)。

| 修订方面 | 权威落点 | 三端分册同步 |
| --- | --- | --- |
| 覆盖范围（含 14 项冲突裁决） | CR-02 §2（表 3-2~3-5） | `平台端/01`、`公寓端/01`、`应用端/01` §0 |
| 交互协议 | CR-02 §3（四层协议栈、20 编号不新增、N-01~N-18 接口） | `公寓端/04`、`公寓端/09`、`平台端/05`、`应用端/04` §0 |
| 交互数据 | CR-02 §4（上行信封、`bizType`、payload、枚举、错误码） | 同上 |
| 模块与数据表设计 | CR-02 §5、§6、§10（新增 17 张表、3 处补列、公寓本地库统一 **59 张**） | `平台端/03`、`公寓端/03`、`应用端/03` §0 |
| Asterisk 配置数据管理补遗 | [公寓端/00](./公寓端/00-公寓端主要功能设计.md) §3：`AC-01`~`AC-05` 四类数据表的字段 / CRUD / 权限，SIP 分机离线自动告警的触发条件、级别、通知与留存；权威增量见 CR-02 §10 | `公寓端/00`、`公寓端/03`、`04`、`05`、`09` |
| 两类叫乘实现方式的业务流程 | [公寓端/05](./公寓端/05-关键流程.md) §9：SIP 语音叫乘（Asterisk 主动呼叫 → 终端接听入会 → 播放提示语音 → AMI 事件上报状态）与平板叫乘（拉取任务 → 本地定时播放 → 刷脸签到 → 结果上报公寓服务）的触发条件、交互时序、状态上报机制与四条结果反馈路径；权威登记见 CR-02 §11 | `公寓端/05`、`04`、`03`、`09`、`01`、`00` |
| 关键流程变更 | CR-02 §7（F-A~F-Q） | `公寓端/05`、`平台端/06`、`应用端/05` §0 |
| **人脸数据下发管理** | [公寓端/10-人脸数据下发管理.md](./公寓端/10-人脸数据下发管理.md)：`AF-01`~`AF-06` 六项功能的触发条件、数据范围、同步与清理机制、权限隔离与异常处理；**注册链路按 CR-C25**：签到终端发起注册申请并上传人脸 → 值班员在值班台完成人员注册 → 注册成功后人脸进入公寓服务系统 → **分别**上传平台与下发公寓内设备（双路解耦、互不阻塞）；人员主数据照片与特征值按 **CR-C24** 允许跨端，业务抓拍 / 录音仍不出公寓。权威登记见 CR-02 §12（CR-C24~CR-C25、F-J、R-85~R-93、Q-30~Q-35、验收 15~17） | `公寓端/10`、`00`、`01`、`03`、`04`、`05`、`09`、`应用端/04` |
| **人员入住作业流程** | [公寓端/11-人员入住作业流程.md](./公寓端/11-人员入住作业流程.md)：`CI-01`~`CI-05` 五环节（注册与签到、入住申请、值班员审核与房间调整、#9 提报与平台运安匹配、#7 任务查询进入叫乘），含三条状态链、`apt_local_task` 补列结构、N-38~N-47 请求 / 响应字段、Q-36~Q-40 与验收 8 项；**"已入住"为流程态 + 业务事实双重表达，不新增 `gy_jcxx` 状态字段、不新增业务表**。权威登记见 CR-02 §13（CR-C26~CR-C30、F-K、R-95~R-103、验收 18~20） | `公寓端/11`、`00`~`09`、`平台端/05`、`06`、`应用端/01`、`04`、`05` |
| **消费、充值与菜品管理** | [公寓端/12-消费充值与菜品管理.md](./公寓端/12-消费充值与菜品管理.md)：`CF-01`~`CF-03` 三流程（人员消费：选餐加菜显示金额 → 查补贴 / 现金额度 → 补贴优先、现金补足 → 上报并同步平台落入人员账户；人员线下充值：**仅线下现金、扫码只识别公寓、系统只记账**，管理员核对后计入现金额度并同步平台；公寓菜品管理：阶段性食谱发布 → 终端查看菜品并加入选择菜单 → 远程点菜仅预留入口），含四条状态链、双额度 CAS 扣减与"一笔消费只一条流水"、`gy_ykt_*` / `apt_ledger_offline` / `YKT_MEALS` 补列、N-48~N-58 请求 / 响应字段、Q-41~Q-45 与验收 8 项；**不新增业务表、不新增状态字段、不新增跨端编号与 `bizType`**。权威登记见 CR-02 §14（CR-C31~CR-C35、F-L / F-M / F-N、R-104~R-113、验收 21~23） | `公寓端/12`、`00`~`09`、`平台端/01`、`03`、`04`、`05`、`06`、`应用端/01`、`03`、`04`、`05`、`07` |
| **三端一致性同步与平台统计分析** | CR-02 §15 为权威登记（**表 3-63 变更点与影响范围**、CR-C36~CR-C42、表 3-65 四能力三端对照、**表 3-66「三端状态映射与数据同步机制」唯一权威表**、F-O / F-P / F-Q、R-114~R-125、Q-46~Q-50、验收 24~26）：公寓端已完成的**平板叫乘 / 人脸签到 / 消费 / 菜品管理**在应用端与平台端同步落地业务规则、交互流程、权限控制与异常处理；平台新增 [平台端/10-公寓统计分析与排名报表.md](./平台端/10-公寓统计分析与排名报表.md)（五类指标、月 / 季 / 年报表、公寓分类 + 综合排名、`S-01`~`S-07`）。平台库新增 2 张另计（累计 5 张），公寓 **59 张**、跨端 20 编号、`v2-draft`、平台零回调不变 | `平台端/10`、`平台端/01`~`09`、`应用端/01`~`09`、`公寓端/00`~`12`、CR-02 §15 |

> `10-架构优化方案-三端拆分.md` 修订记录已追加 v1.3 / v1.4 / v1.5 / v1.6 / v1.7 / v1.8 / v1.9 / **v2.0**（三端一致性同步 + 平台统计分析，CR-02 §15）；跨端接口仍为 20 个编号，不新增、不重排；平台不回调公寓；人脸模块、入住作业流程、消费 / 充值 / 菜品管理与三端一致性同步均**不新增公寓业务表**（公寓本地库仍 59 张），平台库新增 2 张 `pl_apt_stat_*` 另计（累计 5 张）；新增表与补列均为设计定义，DDL 待阶段二契约冻结评审通过后执行；仅线下充值不接线上支付与回调，远程点菜仅预留入口；统计结果不回写任何业务状态。**变更点与影响范围见 CR-02 §15 表 3-63。**

### 公寓端小步迭代开发计划（2026-11-10）

| 项 | 内容 |
| --- | --- |
| 文档 | [公寓端/13-公寓端小步迭代开发计划.md](./公寓端/13-公寓端小步迭代开发计划.md)（v1.0，**实施排期设计稿，非设计变更**） |
| 依据 | `dev/RuoYi-Vue-master/`（后端）、`dev/RuoYi-Vue2-master/`（前端）实测代码基础 + `docs/10` §9、`公寓端/07` 表 7-1~7-8 |
| 范围 | `IT-0`~`IT-8` 九个小步迭代：**入住 + 叫乘核心闭环优先（P1）**；消费 / 充值 / 菜品 `IT-9`~`IT-11` **整体延后（P2）**；里程碑 `MS-0`~`MS-5`、交付物 `DV-0`~`DV-8`、设计文档 × 代码模块对齐矩阵、风险台账、跨迭代联调与测试、P2 衔接规划 |
| 权威关系 | 阶段划分 / 批次顺序 / 验收口径仍以 `docs/10` §9、`公寓端/07` 为准；业务规则 / 状态 / 接口仍以 CR-02 §11~§15 与各专册为准；`13` 只做排序、切分、对齐、衔接 |
| **变更点与影响范围** | 新增 1 篇排期文档；同步 `公寓端/00`、`公寓端/README.md`、`公寓端/07`、`公寓端/08`、`docs/README.md` 与 CR-02 表 0-2 **v1.7** / 表 0-3 索引。**不改动** CR-02 §12~§15 权威表述、不新增 `M7` / 阶段六 / `D-4` / `Q-*` / `R-*` 等既有编号；跨端 20 编号、`v2-draft`、公寓本地库 59 张表、平台零回调、统计结果不回写均不变 |

> 6 项 P0 排期前提（技术基线冲突、表数口径、前端入口、CI/测试、明文凭据、契约冻结）与 3 项口径偏离须经评审签字后方可执行，见 `公寓端/13` 表 13-4 / 表 13-6。

### 第二轮开发（IT-1）交付（2026-11-10）

| 项 | 内容 |
| --- | --- |
| 文档 | [公寓端/15-第二轮开发（IT-1）交付说明.md](./公寓端/15-第二轮开发（IT-1）交付说明.md)（v1.0，**实现说明，非设计变更**） |
| 范围 | 运行时基座 M0：四前缀治理与 `/apt/**` 鉴权、`gyid` 隔离、统一错误码与表 4-4 真实 HTTP 状态、401/403 处理器、审计切面落 `duty_operation_log`、分页上限 100、springdoc 分组、权限点种子、交路只读列表骨架（不含 CRUD） |
| 验证 | `mvn package` 7 模块 `BUILD SUCCESS`；41 个单测全绿；`dev/scripts/verify-it1-m0.ps1` 真实进程端到端 M0 **5/5 通过**（401 / 40301 / 40302 / 异常无堆栈外泄 / `pageSize=1000→100`） |
| 权威关系 | 阶段划分与验收仍以 `公寓端/07` 为准，业务规则 / 状态 / 接口仍以 CR-02 §11~§15 为准；`15` 只记实现、验证、口径偏离与影响范围 |
| **变更点与影响范围** | 新增 1 篇交付说明与 1 个 M0 验收脚本；同步 `公寓端/README.md`、`公寓端/14` 表 14-23、`docs/README.md` 与 CR-02 表 0-2 **v1.8**；不改动 CR-02 §12~§15 权威表述、不新增既有编号，跨端 20 编号、`v2-draft`、平台零回调、59 张表不变；**契约冻结签字与 `D5` 签字仍为 P0 待办** |

### 第三轮开发（IT-2）交付（2026-11-11）

| 项 | 内容 |
| --- | --- |
| 文档 | [公寓端/16-第三轮开发（IT-2）交付说明.md](./公寓端/16-第三轮开发（IT-2）交付说明.md)（v1.0，**实现说明，非设计变更**） |
| 范围 | M1 交路 CRUD / 启停原因审计 / 复算校验、M2 房间档案 / 房态 / `state_version` / `commandId` 幂等、主数据下行 Mock 灌数与版本标记（`/apt/master/versions`）、审计独立事务与参数校验异常分派；不含人员关联 Tab 与叫乘；前端页面已补齐，见 `公寓端/16` 第 10 章与下文「公寓端前端页面」段 |
| 验证 | `mvn package` 7 模块 `BUILD SUCCESS`；79 个单测全绿；`dev/sql/apt_rev01/10~12` 实库执行与校验通过；`dev/scripts/verify-it2-m1m2.ps1` 真实进程端到端 **24/24 通过**（第 9 章模块归置后新增 M0-5 配置导入校验） |
| 权威关系 | 阶段划分与验收仍以 `公寓端/07` 为准，业务规则 / 状态 / 接口仍以 CR-02 §11~§15 为准；`16` 只记实现、验证、口径偏离与影响范围 |
| **变更点与影响范围** | 新增 1 篇交付说明与 2 个脚本（SQL 重放、端到端验收）；同步 `公寓端/README.md`、`公寓端/14` 表 14-23、`公寓端/15` 表 15-17、`docs/README.md` 与 CR-02 表 0-2 **v1.9**；不改动 CR-02 §12~§15 权威表述、不新增既有编号，跨端 20 编号、`v2-draft`、平台零回调、59 张表不变；**契约冻结 / `D5` / `D8'` / `D3` / `D7` 签字仍为 P0 待办** |

### 公寓端集中模块 `ruoyi-apt`（2026-11-11）

| 项 | 内容 |
| --- | --- |
| 模块 | `dev/RuoYi-Vue-master/ruoyi-apt`（Maven jar，包 `com.ruoyi.apt.**`）；64 个公寓端文件从 4 个旧模块统一迁入 |
| 职责 | 四前缀接口、业务逻辑、上下文与错误码、拦截器与鉴权、审计、`apt.*` 配置、Mapper XML、79 个测试、前端静态资源挂载点 |
| 结构定位 | 上层业务模块：依赖 `ruoyi-common` / `ruoyi-framework`（传递 `ruoyi-system`），被唯一启动模块 `ruoyi-admin` 依赖；`ruoyi-framework` 仅按 Spring Security 接口 + bean 名运行时装配 401/403 处理器，编译期零反向依赖 |
| 前端 / 运维边界 | Vue 源码已落在 `dev/RuoYi-Vue2-master/src/views/apt/**`（§2.5 前端落地口径：单入口 + `sys_menu` 动态路由），构建产物可挂载到模块内 `static/apt/`；DDL 与验收脚本保持 `dev/sql/apt_rev01`、`dev/scripts` 原位，不进 Maven jar |
| 验证 | `mvn -pl ruoyi-admin -am clean package` 7 模块 `BUILD SUCCESS`；79 个单测全绿；`verify-it2-m1m2.ps1` 端到端 **24/24 通过**（含 `apt-defaults.yml` 导入与 springdoc 分组校验） |
| 权威落点 | [公寓端/02](./公寓端/02-技术基线与工程结构.md) §2.5（表 2-14 / 2-15、图 2-3）、[公寓端/16](./公寓端/16-第三轮开发（IT-2）交付说明.md) 第 9 章（归置清单、图 16-2、验证） |
| **非设计变更** | 只调整实现层模块归属与构建配置；不改动 CR-02 §12~§15 权威表述、不新增既有编号，跨端 20 编号、`v2-draft`、平台零回调、59 张表不变 |

### 公寓端前端页面补齐（2026-11-11）

| 项 | 内容 |
| --- | --- |
| 范围 | 只补齐 `IT-0`~`IT-2` 已有后端 Controller 的 4 个功能域：交路、房间、主数据版本、连通性自检；`IT-3`~`IT-11` 仅设计页面不建（判据见 `公寓端/16` 表 16-25） |
| 页面 | `dev/RuoYi-Vue2-master/src/views/apt/`：4 个菜单列表页 + 2 个隐藏详情页；API 在 `src/api/apt/**`，公共常量 / 错误提示 / 导出在 `src/utils/apt.js` |
| 规范 | 与 `system/post`、`system/user` 同构：`.app-container` + 查询 `el-form` + `el-row.mb8` 按钮区 + `el-table` + `pagination` + `el-dialog`；复用 `Pagination` / `RightToolbar` / `DictTag`、Element 语义色与主题变量、`v-hasPermi`、`$modal`、`rules` 校验、`v-loading`、响应式栅格与小屏全屏弹窗 |
| 路由与菜单 | `dev/sql/apt_rev01/13_it2_frontend_menus.sql` 新增 4 条 `C` 菜单（3101~3104），由 `getRouters` 下发、已实库执行；详情页走 `dynamicRoutes` 并按权限过滤 |
| 未开放能力 | 房间新增 / 删除 / 导入 / 主数据重同步以禁用态 + tooltip 如实呈现；导出为前端 CSV（后端无 `/export`，不伪造接口） |
| 验证 | `npm run build:prod` `exitCode=0`；菜单树 `M=1 / C=4 / F=15`、超管关联 4、置灰项 0、M0 账号 0；lints 0 |
| 权威落点 | [公寓端/16](./公寓端/16-第三轮开发（IT-2）交付说明.md) 第 10 章（表 16-25~16-30、图 16-3）、[公寓端/02](./公寓端/02-技术基线与工程结构.md) §2.5 前端落地口径、CR-02 表 0-2 **v2.1** |

## 建议阅读路径

- **第一次接触项目**：01 → 02 → 03 → 04；再看前端 01 → 02 → 04。
- **要接一个需求**：03 定位模块 → 04 看流程 → 09 查落点与风险 → 06/05 查接口和表；涉及页面时读前端 04/05。
- **线上排障**：07（外部依赖/定时任务）→ 04（状态机）→ 05（数据与状态码）→ 08（配置）；前端问题读前端 05/07。
- **准备重构**：02（分层）→ 09（技术债与建议）→ 10（三端拆分方案）→ 11（既有库结构分析）；前端读前端 02/04/07。
- **做界面设计 / 验收**：12（三端规划）→ 13（六模块补全）→ 14（入口整合与房间维度）→ 15（原系统功能对照）→ `UI/V7-A01`（四维查询与紧急区）→ `UI/_src/duty-console-v7.html`（交互）→ `UI/V7-A14`（追溯矩阵）→ `UI/A13`（28 项走查）。

## 快速事实

- 后端：Spring Boot 2.6.13 + Java 8，默认 jar 打包（可改 WAR），上下文路径 `/yktgl`，默认端口 `8081`。
- 数据库：KingbaseES 8（兼容 Oracle 语法），Redis 存 Session。
- 多公寓：同一套代码通过“客户端 IP → 公寓”解析 `gyid`，不依赖前端传参。
- 核心链路：设备/网页入寓登记 → 生成叫乘计划（Quartz 三个任务）→ 叫乘/复叫/报警/应答 → 离寓归档。
- 最大单体：后端 `jcgl/service/JcglService.java`（约 4192 行）；前端 `src/views/JcXx.vue`（5294 行）。
- 前端：Vue 2.6 + Element UI，生产静态与接口同域 `/yktgl`；登录无真实 token，公寓 `gyid` 由后端按客户端 IP 解析。