zfjia
329e27b515
docs/：系统梳理、架构优化方案、CR-02 三端功能设计修订（含 §15 三端一致性同步与平台统计分析）、公寓端/应用端/平台端分册、公寓统计分析与排名报表、公寓端小步迭代开发计划（IT-0~IT-8） dev/：RuoYi-Vue-master（后端）与 RuoYi-Vue2-master（前端）官方上游基线，未改动
49 lines
4.6 KiB
Markdown
49 lines
4.6 KiB
Markdown
# 叫乘管理系统 前端梳理文档
|
||
|
||
本目录是对 `YktVue/` 前端工程的结构化梳理，与后端文档 `../README.md` 配套使用。目标同样是给后续迭代一张“地图”：页面在哪里、数据从哪来、实时消息怎么走、改动会落到哪些文件。
|
||
|
||
> 适用范围：`YktVue/`（Vue 2 + Element UI）。
|
||
> 梳理基准：`main` 分支提交 `135a192`（2026-11-07），前端有效源码约 1.39 万行（不含备份/模板遗留）。
|
||
> 后端契约以 `yktgl/` 同提交为准，详见 [后端文档索引](../README.md)。
|
||
|
||
## 文档索引
|
||
|
||
| 文档 | 内容 | 适用场景 |
|
||
| --- | --- | --- |
|
||
| [01-前端总览与技术栈.md](./01-前端总览与技术栈.md) | 系统定位、使用角色、运行拓扑、技术栈、四类界面 | 新人入门、方案评审 |
|
||
| [02-工程结构与请求链路.md](./02-工程结构与请求链路.md) | 目录结构、启动装配、登录与路由守卫、axios 链路、API 封装与后端映射 | 找代码、改接口、排网络问题 |
|
||
| [03-路由与页面职责.md](./03-路由与页面职责.md) | 13 条路由、页面分组、入口关系、遗留页面 | 评估页面改动影响面 |
|
||
| [04-核心页面拆解-JcXx.md](./04-核心页面拆解-JcXx.md) | 值班主界面布局、状态与配色、全部操作、时间规则、轮询、历史数据 | 改叫乘业务前必读 |
|
||
| [05-实时通信与语音告警.md](./05-实时通信与语音告警.md) | 4 路 WebSocket + SIP、消息协议、告警状态机、弹窗队列、TTS 队列 | 改推送/告警/语音 |
|
||
| [06-食堂与自助终端模块.md](./06-食堂与自助终端模块.md) | 自助登记终端、点餐/结算/厨师/保洁终端、房间选择与房间维护 | 改终端类需求 |
|
||
| [07-构建部署与风险清单.md](./07-构建部署与风险清单.md) | 构建脚本、环境变量、部署要点、测试基线、P0/P1/P2 风险 | 排期、上线、评审 |
|
||
| [08-JcXx页面体验优化说明.md](./08-JcXx页面体验优化说明.md) | `JcXx.vue` 体验优化版：六类问题定位、4 处样式错误修正、前后对比验收与替换方式 | 主界面体验优化、上线前走查 |
|
||
|
||
## 建议阅读路径
|
||
|
||
- **第一次接触前端**：01 → 02 → 03 → 04。
|
||
- **接一个叫乘需求**：04 看页面与操作 → 05 看消息 → 02 查接口 → 07 查风险。
|
||
- **接一个终端/食堂需求**：06 → 02（API 封装）→ 07（构建与遗留问题）。
|
||
- **线上排障**：05（WebSocket/告警）→ 02（请求 baseURL/响应码）→ 07（已知缺陷）。
|
||
- **准备重构**：02（工程结构）→ 04（单体页面）→ 07（风险与落点）。
|
||
- **做主界面体验优化**：04 看现状 → 08 看改动与验收 → `YktVue/src/views/JcXx.optimized.vue`（新页面）→ `ui/JcXx-优化后-*.png`（五档视口对比图）。
|
||
|
||
## 快速事实
|
||
|
||
- 技术栈：Vue 2.6.12 + Vue Router 3.4.9 + Element UI 2.15.13 + axios 0.24.0 + ECharts 5.4.0，Vue CLI 4.4.6 / webpack 4。
|
||
- 启动脚本是 `npm run dev`（不是 README 里写的 `npm run serve`），开发端口 `8080`，代理 `/dev-api` → `http://127.0.0.1:8081/yktgl`。
|
||
- 生产 `publicPath` 为 `/yktgl/`，接口 `baseURL` 固定 `/yktgl`，按“前后端同域反向代理”部署设计。
|
||
- 登录走后端 `/auth/logon`：只校验公寓账号与来源 IP，**后端不返回 token**，前端落一个 `fake-token-*`，并把用户名同时写入 `gyid` 与 `loginAccount`。
|
||
- 主界面 `src/views/JcXx.vue` 5294 行，是绝对的单体页面：布局、状态、告警、TTS、SIP、历史、导出全在一个文件里。
|
||
- 实时通道有 4 类业务 WebSocket（叫乘/交路/人员/食堂）外加 1 路本机 SIP WebSocket（`ws://127.0.0.1:9004/sipclient/{gyid}`）。
|
||
- 前端没有 Vuex store、没有安装 `src/plugins/*`；`utils/permission.js` 与部分 RuoYi 模板代码是死代码。
|
||
- 已有两个纯 Node 测试脚本：`tests/alarm-state.test.cjs`、`tests/recharge-cancellation.cjs`，无 jest/npm test。
|
||
|
||
## 约定与说明
|
||
|
||
- 文档中的“行号”以本提交源码为准，重构后会漂移，优先按方法名/文件名检索。
|
||
- 前端很多页面依赖全局变量 `apiRoot`、`gyid`（由 `public/config.js` 注入），不是模块导入；搜索时直接搜变量名。
|
||
- 标注“已禁用/未接线”的代码表示界面上仍存在，但当前不会触发后端动作，改动前需确认是否要恢复。
|
||
- 本目录只做梳理，不对既有代码做修正；发现的问题统一收敛在 07 的风险清单。
|
||
- 08 附带的 `JcXx.optimized.vue` 是独立新文件，`<script>` 逐字节未改、原 `JcXx.vue` 未被修改；替换前请先备份。
|