# 云仓视频溯源系统 前后端分离 + 一个浏览器扩展 + 一个 Windows 本机软件(WPF)+ 一个 Android 设备端,五个目录: ``` packService/ ├── backend/ # Egg.js 3(纯 API;MySQL + Redis) ├── frontend/ # Vite + Vue3 + TypeScript(用户端 SPA) ├── extension/ # Chrome MV3 扩展:注入第三方 WMS 页面,把运单号加工成溯源入口 ├── desktop/ # WPF 本机软件:HTTP 17300(查询/唤起/下载)+ WS 17301(拉通道/预览/云台)+ yuncang:// 启动协议 └── AndroidStation/ # Android 设备端:UDP 48899 被桌面端发现 + TCP 8087 推送 USB 扫码结果 ``` ## 端口约定(⚠️ 本机项目多,不要用 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` | | 本机软件(WPF,只监听 loopback) | **17300**(HTTP)/ **17301**(WebSocket) | `cd desktop && dotnet run`(详见 [`desktop/README.md`](desktop/README.md)) | | 扩展自测页(可选) | **7310** | `npx --yes http-server extension/test -p 7310` | - 前端端口可用 `VITE_PORT=7303 npm run dev` 覆盖;`strictPort: true` → 端口被占用时**直接报错**,不会偷偷换端口(否则代理会对不上)。 - 后端端口可用 `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 `(typ=user) | `/api/web/*`(登录/资料/设备/记录) | | 设备(扫描枪、中控) | `Authorization: Bearer `(typ=scanner) | `/api/device/login`、`/api/scanner/*`、`/api/scan/*` | | 公开 | 无 | `/api/wechat-gateway/notify`(网关回调,**靠签名**)、`/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,零构建):注入第三方 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] **待支付订单 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 字幕」) - [ ] 扩展:目标地址换成真实打包视频页(现在指向百度占位)—— 在扩展「设置」里改「目标地址模板」即可,需要真实地址 后端接口细节见 [`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` 兜底; - **表单字段不用 `