packServer/README.md
liufumingren 228723e0c3 设备端扫码上报 + 桌面端/Android 正式包发布脚手架
AndroidStation(原中控改造为纯设备端)
- 只做三件事:UDP 48899 被桌面端发现、TCP 8087 推送 USB 扫码结果、离线语音播报
- 扫码不再经过 UI:去掉逐键重绘,50ms 自动提交,同一码重复扫码也一律上报
- 离线语音种子(数字/字母/“开始打包”/欢迎语)随包安装,MediaPlayer 播放,启动把音量拉满
- 启动播报「欢迎使用溯源系统,初始化已经完成,扫码即可开始打包」
- 移除 Device Owner / 设备管理员 / lock task / 网络与 IP 设置等非普通应用能力(仅保留开机自启)
- 正式签名 keystore + release 签名配置,versionName/versionCode 可由打包脚本覆盖

发布脚手架
- backend/android_client:Android 正式包构建(build.ps1 + package.config.json)
- backend/scripts/deploy/publish-android.cjs + npm run android:build / android:publish
- 桌面端安装包改为 download/desktop,Android 为 download/android_client;
  version.json 仍走 /download/version.json(老客户端写死),新增 /download/android_client/version.json
- 谷歌插件随桌面端 MSI 安装到 <安装目录>\extension,工具菜单新增「复制谷歌插件地址」
- git-safety-check 增加仓库级禁区(keystore.properties / *.jks / local.properties)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-10-21 05:53:27 +08:00

103 lines
10 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)
├── miniprogram/ # uni-app + Vue3 + TypeScript(微信小程序:抽屉登录(个人中心为整页登录)/ 协议弹窗 / 首页统计 / 扫码记录 / 我的)
├── 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` |
| 小程序 H5 预览(可选) | **7304** | `cd miniprogram && npm run dev:h5` |
| 本机软件(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/{login,status,qrcode.svg}`、`/api/web/auth/*` |
前端**不用 cookie/session**:令牌存本地、放 header,所以没有跨域 cookie 与 CSRF 的问题
(JWT 用 `typ` 声明隔离:用户令牌调设备接口一律 401)。
## 当前进度
- [x] 目录拆分为 `backend/` + `frontend/`
- [x] 前端脚手架(Vite + Vue3 + TS)跑通,登录页走通 `/api/web/auth/*`
- [x] 小程序脚手架 `miniprogram/`(uni-app + Vue3 + TS):微信一键登录(code2Session)+ 账号登录双 tab / 首页统计 / 扫码记录 / 个人中心;登录前需阅读并同意协议(版本落库);不强制登录(启动不弹窗,点功能或 401 才提示,符合小程序审核)
- [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/*}`(范围一律限定在令牌对应的那个用户)
- [ ] 扩展:目标地址换成真实打包视频页(现在指向百度占位)—— 在扩展「设置」里改「目标地址模板」即可,需要真实地址
后端接口细节见 [`backend/README.md`](backend/README.md),扩展用法见 [`extension/README.md`](extension/README.md),小程序用法见 [`miniprogram/README.md`](miniprogram/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/qrcode.svg?code=…`,**没有任何外链资源**);
- 三角形只在自己那块折角区域可点(`clip-path` 把命中区一起裁了)→ 自动化点击要点在折角内(如 right-10 / top+10),点元素中心会落空;
- **注册字段顺序固定**:用户名 → 邮箱 → 邮箱验证码(右侧「获取验证码」按钮,同一行 `.input-row`)→ 密码 → 重复密码;单列排布、没有步骤小标题、不收昵称/手机号;
- **后台页(测试页 / 个人中心)的表单**保留 `label + placeholder` 的写法(字段多、需要一直可见),列表页与表单页共用 `.card`(卡片间距由 `.card + .card` 统一);
- **列表页**(设备管理 / 扫码记录)用 `<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` 长轮询一节)。
### 前端常用命令
```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 端口 / 代理目标 |
> ⚠️ 运维接口的默认白名单是**内置管理员(id=1)**:上线前请配 `INTERNAL_TOKEN`,或把真正的管理员 id 写进 `INTERNAL_ADMIN_IDS`。