jcgl/docs/frontend/01-前端总览与技术栈.md

01 前端总览与技术栈

1. 系统定位

前端是“叫乘 / 公寓管理”系统的操作层，服务四类现场角色，共用一个 Vue 工程、一套构建产物：

界面	主要使用者	典型设备	入口路由
叫乘值班控制台	公寓值班员	值班室大屏 / 双屏 PC	/jcxx（登录后默认页）
入寓自助终端	乘务员本人	触摸屏一体机（带摄像头、读卡器）	/ykt_main
食堂终端	乘务员、厨师、保洁	点餐屏 / 后厨屏 / 保洁屏	/MealsOrdering、/paymentPlatform、/chefOrders、/roomService
房间维护与同步查询	值班员、管理员	PC	值班台弹窗 + /synJcXx

前端不承担鉴权与公寓归属判断：公寓 gyid 最终以后端按客户端 IP 解析的结果为准。前端登录时把用户名写入 localStorage.gyid，主要用于 WebSocket 的 {username} 路径段和部分页面查询参数；两者不一致是本系统最常见的联调问题来源，详见 02 与 07。

2. 运行拓扑

flowchart LR
  subgraph Browser["浏览器（现场终端）"]
    Duty["值班控制台 JcXx.vue"]
    Self["自助终端 shijinpeng/main.vue"]
    Meal["食堂终端 zhengchuang/*"]
    RoomUI["房间选择/维护 Room.vue / RoomLook.vue"]
  end

  subgraph SameOrigin["同域静态资源"]
    Static["/yktgl/ 前端 dist"]
  end

  subgraph Backend["后端 yktgl（8081，context /yktgl）"]
    API["REST /jcgl /jlgl /Meals /clean /recharge /heartBeat /excel /jwDataLog"]
    WS["WebSocket /jcwebsocket /jlwebsocket /rlywebsocket /MealsWebsocket"]
    SIPGW["SIP 客户端网关 :9004 /sipclient"]
  end

  PBX["Asterisk / AMI / 广播设备"]

  Duty --> Static
  Self --> Static
  Meal --> Static
  RoomUI --> Static
  Duty -->|"axios baseURL /yktgl（生产）或 /dev-api→/yktgl（开发）"| API
  Self -->|"axios 同源 /yktgl"| API
  Meal -->|"axios 同源 /yktgl"| API
  RoomUI -->|"axios 同源 /yktgl"| API
  Duty -->|"ws://host/yktgl/jcwebsocket/{gyid}"| WS
  Duty -->|"ws://host/yktgl/jlwebsocket/{gyid}"| WS
  Self -->|"ws://host/yktgl/rlywebsocket/test33"| WS
  Meal -->|"ws://host/yktgl/MealsWebsocket/test33"| WS
  Duty -->|"ws://127.0.0.1:9004/sipclient/{gyid}"| SIPGW
  SIPGW --> PBX
  Backend --> PBX

要点：

