53 lines
4.8 KiB
Markdown
53 lines
4.8 KiB
Markdown
# 叫乘管理系统 梳理文档
|
||
|
||
本目录是对既有代码的结构化梳理，目的是为后续迭代提供统一的“地图”：知道每个业务落在哪个包/页面、数据怎么流转、接口和外部系统怎么对接、改动时应该看哪些文件。
|
||
|
||
> 后端：`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) | 平台端/公寓端/应用端拆分：现状评估、目标架构、职责边界、模块与数据归属、接口契约、设备接入、部署与迁移路径 | 架构评审、重构设计 |
|
||
| [11-既有数据库结构分析.md](./11-既有数据库结构分析.md) | 实测库级参数、40 表清单与规模、零主键零索引等结构缺陷、数据质量实证、表归属矩阵、类型归一与拆表建议 | 库设计评审、迁移改造 |
|
||
|
||
## 前端文档
|
||
|
||
前端梳理独立成册，入口见 [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 风险 |
|
||
|
||
## 建议阅读路径
|
||
|
||
- **第一次接触项目**：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。
|
||
|
||
## 快速事实
|
||
|
||
- 后端：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 解析。
|