18 KiB
18 KiB
叫乘管理系统 梳理文档
本目录是对既有代码的结构化梳理，目的是为后续迭代提供统一的“地图”：知道每个业务落在哪个包/页面、数据怎么流转、接口和外部系统怎么对接、改动时应该看哪些文件。
后端：
yktgl/；前端：YktVue/，见 frontend/。 梳理基准：main分支提交135a192（2026-11-07）。
文档索引
| 文档 | 内容 | 适用场景 |
|---|---|---|
| 01-系统总览.md | 业务定位、角色、运行形态、技术栈、关键设计约束 | 新人入门、方案评审 |
| 02-工程结构与分层.md | 目录/包结构、分层约定、启动流程、公共组件 | 找代码、定落点 |
| 03-业务模块地图.md | 各业务模块职责、控制器、服务、依赖关系 | 评估改动影响面 |
| 04-核心业务流程.md | 入住、叫乘、复叫、报警、应答、离寓、房间、交路同步、卡务 | 改业务逻辑前必读 |
| 05-数据模型.md | 核心表、字段语义、状态码、归档与锁 | 写 SQL / 改表 / 排查数据 |
| 06-接口清单.md | Web 接口与设备接口清单、协议枚举 | 联调、接口扩展 |
| 07-外部集成与定时任务.md | Asterisk AMI、运安 SOAP、中心 HTTP、WebSocket、Quartz/@Scheduled | 排障、集成改造 |
| 08-部署与配置.md | Profile、数据库/Redis、资源目录、升级脚本 | 部署、环境切换 |
| 09-迭代指引与风险清单.md | 技术债、改动落点速查、待确认问题、迭代建议 | 排期、评审 |
| 10-架构优化方案-三端拆分.md | 平台端/公寓端/应用端拆分：现状评估、目标架构、职责边界、模块与数据归属、接口契约、设备接入、部署与迁移路径；含公寓端细化（RuoYi-Vue + MySQL 技术基线、应用端复用实现、语音域 Asterisk/AMI/分机/录音与配置收敛对账）及 KingbaseES→MySQL 选型与迁移 | 架构评审、重构设计 |
| 11-既有数据库结构分析.md | 实测库级参数、40 表清单与规模、零主键零索引等结构缺陷、数据质量实证、表归属矩阵、类型归一与拆表建议 | 库设计评审、迁移改造 |
| 12-三端功能规划与应用端值班台设计.md | v4 三端功能范围 / 模块划分 / 职责边界 / 协作关系；应用端「1 台 + 2 层」信息架构与四区值班台；交互与状态反馈、异常与容错、8 类 28 项现场及中老年适配检查项 | 界面重构评审、前端交付与验收走查 |
| 13-值班员端功能补全与常驻盯控导航设计.md | v5 增量：六个功能模块（换乘 / 叫乘历史查询 / 交路管理 / 房间管理 / 交班日志 / 系统告警）、统一入口与导航、常驻盯控骨架与跨模块实时告警、范围变更登记与 41 项验收 | 界面补全评审、前端实现与走查 |
| 14-叫乘功能入口整合与房间维度展示调整.md | v6 形态增量：六入口并入顶部按钮操作区（排在「记录与自检」之后）、六模块全部弹出窗口化且主控区不变、紧急处置区显示全部报警 / 正在执行房间、叫乘信息以房间为单位（2 |
界面整合评审、前端实现与走查 |
| 15-原系统功能对照与逐页落点.md | v7 功能增量：以 JcXx.vue 全文 5295 行为事实源建立追溯矩阵；补齐主台四维查询、详情原系统字段与时刻口径、六模块原系统筛选与功能对照条、吸底值班条口径；10 项原系统缺陷明确不继承；43 项验收 |
功能对齐评审、前端实现与走查 |
前端文档
前端梳理独立成册，入口见 frontend/README.md：
| 文档 | 内容 |
|---|---|
| frontend/01-前端总览与技术栈.md | 四类界面、运行拓扑、技术栈、全局变量 |
| frontend/02-工程结构与请求链路.md | 启动装配、登录守卫、axios、API 与后端映射 |
| frontend/03-路由与页面职责.md | 13 条路由、入口关系、遗留页面 |
| frontend/04-核心页面拆解-JcXx.md | 值班台布局、状态、操作、时间规则、轮询 |
| frontend/05-实时通信与语音告警.md | WebSocket/SIP、消息协议、告警与 TTS 队列 |
| frontend/06-食堂与自助终端模块.md | 自助登记、点餐/结算/后厨/保洁、选房与房间维护 |
| frontend/07-构建部署与风险清单.md | 构建、环境、部署要点、测试基线、P0/P1/P2 风险 |
界面效果图与原型（docs/UI）
| 文件 | 说明 |
|---|---|
| UI/ | 效果图：v4 主台 12 张（A01V6- 前缀）+ v7 当前版 20 张（V7- 前缀） |
| UI/_src/duty-console-v7.html | 当前版原型：v6 形态冻结 + 按 JcXx.vue 补齐四维查询 / 详情字段 / 六模块功能对照 / A14 追溯矩阵；?mod=B01~B06&ref=1&v=A14 等参数 |
| UI/_src/shoot-v7.cjs | v7 出图 + 43 项断言（功能对照 + v4/v5/v6 全量形态回归） |
| UI/_src/duty-console-v6.html | 上一版原型（v6 形态基线，保留对照 / 可复跑）；?mod=B01~B06 等参数 |
| UI/_src/shoot-v6.cjs | v6 出图 + 54 项断言（入口排序 / 弹窗范围 / 紧急区条件 / 房间维度 + v4/v5 回归） |
| UI/_src/duty-console-v5.html | 上一版原型（并列工作区，保留对照 / 可复跑）；?mod=B01~B06 等参数 |
| UI/_src/shoot-v5.cjs | v5 出图 + 41 项断言（21 项 v4 基线回归 + 20 项常驻盯控约束） |
| UI/_src/duty-console-v4.html | 上一版单文件原型（保留可复跑）；URL ?v=&mode=&layout=&dlg= 切页 / 切版本 / 切布局 / 开弹层 |
| UI/_src/shoot-v4.cjs | 批量出图 + 21 项渲染 / 交互 / 适配断言（字号、对比度、点击区、焦点、回退、降级、时钟） |
| 12-三端功能规划与应用端值班台设计.md | 配套规划与验收依据 |
| 14-叫乘功能入口整合与房间维度展示调整.md | 当前版界面形态与验收依据（v7 冻结不变） |
| 15-原系统功能对照与逐页落点.md | 当前版功能口径与逐页落点依据 |
旧稿归档不删除：
UI/_v1-archive/（v1 12 张）、UI/_v2-archive/（v2/v3/D12 共 20 张）。
三端功能设计修订（CR-02，2026-11-09）
依据 公寓端/00-公寓端主要功能设计.md 对公寓端功能的重新规划，结合
backend/（既有后端梳理）与frontend/（既有前端梳理），对平台端 / 公寓端 / 应用端（值班员界面）三端功能设计做了整体修订。权威文档：设计变更/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 §3：AC-01~AC-05 四类数据表的字段 / CRUD / 权限，SIP 分机离线自动告警的触发条件、级别、通知与留存；权威增量见 CR-02 §10 |
公寓端/00、公寓端/03、04、05、09 |
| 两类叫乘实现方式的业务流程 | 公寓端/05 §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：AF-01AF-06 六项功能的触发条件、数据范围、同步与清理机制、权限隔离与异常处理；注册链路按 CR-C25：签到终端发起注册申请并上传人脸 → 值班员在值班台完成人员注册 → 注册成功后人脸进入公寓服务系统 → 分别上传平台与下发公寓内设备（双路解耦、互不阻塞）；人员主数据照片与特征值按 CR-C24 允许跨端，业务抓拍 / 录音仍不出公寓。权威登记见 CR-02 §12（CR-C24 |
公寓端/10、00、01、03、04、05、09、应用端/04 |
| 人员入住作业流程 | 公寓端/11-人员入住作业流程.md：CI-01CI-05 五环节（注册与签到、入住申请、值班员审核与房间调整、#9 提报与平台运安匹配、#7 任务查询进入叫乘），含三条状态链、apt_local_task 补列结构、N-38gy_jcxx 状态字段、不新增业务表。权威登记见 CR-02 §13（CR-C26 |
公寓端/11、00~09、平台端/05、06、应用端/01、04、05 |
| 消费、充值与菜品管理 | 公寓端/12-消费充值与菜品管理.md：CF-01CF-03 三流程（人员消费：选餐加菜显示金额 → 查补贴 / 现金额度 → 补贴优先、现金补足 → 上报并同步平台落入人员账户；人员线下充值：仅线下现金、扫码只识别公寓、系统只记账，管理员核对后计入现金额度并同步平台；公寓菜品管理：阶段性食谱发布 → 终端查看菜品并加入选择菜单 → 远程点菜仅预留入口），含四条状态链、双额度 CAS 扣减与"一笔消费只一条流水"、gy_ykt_* / apt_ledger_offline / YKT_MEALS 补列、N-48bizType。权威登记见 CR-02 §14（CR-C31 |
公寓端/12、00~09、平台端/01、03、04、05、06、应用端/01、03、04、05、07 |
| 三端一致性同步与平台统计分析 | CR-02 §15 为权威登记（表 3-63 变更点与影响范围、CR-C36S-01~S-07）。平台库新增 2 张另计（累计 5 张），公寓 59 张、跨端 20 编号、v2-draft、平台零回调不变 |
平台端/10、平台端/0109、应用端/0109、公寓端/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（v1.0，实施排期设计稿，非设计变更） |
| 依据 | dev/RuoYi-Vue-master/（后端）、dev/RuoYi-Vue2-master/（前端）实测代码基础 + docs/10 §9、公寓端/07 表 7-1~7-8 |
| 范围 | IT-0IT-8 九个小步迭代：入住 + 叫乘核心闭环优先（P1）；消费 / 充值 / 菜品 IT-9IT-11 整体延后（P2）；里程碑 MS-0MS-5、交付物 DV-0DV-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（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 待办 |
建议阅读路径
- 第一次接触项目：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 解析。