• 静态资源与接口同域。生产 vue.config.js 的 publicPath 是 /yktgl/（vue.config.js:21），axios 生产 baseURL 也是 /yktgl（request.js:17），依赖反向代理把 /yktgl/* 转到后端。
• WebSocket 地址是硬编码相对当前主机，没有走 public/config.js 里的 getWebSocketUrl()；协议固定 ws://，HTTPS 部署会失败。
• SIP 地址固定本机 127.0.0.1:9004，意味着值班台必须与 SIP 网关同机部署。
• 浏览器不直连 Asterisk，语音呼叫由后端/SIP 网关完成；前端只发“呼叫/停止”指令。

3. 技术栈

层次	选型	版本	说明
框架	Vue	2.6.12	Options API，无 Composition API
路由	vue-router	3.4.9	hash 默认模式，守卫只判断本地登录痕迹
状态	Vuex	3.6.0	依赖已声明，但工程没有 src/store，实际未使用
UI	Element UI	2.15.13	大量内联样式覆盖主题
请求	axios	0.24.0	统一拦截器 + 两套实例（request.js / fileRequest.js）
图表	ECharts	5.4.0	依赖已声明，业务页面基本未使用
构建	Vue CLI / webpack	4.4.6 / 4	--openssl-legacy-provider 兼容新 Node
样式	Sass	1.32.13	lang="scss"，含全局大屏样式
工具	js-cookie、file-saver、jsencrypt、quill、vuedraggable、vue-cropper	见 package.json	多数为 RuoYi 模板遗留

工程来源是 RuoYi-Vue 模板（package.json 的 repository 仍指向 RuoYi），但业务页面已大幅改造，模板的权限、字典、布局、Vuex 体系基本被剥离或未接线。

4. 四类界面与页面清单

flowchart TB
  Login["/login 登录"] --> Duty["/jcxx 值班控制台"]
  Duty -->|弹窗| Room["Room.vue 选房"]
  Duty -->|弹窗| RoomLook["RoomLook.vue 房间维护"]
  Duty -->|弹窗| History["历史叫乘 / 交路 / 人员 / 充值"]
  Login --> Self["/ykt_main 自助终端"]
  Login --> MealOrder["/MealsOrdering 点餐"]
  Login --> Pay["/paymentPlatform 结算"]
  Login --> Chef["/chefOrders 后厨"]
  Login --> Clean["/roomService 保洁"]
  Login --> Syn["/synJcXx 运安同步查询"]

页面规模与职责：

文件	行数	职责	详细说明
src/views/JcXx.vue	5294	值班主界面：叫乘列表、全部操作、实时告警、SIP、历史、导出	04
src/shijinpeng/main.vue	943	自助入寓/离寓登记、刷脸、餐补查询、录像	06
src/zhengchuang/views/MealsOrdering.vue	988	乘务员自助点餐、刷脸支付、购物车	06
src/zhengchuang/views/paymentPlatform.vue	570	自助结算金额录入	06
src/zhengchuang/views/chefOrders.vue	532	后厨订单队列、完成订单、新单提示	06
src/zhengchuang/views/roomService.vue	339	保洁房间卡片、清扫计时	06
src/components/Room.vue	332	房间选择器，按楼层分组、推荐房、状态过滤	06
src/components/RoomLook.vue	618	房间维护：多选同状态房间、开始/结束保洁、停用/恢复	06
src/views/SynJcXx.vue	101	运安同步叫乘数据只读查询	03
src/views/Login.vue	206	公寓账号登录	02

5. 全局变量与页面差异

public/config.js 在 index.html 中以脚本方式先于应用加载，向 window 注入：

变量	值	用途
apiRoot	window.location.host	拼接 WebSocket 地址；注意不含协议
gyid	localStorage.getItem('gyid') || 'TLXC'	全局公寓标识兜底值

不同页面对这两个变量的使用并不一致：

页面	WebSocket 地址	公寓标识
JcXx.vue	ws://{apiRoot}/yktgl/{jc,jl}websocket/{this.gyid}	this.gyid = localStorage.gyid || 全局 gyid（JcXx.vue:1728）
shijinpeng/main.vue	ws://{apiRoot}/yktgl/rlywebsocket/test33	页面内硬编码 gyid: "SYBXC"、gymc: "沈阳站公寓"（main.vue:291）
MealsOrdering.vue / paymentPlatform.vue	ws://{apiRoot}/yktgl/MealsWebsocket/test33	无
roomService.vue	无	硬编码 gyid: "SYBXC"（roomService.vue:190）
public/config.js 注释	—	保留 PJXC / SJTXC / BYQXC 等多公寓 IP/gyid 手工切换示例

结论：这个工程原本按“一套代码、多个公寓分别部署”的方式维护，多公寓配置靠改 config.js 注释或改页面常量，而不是运行时配置中心。

6. 关键设计约束

1. 同域部署：静态资源 /yktgl/、接口 /yktgl/*、WebSocket /yktgl/*websocket 必须由同一反向代理暴露。
2. 后端按 IP 识别公寓：/jcgl/* 的大量接口不接收前端 gyid，后端用 zdwhService.getGyIdByIp(request) 解析（见 后端 03）。前端传的 gyid 主要用于推送寻址。
3. WebSocket username 必须等于公寓 gyid：JcWebsocket 只向 username == gyid 或 all 的会话发送（见 后端 07）。因此值班员登录名通常就是公寓代码。
4. 无全局状态：所有页面状态各自维护，跨页面协作靠 localStorage、BroadcastChannel 和 location.reload()。
5. 单机终端假设：SIP、自助终端、食堂终端都存在本机地址或固定 test33/SYBXC 的硬编码，跨机部署需要先改代码。

7. 下一步

• 想看一次请求从点击到后端：读 02-工程结构与请求链路。
• 想改叫乘主界面：直接读 04-核心页面拆解-JcXx。
• 想改实时告警：读 05-实时通信与语音告警。