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>
103 lines
10 KiB
Markdown
103 lines
10 KiB
Markdown
# 云仓视频溯源系统
|
||
|
||
前后端分离 + 一个浏览器扩展 + 一个 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`。
|