packServer/README.md
liufumingren 4586fe5217 chore: 移除已弃用的 miniprogram(uni-app 微信小程序)
- 删除 miniprogram/ 整个工程(28 个跟踪文件:uni-app 页面、接口封装、构建配置)
- README 去掉小程序目录、7304 端口、进度条目与用法链接
- cors 中间件与 CORS_ORIGINS 示例注释不再以「小程序 H5 预览」举例

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-10-30 23:10:59 +08:00

140 lines
15 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 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 在 `/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/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`,没发布过安装包时按钮置灰
- [ ] 扩展:目标地址换成真实打包视频页(现在指向百度占位)—— 在扩展「设置」里改「目标地址模板」即可,需要真实地址
后端接口细节见 [`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` 兜底;
- **表单字段不用 `<label>`**(会把卡片撑高):字段名写进 `placeholder`,「必填 + 说明」用**悬浮气泡** `.field-plain > .tip`(`position: absolute` + `opacity/visibility`,hover 或聚焦时才显示,**不参与布局**,所以显不显示都不改变页面高度);
- **登录页版面**:登录 ⇄ 注册用表单底部的**文字链接**互换(不放按钮);**扫码**面板由右上角三角形 `.corner-toggle` 切换,且**只在登录 ↔ 扫码之间**(**注册面板不显示三角**);三角形挂在**卡片**上(`.card.bare-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 |
> ⚠️ 运维接口的默认白名单是**内置管理员(id=1)**:上线前请配 `INTERNAL_TOKEN`,或把真正的管理员 id 写进 `INTERNAL_ADMIN_IDS`。