packServer/README.md
liufumingren cfe318d817 docs(readme): 目录与进度表对齐当前代码(手机网页、端口、11 月新功能)
- 目录树补 mobile-web/、tools/,说明扩展现在走 esbuild 压缩产物分发
- 端口表补手机网页 7303/7304 与后台服务局域网 16100(UDP)/16101(TCP)
- 进度补:微信 Native 支付、工作台多路面单摄像头、面单多码同框、
  NVR 唯一性按主体、回放合并 xstack + 硬件编码、扩展上架 Edge 商店、端口迁出 173xx
- 勾掉「扩展目标地址仍是百度占位」的过期 TODO(默认已指向线上 /local 页)
- 环境变量补 WXPAY_* / PAY_ORDER_TTL,公开接口补微信支付回调
- desktop/README:去掉重复的「构建 / 运行 / 发布」标题,本机接口一节补后台服务端口

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-18 16:07:31 +08:00

182 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 云仓视频溯源系统
前后端分离 + 一个浏览器扩展 + 一个 Windows 本机软件(WPF)+ 一个 Android 设备端 + 一个手机网页:
```
packService/
├── backend/ # Egg.js 3(纯 API;MySQL + Redis)
├── frontend/ # Vite + Vue3 + TypeScript(用户端 SPA)
├── extension/ # Chrome/Edge MV3 扩展:注入第三方 WMS 页面,把运单号加工成溯源入口
├── desktop/ # WPF 本机软件:HTTP 16000(查询/唤起/下载)+ WS 16001(拉通道/预览/云台)+ yuncang:// 启动协议
├── AndroidStation/ # Android 设备端:UDP 48899 被桌面端发现 + TCP 8087 推送 USB 扫码结果
├── mobile-web/ # 手机网页(Vue3 + WeUI):登录 / 首页 / 我的,独立工程(还没接入发布流程)
└── tools/ # 现场排查脚本:scan-web-viewer.ps1(按网页标题扫局域网 80 端口)
```
## 端口约定(⚠️ 本机项目多,不要用 Vite 默认的 5173)
| 用途 | 端口 | 启动方式 |
| --- | --- | --- |
| 前端 dev(Vite) | **7301** | `cd frontend && npm run dev` |
| 前端 preview(dist) | **7302** | `cd frontend && npm run preview` |
| 后端 dev | **7300** | `cd backend && npm run dev` |
| 手机网页 dev | **7303** | `cd mobile-web && npm run dev` |
| 手机网页 preview | **7304** | `cd mobile-web && npm run preview` |
| 本机软件(WPF,只监听 loopback) | **16000**(HTTP)/ **16001**(WebSocket) | `cd desktop && dotnet run`(详见 [`desktop/README.md`](desktop/README.md)) |
| 后台服务(Windows 服务,局域网) | **16100**(UDP 发现)/ **16101**(TCP 取流) | 随桌面端安装,`YUNCANG_EDGE_UDP_PORT` / `YUNCANG_EDGE_HTTP_PORT` 可覆盖 |
| 扩展自测页(可选) | **7310** | `npx --yes http-server extension/test -p 7310` |
- 前端端口可用 `VITE_PORT=7311 npm run dev` 覆盖;`strictPort: true` → 端口被占用时**直接报错**,不会偷偷换端口(否则代理会对不上)。
- 手机网页端口可用 `VITE_MOBILE_PORT` / `VITE_MOBILE_PREVIEW_PORT` 覆盖,`/api` 同样反代到 `127.0.0.1:7300`。
- 后端端口可用 `PORT=7400 npm run dev` 覆盖(默认 **7300**,配置在 `backend/config/config.default.js` 的 `config.cluster.listen.port`)。
- 前端调接口走**同源代理**:Vite 把 `/api`、`/health` 反代到后端(默认 `127.0.0.1:7300`,用 `VITE_BACKEND` 覆盖)。
- 联调更方便的做法:直接开后端 `:7300`,由后端(dev)把 `/` 反代到前端 dev server(`FRONTEND_DEV_SERVER`,默认 `http://127.0.0.1:7301`)。
- **上线**:前端构建产物发布到 `deployRoot/frontend`,由 **nginx 直接托管**(静态资源 + SPA fallback);`/api/*`、`/health` 由 nginx 反代到 Egg,`/download/*` 由 nginx 直接托管安装包目录。发布走 `cd backend && npm run deploy`(双实例蓝绿发布,详见 [`backend/README.md`](backend/README.md)「发布到服务器」)。
- **安装包分发**(`/download/` 由 nginx 直接托管):桌面端安装包(MSI / EXE)在 `/download/desktop/`、Android APK 在 `/download/android_client/`,
版本信息分别是 `/download/version.json`(桌面端自动更新读这个地址,不能改)和 `/download/android_client/version.json`。
单独发版:`cd backend && npm run desktop:publish` / `npm run android:publish`(都只构建+上传,不动后端)。
- **生产强制 HTTPS**:站点 vhost 对 HTTP 一律 `301` 到 HTTPS,HSTS 由 `front.conf` 各 location 声明;后端 `config.proxy = true`,`SITE_URL` / `desktopBaseUrl` 均为 `https://`,桌面端安装包内嵌地址也是 HTTPS。
- **AndroidStation 设备端**不用这些开发端口:它在局域网上监听 **TCP 8087**(桌面端读扫码结果)和 **UDP 48899**(被桌面端发现),详见 [`AndroidStation/README.md`](AndroidStation/README.md)。
## 身份与通讯约定
| 调用方 | 令牌 | 典型接口 |
| --- | --- | --- |
| 前端 SPA(用户端,toC:用户只管自己的设备/记录) | `Authorization: Bearer <user JWT>`(typ=user) | `/api/web/*`(登录/资料/设备/记录) |
| 设备(扫描枪、中控) | `Authorization: Bearer <device JWT>`(typ=scanner) | `/api/device/login`、`/api/scanner/*`、`/api/scan/*` |
| 公开 | 无 | `/api/wechat-gateway/notify`(网关回调,**靠签名**)、`/api/pay/wechat/notify`(微信支付回调,**靠 APIv2 验签**)、`/api/wechat-gateway/qrcode.{svg,gif}`、`/api/wechat/{status,qrcode.svg}`(设备扫码登录的登录码)、`/api/web/auth/*` |
扫码登入用到的 `WX_GATEWAY_*` 只配在**服务端**(appSecret 绝不能进前端/二维码):服务端申请二维码、验签收网关回调,
前端只负责显示二维码和长轮询结果。
前端**不用 cookie/session**:令牌存本地、放 header,所以没有跨域 cookie 与 CSRF 的问题
(JWT 用 `typ` 声明隔离:用户令牌调设备接口一律 401)。
## 当前进度
- [x] 目录拆分为 `backend/` + `frontend/`
- [x] 前端脚手架(Vite + Vue3 + TS)跑通,登录页走通 `/api/web/auth/*`
- [x] 浏览器扩展 `extension/`(MV3,**源码零构建**;分发用 esbuild 压缩产物 `extension/dist`,不合并文件):注入第三方 WMS 页面,在运单号**旁边**渲染「查看打包视频」按钮 → 点按钮打开溯源页
- [x] **后端去掉服务端渲染**:删除 `app/controller/page/`、`app/view/`、`app/lib/page.js`、nunjucks / session / CSRF 配置与依赖,后端只剩 JSON 接口
- [x] 页面全部迁移到前端:登录 / 注册 / 找回密码 / 扫码 / 扫码确认 / 首页统计 / 设备管理 / 扫码记录 / 个人中心 / 测试页(仅开发构建,生产不打包)
- [x] 后端 dev 反代前端(`app/middleware/frontend.js`);生产由 nginx 直接托管前端构建产物(Egg 只提供 API)
- [x] 运维接口加鉴权:`app/controller/admin/` → `internal/`,统一挂 `middleware.internalAuth()`
- [x] 新增用户端接口:`/api/web/{stats,devices*,records,test/*}`(范围一律限定在令牌对应的那个用户)
- [x] 工作台成员登录(2026-10-24):成员扫码登入(是主体成员记工号/姓名,否则记昵称);
「成员」弹窗看当前/历史成员、手动下线、一键全部下线;扫码上报刷新最后活跃时间,超过设置(团购 1h / 散单 30min)由定时任务自动下线;
运单查询(`/api/web/pack-query`)每条记录带上当时的打包人员 `packers`
- [x] **对接微信登录网关(2026-10-28)**:扫码登录 / 绑定微信 / 工作台扫码登入统一走
[gateway.gztbyc.com](https://gateway.gztbyc.com/#/docs)(申请临时码 → 本地画二维码 → 手机微信确认 → 网关带签名回调);
- **废弃自建登录码**:登录页的 6 位扫码串码(`GET /api/wechat/login`)与工作台的 `WSC-` 登录码都已删除,
二维码改为**按需生成、一次有效**;
- **个人中心新增「微信绑定」**:扫码绑定/解绑;绑定后可直接用微信扫码登录,也能扫码登入工作台;
- **主体成员改为「扫码绑定」**:管理员出二维码 → 成员用微信扫码 → 微信已有平台账号的直接继承(自动建的临时账号删掉),
还没有账号的由服务端自动给这名成员建号并把微信绑成它的登录方式;旧的 6 位绑定码与 `/wechat?bind=<码>` 手机确认页已删除;
绑错了可以「解除绑定」重来;
- 配置见 `WX_GATEWAY_APP_KEY` / `WX_GATEWAY_APP_SECRET`(不配则扫码入口提示「未开通」),
网关管理台的「服务端通知地址」要配成 `https://<域名>/api/wechat-gateway/notify`
- [x] **移除自建的微信授权表(2026-10-29)**:微信侧接入收敛到登录网关后,删除 `wechat_oauth`(公众号网页授权)与
`wechat_mp_accounts`(小程序一键登录)两张表及其代码/接口/环境变量
(详见 [`backend/README.md`](backend/README.md) 的「已下线:小程序微信一键登录」)
- [x] **平台管理员 + 平台管理台(2026-10-29)**:新表 `admin_members`(平台管理员名单,`INTERNAL_ADMIN_IDS` 为内置/救急入口);
平台管理员登录后左侧菜单多出「平台管理」:**主体管理**(所有主体 + 直接改授权到期时间:选时间或顺延)、
**订单管理**(所有订单 + 确认订单 = 支付回调的同一套后续动作)、**管理员**(成员列表 + 按账号添加/移除)
- [x] **平台管理 · 套餐管理(2026-11-07)**:左侧「平台管理」新增**套餐管理**(`/admin/plans`):
新增 / 改价 / 改天数 / 上下架 / 删除续期套餐;续期下单只按库里的售价算钱,改完即生效、不用发版
(接口 `GET/POST/PUT/DELETE /api/web/admin/plans`,详见 [`backend/README.md`](backend/README.md))
- [x] **登录入口与文档站(2026-11-07)**:
- **`/` 就是入口**:已登录 → 自动进看板 `/dashboard`;未登录 → **原地**显示登录页(地址保持在 `/`,不再跳 `/login`);
看板路由从 `/` 挪到 `/dashboard`,侧边栏「首页」与各处「被拒绝」回跳同步改过去;
- **文档站** `/doc/**`:后端生成的**静态 HTML**(顶部 tab 切栏目、左侧直接列出该栏目的内容页、右侧本页目录),
页面保存后自动重生成,新链接追加到 `/sitemap.txt`;
- **平台管理 · 文档管理**(`/admin/doc`):**栏目 → 内容页**(Markdown)两级简易 CMS,保存即重生成;
- 登录页右下角、顶栏(登录后)与看板右上角都有进入文档站的链接
- [x] **待支付订单 2 小时自动失效(2026-10-29)**:下单后 2 小时(`PAY_ORDER_TTL`,默认 7200 秒)内未支付,
订单自动关闭(`status=2`);之后的支付回调 / 手工确认一律 409。与微信扫码支付二维码有效期对齐,
定时任务每分钟扫一次,详情 / 列表 / 回调读路径也会顺手收口(详见 [`backend/README.md`](backend/README.md))
- [x] **顶栏下载入口(2026-10-29)**:所有页面右上角都有「桌面端 / Android 扫码台」下载按钮(**不看权限**),
版本号读 `/download/version.json` 与 `/download/android_client/version.json`,没发布过安装包时按钮置灰
- [x] **工作台 OSD 字幕(2026-11-01)**:设备服务按工作台把「摄像头名 + 运单号」写进每路摄像头的 OSD
(= 录像机通道名,录像/回放都带);运单号没变不重写,连续 60 秒没扫到还原成摄像头名;
配置由 GET /api/scanner/workstations 下发(详见 [desktop/README.md](desktop/README.md) 的「工作台 OSD 字幕」)
- [x] **扩展上架 Edge 应用商店(2026-11-01)**:拓展走商店分发(桌面端菜单一键打开商店页),
Chrome 用「复制插件路径 + 开发者模式」;**企业策略强制安装已下线**(老机器残留的 HKLM 策略需手工清理)
- [x] **手机网页 `mobile-web/`(2026-11-01)**:独立的 Vue3 + WeUI 手机端(登录 / 首页 / 我的),
接口反代到后端 7300;目前只在本地开发,没有接入发布流程
- [x] **微信 Native 扫码支付(2026-11-07)**:续期下单直接出微信二维码(服务端本地生成 SVG,不跳外部收银台),
前端按 2 秒轮询支付结果;同主体 + 同套餐复用未超时待支付单,回调 / 查单 / 手工确认统一走 `payNotify`;
凭证 `WXPAY_APP_ID` / `WXPAY_MCH_ID` / `WXPAY_API_KEY` 只配服务端,缺任意一项 = 未开通(详见 [`backend/README.md`](backend/README.md))
- [x] **工作台多路面单摄像头(2026-11-08)**:一台工作台可绑多路面单摄像头,识别配置按「工作台 + 摄像头」逐路下发、
多路共用上报通道;绑定管理新增画布尺寸(宽×高)编辑,已摆放的摄像头按比例缩放
- [x] **面单多码同框(2026-11-10)**:一帧里的候选全部解码(两张面单并排不再只报旧码),
新增条码历史(最多 4 个)判断「新码 / 最后出现」,一直看得见的码不重排、离开 45 秒再回来才算新码
- [x] **NVR 唯一性按主体(2026-11-16)**:唯一键从全局 `(host, port, username)` 改为 `(subject_id, host, port, username)`,
不同仓库内网地址相同时不再互相顶掉
- [x] **回放合并提速 + 硬件编码(2026-11-17)**:链式 `overlay` 改为一条 `xstack` 一次合成(同画质、耗时约 -35%),
编码优先 h264_qsv / nvenc / amf,失败自动回落 libx264(详见 [desktop/README.md](desktop/README.md))
- [x] **端口迁出 173xx(2026-11-18)**:本机服务 17300/17301 → **16000/16001**,
后台服务局域网 17310/17311 → **16100/16101**(16010 被向日葵占用,统一避开 160xx);
前端、扩展、安装包同步,安装/升级时自动清理旧防火墙规则
- [x] 扩展默认目标地址已切到线上 `https://pack.wms.gztbyc.com/local?code={code}`(可在扩展「设置」里改「目标地址模板」)
后端接口细节见 [`backend/README.md`](backend/README.md),扩展用法见 [`extension/README.md`](extension/README.md)。
## 前端页面风格约定(`frontend/`)
页面的样式规则集中在 `frontend/src/styles/main.css`,各页只写自己的局部样式。**新增页面请照下面这套来**(都是前端迁移时逐条定下来的):
- **登录 / 注册 / 找回密码 / 重置密码 / 扫码确认**这类「裸页」:居中卡片(`.bare-page` + `.bare-card`,宽 360px)。
- ⚠️ 外层**不要用 `align-items: center`**:卡片比视口高时顶部会被裁掉且滚不上去 —— 用 `.bare-card { margin: auto }` 让它在容器里自己居中,`overflow-y: auto` 兜底;
- ⚠️ **登录页是唯一例外**(见下一条):它自己画深色背景 + 左右分栏,用 `.login-page` / `.login-card`,不套 `.bare-page` / `.bare-card`;
- **表单字段不用 `<label>`**(会把卡片撑高):字段名写进 `placeholder`,「必填 + 说明」用**悬浮气泡** `.field-plain > .tip`(`position: absolute` + `opacity/visibility`,hover 或聚焦时才显示,**不参与布局**,所以显不显示都不改变页面高度);
- **登录页版面**:整页**深色科技底**(海军蓝渐变 + 淡网格 + 光晕,`LoginView` 的 `.login-page` / `.login-bg`,装饰层 `pointer-events: none`),**左右分栏**——左边品牌区(标题 + 副标题 + 等距插画 `frontend/src/assets/login-hero.svg`,宽度自适应、`max-width: 560px`),右边**白色卡片** `.login-card`(宽 300px,复用全局 `.card`);窄屏(`≤960px`)隐藏品牌区、卡片回中间;登录 ⇄ 注册用表单底部的**文字链接**互换(不放按钮);**扫码**面板由右上角三角形 `.corner-toggle` 切换,且**只在登录 ↔ 扫码之间**(**注册面板不显示三角**);三角形挂在**卡片**上(`.login-card` 设 `position: relative` + `overflow: hidden`,让它的直角被卡片圆角裁掉),`.panel-switch.is-login` / `.is-wechat` 给 `padding-top: 18px` + `min-height: 282px`(卡片自身 padding 20 + 18 = 38,正好让开三角)→ 登录与扫码**同高、同位置**,来回切不跳;卡片标题跟着面板走(`欢迎登录` / `注册账号` / `微信扫码登录`),品牌名只出现在左侧品牌区;扫码面板只有二维码 + **「使用微信扫码登录」**一行字;
- 扫码面板**只放二维码 + 返回入口**,不要写说明文字;二维码是后端本地画的 SVG(登录页 `/api/wechat-gateway/qrcode.svg?state=…`,设备扫码登录 `/api/wechat/qrcode.svg?code=…`,**没有任何外链资源**);
- 三角形只在自己那块折角区域可点(`clip-path` 把命中区一起裁了)→ 自动化点击要点在折角内(如 right-10 / top+10),点元素中心会落空;
- **注册字段顺序固定**:用户名 → 邮箱 → 邮箱验证码(右侧「获取验证码」按钮,同一行 `.input-row`)→ 密码 → 重复密码;单列排布、没有步骤小标题、不收昵称/手机号;
- **后台页(测试页 / 个人中心)的表单**保留 `label + placeholder` 的写法(字段多、需要一直可见),列表页与表单页共用 `.card`(卡片间距由 `.card + .card` 统一);
- **网格里的卡片要清掉 `.card + .card` 的间距**:全局 `.card + .card { margin-top: 16px }` 只适合单列堆叠;放进 `display: grid` 的容器里会把第 2 张之后的卡片整体下推 16px,看起来就是「卡片高度/位置不一致」。网格内用 `gap` 排版,并写 `.你的网格 > .card { margin-top: 0 }`(首页 `.stat-grid` / `.charts` 就是这么做的,另外 `grid-auto-rows: 1fr` 保证换行后的每一行也等高);
- **列表页**(设备管理 / 扫码记录)用 `<AppLayout fill>`:内容区不滚动、卡片吃掉剩余高度、只有 `.table-wrap` 内部滚动(表头 `position: sticky` 吸顶、分页条贴在卡片底部);表单/详情页不传 `fill`,滚动落在内容区,侧边栏底部始终可见;
- **接口调用**一律走 `api/client.ts`(自动带 `Authorization: Bearer`、401 自动清令牌)+ `api/web.ts`;**不用 cookie/session,也就不需要 CSRF**;
- **扫码头像期**:前端要自己设客户端超时(服务端挂 60s,客户端 70s),切走面板 / 离开页面(`pagehide`)时要 `abort()` 长轮询 —— 后端会立刻停止等待(见 `backend/README.md` 长轮询一节)。
- **首页是「实时看板」**:深色科技风(海军蓝底 + 青色 `#24bbcd`/`#39d6ff` 描边与发光,参考 `D:\WMS_ANDROID_TV` 的看板),
主题变量集中在 `HomeView.vue` 的 `.dashboard { --tech-* }` 里,图表组件本身保持中性、只在看板内 `:deep()` 染成青色;
- **刷新策略**:每 **30 秒**静默刷新一次(`REFRESH_SECONDS`,不闪 loading、失败保留旧数据),
切维度 / 切回前台(`visibilitychange`)立刻刷;页面在后台(`document.hidden`)时跳过;
头部显示「刷新于 hh:mm:ss · 每 30 秒自动刷新」;
- **工作台榜**:条长 = 该工作台打包数 / 该时间段总扫码数(**占比**,右侧同时给条数与百分比),
没关联工作台的那部分单独一行;工作台只显示名称,`WS-xxxx` 编码只进 hover 提示(别再挤占名称列);
- **全屏按钮**:优先调浏览器原生 `requestFullscreen()`(Esc 可退),不支持/被拒时降级成「只隐藏菜单与顶栏」;
`<AppLayout :immersive="true">` 会隐藏左侧菜单与顶栏、内容占满整屏(`is-immersive` 类);
- 大屏模式下数值字号加大(`.dashboard.is-immersive .kpi-value`),离开首页会自动退出原生全屏。
### 前端常用命令
```bash
cd frontend
npm run dev # 7301(VITE_PORT 可覆盖)
npm run typecheck # vue-tsc --noEmit
npm run build # typecheck + vite build(产物 dist/,发布时由 nginx 直接托管)
```
## 常用环境变量
| 变量 | 默认值 | 作用 |
| --- | --- | --- |
| `PORT` | `7300` | 后端监听端口 |
| `FRONTEND_DEV_SERVER` | `http://127.0.0.1:7301` | 开发时把页面请求反代到哪里 |
| `FRONTEND_DIST` | `frontend/dist` | 仅当让 Egg 托管前端时使用(默认由 nginx 托管,`FRONTEND_ENABLE=false`) |
| `FRONTEND_ENABLE` | `true` | 关掉后后端不管页面(纯接口模式) |
| `INTERNAL_TOKEN` | 空 | 运维接口的静态令牌(header `X-Internal-Token`);不配就只能靠白名单账号的 user JWT |
| `INTERNAL_ADMIN_IDS` | `1` | 哪些用户 id 能调运维接口(逗号分隔) |
| `SITE_URL` | 空 | 二维码 / 邮件里链接用的绝对域名(不配则用请求的 host) |
| `VITE_PORT` / `VITE_BACKEND` | `7301` / `http://127.0.0.1:7300` | 前端 dev 端口 / 代理目标 |
| `WX_GATEWAY_BASE` | `https://gateway.gztbyc.com` | 微信登录网关地址 |
| `WX_GATEWAY_APP_KEY` / `WX_GATEWAY_APP_SECRET` | 空 | 网关应用的 appKey / appSecret(**只配服务端**);不配则扫码相关接口返回 503 |
| `WXPAY_ENABLED` | `true` | 微信 Native 支付的开关(`false` 时仍可建单,只是不出二维码) |
| `WXPAY_APP_ID` / `WXPAY_MCH_ID` / `WXPAY_API_KEY` | 空 | 微信支付凭证(**只配服务端**);缺任意一项 = 未开通 |
| `WXPAY_NOTIFY_URL` | 空 | 支付回调地址(公网 HTTPS,不带参数);不配则用 `SITE_URL/api/pay/wechat/notify` |
| `PAY_ORDER_TTL` | `7200` | 待支付订单有效期(秒),超时自动关单 |
> ⚠️ 运维接口的默认白名单是**内置管理员(id=1)**:上线前请配 `INTERNAL_TOKEN`,或把真正的管理员 id 写进 `INTERNAL_ADMIN_IDS`。