jcgl-dev/docs/frontend/07-构建部署与风险清单.md

07 构建部署与风险清单

1. 构建脚本

package.json 实际脚本：

命令	作用	说明
npm run dev	开发服务器	端口 8080，host 0.0.0.0，启动后自动开浏览器
npm run build:prod	生产构建	输出 dist/，publicPath=/yktgl/
npm run build:stage	staging 构建	仍请求 /yktgl（环境变量未生效）
npm run preview	预览	依赖 build/index.js，仓库中不存在该文件
npm run lint	ESLint	eslint --ext .js,.vue src

环境要求：

"engines": { "node": ">=16 <19", "npm": ">=8 <11" }

实际脚本使用 node --openssl-legacy-provider（Vue CLI 4 / webpack 4 在新 OpenSSL 下的兼容做法）。Node 16 使用的是 OpenSSL 1.1.1，可能不识别该参数；建议统一到 Node 18 LTS，并锁定 npm 版本。

YktVue/README.md 仍写 npm run serve / npm run build，与 package.json 不一致，按上表为准。

2. 环境与地址矩阵

环境	启动方式	页面地址	接口 baseURL	WebSocket
开发	npm run dev	http://localhost:8080	/dev-api → 代理到 http://127.0.0.1:8081/yktgl	ws://localhost:8080/yktgl/... → 开发服务器是否代理 WS 未配置
生产	npm run build:prod	http://host/yktgl/	/yktgl	ws://host/yktgl/...
staging	npm run build:stage	同生产	/yktgl	同生产

开发代理配置在 vue.config.js：

'/dev-api': {
  target: 'http://127.0.0.1:8081/yktgl',
  changeOrigin: true,
  pathRewrite: { '^/dev-api': '' }
}

注意：

• 开发代理只配了 HTTP，没有 ws: true；本地 WebSocket 实际连的是前端 dev server 的 8080，不会自动转到 8081，需要浏览器插件/反向代理或直接改代码。
• .env.* 的 VUE_APP_BASE_API 全部未生效；request.js 写死 /dev-api 与 /yktgl。
• fileRequest.js 写死 /yktgl，开发环境导出 404。

3. 部署要点

仓库内没有 nginx、Dockerfile、部署脚本，部署依赖现场约定。按代码推断的最小拓扑：

server {
  listen 80;
  server_name _;

  # 前端静态资源
  location /yktgl/ {
    root /opt/app;             # /opt/app/yktgl/index.html
    try_files $uri $uri/ /yktgl/index.html;
  }

  # 后端接口与 WebSocket
  location /yktgl/ {
    proxy_pass http://127.0.0.1:8081/yktgl/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
  }
}

上面的两段 location /yktgl/ 会冲突，实际部署需要按路径拆分（例如静态资源用 /yktgl/static/、/yktgl/index.html，接口用 /yktgl/jcgl/ 等），或让后端同时托管静态资源。上线前必须拿到现场真实 nginx 配置，不要照抄本示例。

关键约束：

1. 静态与接口同源：publicPath、baseURL、WebSocket 路径都假定 /yktgl 由同一个 host 提供。
2. SIP 网关必须在本机 9004：值班台写死 ws://127.0.0.1:9004。
3. HTTPS 不可用：所有 WebSocket 都是 ws://，页面一旦上 HTTPS 会被浏览器按混合内容拦截。
4. 浏览器权限：自助终端使用 getDisplayMedia 录屏，需要现场授权；无人值守场景要配置 kiosk 模式与自动授权。
5. 多公寓：当前产物只能通过改 public/config.js、shijinpeng/main.vue、roomService.vue 的常量来切换，不能一套包多公寓运行。

4. 测试基线

仓库没有 jest/vitest，也没有 npm test。现有两个纯 Node 脚本，直接在 YktVue/ 下运行：

node tests/alarm-state.test.cjs
node tests/recharge-cancellation.cjs

脚本	覆盖内容	当前结果（2026-11-07）
tests/alarm-state.test.cjs	告警事件去重、新事件响铃、分组行、列表响应乱序、停止报警使在途响应失效	5 个场景通过
tests/recharge-cancellation.cjs	充值弹窗按 id 匹配取消、无关取消、后端拒绝、旧成功响应、网络失败	5 个场景通过

两个脚本通过正则截取 JcXx.vue 的方法源码再 new Function 执行，重构方法名/缩进会导致测试失效，改 JcXx.vue 后要同步检查。

建议补充的测试优先级：

1. 时间规则计算与 24 小时校验（buildFollowUpTimes、validateCallDutyTimeline）；
2. 时间输入规范化（8、815、0815、081530）；
3. 房间可选状态过滤（Room.vue 的 1/3/5/6）；
4. 请求响应码分支（11111 的业务处理）；
5. 食堂下单失败/部分明细失败的回滚策略（需要先重构）。

5. 风险清单

P0：上线/运行阻断

#	风险	证据	影响	建议
P0-1	登录态是本地假 token，守卫可绕过	Login.vue:83、router/index.js:85	任何人写 localStorage.loginAccount 即可进入；后端 Session 过期后页面仍可操作，接口才失败	后端签发 token/Session 标识，前端守卫校验并处理 401；退出调用后端
P0-2	WebSocket 断开即整页刷新，且 destroyed 主动触发	JcXx.vue:1743、:2086、:2198	后端重启/网络抖动导致值班台反复重载，告警期间可能丢失操作	改为退避重连；destroyed 只关闭连接，不调用含 reload 的方法
P0-3	自助终端导入不存在的 getRyxx，且入寓分支不提交后端	main.vue:280、:428、:675	入寓登记刷脸必抛异常；即使修复，也只广播不落库，终端主功能不可用	改为 getRyXxByRyId，并在 ryzt=1 分支调用 /jcgl/submitAll 后联调
P0-4	结算页刷脸链路被注释且不扣款	paymentPlatform.vue:212、:314	结算闭环不成立，可能“下单不扣钱”	确认该页是否在用；启用 WS 并调用 /Meals/consume
P0-5	生产强依赖 ws:// 与本机 SIP	JcXx.vue:2007、:2020	HTTPS 部署失败；值班台与 SIP 网关必须同机	统一用 getWebSocketUrl()；SIP 地址配置化
P0-6	多公寓/多终端标识硬编码	shijinpeng/main.vue:291、roomService.vue:190、各 WS 的 test33	换公寓/多终端需要改代码重打包；消息无法定向	改为登录/URL 参数/后端下发

P1：功能错误或明显数据风险

#	风险	证据	影响
P1-1	11111 被拦截器当成功返回	request.js:79	调用方漏判时会把业务失败当成功；各页面处理不一致
P1-2	网络错误无全局提示，.catch() 多为空	request.js:94	用户点按钮无反应，排障困难
P1-3	环境变量不生效、两套 baseURL	request.js:17、fileRequest.js:6	切环境/切域名必须改代码；开发导出失败
P1-4	自动导出每 10 分钟	JcXx.vue:1792	值班机持续下载，占磁盘、干扰浏览器
P1-5	点餐餐次判断恒为偏餐	MealsOrdering.vue:262	早餐/正餐菜单和价格取错
P1-6	点餐定时器调用不存在的方法	MealsOrdering.vue:257	30 分钟后报错，菜单不刷新
P1-7	扣款与建单非原子	MealsOrdering.vue:334	钱扣了没订单，或订单缺明细
P1-8	保洁完成不回写	roomService.vue:260	房间状态永远停在“正在保洁/待清扫”
P1-9	JcXx.vue 5294 行单体	src/views/JcXx.vue	修改风险高、测试只能截取方法、多人协作冲突
P1-10	防重复提交只写不判	request.js:51	双击/弱网重试可能重复充值、重复叫乘
P1-11	前端 gyid 与后端 IP 解析 gyid 双源	JcXx.vue:1728、后端 getGyIdByIp	登录名不是公寓代码时，推送收不到/查询与推送范围不一致

P2：代码质量与遗留

#	风险	证据
P2-1	setRowStyle 渲染期修改 this.message	JcXx.vue:3723
P2-2	formatTime 重复定义	JcXx.vue:2276、:3153
P2-3	JcXx.vue 导入不存在的 auditJlXx	JcXx.vue:1392
P2-4	handleDelete 使用未安装的 $modal	JcXx.vue:3034
P2-5	plugins/* 未安装、utils/permission.js 依赖不存在的 store	src/plugins/、src/utils/permission.js
P2-6	App.vue 结尾多字面量 3	App.vue:32
P2-7	Home.vue 使用未注册的 <test1>	Home.vue:6
P2-8	遗留文件：JcXx.vue.bak_mojibake、RoomLook copy.vue、media.vue	src/views/、src/components/
P2-9	后厨 BroadcastChannel 监听器泄漏	chefOrders.vue:412
P2-10	channel_rly_jc 无人监听	main.vue:285
P2-11	状态 6 选房确认文案 undefined	Room.vue:229
P2-12	批量房间操作无失败回滚/提示	RoomLook.vue:313
P2-13	无 404 路由	router/index.js
P2-14	README 命令与实际脚本不一致	YktVue/README.md

6. 改动落点速查

需求类型	首选落点	需要同步
新增业务接口	src/api/jcgl/jcgl.js	页面调用、后端文档 06
改登录/鉴权	Login.vue、utils/auth.js、router/index.js、request.js	后端 /auth/*、部署 Session
改 WebSocket/告警	JcXx.vue 的 initWebSocket、jcwebsocketonmessage、syncAlarmVoice	后端 Jcwebsocket、文档 05
改叫乘操作	JcXx.vue 对应 handle* 方法	后端 JcglController/Service、文档 04
改房间状态	Room.vue、RoomLook.vue	/jcgl/getRoomList、/clean/*、状态码表
改自助终端	shijinpeng/main.vue	rlywebsocket、/jcgl/submitAll、设备录像协议
改食堂	zhengchuang/views/*、api/zhengchuang/mealsOrdering.js	/Meals/*、MealsWebsocket、广播协议
改构建/代理	vue.config.js、request.js、fileRequest.js	nginx、.env.*、部署文档

7. 待确认问题

以下问题无法仅从代码判断，需要业务/现场确认：

1. paymentPlatform 是否仍在用？如果不用，是否下线路由和页面？
2. shijinpeng/main.vue 的入寓登记是否还有现场依赖？getRyxx 是改名遗漏还是有意停用？
3. 现场是否有 HTTPS/域名计划？如果有，WebSocket 必须改 wss，SIP 也要确认是否支持 TLS。
4. 自动导出 Excel 是业务要求还是调试遗留？如果是要求，应改为后端定时任务或手工导出。
5. 多公寓是否仍靠“一套代码改常量分别打包”？是否有统一配置中心计划？
6. 值班台是否会在同一浏览器打开多个页面？location.reload() 和 BroadcastChannel 的假设都基于单页/单终端。
7. 后端 jcwebsocket 的 cz_cancel、autoCallFailed、missedCallWarning 消息是否已稳定？后端文档需要同步补齐。

8. 建议的迭代顺序

1. 先修 P0 阻断：自助终端导入、结算闭环确认、WebSocket 重连、鉴权方案。
2. 再修 P1 数据风险：扣款/建单一致性、自动导出、餐次判断、时间规则测试。
3. 然后做结构治理：拆分 JcXx.vue（布局 / 列表 / 告警 / 操作 / 历史），统一请求层与环境配置。
4. 最后清遗留：删除模板页面/插件/备份文件，补 404、补测试、更新 README。

9. 文档维护

• 本目录与后端文档同基准提交；改接口、改路由、改 WebSocket 消息时同步更新对应章节。
• 行号会随重构漂移，检索时优先用方法名/文件名。
• 新增前端文档时在 README 索引中登记，并保持与 后端文档索引 的交叉链接。