chore: 忽略内置 ffmpeg 可执行文件并更新各端 README
This commit is contained in:
parent
79f89ec392
commit
2573404981
3
.gitignore
vendored
3
.gitignore
vendored
@ -69,3 +69,6 @@ desktop.ini
|
||||
* - 副本.*
|
||||
# 联调用的临时脚本(如 .tmp-reset-probe.js / .tmp-css-audit.cjs),跑完就删,别提交
|
||||
.tmp-*
|
||||
|
||||
# ---------- 内置 ffmpeg(exe 体积大不进仓库;打包前按 desktop/native/ffmpeg/README.md 放好) ----------
|
||||
desktop/native/ffmpeg/*.exe
|
||||
|
||||
22
README.md
22
README.md
@ -1,12 +1,13 @@
|
||||
# 云仓视频溯源系统
|
||||
|
||||
前后端分离 + 一个浏览器扩展,三个目录:
|
||||
前后端分离 + 一个浏览器扩展 + 一个 Windows 本机软件(WPF),四个目录:
|
||||
|
||||
```
|
||||
packService/
|
||||
├── backend/ # Egg.js 3(纯 API;MySQL + Redis)
|
||||
├── frontend/ # Vite + Vue3 + TypeScript(用户端 SPA)
|
||||
└── extension/ # Chrome MV3 扩展:注入第三方 WMS 页面,把运单号加工成溯源入口
|
||||
├── extension/ # Chrome MV3 扩展:注入第三方 WMS 页面,把运单号加工成溯源入口
|
||||
└── desktop/ # WPF 本机软件:本机 HTTP 服务(127.0.0.1:17300)+ yuncang:// 启动协议
|
||||
```
|
||||
|
||||
## 端口约定(⚠️ 本机项目多,不要用 Vite 默认的 5173)
|
||||
@ -15,13 +16,14 @@ packService/
|
||||
| --- | --- | --- |
|
||||
| 前端 dev(Vite) | **7301** | `cd frontend && npm run dev` |
|
||||
| 前端 preview(dist) | **7302** | `cd frontend && npm run preview` |
|
||||
| 后端 dev | **7001** | `cd backend && npm run dev` |
|
||||
| 后端 dev:test(与 7001 并存) | **7300** | `cd backend && $env:LOG_DIR='logs-test'; npm run dev:test` |
|
||||
| 后端 dev | **7300** | `cd backend && npm run dev` |
|
||||
| 本机软件(WPF,只监听 loopback) | **17300** | `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` → 端口被占用时**直接报错**,不会偷偷换端口(否则代理会对不上)。
|
||||
- 前端调接口走**同源代理**:Vite 把 `/api`、`/health` 反代到后端(默认 `127.0.0.1:7001`,用 `VITE_BACKEND` 覆盖)。
|
||||
- 联调更方便的做法:直接开后端 `:7001`,由后端(dev)把 `/` 反代到前端 dev server(`FRONTEND_DEV_SERVER`,默认 `http://127.0.0.1:7301`)。
|
||||
- 后端端口可用 `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`)。
|
||||
- **上线**:后端托管 `frontend/dist`(静态资源 + SPA fallback),`/` 出前端、`/api/*` 出 JSON。
|
||||
|
||||
## 身份与通讯约定
|
||||
@ -39,7 +41,7 @@ packService/
|
||||
|
||||
- [x] 目录拆分为 `backend/` + `frontend/`
|
||||
- [x] 前端脚手架(Vite + Vue3 + TS)跑通,登录页走通 `/api/web/auth/*`
|
||||
- [x] 浏览器扩展 `extension/`(MV3,零构建):注入第三方 WMS 页面识别运单号 → 点击打开溯源页
|
||||
- [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`)+ 生产托管 `frontend/dist`(SPA 深链回退)
|
||||
@ -56,7 +58,7 @@ packService/
|
||||
- **登录 / 注册 / 找回密码 / 重置密码 / 扫码确认**这类「裸页」:居中卡片(`.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 或聚焦时才显示,**不参与布局**,所以显不显示都不改变页面高度);
|
||||
- **登录页版面**:顶部「登录 / 注册」两个 tab;**扫码**面板由右上角三角形 `.corner-toggle` 切换,三角形挂在 `.panel-switch` 容器上(与输入框右边缘对齐),容器 `padding-top: 38px` 给它留位;`.is-login` / `.is-wechat` 用 `min-height: 300px` 定成**同高** → 来回切卡片高度与位置不变;
|
||||
- **登录页版面**:登录 ⇄ 注册用表单底部的**文字链接**互换(不放按钮);**扫码**面板由右上角三角形 `.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`)→ 密码 → 重复密码;单列排布、没有步骤小标题、不收昵称/手机号;
|
||||
@ -79,13 +81,13 @@ npm run build # typecheck + vite build(产物 dist/,后端生产模式
|
||||
|
||||
| 变量 | 默认值 | 作用 |
|
||||
| --- | --- | --- |
|
||||
| `PORT` | `7001` | 后端监听端口 |
|
||||
| `PORT` | `7300` | 后端监听端口 |
|
||||
| `FRONTEND_DEV_SERVER` | `http://127.0.0.1:7301` | 开发时把页面请求反代到哪里 |
|
||||
| `FRONTEND_DIST` | `frontend/dist` | 生产托管的前端构建产物目录 |
|
||||
| `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:7001` | 前端 dev 端口 / 代理目标 |
|
||||
| `VITE_PORT` / `VITE_BACKEND` | `7301` / `http://127.0.0.1:7300` | 前端 dev 端口 / 代理目标 |
|
||||
|
||||
> ⚠️ 运维接口的默认白名单是**内置管理员(id=1)**:上线前请配 `INTERNAL_TOKEN`,或把真正的管理员 id 写进 `INTERNAL_ADMIN_IDS`。
|
||||
|
||||
@ -113,18 +113,16 @@ npm run db:init
|
||||
# npm run db:init sql/migrations/20261016_add_user_password.sql # 增加 password_hash
|
||||
# npm run db:init sql/migrations/20261016_devices_to_scanners.sql # 删掉旧的 devices 表(改用 scanners)
|
||||
# npm run db:init sql/migrations/20261016_add_user_email.sql # users 增加 email(可当登录账号)
|
||||
# npm run db:init sql/migrations/20261017_add_user_password_changed_at.sql # users 增加 password_changed_at(改密后旧 JWT 失效)
|
||||
|
||||
# 4. 建一个登录账号(不存在会直接创建,密码 bcrypt 入库)
|
||||
npm run user:pass -- admin 123456 管理员
|
||||
|
||||
# 5. 启动(默认 http://127.0.0.1:7001)
|
||||
# 登录页:http://127.0.0.1:7001/login(用上面的账号登录)
|
||||
# 5. 启动(默认 http://127.0.0.1:7300)
|
||||
# 登录页:http://127.0.0.1:7300/login(用上面的账号登录)
|
||||
npm run dev
|
||||
|
||||
# 本地测试想要一个“专用端口”(默认 7300,可与 npm run dev 同时开):
|
||||
npm run dev:test
|
||||
# → http://127.0.0.1:7300 ;想换端口:egg-bin dev --port 7400,或 $env:PORT=7400; npm run dev
|
||||
# 两实例并存时给测试实例单独日志目录:$env:LOG_DIR='logs-test'; npm run dev:test
|
||||
# 想临时换端口:egg-bin dev --port 7400,或 $env:PORT=7400; npm run dev(默认端口在 config/config.default.js)
|
||||
|
||||
# 生产模式
|
||||
npm start # egg-scripts 后台启动
|
||||
@ -134,14 +132,14 @@ npm stop
|
||||
验证:
|
||||
|
||||
```bash
|
||||
curl -I http://127.0.0.1:7001/login # 200:反代到前端 dev server(前端没起则 502 提示页)
|
||||
curl http://127.0.0.1:7001/health
|
||||
curl http://127.0.0.1:7001/api/users # 401:内部接口要令牌(X-Internal-Token 或管理员 user JWT)
|
||||
curl -H 'X-Internal-Token: <INTERNAL_TOKEN>' http://127.0.0.1:7001/api/users # 200
|
||||
curl -I http://127.0.0.1:7300/login # 200:反代到前端 dev server(前端没起则 502 提示页)
|
||||
curl http://127.0.0.1:7300/health
|
||||
curl http://127.0.0.1:7300/api/users # 401:内部接口要令牌(X-Internal-Token 或管理员 user JWT)
|
||||
curl -H 'X-Internal-Token: <INTERNAL_TOKEN>' http://127.0.0.1:7300/api/users # 200
|
||||
```
|
||||
|
||||
> 后端只管接口:页面在 `../frontend/`(`npm run dev` 起在 7301)。
|
||||
> 联调推荐**只开后端地址** `http://127.0.0.1:7001`(dev 环境自动把页面请求反代给前端);也可以直接开前端 7301(Vite 把 `/api` 反代到 7001)。
|
||||
> 联调推荐**只开后端地址** `http://127.0.0.1:7300`(dev 环境自动把页面请求反代给前端);也可以直接开前端 7301(Vite 把 `/api` 反代到 7300)。
|
||||
|
||||
## 单元测试
|
||||
|
||||
@ -150,13 +148,13 @@ npm test # 无需本机启动 MySQL / Redis
|
||||
npm run cov
|
||||
```
|
||||
|
||||
### 本地专用测试端口(`npm run dev:test`)
|
||||
### 本地端口
|
||||
|
||||
- `npm run dev:test` = `egg-bin dev --port 7300`(可与 7001 的 `npm run dev` 同时跑);端口也可用环境变量 `PORT` 覆盖(egg-cluster 会读 `process.env.PORT`),`config.cluster.listen.port` 的默认值是 `Number(PORT || 7001)`;
|
||||
- **登录态是共享的**:cookie(`packs_sess`)不带端口,`127.0.0.1:7001` 的登录 cookie 在 `127.0.0.1:7300` 一样有效,换端口不用重新登录;两个实例也共用同一套 MySQL / Redis(都读 `config/config.local.js`);
|
||||
- **扫码二维码地址会自动跟随端口**:二维码内容是 `ctx.origin` 拼的 `http://<当前访问的 host:port>/wechat?spm=1.0.<码>.1`,所以在 7300 打开的登录页,扫出来的就是 7300 的地址,不用改配置;邮件里的重置链接同理(`config.email.siteUrl || ctx.origin`),只有显式配了 `SITE_URL` 才需要跟着改;
|
||||
- 两个实例并存时日志默认都写 `logs/pack-service/`,想分开就 `$env:LOG_DIR='logs-test'; npm run dev:test`(PowerShell)/ `LOG_DIR=logs-test npm run dev:test`(bash);
|
||||
- `npm test` 是单测(不监听固定端口),和这两个端口不冲突;
|
||||
- 后端默认监听 **7300**:`config.cluster.listen.port = Number(PORT || 7300)`,临时换口用 `PORT=7400 npm run dev`(PowerShell:`$env:PORT=7400; npm run dev`);
|
||||
- **二维码 / 邮件链接会自动跟随端口**:二维码内容是 `ctx.origin` 拼的 `http://<当前访问的 host:port>/wechat?spm=1.0.<码>.1`,在哪个端口打开登录页,扫出来就是那个地址,不用改配置;邮件里的重置链接同理(`config.email.siteUrl || ctx.origin`),只有显式配了 `SITE_URL` 才需要跟着改;
|
||||
- 想同时跑两个实例(例如一边联调一边自测),给其中一个换端口 + 分日志:`$env:PORT=7400; $env:LOG_DIR='logs-test'; npm run dev`;
|
||||
- 多个实例共用同一套 MySQL / Redis(都读 `config/config.local.js`);
|
||||
- `npm test` 是单测(不监听固定端口),和上面的端口不冲突;
|
||||
|
||||
- `config/plugin.unittest.js` 在测试环境关闭 `sequelize` 与 `redis` 插件(这两个插件在启动时都会连库);
|
||||
- 测试中用 `mock(app, 'model', fakeModel)` / `mock(app, 'redis', fakeRedis)` 注入假实现,因此 CI 上不依赖外部服务。
|
||||
@ -183,6 +181,7 @@ npm run cov
|
||||
| `SITE_NAME` | `云仓视频溯源系统` | 站点/产品中文名(页面标题、侧边栏品牌、邮件主题与正文都用它) |
|
||||
| `SCANNER_JWT_EXPIRES` | `365d` | 扫描器长期 JWT 默认有效期(`jsonwebtoken` 语法,如 `30d` / `720h`) |
|
||||
| `DEVICE_JWT_EXPIRES` | 同 `SCANNER_JWT_EXPIRES` | `/api/device/login` 下发令牌的**默认时长 + 上限**;设备可用 `?expiresIn=30d` 申请更短的,不能更长 |
|
||||
| `DEVICE_REFRESH_EXPIRES` | `730d` | 刷新令牌有效期(`POST /api/device/refresh` 轮换时顺延) |
|
||||
| `REGISTER_ENABLED` | `true` | 是否允许登录页自助注册(`false`/`0`/`no`/`off` 关闭;**生产建议关掉**,用 `npm run user:pass` 建号) |
|
||||
| `SMTP_HOST` | 空 | SMTP 主机;**不配就走开发模式**(验证码只写日志 + 注册页回显,不发真邮件) |
|
||||
| `SMTP_PORT` | `465` | SMTP 端口 |
|
||||
@ -229,6 +228,8 @@ $env:MYSQL_PASSWORD = 'your-pass'; $env:REDIS_PASSWORD = 'your-pass'; npm run de
|
||||
| status | tinyint unsigned | 1 正常 / 0 禁用 |
|
||||
| remark | varchar(255) | 备注 |
|
||||
| last_login_at | datetime | 最近登录时间 |
|
||||
| password_hash | varchar(100) | bcrypt 密码哈希(接口/页面都不外泄,查询时显式 exclude) |
|
||||
| password_changed_at | datetime | 最近一次设置/重置密码的时间(可空);**签发时间早于它的 user JWT 立即失效** |
|
||||
| created_at / updated_at / deleted_at | datetime | 时间戳与软删除 |
|
||||
|
||||
### wechat_oauth 微信授权表
|
||||
@ -270,6 +271,8 @@ $env:MYSQL_PASSWORD = 'your-pass'; $env:REDIS_PASSWORD = 'your-pass'; npm run de
|
||||
| ip | varchar(45) | 最近登录 IP |
|
||||
| secret_hash | varchar(100) | **历史字段**(早期 sn+secret 登录用),现已不再写入 |
|
||||
| token_jti | varchar(64) | 当前长期 JWT 的 `jti`,唯一;**库里不存令牌本体** |
|
||||
| refresh_token_hash | varchar(128) | 刷新令牌 sha256(不存原文;索引 `idx_scanners_refresh_token_hash`) |
|
||||
| refresh_expires_at | datetime | 刷新令牌过期时间(每次刷新顺延) |
|
||||
| token_expires_at | datetime | 令牌过期时间(默认 365 天) |
|
||||
| status | tinyint unsigned | 1 正常 / 0 禁用(禁用后登录与所有带令牌的接口都 403) |
|
||||
| last_register_at / last_login_at / last_seen_at | datetime | 最近注册、最近登录、最近心跳时间 |
|
||||
@ -299,6 +302,17 @@ $env:MYSQL_PASSWORD = 'your-pass'; $env:REDIS_PASSWORD = 'your-pass'; npm run de
|
||||
|
||||
令牌取用顺序:`Authorization: Bearer <token>` → `X-Scanner-Token` → `?access_token=`(见 `app/middleware/scanner_auth.js`)。
|
||||
|
||||
#### 刷新令牌(自动续期,2026-10-19)
|
||||
|
||||
访问令牌(365 天)到期后,无人值守的后台服务没法自己登录,所以激活时**同时下发刷新令牌**:
|
||||
|
||||
- 刷新令牌是不透明随机串(32 字节 base64url);库里只存 `sha256`(`scanners.refresh_token_hash`),不存原文;
|
||||
- 有效期默认 **730 天**(`config.jwt.deviceRefreshExpiresIn`,env `DEVICE_REFRESH_EXPIRES`);**每次刷新都会轮换并顺延**;
|
||||
- 接口:`POST /api/device/refresh`,body `{ refreshToken, sn? }`(也认 header `X-Refresh-Token`);
|
||||
**不需要访问令牌**(它可能已过期);成功返回新的 `token` + `refreshToken`(旧的立即失效)+ `expiresIn/refreshExpiresIn`;
|
||||
- 撤销:关闭设备服务(`revokeToken`)、同主体其它设备激活(踢下线)、禁用/删除设备都会把 `refresh_token_hash` 清掉,刷新令牌一并失效;
|
||||
- 桌面端后台服务在访问令牌剩余不足 7 天时自动调用,结果写 `%ProgramData%\YuncangTrace\agent-token.json`。
|
||||
|
||||
### scan_channels 扫描中控通道表
|
||||
|
||||
「中控」就是绑定端(复用 `scanners`,用自己的 `sn` + 长期 JWT 上报):一台中控可接多个扫码设备,
|
||||
@ -330,15 +344,36 @@ $env:MYSQL_PASSWORD = 'your-pass'; $env:REDIS_PASSWORD = 'your-pass'; npm run de
|
||||
| barcode | varchar(255) | 条码内容 |
|
||||
| scan_time | datetime | 扫描时间(中控上报,**精确到秒**,去重键之一) |
|
||||
| reported_at | datetime | 服务端接收时间 |
|
||||
| subject_id | bigint unsigned | 所属主体(跟随中控) |
|
||||
| workstation_id | bigint unsigned | **扫码当时**绑定的工作台 |
|
||||
| workstation_snapshot | json | **扫码当时**的工作台快照(录像机 / 摄像头 / 画布布局 / 录制范围) |
|
||||
| created_at / updated_at | datetime | 时间戳 |
|
||||
|
||||
> 快照是 2026-10-18 才加的(迁移 `20261018240000`)。历史记录没有快照,
|
||||
> 查回放时回落到「当前绑定」并打 `snapshotMiss`;想让历史数据也走快照,跑:
|
||||
|
||||
```
|
||||
# 只补某个运单(跳过已有快照的)
|
||||
npm run backfill:snapshot -- --code=79150895123619
|
||||
# 全部缺快照的记录 / 连已有快照也覆盖成当前配置 / 只看不写
|
||||
node scripts/backfill-snapshot.js
|
||||
node scripts/backfill-snapshot.js --all
|
||||
node scripts/backfill-snapshot.js --dry-run
|
||||
```
|
||||
|
||||
> ⚠️ 补出来的快照 = **现在**的工作台配置,不是当年的。只适合「配置没变过」的历史数据。
|
||||
> 补快照用的是 `app/lib/workstation-snapshot.js`(与实时入库同一份逻辑)。
|
||||
|
||||
去重规则(唯一键 `uk_scan_dedup` = `(scanner_id, channel_id, barcode, scan_time)`):
|
||||
|
||||
- **同一中控 + 同一通道 + 同一条码 + 同一扫描时间(秒)** 只入库一次,重复上报不会报错,接口返回 `duplicated` 计数;
|
||||
- 上报前先用一次查询(按中控 + 通道 + 时间范围)捞出已存在的记录做过滤,剩下的批量插入;
|
||||
- **同一运单号 24 小时内只保留一条**(现场要求):主体内按 `barcode` 判断,**跨中控/通道也算同一条**;
|
||||
后上报的扫描时间如果更新,就**覆盖**这条记录的 `scan_time`、通道与工作台快照(计入 `updated`);
|
||||
如果上报的时间比库里那条旧(乱序/重试),则忽略(计入 `suppressed`),不会把时间改回过去;
|
||||
距上一条超过 24 小时后重新扫,算一次新的上报;
|
||||
- 同一批里同一运单出现多次 → 只保留**最晚**的一条,其余忽略;
|
||||
- 上报前先用一次查询(按中控 + 通道 + 时间范围)捞出已存在的记录做精确去重,剩下的批量插入;
|
||||
真出现并发撞唯一键时会自动退化成逐条插入,撞上的计入 `duplicated`;
|
||||
- 同一批里完全相同的上报也只留一条(内存里先去重);
|
||||
- 条码相同但时间或通道不同 → 视为两条不同记录;
|
||||
- 时间精度到秒:`scan_time` 会先把毫秒截断,再做去重与入库(同一秒内的同条码算重复)。
|
||||
|
||||
> 本表**不用软删除**(paranoid 关闭):软删除会让记录占用唯一键,导致同一条扫码数据再也无法入库;
|
||||
@ -364,7 +399,7 @@ $env:MYSQL_PASSWORD = 'your-pass'; $env:REDIS_PASSWORD = 'your-pass'; npm run de
|
||||
**后端怎么把页面交出去**(`app/middleware/frontend.js`,只接管「非 `/api`、`/health`」的 GET/HEAD 请求):
|
||||
|
||||
- **开发**(`env=local`):**反代**到 `FRONTEND_DEV_SERVER`(默认 `http://127.0.0.1:7301`,即 `frontend/ && npm run dev`),
|
||||
包含 HMR 的 WebSocket 升级 —— 所以联调只开 `http://127.0.0.1:7001` 一个地址就够(前端热更新照常生效);
|
||||
包含 HMR 的 WebSocket 升级 —— 所以联调只开 `http://127.0.0.1:7300` 一个地址就够(前端热更新照常生效);
|
||||
前端没起来时会回一个 502 提示页,而不是白屏;
|
||||
- **生产**:托管 `FRONTEND_DIST`(默认 `../frontend/dist`);找不到文件且请求要 HTML 时回退 `index.html`
|
||||
(SPA 深链 `/devices` 刷新不会 404);dist 不存在时回 503 并提示先 `npm run build`;
|
||||
@ -410,7 +445,8 @@ $env:MYSQL_PASSWORD = 'your-pass'; $env:REDIS_PASSWORD = 'your-pass'; npm run de
|
||||
| GET | `/api/configs/:group` | 取分组内所有启用配置 |
|
||||
| PUT | `/api/configs` | 新增/更新(幂等),body: `{"groupName":"wechat","configKey":"appid","configValue":"wx123"}` |
|
||||
| DELETE | `/api/configs/:group/:key` | 软删除(清缓存) |
|
||||
| GET | `/api/device/login` | **设备「扫码登录 + 注册」**(参考 `/api/wechat/login`,但下发**长期** JWT):**不需要凭据、不需要预先注册**(公开接口);`?sn=`/`name`/`vendor`/`model`/`firmware` 可选(发码时带上最省事,服务端会暂存)、`?expiresIn=30d` 可选(只能比服务端上限短);不带 `code` → 发登录码(`code` / `spm` / **`qrContent`(二维码要编的完整网址)** / `qrImageUrl`(完整地址的 SVG));带 `?code=&wait=N` → 长轮询,手机用 `POST /api/wechat/confirm` 确认后**立即**返回 `{ firstTime, sn, token, expiresIn, expiresAt, scanner, user }`,**注册/绑定就发生在这一刻**(SN 已属于别人 → 403) |
|
||||
| GET | `/api/device/login` | **设备「扫码登录 + 注册」**(参考 `/api/wechat/login`,但下发**长期** JWT):**不需要凭据、不需要预先注册**(公开接口);`?sn=`/`name`/`vendor`/`model`/`firmware` 可选(发码时带上最省事,服务端会暂存)、`?expiresIn=30d` 可选(只能比服务端上限短);不带 `code` → 发登录码(`code` / `spm` / **`qrContent`(二维码要编的完整网址)** / `qrImageUrl`(完整地址的 SVG));带 `?code=&wait=N` → 长轮询,手机用 `POST /api/wechat/confirm` 确认后**立即**返回 `{ firstTime, sn, token, expiresIn, expiresAt, refreshToken, refreshExpiresIn, scanner, user }`,**注册/绑定就发生在这一刻**(SN 已属于别人 → 403) |
|
||||
| POST | `/api/device/refresh` | 用刷新令牌换新访问令牌(**无需访问令牌**):body `{ refreshToken, sn? }` → `{ sn, token, tokenType, expiresIn, refreshToken, refreshExpiresIn, refreshExpiresAt }`;两者都会轮换,旧的立即失效 |
|
||||
| POST | `/api/scanner/bind` | **管理侧**:把设备绑定到账号,body: `{ sn, username }` 或 `{ sn, userId }` |
|
||||
| POST | `/api/scanner/unbind` | **管理侧**:解绑,body: `{ sn }`(设备可再扫码重新认领) |
|
||||
| GET | `/api/scanner/me` | **需 JWT**:返回当前设备信息(自检连通性) |
|
||||
@ -420,10 +456,11 @@ $env:MYSQL_PASSWORD = 'your-pass'; $env:REDIS_PASSWORD = 'your-pass'; npm run de
|
||||
| DELETE | `/api/scanners/:id` | 软删除扫描器 |
|
||||
| POST | `/api/scan/channels` | **需扫描器 JWT**:中控上报通道,body: `{ channels: [{ channelId, channelName }] }`(单条也可)→ `{ created, updated, invalid, errors }` |
|
||||
| GET | `/api/scan/channels?page=&pageSize=&keyword=&status=` | **需扫描器 JWT**:当前中控已登记的通道 |
|
||||
| POST | `/api/scan/records` | **需扫描器 JWT**:中控上报扫码,body: `{ records: [{ barcode, scanTime, channelId }] }` → `{ received, inserted, duplicated, invalid, unknownChannels }` |
|
||||
| POST | `/api/scan/records` | **需扫描器 JWT**:中控上报扫码,body: `{ records: [{ barcode, scanTime, channelId }] }` → `{ received, inserted, updated, duplicated, suppressed, invalid, unknownChannels }`(`updated` = 24 小时内同一运单被覆盖为最新扫描时间的条数;`suppressed` = 比库里已有记录更旧、被忽略的条数) |
|
||||
| GET | `/api/scan/records?page=&pageSize=&channelId=&barcode=&startTime=&endTime=` | **需扫描器 JWT**:当前中控上报的扫码记录 |
|
||||
|
||||
扫码上报的两个接口都**不会因为重复而报错**(幂等):重复条数计入 `duplicated`;
|
||||
扫码上报的两个接口都**不会因为重复而报错**(幂等):完全重复的条数计入 `duplicated`,
|
||||
**同一运单号 24 小时内重复扫描的只保留一条**:时间更新就覆盖(`updated`),更旧的上报忽略(`suppressed`);
|
||||
单条非法(缺条码 / 时间非法 / 超长)会被跳过并计入 `invalid` + `errors`;整体为空数组才返回 422。
|
||||
上报还支持 `records` 传 JSON 字符串(部分设备端会这么塞);上报成功会顺手刷新中控心跳与通道的 `last_report_at`,
|
||||
遇到未登记的通道会自动补建一行(`channel_name` 留空,同时记 WARN 日志)。
|
||||
@ -539,13 +576,23 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
|
||||
- 发信走 `app/service/mail.js`:**未配 `SMTP_HOST` 时是开发模式**(验证码写服务端日志 + 在接口返回里带 `code`,前端直接提示,仅本地/测试);配上 `SMTP_HOST/PORT/USER/PASSWORD/FROM` 后自动改用 nodemailer 真发信(依赖懒加载);
|
||||
- 验证码逻辑不抛异常,统一返回 `{ ok, message }`,失败都是接口报错(Redis 不可用会提示“验证码服务暂不可用”而不是 500);
|
||||
- **邮箱找回密码(发重置链接)**:前端「忘记密码?」页 → `POST /api/web/auth/forgot` 生成带令牌的链接并**发到邮箱** → 邮件里的链接打开前端 `/reset?token=...` 设置新密码 → `POST /api/web/auth/reset` 改哈希(**不自动登录**,要求用新密码再登一次)。
|
||||
- 令牌存 Redis(`app/service/password_reset.js`):`packs:reset:token:<sha256(令牌)>` → 用户 id(TTL `EMAIL_RESET_TTL`,默认 30 分钟)、`packs:reset:user:<id>` → 当前令牌摘要、`packs:reset:sent:<id>` 重发节流(`SET NX`,默认 60 秒);**Redis 里只存摘要,不存令牌原文**(泄库也拿不到可用的链接);
|
||||
- **一次性**:重置成功后 `consume()` 删掉令牌;**重新申请会让旧链接立刻失效**(同一用户只保留最新一条);校验失败的提交(密码太短/两次不一致/令牌不对)**不会**消费令牌;
|
||||
- **只存 Redis(缓存),不落库**:`users` 表没有 token/过期时间列,也没有 reset 表(实测确认);重启 Redis / 清 `packs:reset:*` 会让未用的链接立即失效;
|
||||
- 三个 key(`app/service/password_reset.js`,前缀 `config.cache.prefix`):
|
||||
|
||||
| key | 值 | TTL(实测) |
|
||||
| --- | --- | --- |
|
||||
| `packs:reset:token:<sha256(令牌)>` | 用户 id | `EMAIL_RESET_TTL`,默认 **1800s(30 分钟)** |
|
||||
| `packs:reset:user:<用户id>` | 该用户**当前最新**令牌的摘要 | 同上(用「旧链接立刻失效」) |
|
||||
| `packs:reset:sent:<用户id>` | `1` | `EMAIL_CODE_RESEND`,默认 **60 秒**(重发节流) |
|
||||
|
||||
- **Redis 里只存令牌的 sha256 摘要,不存原文**(泄库也拿不到可用的链接;令牌本身是 `randomBytes(32)` 的 64 位 hex);
|
||||
- **有效期是固定的 30 分钟**(不滑动:`verify()` 不续期);**一次性**:重置成功后 `consume()` 删掉令牌;**重新申请会让旧链接立刻失效**(同一用户只保留最新一条);校验失败的提交(密码太短/两次不一致/令牌不对)**不会**消费令牌;
|
||||
- **重发节流 60 秒**:命中时 `/forgot` 返回 **429** + `{ ok:false, status:'throttled', message:'重置链接已发送,请 60 秒后再试' }`(⚠️ 2026-10-17 修:以前抛 500,被 error_handler 盖成「服务器内部错误」,用户看不懂);Redis 写失败/发信失败 → **503** + `status:'unavailable' | 'mail'`;
|
||||
- **防账号枚举**:邮箱格式不对才报错;邮箱未注册或账号被禁用时,提示与成功完全一致(“如果该邮箱已注册,链接已经发出”),并且不发信;
|
||||
- 邮件正文由 `service.mail.sendResetLink()` 生成(与验证码同一套开发模式/SMTP 逻辑:未配 `SMTP_HOST` 时链接写日志 + 接口返回 `url`,前端直接给个可点链接,方便本地点开);
|
||||
- 链接地址默认取当前请求的 host,正式部署建议配 `SITE_URL`(有反代/多域名时更可靠);
|
||||
- 待加固(按需):JWT 是无状态的,重置密码后**旧令牌在过期前仍然有效**(要立即失效可给 `users` 加 `password_changed_at`,鉴权中间件里比对);
|
||||
- **扫码登录**(`app/service/wechat_login.js`):前端登录页顶部是「登录 / 注册」两个 tab,**扫码**用右上角的三角形切换(挂在一个 `.panel-switch` 容器上,和输入框右边缘对齐;登录/扫码面板定成同高,切换时卡片高度不变):
|
||||
- **改密 / 重置密码后旧令牌立即失效(2026-10-17 已做)**:`users` 新增 `password_changed_at`(迁移 `sql/migrations/20261017_add_user_password_changed_at.sql`;老数据为 NULL = 不限制);`service.user.setPassword()`(注册/重置/脚本)与 `auth.changePassword()` 写这个时间;`middleware/api_auth.js` 与 `middleware/internal_auth.js` 比对 JWT 的 `iat`:**iat 秒 < 改密秒 → 401** `{ status:'password_changed', message:'密码已修改,请重新登录' }`(**留 1 秒容差**:改密当秒新签发的令牌仍然可用,避免误杀);
|
||||
- **扫码登录**(`app/service/wechat_login.js`):前端登录页顶部是「登录 / 注册」两个 tab,**扫码**用右上角的三角形切换(三角形挂在**卡片**右上角,只在登录 ↔ 扫码之间切,注册面板不显示):
|
||||
- **串码**:服务端生成 **6 位数字 + 字母**随机串码(`WECHAT_CODE_LENGTH`,字符集去掉了 0/O/1/I 等易混字符),写进 Redis `packs:wechat:state:<code>` = `pending`(TTL `WECHAT_STATE_TTL`);
|
||||
- **二维码内容 = 本站地址**:`http://<域名>/wechat?spm=1.0.<code>.1`(spm 格式由 `WECHAT_SPM_PATTERN` 决定);二维码图片本身用零依赖的 `qrcode-generator` 现场画成 **SVG**(`GET /api/wechat/qrcode.svg?code=…`)——**不需要任何外链资源**;
|
||||
- **完整时序**(都是我们自己的接口,不需要第三方 JS/iframe):
|
||||
@ -583,14 +630,14 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
|
||||
- **联调/自测(三个终端就能跑通整个扫码登录)**:
|
||||
```bash
|
||||
# ① 电脑端:拿登录码
|
||||
curl -s http://127.0.0.1:7001/api/wechat/login
|
||||
curl -s http://127.0.0.1:7300/api/wechat/login
|
||||
# → {"ok":true,"data":{"code":"XBUBHP","spm":"1.0.XBUBHP.1","qrUrl":"/login/wechat/qrcode.svg?code=XBUBHP",...}}
|
||||
|
||||
# ② 电脑端:挂在长轮询上等(25s 内有人确认就立即返回,没人扫就换新码)
|
||||
curl -s 'http://127.0.0.1:7001/api/wechat/login?code=XBUBHP&wait=60'
|
||||
curl -s 'http://127.0.0.1:7300/api/wechat/login?code=XBUBHP&wait=60'
|
||||
|
||||
# ③ 已登录的客户端(或用手机打开 /wechat?spm=1.0.XBUBHP.1):用登录码触发登录
|
||||
curl -s -X POST http://127.0.0.1:7001/api/wechat/confirm \
|
||||
curl -s -X POST http://127.0.0.1:7300/api/wechat/confirm \
|
||||
-H 'Authorization: Bearer <用户JWT>' -H 'Content-Type: application/json' \
|
||||
-d '{"code":"XBUBHP"}'
|
||||
# → ② 的请求会立即返回 {"data":{"status":"confirmed","token":"<JWT>",...}}
|
||||
@ -658,13 +705,13 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
|
||||
- 联调(**新设备不需要先注册**;第三终端是已登录的手机/小程序):
|
||||
```bash
|
||||
# ① 设备发码(拿 code / qrContent / qrImageUrl 显示二维码;带上自己的 SN 与名称)
|
||||
curl -s 'http://127.0.0.1:7001/api/device/login?sn=SN-NEW-01&name=门口扫码枪'
|
||||
curl -s 'http://127.0.0.1:7300/api/device/login?sn=SN-NEW-01&name=门口扫码枪'
|
||||
|
||||
# ② 设备挂长轮询(有人确认就立即返回;参数带上也行)
|
||||
curl -s 'http://127.0.0.1:7001/api/device/login?sn=SN-NEW-01&code=<登录码>&wait=60'
|
||||
curl -s 'http://127.0.0.1:7300/api/device/login?sn=SN-NEW-01&code=<登录码>&wait=60'
|
||||
|
||||
# ③ 手机确认(现有接口,鉴权走 header,不认 cookie)
|
||||
curl -s -X POST http://127.0.0.1:7001/api/wechat/confirm \
|
||||
curl -s -X POST http://127.0.0.1:7300/api/wechat/confirm \
|
||||
-H 'Authorization: Bearer <用户JWT>' -H 'Content-Type: application/json' \
|
||||
-d '{"code":"<登录码>"}'
|
||||
# → ② 立即返回 {"data":{"status":"confirmed","firstTime":true,"sn":"SN-NEW-01",
|
||||
@ -700,7 +747,7 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
|
||||
`POST /api/wechat/confirm` 与同一套 6 位串码(`service/wechatLogin`),**不新增确认接口、不新增 Redis key 空间**;
|
||||
`SN 已属于其他账号 → 403`(不会把别人的设备扫走),无主记录(老接口注册出来的)由本次确认者认领;
|
||||
- **没有 CSRF**:后端已关掉 CSRF(`config.security.csrf.enable = false`),页面表单/会话都没了;扫描器用 JWT 调 JSON 接口不会遇到 403;
|
||||
- 扫码去重放在**数据库唯一键 + 服务层预过滤**两层:唯一键 `(scanner_id, channel_id, barcode, scan_time)` 是最终保证,服务层先查一次再做批量插入(并发撞键时退化为逐条插入并计数),所以重复上报既不报错也不产生脏数据;
|
||||
- 扫码去重放在**数据库唯一键 + 服务层预过滤**两层:唯一键 `(scanner_id, channel_id, barcode, scan_time)` 是最终保证,服务层先查一次再做批量插入(并发撞键时退化为逐条插入并计数),所以重复上报既不报错也不产生脏数据;另外**同一运单号 24 小时内只保留一条**,后上报的扫描时间更新时覆盖原记录(时间 + 工作台快照),旧上报不回退;
|
||||
- 扫码记录是**流水表、不用软删除**(`paranoid: false`):软删除会让记录占用唯一键,导致同一条数据无法再入库;清理请按时间物理删除;
|
||||
- 中控上报遇到未登记的通道会自动补建一行(`channel_name` 留空 + WARN 日志),避免丢数据;若希望严格模式,可在 `app/service/scan.js` 的 `touchChannels()` 里改成抛错;
|
||||
- 前端「测试页」的「模拟中控上报」卡片用**设备 SN + 长期 JWT** 校验身份(验签 + 回查 + 比对 `jti`,与 `middleware/scannerAuth()` 同一条 `service.scanner.resolveByToken()`),再走 `service.scan.*`,等价于设备的 `POST /api/scan/channels` + `POST /api/scan/records`(提交两次即可看到 `duplicated=1`);令牌就是上一张卡片发下来的那枚,重新扫码登录会换新令牌(旧令牌立即失效);
|
||||
@ -711,3 +758,57 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
|
||||
- **鉴权总览**:`/api/web/*`、`/api/wechat/confirm` 走 `app/middleware/api_auth.js`(**只认 header 里的用户令牌**);`/api/users*`、`/api/configs*`、`/api/scanners*` 走 `app/middleware/internal_auth.js`(`X-Internal-Token` 或白名单账号的 user JWT);`/api/scanner/*`、`/api/scan/*` 走 `app/middleware/scanner_auth.js`(设备长期 JWT);公开接口只有 `/api/info`、`/health`、`/api/wechat/{login,status,qrcode.svg,callback}`、`/api/device/login` 与 `/api/web/auth/*`;
|
||||
- 密码等敏感信息放 `config/config.local.js`(已 gitignore)或环境变量,不要写进 `config.default.js`。
|
||||
- 生产环境请修改 `config/config.default.js` 中的 `config.keys`。
|
||||
|
||||
## 主体(租户)体系(2026-10-18)
|
||||
|
||||
业务数据(设备 / NVR / 摄像头 / 工作台 / 扫码记录 / 扫码通道)全部挂在**主体**下,接口按主体隔离。
|
||||
|
||||
### 数据表
|
||||
|
||||
| 表 | 说明 |
|
||||
|---|---|
|
||||
| `subjects` | 主体:`name`、`admin_user_id`(管理员,默认创建人)、`expire_at`(使用期限)、`status`、`remark` |
|
||||
| `subject_members` | 成员:`subject_id` + `name`(姓名,必填)+ `user_id`(绑定账号,可为空)+ `role`(1 管理员 / 2 成员)+ `wechat_openid` / `bound_at` |
|
||||
| 业务表 | `scanners` / `nvrs` / `cameras` / `workstations` / `scan_channels` / `scan_records` 都有 `subject_id` |
|
||||
|
||||
升级时(迁移 `20261018230000-create-subject-tables`)会给**已有数据**的账号各建一个主体(管理员=本人、期限 +365 天),
|
||||
并把名下数据回填进去,保证旧数据不丢。
|
||||
|
||||
### 接口
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|---|---|---|
|
||||
| GET | `/api/web/subjects` | 我可进入的主体列表(含角色 / 成员数 / 是否过期 / `trialDays`) |
|
||||
| POST | `/api/web/subjects` | 创建主体 `{ name, remark? }` → 管理员=创建人,**默认赠送 7 天**(`config.subject.trialDays`,env `SUBJECT_TRIAL_DAYS`) |
|
||||
| GET/PUT | `/api/web/subjects/:id` | 详情 / 改名·备注·续期 `{ name?, remark?, extendDays? }`(仅管理员) |
|
||||
| GET | `/api/web/subjects/:id/members` | 成员列表 |
|
||||
| POST | `/api/web/subjects/:id/members` | 按姓名快速添加成员 `{ name }`(此时还没绑账号) |
|
||||
| DELETE | `/api/web/subjects/:id/members/:memberId` | 移除成员(不能删管理员/自己) |
|
||||
| POST | `/api/web/subjects/:id/members/:memberId/bind-code` | 生成成员绑定码(`{ code, bindUrl, qrUrl, expiresIn }`,10 分钟有效) |
|
||||
| GET | `/api/subject/member-bind?code=` | 绑定码状态(**公开**,手机扫码页轮询) |
|
||||
| POST | `/api/subject/member-bind/confirm` | 手机端确认绑定 `{ code }`(需 user JWT)→ 该账号成为成员 |
|
||||
|
||||
二维码:`GET /api/wechat/qrcode.svg?code=<码>&mode=member`(内容是 `<站点>/wechat?bind=<码>`,前端扫码页显示「确认绑定」)。
|
||||
|
||||
### 主体上下文(统一处理)
|
||||
|
||||
- 业务接口除 `apiAuth` 外**必须再挂 `middleware.subjectAuth()`**;它按 **`X-Subject-Id` header**(也认 `?subjectId=` / body.subjectId)解析主体:
|
||||
- 没带 → **400** `{ status: 'subject_required' }`
|
||||
- 不是该主体成员 / 主体不存在 → **404**
|
||||
- 主体被停用 → **403** `subject_disabled`;主体到期 → **403** `subject_expired`(带 `expireAt`)
|
||||
- 通过后写 `ctx.state.subjectId / subject / subjectMember`,service 一律用 `subjectId` 限定范围
|
||||
- 登录(`POST /api/web/auth/login`)的返回里**带 `subjects` 列表**,前端存下并记住上次使用的主体(`localStorage.packs_subject_id`)。
|
||||
- 设备(中控)没有「当前主体」概念:`GET /api/device/login?subjectId=` 可选,不传就用确认人可进入的第一个主体。
|
||||
|
||||
### 桌面端「设备服务」(本机作为扫码中控)
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|---|---|---|
|
||||
| GET | `/api/web/devices/active` | 本主体已绑定设备(开启前检查用) |
|
||||
| POST | `/api/web/devices/activate` | **仅主体管理员**;`{ sn?, name? }` → `{ device, token, tokenType, expiresIn, kicked[] }` |
|
||||
| POST | `/api/web/devices/:id/logout` | 关闭设备服务(轮换 jti → 该设备令牌立即 401) |
|
||||
| GET | `/api/wechat/qrcode.gif?code=&mode=` | 同一张二维码的 **GIF**(桌面端 WPF 不能渲染 SVG;`online.png` 不需要) |
|
||||
|
||||
**「一个主体只允许一台设备在线」**:`activate` 会把同主体下**其他**设备的 `token_jti` 全部轮换(旧 JWT 立即失效),
|
||||
并在返回的 `kicked` 里列出被踢的设备;同一 SN 重复开启只是换发令牌,不会新建记录。
|
||||
设备令牌用于设备侧上报:`POST /api/scan/channels`、`POST /api/scan/records`(`scannerAuth`,不需要主体 header)。
|
||||
|
||||
@ -95,6 +95,16 @@ dotnet publish -c Release -r win-x64 -p:ServerBaseUrl=https://trace.example.com
|
||||
|
||||
- 编译:**.NET 8 SDK**(`dotnet --list-sdks` 能看到 `8.x`)
|
||||
- 只运行已发布的 exe:**.NET 8 Desktop Runtime**(不需要 SDK)
|
||||
- 打安装包:`desktop\native\ffmpeg\ffmpeg.exe` 必须存在(见 [native/ffmpeg/README.md](native/ffmpeg/README.md))
|
||||
- **默认普通权限运行**:`app.manifest` 是 `asInvoker`(不是 `requireAdministrator`)。
|
||||
双击、开始菜单、网页 `yuncang://` 协议唤起都**不弹 UAC**。
|
||||
- **只有改系统时间才提权**:NTP 窗口点「立即校时 / 同步 NVR 时间」时,才会用 `runas` 拉起
|
||||
一个只做校时的临时进程(弹一次 UAC,见 `Services/ElevatedNtp.cs`)。
|
||||
非管理员启动时,启动/定时自动校时会跳过(日志有 `[ntp] 当前不是管理员权限`)。
|
||||
|
||||
> **ffmpeg 已打进安装包**(`native\ffmpeg\ffmpeg.exe`)。客户机(尤其是非设备服务器的查件电脑)
|
||||
> 不需要自己装 ffmpeg 就能做回放校验、多路合并。bin 里的 exe **不再**去 PATH 里找 ffmpeg 时才可用 ——
|
||||
> 开发时仍可用环境变量 `YUNCANG_FFMPEG` 覆盖版本。
|
||||
|
||||
> 本机 SDK 装在用户目录(免管理员):`%LOCALAPPDATA%\Microsoft\dotnet`,
|
||||
> 已加入用户 `PATH` 和 `DOTNET_ROOT`。**新开的终端**才能直接用 `dotnet`;
|
||||
@ -102,6 +112,34 @@ dotnet publish -c Release -r win-x64 -p:ServerBaseUrl=https://trace.example.com
|
||||
> 直接双击 `bin\...\*.exe` 也需要 `DOTNET_ROOT` 已生效(否则报 “You must install .NET”)。
|
||||
> 官方安装包:`winget install --id Microsoft.DotNet.SDK.8 -e`(要 UAC)。
|
||||
|
||||
## NTP 校时(2026-10-19)
|
||||
|
||||
扫码时间取**本机时钟**,回放按**录像机本地时间**定位;本机时间不准会让录像整体错位
|
||||
(现场实测 Windows 时间服务没启动,本机慢了近 10 秒,30 秒的回放窗口直接把面单截到窗口外)。
|
||||
|
||||
- **入口在「服务 → NTP 校时…」**,只有**设备服务开启**(服务模式)时才显示;关闭设备服务后菜单隐藏。
|
||||
- **服务模式强制项**:NTP 校时必须启用、启动时必须校时、定时校时不能停(间隔至少 5 分钟),
|
||||
窗口里的两个开关会置灰,保存时后端(桌面端)也会再强制一次。
|
||||
- 设置项:NTP 服务器、自动校时间隔(分钟,0 = 仅启动时)、「立即校时」。
|
||||
- **「同步 NVR 时间」**:拉取当前主体全部录像机(`GET /api/web/nvrs`,后端已有,无需新增接口),
|
||||
逐台静默执行:
|
||||
1. 用 8000 私有协议写 NTP(`NET_DVR_SET_NTPCFG`,与桌面端**同一个 NTP 地址**);
|
||||
2. 立即生效:`NET_DVR_SET_TIMECFG` 把设备时间直接校准到 NTP 时间;
|
||||
3. 回读 NTP 配置与设备时间,在窗口里逐台返回结果(✔/✘ + 偏差)。
|
||||
- 启动时校一次 + 运行期间默认每 **30 分钟**校一次;偏差小于 **0.2 秒**不调整。
|
||||
- 实现:`Services/NtpClient.cs`(UDP 123 SNTP)+ `Services/ClockSyncService.cs`
|
||||
(打开 `SeSystemtimePrivilege` 后调用 `SetSystemTime`);NVR 侧在 `HikDeviceService.GetNtpConfig/SetNtpConfig/SetDeviceTime`。
|
||||
- 改系统时间需要管理员,但**不再要求整个软件以管理员启动**:
|
||||
非管理员时点「立即校时 / 同步 NVR 时间」会通过 `runas` 起一个只做校时的临时进程
|
||||
(`--ntp-sync-elevated`,见 `Services/ElevatedNtp.cs`),结果写到临时 JSON 供主进程读回;
|
||||
用户点「否」只提示「已取消」,不会报错。
|
||||
- 日志:`[ntp] 启动校时完成:ntp.aliyun.com 偏差 +9.60 秒,往返 30 ms`;
|
||||
`[ntp] 同步 NVR 完成:1/1 台(…)`;失败只记日志,不影响登录/查询。
|
||||
- 回放侧仍会按录像机时钟做二次对齐(`HikPlaybackService.ClockOffset`),
|
||||
即使本机时间临时不准也不会截掉面单。
|
||||
|
||||
## 构建 / 运行 / 发布
|
||||
|
||||
## 构建 / 运行 / 发布
|
||||
|
||||
```powershell
|
||||
@ -158,7 +196,9 @@ cd desktop\installer
|
||||
### 脚本做了什么
|
||||
|
||||
1. `dotnet publish`(自包含单文件,不依赖 .NET 运行时;版本号一起注入程序集);
|
||||
2. `wix build` 生成 MSI;
|
||||
**同时把 `native\HCNetSDK\**`、`native\ffmpeg\**` 作为独立文件输出**(不走单文件自解压);
|
||||
缺 `publish\native\ffmpeg\ffmpeg.exe` 会直接报错中止;
|
||||
2. `wix build` 生成 MSI(`Product.wxs` 用 `<Files Include="..\publish\native\**" />` 递归收集,保持目录结构);
|
||||
3. 算 MD5 → 写 `version.json`;
|
||||
4. 复制到后端:MSI → `backend/app/public/download/`,`version.json` → `backend/app/public/version/`;
|
||||
5. 本地 `out/` 与后端目录**各只保留最近 5 个**安装包(`keepVersions` 可配)。
|
||||
@ -403,29 +443,45 @@ reg query "HKCU\Software\Classes\yuncang\shell\open\command"
|
||||
|
||||
## ★ 接真实数据
|
||||
|
||||
只改一处:`Services/OrderQueryService.cs` 的 `Query(string? code)`。
|
||||
运单查询已经接后端了:`Services/OrderQueryService.cs` 的 `QueryAsync(code)` 调
|
||||
`GET /api/web/pack-query?code=`(用户令牌 + `X-Subject-Id`),**范围限定当前主体**。
|
||||
|
||||
```csharp
|
||||
public QueryResult Query(string? code)
|
||||
{
|
||||
var value = (code ?? "").Trim();
|
||||
if (value.Length == 0) return QueryResult.BadRequest("缺少运单号");
|
||||
后端用**扫码当时的工作台快照**(`scan_records.workstation_snapshot`)算好回放计划,
|
||||
本机只负责把返回拍成「项目 / 值」两列:
|
||||
|
||||
// 例:查本地 SQLite / 扫本地打包视频目录 / 调内部接口
|
||||
var row = _db.FindByCode(value);
|
||||
if (row is null) return QueryResult.NotFound($"没有找到 {value} 的记录");
|
||||
| 字段 | 含义 |
|
||||
| --- | --- |
|
||||
| `扫码记录数` | 同一运单被扫了几次(不同中控/通道/重复扫) |
|
||||
| `记录 N · 扫码时间` | 已转成本机本地时间 |
|
||||
| `记录 N · 中控 / 通道` | 哪台中控的哪个通道 |
|
||||
| `记录 N · 工作台` | 当时的工作台 + 类型(团购 / 散单) |
|
||||
| `记录 N · 回放区间` | `开始 ~ 结束(秒)`,散单被最大录制时长截断时会标注 |
|
||||
| `记录 N · 录像机` | 涉及的录像机(名称 + `IP:端口`) |
|
||||
| `记录 N · 摄像头` | 通道号 + 名称 + 在画布上的位置/尺寸(多路合并要按这个摆) |
|
||||
|
||||
return QueryResult.Success(new Dictionary<string, object?>
|
||||
{
|
||||
["code"] = row.Code,
|
||||
["orderNo"] = row.OrderNo,
|
||||
["printStatus"] = row.PrintStatus,
|
||||
["videoPath"] = row.VideoPath,
|
||||
});
|
||||
}
|
||||
```
|
||||
> **自动校验回放**:查询命中(后端返回了 `streams`)后,桌面端会**立刻**逐路去录像机试拉
|
||||
> (每路 2 秒,面板里显示进度),**任意一路拉到录像就停止校验**并显示「预览回放 / 下载录像」按钮 ——
|
||||
> 不需要把每一路都验完,也不需要用户手动点「校验」。
|
||||
> 预览和下载仍按**全部**流处理:没录像的那几路在下载时自己跳过,保证多路合并不会退化成单路。
|
||||
>
|
||||
> **回放时间按录像机时钟对齐**:扫码时间来自本机时钟,回放是按录像机本地时间定位的。
|
||||
> 每次校验/预览/下载前会读一次录像机时间(8000 私有协议),把请求窗口整体平移,
|
||||
> 日志里能看到 `[playback] 录像机 … 与本机时钟相差 X 秒`。本机时间不准(比如 Windows
|
||||
> 时间服务没开、慢了几秒)时,短回放窗口会把面单截到窗口外 —— 这一步就是防这个。
|
||||
|
||||
返回对象**平铺**即可,前端页面会把顶层字段渲染成「项目 / 值」两列(字段随便加)。
|
||||
查询日志只记结论(`[pack-query] 运单号 → found=… records=… streams=…`),不再写完整 JSON;
|
||||
要排查原始数据看后端日志或页面。
|
||||
|
||||
要换成别的数据源,只改 `OrderQueryService.QueryAsync` 一个方法就行(返回 `QueryResult`,
|
||||
`Data` 是扁平字典即可,前端 `/local` 页也吃这份数据)。
|
||||
|
||||
### 扫码 → 查询(不跳页)
|
||||
|
||||
- 手动输入 / 回车 / 点查询 / 协议唤起:`RunQueryAsync()`,**切到「打包查询」页**展示;
|
||||
- 通道扫码:`OnChannelBarcode` 后台算一次结果,**绝不切页签**
|
||||
(用户还在「扫码通道 / 扫码记录」页时,只在「打包查询」页签上加 `●`,
|
||||
切过去时才把结果显示出来);
|
||||
- 扫码数据本身仍由 `ScanService` 落记录 + 上报,跟查询是两条独立的路。
|
||||
|
||||
## 常见问题
|
||||
|
||||
@ -437,3 +493,147 @@ public QueryResult Query(string? code)
|
||||
| 点网页「启动本机软件」没反应 | 协议没注册(界面看「启动协议」状态);或浏览器拦了自动跳转(必须用户点击) |
|
||||
| 唤起时弹「You must install .NET Desktop Runtime」 | 唤起的是 `bin\Debug` 这类 framework-dependent 的 exe(拿不到 `DOTNET_ROOT`)。用自包含发布产物,并让它启动一次以校正注册表 |
|
||||
| 改了协议名 | 注册表重注册 + 前端 `VITE_APP_PROTOCOL` 同步 + 插件目标地址同步 |
|
||||
|
||||
## 主体切换 / 微信扫码登录 / 设备服务(2026-10-18)
|
||||
|
||||
### 登录窗
|
||||
- **微信扫码登录**:点「微信扫码登录」→ `GET /api/wechat/login` 发码 → 显示二维码
|
||||
(`GET /api/wechat/qrcode.gif?code=`,WPF 不能渲染 SVG 所以后端额外给了 GIF 版)→ 长轮询
|
||||
`GET /api/wechat/login?code=&wait=25`,手机确认后直接拿令牌进主界面;码过期会自动换新。
|
||||
- 账号密码登录与微信登录**都会带回主体列表**(`subjects`),主界面右上角显示当前主体。
|
||||
|
||||
### 主界面
|
||||
- 左上状态行:`主体:xxx · 设备服务:未开启 / 已开启(SN)`。
|
||||
- 菜单 **服务**:
|
||||
- `当前主体:xxx` → 弹窗切换主体(`GET /api/web/subjects`;切换后设备服务若开着会提示在新主体下重新开启)
|
||||
- `开启设备服务`(**只有主体管理员可见**;默认关闭)
|
||||
- `关闭设备服务`(开启后才出现)
|
||||
- `服务状态:运行中/未启动`
|
||||
- **开启流程**:先 `GET /api/web/devices/active` 看该主体是否已有设备 → 有就弹确认
|
||||
「一个主体只允许一台设备在线,开启后它会被踢下线」→ `POST /api/web/devices/activate`
|
||||
(服务端踢人 + 发长期设备 JWT)→ 上报本机通道 `DESKTOP / 本机中控`。
|
||||
- **上报**:开启后,本机每处理一个运单号(协议唤起 / 测试查询)都会 `POST /api/scan/records`
|
||||
(通道 `DESKTOP`,服务端按 设备+通道+条码+秒 去重)。关闭/退出登录时会 `POST /api/web/devices/:id/logout` 让令牌立即失效。
|
||||
- 状态都落在 `%LOCALAPPDATA%\YuncangTrace\settings.json`(`SubjectId/SubjectName/SubjectRole`、
|
||||
`DeviceServiceEnabled/DeviceId/DeviceSn/DeviceToken`),其中 `DeviceServiceEnabled` **默认 false**。
|
||||
|
||||
### 相关文件
|
||||
`Services/ApiClient.cs`(登录/微信/主体/设备/上报)、`Services/DeviceService.cs`(开启/关闭/上报)、
|
||||
`Services/AppSettings.cs`(新增主体与设备字段)、`LoginWindow.*`(微信面板)、`MainWindow.*`(服务菜单 + 状态行)、
|
||||
`SubjectPickerWindow.*`(切换主体弹窗)。
|
||||
|
||||
### 后台扫码服务(Windows 服务,2026-10-19)
|
||||
|
||||
「开启设备服务」不再依赖桌面端常驻:会安装系统服务 **`YuncangTraceAgent`**(LocalSystem、自动启动),
|
||||
**退出软件 / 注销用户 / 重启电脑后继续收码上报**。
|
||||
|
||||
| 项 | 位置 / 说明 |
|
||||
|---|---|
|
||||
| 服务程序 | `%ProgramData%\YuncangTrace\agent\YuncangTraceAgent.exe`(从安装目录复制;**MSI 升级不会撞「文件被占用」**) |
|
||||
| 服务配置 | `%ProgramData%\YuncangTrace\agent.json`:服务器地址 + **长期设备令牌**(默认 365 天)+ NTP 设置 |
|
||||
| 服务令牌 | `%ProgramData%\YuncangTrace\agent-token.json`:访问令牌 + **刷新令牌**(服务自动续期后更新;单独一份避免和 agent.json 互相覆盖) |
|
||||
| 共享数据 | `channels.json` / `scan-records.json` 在 `%ProgramData%\YuncangTrace\`(普通模式仍在 `%LOCALAPPDATA%`) |
|
||||
| 运行状态 | `agent-status.json`:是否运行 / 通道在线 / 待上传条数 / NTP 结果,桌面端只读展示 |
|
||||
| 命令 | `agent-command.json`:立即上传 / 清空记录 / 重新加载通道 / 立即校时 / 立即续期令牌(服务每秒轮询) |
|
||||
| 发现列表 | `agent-discovered.json`(桌面端「扫码通道」页展示用) |
|
||||
| NTP | 服务以 LocalSystem 定时校时,**不再需要 UAC**;NTP 窗口的「立即校时」只写命令文件 |
|
||||
| 安装 / 卸载 | 开启 / 关闭设备服务时用 `runas` 提权(**各弹一次 UAC**),之后日常使用无 UAC |
|
||||
| 升级 | 新版本启动后检测服务副本版本,提示更新(一次 UAC) |
|
||||
| 日志 | `%ProgramData%\YuncangTrace\agent\logs\log_*.txt` |
|
||||
| 日志策略 | 按天一个文件,**自动保留 14 天**;状态文件改为「内容变化才写 + 30 秒保活」(不再每 2 秒重写);面单压着扫码器时同一个码每 5 分钟才记一行 |
|
||||
| 手动排障 | `sc query YuncangTraceAgent` / `sc start|stop YuncangTraceAgent` |
|
||||
| 调试 | `YuncangTrace.LocalService.exe --agent-run`(不经 SCM,直接跑后台循环) |
|
||||
|
||||
> **退出登录不会关闭设备服务**:服务模式下只清登录态,设备令牌和 `agent.json` 保留,扫码继续上报。
|
||||
> 要停止必须走「服务 → 关闭设备服务」。
|
||||
>
|
||||
> **换账号登录(不属于后台服务主体)**:后台服务是独立进程,继续按原主体扫码/上报;
|
||||
> 桌面端会把**界面主体**自动切到当前账号可用的主体(查询用),并在状态行标注「服务主体 id=xxx」。
|
||||
> 此时:
|
||||
> - **管理员**:扫码通道 / 扫码记录页照常显示,但页顶有醒目提示「后台服务运行在主体 id=xxx,与当前主体不一致」,
|
||||
> 要换到当前主体必须先「服务 → 关闭设备服务」,再「开启设备服务」重新绑定;
|
||||
> - **普通成员**:扫码通道 / 扫码记录页**直接隐藏**(本地文件是那台服务的数据,与当前账号的主体无关),只保留打包查询;
|
||||
> - 查询接口用的是当前账号的主体;「关闭设备服务」仍可执行:先停/卸载本地服务,再尝试通知服务器注销(不是该主体成员时服务端注销会失败,日志有记录);
|
||||
> - 账号下**一个主体都没有**:弹窗提醒后**直接退回登录页**(后台服务保持运行,换有主体的账号登录即可)。
|
||||
>
|
||||
> 只有当前界面主体就是服务主体时,切换主体才必须先关闭设备服务(避免扫码写到旧主体)。
|
||||
>
|
||||
> **令牌自动续期**:激活时后端同时下发访问令牌(365 天)和刷新令牌(默认 730 天)。
|
||||
> 后台服务在访问令牌剩余不足 7 天时自动调 `POST /api/device/refresh` 换新(两者都轮换),
|
||||
> 结果写到 `agent-token.json`;只要服务在跑就不需要人工重新激活。
|
||||
> 关闭设备服务 / 被同主体其它设备踢下线时,刷新令牌一并作废。
|
||||
> 需要验证续期流程时:菜单 **服务 → 立即续期设备令牌**(写 `RefreshTokenAt` 命令),服务会立即换一次并记日志。
|
||||
>
|
||||
> **设备心跳**:后台服务每 **60 秒**调 `POST /api/scanner/heartbeat` 刷新后端 `last_seen_at`,
|
||||
> 所以即使长时间没扫码,网页设备列表也能看出服务在线;心跳 401 会触发令牌续期。
|
||||
>
|
||||
> 服务模式下桌面端只做界面/配置:不启动本进程的 `ScanService`(避免和后台服务抢设备连接),
|
||||
> 通道在线状态、扫码记录都从服务写的文件里读。
|
||||
|
||||
## 扫码服务(从 AndroidScanCenter 移植,2026-10-18)
|
||||
|
||||
扫码中控不再由 Android 盒子承担,**TCP/UDP 通讯全部搬到桌面端**:
|
||||
|
||||
| 能力 | 实现 | 说明 |
|
||||
|---|---|---|
|
||||
| 设备发现 | `Services/Scan/DiscoveryMonitor.cs` | **常驻 UDP**:一个 socket 一直开着,每 3s 向 `255.255.255.255` + 各网段定向广播发一次探测,期间**持续收**、按 MAC 合并,12s 没见到就摘掉。⚠️ 设备**不会主动广播**(实测绑 48899 静听 40s 只能收到自己的探测包),回复只发回**发送方源端口**,所以不能在 48899 上被动监听 |
|
||||
| 设备配置 / 重启 | 同上(JCMD) | `CID 10003` 读 SYS、`10005` 写 SYS(增量)、`20003` 重启;**不要发 `DO_RELOAD`**(会抹掉改动) |
|
||||
| 写设备名 / 确保 TCP 服务 | `Services/Scan/DeviceConfig.cs` | 条目 **`packcenter` / TCP-SERVER / 8087**(**不用 Android 的 `scancenter:8086`**),缺失/不对则整条写入 → `10017` **落 flash** → 回读校验;**设备最多放 3 条 SOCK**,满了就复用一条非保留条目(`scancenter`、`netp` 是别人的,绝不动),实际用的名字记在通道的 `SockName` 上;写前备份全部条目原始字段,写完发现别人的条目丢了会**原样写回** |
|
||||
| 自愈 | `ScanService.HealAsync` | 通道连续 3 次连不上 → 回查设备 SOCK 条目,被删/被改就重建(每台设备 60s 最多一次) |
|
||||
| 收条码 | `Services/Scan/ChannelConnection.cs` | 每条通道一条 **TCP 出向连接**到设备 `:8087`(设备当服务端),按 CR/LF 切行,断线 5s 重连;设备每 ~0.7s 推的 6 字节二进制帧(`04 D0 00 00 FF 2C`)会被忽略,不污染条码行 || 扫码枪设置 | `Services/Scan/ScannerCommands.cs` | 连上后一次写 28 字节:**连续扫描 + 识别间隔 0s + 静音状态**(9+9+10,静音那两条是 10 字节,校验位照抄)。写失败不影响收码。扫码枪自己重启会丢设置,靠“每次重连都下发”自动兜住 |
|
||||
| 静音 | `ScanService.SetMuted` | **只存本地 + 让连接重走一遍**(关 socket → 立即重连 → 整条设置重下发)。不在现有 socket 上补写指令:Android 侧实测“字节发出去了但枪没执行”时无法判断 |
|
||||
| 串口指令调试 | `Views/ScannerCommandWindow`(通道页「串口指令…」) | 发任意 **HEX 字节**透传给扫码枪,预填四条常用指令(静音/恢复蜂鸣/连续扫描/间隔 0s)。换批枪后指令集不同时现场自己试,不用发版 |
|
||||
| 假死看门狗 | `ScanService.WatchdogLoopAsync` | 每 30s:连接看着在线但 **60s 没字节** → 回查设备侧 `SOCK.ClientIP`(CID 10001 才有)→ 本机 IP 不在里面就强制重连(设备断电重启时 TCP 不发 FIN,`ReadAsync` 会永久挂住) |
|
||||
| IP 变化 | `ScanService.ApplyDiscoveredIps` | 每次发现结果回来就刷新各通道 `LastIp`,变了立即用新地址重连(DHCP 续租后不会卡在旧 IP) || 通道配置 | `Services/Scan/ChannelStore.cs` | `%LOCALAPPDATA%\YuncangTrace\channels.json`(服务模式:`%ProgramData%\YuncangTrace\channels.json`),通道号取最小空号、删除后不复用;**不再有团购/散单字段**(团散在「工作台」区分) |
|
||||
| 编排 | `Services/Scan/ScanService.cs` | 启动→连接所有启用通道;**通道一旦变动(增/删/停用)自动同步到服务器**:`POST /api/scan/channels` → `GET /api/scan/channels` 回查确认 → 缺了就退避重试(1s→30s)直到服务器真的有 |
|
||||
| 扫码记录 | `Services/Scan/ScanRecordStore.cs` | `%LOCALAPPDATA%\YuncangTrace\scan-records.json`(服务模式:`%ProgramData%\YuncangTrace\scan-records.json`),每个通道最多 5000 条;**先落本地、服务器确认后才标「已上传」**,没确认的一直重试,断网不丢;连续扫描只刷新「最近一次扫到的时间」;**扫到后 5 分钟没再扫到同一个码才上报**,上报的就是最后一次扫描时间;同一运单 24 小时内再次扫到会**重新激活同一条本地记录**(不新增行),下一轮上报覆盖服务器记录 |
|
||||
| 上报队列 | `Services/DeviceService.cs` | 条码静默满 5 分钟后后台攒批(50 条/批)推 `POST /api/scan/records`,失败不标记、指数退避重发(服务端按 设备+通道+条码+秒 精确去重;**同一运单 24 小时内只保留一条,后上报的新时间会覆盖旧记录的时间与工作台快照**) |
|
||||
|
||||
### 添加通道(设备名 + 通道号)
|
||||
|
||||
`扫描设备 → 选中 → 添加为通道` 会弹窗让用户定**通道号**与**设备名**(与 AndroidScanCenter 一致):
|
||||
|
||||
- **通道号**:`1..50` 的下拉框,已占用的号照样列出来并标注「已被 xx 占用」,选中就提示、不关框;
|
||||
默认勾在最小空号上。没有「通道号」设备字段 —— 它是**本地概念**(现场认工位),上报时就是 `channelId`。
|
||||
- **设备名**:默认填设备自报的 `HostName`,会**写进设备**(`SYS.HostName`,UTF-8 支持中文)并落 flash;
|
||||
留空则用设备自报名。写失败**不阻断**添加(只影响设备面板/其他上位机看到的叫法)。
|
||||
|
||||
添加顺序是「**先配设备、后落本地**」(回滚本地行不通:设备名可能已经写上去了):
|
||||
|
||||
1. 确保设备有给中控用的 TCP 服务(`SOCK` 段 `packcenter / TCP-SERVER / 8087`):
|
||||
已就绪则不写;缺失/不对则整条写入 → **回读确认**(设备 `RC=0` 只代表报文收到了,端口冲突它不报错);
|
||||
这一步失败就**整个添加失败**,本地什么都不写(否则会得到一条永远连不上的死通道)。
|
||||
2. 设备名与自报的不同 → `10005` 写 `SYS.HostName` → `10017` 落 flash(不落盘一次重载就丢)。
|
||||
3. 才把通道写进本地配置、开始连 TCP,并同步通道列表到服务器。
|
||||
|
||||
真机验证(`192.168.9.204`,E10C 1.41.1):`写设备配置 SYS:0` → `保存到 flash:0` →
|
||||
广播里的 `HostName` 立即变成新名字 → `通道 1(工位 9)已连接 192.168.9.204:8087`。
|
||||
|
||||
### 界面
|
||||
- 主窗口改成页签:**打包查询** / **扫码通道**(后者仅在「设备服务」开启后出现)。
|
||||
查到条码(协议唤起或通道扫码)时**默认切回「打包查询」页签**并自动查询。
|
||||
- 扫码通道页:**每个区块的状态与按钮都在各自标题行上**。
|
||||
- 「扫码通道」标题行:状态(`扫码服务运行中 · 通道 N 个(在线 M)` + 通道同步状态 + 待上传条数)+ `重连全部` / `停用` / `静音`(选中行切换,已静音时叫「恢复蜂鸣」)/ `读取设备配置` / `删除通道`;
|
||||
通道列表有「状态」「静音」两列;
|
||||
**没有「同步通道」按钮** —— 通道增删/启停都会自动上传并回查确认;
|
||||
- 「发现到的设备」标题行:`开始扫描`(**开关**,打开后常驻发现:每 3s 探测、socket 一直收,直到手工停止)+ `添加为通道` + 状态(`正在扫描… 未添加 N 台` / `发现 N 台未添加的设备(另有 M 台已添加)`)。
|
||||
- **已经添加为通道的设备不会再出现在发现列表里**:显示集合与「发现到的全集」分开存(`_allDevices` / `_devices`),
|
||||
按通道 MAC 过滤;删掉通道后那台设备会自己回到列表里,不用重新扫。每轮结果按 MAC 合并,不整表覆盖(UDP 丢包时设备不会闪没)。
|
||||
- 扫码记录页(对应 AndroidScanCenter 的「通道回放」,`Views/ScanRecordsView`):
|
||||
通道筛选 / `立即上传` / `清空`,列表显示 时间 / 通道 / 号 / 条码 / **已上传或待上传** / 确认时间,
|
||||
状态行是 `全部通道:显示 N 条 · 本地共 M 条 · 待上传 K 条`。
|
||||
数据源是本地记录库,所以**服务器挂了也能看到刚才扫了什么、还有多少没传出去**。
|
||||
- 菜单 **工具 → 打开配置页(后台)**:用系统浏览器打开 `{服务器}/?token=<用户JWT>`,
|
||||
前端启动时读 `?token=` 存进 localStorage 并把参数从地址栏去掉(免登录,见 `frontend/src/router/index.ts`)。
|
||||
|
||||
### 联调验证(本机)
|
||||
用 `node` 起一个假设备(`127.0.0.1:8087` 推两行条码)→ 开启设备服务 → 日志:
|
||||
```
|
||||
[scan] 扫码服务已启动,通道 1 个
|
||||
[scan] 通道已同步到服务器并确认:1 个
|
||||
[scan] 通道 1(模拟扫码枪)已连接 127.0.0.1:8087
|
||||
[scan] 通道 1 扫码:TESTCH-BARCODE-9001(5 分钟未再扫到后上报)
|
||||
(5 分钟后)
|
||||
[scan] 已上报扫码 1 条
|
||||
```
|
||||
数据库 `scan_records` 里 `channel_id=1`、`device_sn=MINGREN`;工作台可绑定通道 `1/模拟扫码枪`。
|
||||
|
||||
56
desktop/native/ffmpeg/README.md
Normal file
56
desktop/native/ffmpeg/README.md
Normal file
@ -0,0 +1,56 @@
|
||||
# native\ffmpeg —— 内置 ffmpeg(随安装包一起发)
|
||||
|
||||
> **当前内置**:`ffmpeg version 9.0.2-essentials_build`(gyan.dev),100.5 MB,静态单文件,
|
||||
> 含 `libx264`(合并要重新编码)。安装包里就是这一份,客户机不需要自己装 ffmpeg。
|
||||
|
||||
## 为什么放在这里
|
||||
|
||||
回放校验、多路合并、主码流转 MJPEG 都靠 ffmpeg。以前没打进安装包,客户机必须自己装
|
||||
ffmpeg —— 非设备服务器(普通查件电脑)就永远「合并失败,已保留各路段」。
|
||||
|
||||
现在 `YuncangTrace.LocalService.csproj` 会把本目录的内容复制到 `publish\native\ffmpeg\`,
|
||||
`installer\Product.wxs` 的 `<Files Include="..\publish\native\**" />` 再把它装到
|
||||
`%LOCALAPPDATA%\Programs\YuncangTrace\native\ffmpeg\`。
|
||||
|
||||
运行时查找顺序(`HikFfmpegService.ResolveFfmpeg`):
|
||||
|
||||
1. 环境变量 `YUNCANG_FFMPEG`(指向 ffmpeg.exe,用于临时换版本排障)
|
||||
2. 程序目录下 `native\ffmpeg\ffmpeg.exe` ← **安装包带的就是这个**
|
||||
3. 系统 PATH 里的 `ffmpeg.exe`
|
||||
|
||||
## 放什么
|
||||
|
||||
只需要一个文件:`desktop\native\ffmpeg\ffmpeg.exe`(**静态构建**,不带 DLL)。
|
||||
|
||||
- `ffmpeg.exe` 要 **ExcludeFromSingleFile**(已在 csproj 里配好),否则会被塞进自解压 exe,体积暴涨且目录不存在。
|
||||
- 不要放 `ffplay.exe` / `ffprobe.exe`(程序用不到,白占 ~200MB)。
|
||||
|
||||
推荐构建(体积从小到大):
|
||||
|
||||
| 来源 | ffmpeg.exe | 说明 |
|
||||
| --- | --- | --- |
|
||||
| gyan.dev `ffmpeg-release-essentials` | ≈ 100 MB | 含 libx264(合并要重新编码),够用 |
|
||||
| BtbN `ffmpeg-master-latest-win64-gpl` | ≈ 90 MB | 同样含 libx264 |
|
||||
| gyan.dev `full_build` | ≈ 231 MB | 库最全,但安装包会涨到 ~190 MB,不建议 |
|
||||
|
||||
下载 zip 后从 `bin\` 里取 `ffmpeg.exe` 拷到本目录即可。
|
||||
|
||||
```
|
||||
# 例:用 winget 装过 full build 的机器上直接取
|
||||
Copy-Item "$env:LOCALAPPDATA\Microsoft\WinGet\Packages\Gyan.FFmpeg_*\ffmpeg-*\bin\ffmpeg.exe" `
|
||||
"D:\packService\desktop\native\ffmpeg\ffmpeg.exe" -Force
|
||||
```
|
||||
|
||||
## 校验
|
||||
|
||||
```powershell
|
||||
.\desktop\native\ffmpeg\ffmpeg.exe -hide_banner -version
|
||||
.\desktop\native\ffmpeg\ffmpeg.exe -hide_banner -encoders | Select-String libx264
|
||||
```
|
||||
|
||||
`libx264` 必须存在 —— 多路合并走的是 `-c:v libx264 -preset veryfast -crf 23`。
|
||||
|
||||
## 注意
|
||||
|
||||
- 本目录的 `*.exe` **不进 git**(见根 `.gitignore`),克隆后按上面的说明放好即可。
|
||||
- `installer\build.ps1` 打包前会检查 `publish\native\ffmpeg\ffmpeg.exe` 是否存在,缺了直接报错,不会悄悄打出一个不能用的包。
|
||||
@ -2,8 +2,8 @@
|
||||
|
||||
Chrome / Edge 扩展(**Manifest V3 + 原生 JS,零构建**)。
|
||||
|
||||
它注入到**第三方 WMS / 后台页面**里,按规则把「运单号」这类字段就地**二次加工**成可点击元素;
|
||||
点击后打开溯源页面(当前先用 `https://www.baidu.com/?keyword={code}` 占位),把编号作为关键词带过去。
|
||||
它注入到**第三方 WMS / 后台页面**里,按规则找到「运单号」这类字段,在它**旁边**渲染一个
|
||||
「▶ 查看打包视频」按钮(宿主元素一个字都不改);点击按钮打开溯源页面,把编号作为关键词带过去。
|
||||
|
||||
> 首个取样站点:`https://wms.wms.gztbyc.com/order/orderManagement`
|
||||
> 运单号长这样:
|
||||
@ -11,7 +11,14 @@ Chrome / Edge 扩展(**Manifest V3 + 原生 JS,零构建**)。
|
||||
> <span class="click-copy-link" role="button" tabindex="0"
|
||||
> title="点击复制并查看快递单号二维码">321408064481776</span>
|
||||
> ```
|
||||
> 点击它 → 小窗打开 `https://www.baidu.com/?keyword=321408064481776`
|
||||
> 扩展会在它后面插一个按钮(插在 `+1` 展开按钮之前):
|
||||
> ```html
|
||||
> <span class="click-copy-link" …>321408064481776</span>
|
||||
> <button class="pst-trace-mark pst-trace-btn" data-pst-code="321408064481776"
|
||||
> data-pst-url="https://www.baidu.com/?keyword=321408064481776">查看打包视频</button>
|
||||
> ```
|
||||
> 点按钮 → 小窗打开 `https://www.baidu.com/?keyword=321408064481776`。
|
||||
> 原来的运单号仍保留 WMS 自带的「点击复制二维码」行为。
|
||||
|
||||
---
|
||||
|
||||
@ -45,30 +52,81 @@ extension/
|
||||
用 `<script src>` 或 `manifest.content_scripts.js` 按顺序加载它。改完代码在 `chrome://extensions` 点一下
|
||||
刷新即可(改 `manifest.json` 才需要重装)。
|
||||
|
||||
## 3. 两种匹配方式
|
||||
## 3. 匹配方式 × 加工方式
|
||||
|
||||
**匹配(怎么找)**
|
||||
|
||||
| 方式 | 适用 | 关键字段 |
|
||||
| --- | --- | --- |
|
||||
| **文本正则** | 页面结构会变、但有稳定的编号格式(`YT1234…`) | `pattern` + `flags`(可带 `exclude` 排除) |
|
||||
| **CSS 选择器** | 元素本身很好定位(Element-Plus 表格里的 `[title*="快递单号"]`) | `selector` + `attr`(空 = 取元素文本) |
|
||||
| **CSS 选择器** | 元素本身好定位,**或编号在属性里** | `selector` + `attr`(空 = 取元素文本)+ 可选 `pattern` |
|
||||
| **文本正则** | 页面结构会变、但有稳定的编号格式(`YT1234…`) | `pattern` + `flags`(必填,可用 `exclude` 排除) |
|
||||
|
||||
- **文本正则**:遍历文本节点,把**命中的子串**包成 `<span class="pst-trace-mark" data-pst-code="…">`。
|
||||
原文原样保留在 span 里,所以宿主页读 `textContent`、复制粘贴、表单校验拿到的内容**都不变**。
|
||||
- **CSS 选择器**:直接给命中元素加类名和 `data-pst-*`,不包一层(适合本来就是个 `<span>` / `<tr>` 的情况)。
|
||||
- `pattern` 的**第 1 个捕获组**会被当成编号(`{code}` 的值);没写捕获组就用整个匹配。
|
||||
- 选择器模式下 `pattern` 是**可选**的:填了就从「`attr` 取到的值 / 元素文本」里**再抽一次**编号。
|
||||
- ⚠️ **属性里的值只能用选择器模式**:文本正则只遍历文本节点,拿不到属性值。
|
||||
|
||||
### 例:编号藏在 `javascript:` 链接里
|
||||
|
||||
```html
|
||||
<a href="javascript:MM_openTrace('../system/view-trace!viewTrace.jspb?postNum=202610101621&wareHouseId=5400')">
|
||||
202610101621
|
||||
</a>
|
||||
```
|
||||
|
||||
这条的编号既在链接文字里、也在 `href` 的 `postNum=` 参数里。两种写法都行:
|
||||
|
||||
| 写法 | selector | attr | pattern | 说明 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| **从属性抽(推荐)** | `a[href*="postNum="]` | `href` | `postNum=([0-9A-Za-z_-]+)` | 不依赖链接文字,文字被改成「查看轨迹」也照样能取到编号 |
|
||||
| 取链接文字 | `a[href*="postNum="]` | *(空)* | *(空)* | 简单;引擎会对取到的文本 `trim()`,那一大串换行/制表符会被去掉 |
|
||||
|
||||
内置示例规则不再默认带着这种结构(2026-10-17 已移除);真要处理 旧版 JSP 轨迹链接,在配置页自己加一条规则(下表两种写法都行)。
|
||||
因为是 `button` 加工方式,按钮插在 `<a>` **之后**,`<a>` 自己那个 `javascript:MM_openTrace(...)` 照旧能用。
|
||||
|
||||
**加工(找到之后干什么)**
|
||||
|
||||
| 方式 | 行为 | 适合 |
|
||||
| --- | --- | --- |
|
||||
| **`button`(默认)** | 命中元素**一个字都不改**,只在它旁边插一个「查看打包视频」兄弟按钮 | 元素本身有自己的点击行为(比如「点击复制二维码」),不能抢 |
|
||||
| **`chip`** | 命中元素**自己**变成可点(加类名 / 改写 `title` / 接管点击);可配下划线 / 高亮 / 胶囊 + ▶ 角标 | 命中处本来只是普通文字 |
|
||||
|
||||
- `button` 方式是**零侵入**的:
|
||||
- 不加类名、不改 `title`、不动 `role` / `tabindex`、**不接管它的点击** → 页面原有的行为完全不受影响;
|
||||
- 只往宿主元素上写 `data-pst-code` / `data-pst-rule` 两个属性当「已处理」记号
|
||||
(`data-*` 对事件和渲染没有任何影响),撤销时一并摘掉;
|
||||
- 按钮插在命中元素之后;若命中元素在 `<a>` 里,则退到那个 `<a>` 之后
|
||||
—— `<button>` 嵌进 `<a>` 是非法嵌套。
|
||||
- `chip` 方式下点击会被脚本在捕获阶段拦掉(`preventDefault + stopImmediatePropagation`),
|
||||
所以**原元素自己的点击不会再触发**;想用原功能就按住修饰键点(见「行为约定」)。
|
||||
- `text` 正则 + `button`:因为要把按钮放到「命中位置的旁边」,必须包一层**纯定位**的
|
||||
`<span class="pst-trace-anchor">`(无任何视觉、不带可点类名、不拦点击);它是原文照抄的,
|
||||
所以被匹配到的那段文字没变。
|
||||
- 按钮文案在**基本设置**里配(默认「查看打包视频」);全局和单条规则都能设 `actionMode`,规则留空则跟随全局。
|
||||
- 提醒:按钮是真实 DOM,所以**容器元素的 `textContent` 会多出按钮文案** —— 这是插入 UI 的必然结果,
|
||||
被匹配的那段文字本身没有被改动。
|
||||
|
||||
### 内置规则
|
||||
|
||||
**只内置一条**(实测这一条就能盖住真实页面的单号):
|
||||
|
||||
| id | 说明 | 生效站点 | 默认 |
|
||||
| --- | --- | --- | --- |
|
||||
| `wms-waybill` | `[title*="快递单号"]`,取文本 —— **取样自 gztbyc WMS** | `wms.wms.gztbyc.com` / `*.gztbyc.com` | 开 |
|
||||
| `express` | `\b(?:YT\|SF\|JD\|ZTO\|YTO\|STO\|EMS\|DBL)\d{10,16}\b` 通用文本规则 | 全部 | 开 |
|
||||
| `numeric` | 纯数字 12~20 位 | 全部 | **关**(容易把时间戳、内部 ID 点亮,页面上到处下划线反而没人敢用) |
|
||||
| `dom-attr` | `[data-order-no]` 取属性 | 全部 | 关(示例) |
|
||||
| `express` | 文本规则 `\b(?:YT\|SF\|JD\|ZTO\|YTO\|STO\|EMS\|DBL\|32\|77)\d{10,16}\b`(`gi`) | 全部 | 开 |
|
||||
|
||||
> ⚠️ gztbyc WMS 一行里有 4 个长得很像的 `.click-copy-link`:
|
||||
> 发货单号 `JY2026101619599`、运单号 `321408064481776`、波次号 `E2026101600069`、平台交易单号 `6930529169563286869`。
|
||||
> **只有运单号那个的 `title` 含「快递单号」**,所以规则用 `[title*="快递单号"]` 而不是 `.click-copy-link`。
|
||||
- **前缀表就是唯一要维护的地方**:在 `src/lib/rules.js` 的 `EXPRESS_PREFIXES` 里往数组里追加新前缀即可
|
||||
(以前没出现过、又确实出现在单号开头的就加进去)—— 正则会跟着拼出来,**不用改正则本身**:
|
||||
```js
|
||||
const EXPRESS_PREFIXES = [ 'YT', 'SF', 'JD', 'ZTO', 'YTO', 'STO', 'EMS', 'DBL', '32', '77' ];
|
||||
const EXPRESS_PATTERN = '\\b(?:' + EXPRESS_PREFIXES.join('|') + ')\\d{10,16}\\b';
|
||||
```
|
||||
- 前缀后面必须跟 **10~16 位数字**(`\d{10,16}`):所以 `321408064481776`(WMS 运单号,`32` 开头)会被命中,
|
||||
而同一行的波次号 `E2026101600069`、发货单号 `JY2026101619599`、平台交易单号、17 开头的毫秒时间戳都不会;
|
||||
- ⚠️ **数字前缀(`32` / `77`)最容易被内部 ID、订单号一起点亮** —— 发现误标就把那个前缀拿掉,或者给规则加 `exclude`;
|
||||
- 其它匹配方式(CSS 选择器 / 从 `href` 抽编号 / 按 `data-*` 取值)**不再内置示例**,需要时在配置页自己加一条即可,写法见上面的例子;
|
||||
- **升级迁移(config version 1 → 2)**:扩展升级后第一次打开配置页/页面时,会
|
||||
① 把已移除的示例规则(`wms-waybill` / `numeric` / `legacy-postnum` / `dom-attr`)从你的规则里剔掉,
|
||||
② 内置的 `express` 如果还是老正则(说明你没改过它)就换成带新前缀表的正则 ——
|
||||
**你自己加的规则、以及你改过的 `express` 都不动**(见 `upgradeRules()`)。
|
||||
|
||||
## 4. 目标地址模板
|
||||
|
||||
@ -108,15 +166,16 @@ npx --yes http-server extension/test -p 7310 # → http://127.0.0.1:7310/wms
|
||||
```
|
||||
(也可以直接双击打开 `file://`,但要在扩展详情里额外开启「允许访问文件网址」。)
|
||||
|
||||
预期:表格里 **3 个运单号**被标记(青色虚线下划线 + ▶ 角标),其余 9 个蓝色文本不受影响。
|
||||
预期:表格里 **3 个运单号**旁边各多一个「▶ 查看打包视频」按钮(插在运单号和 `+1` 之间),
|
||||
其余 9 个蓝色文本不受影响;页面底部那行 `SF1234567890123` 也会被文本正则命中并插按钮。
|
||||
|
||||
## 7. 行为约定
|
||||
|
||||
- **点击拦截**在捕获阶段完成,`preventDefault + stopImmediatePropagation`,不会触发宿主页的委托逻辑,
|
||||
也不会让外层 `<a>` 跳走。
|
||||
- **修饰键放行**:按住 <kbd>Ctrl</kbd> / <kbd>⌘</kbd> / <kbd>Alt</kbd> / <kbd>Shift</kbd> 点击 = 不拦,
|
||||
交还给页面原本的行为。
|
||||
(gztbyc WMS 上那个运单号 span 原本是「点击复制二维码」,想用原功能就按住 Ctrl 点。)
|
||||
- **默认(button)模式下完全不碰宿主元素**:命中元素的点击、样式、`title` 全部原样,
|
||||
只有我们自己新插的那个按钮会响应点击。
|
||||
- **chip 模式下**点击拦截在捕获阶段完成(`preventDefault + stopImmediatePropagation`),
|
||||
不会触发宿主页的委托逻辑,也不会让外层 `<a>` 跳走;此时可以用修饰键放行 ——
|
||||
按住 <kbd>Ctrl</kbd> / <kbd>⌘</kbd> / <kbd>Alt</kbd> / <kbd>Shift</kbd> 点击就不拦,交还给页面原本的行为。
|
||||
- **SPA 友好**:`MutationObserver`(默认 400ms 防抖)盯着新增节点和文本变化自动补标;
|
||||
自己也写了 DOM 会触发观察器,用 `quietUntil` 时间窗把这类回声挡掉,避免无限重扫。
|
||||
- **完整可撤销**:关掉总开关、改规则、或当前站点不在生效范围时会 `unmark()`——
|
||||
@ -146,6 +205,11 @@ npx --yes http-server extension/test -p 7310 # → http://127.0.0.1:7310/wms
|
||||
- **`tools/make-icons.ps1` 必须保持纯 ASCII**:PowerShell 5.1 在中文机器上把**无 BOM** 的 `.ps1`
|
||||
按 GBK 读,UTF-8 中文变乱码;乱码落进 `("{0}" -f $x)` 这类格式串里会直接报
|
||||
`Input string was not in a correct format` 而中断脚本。
|
||||
- **`acceptTextNode` 的「已处理」判断必须看 `data-pst-code`,不能只看类名**:button 模式不给宿主元素加类名,
|
||||
只看类名会让 text 正则规则把同一个编号再包一遍,插出第二个按钮。
|
||||
- **button 模式要能跨重扫去重**:`applyMarks` 只处理「还没标过」的节点,而 button 模式的宿主元素**永远不带 markClass**,
|
||||
每轮增量重扫都会重新命中它 → 靠 `data-pst-code` 记号 + `existingButton()`(看 `nextElementSibling`)两道保险,
|
||||
实测连续 `applyMarks` 5 次仍然是 3 个按钮。
|
||||
- **命中数不能只看 `applyMarks` 的返回值**:它只处理「还没标过的」节点,滚动/翻页是增量补标,
|
||||
返回值只是本轮新增。所以 `status` 里的清单是**直接数 DOM 上的 `.pst-trace-mark`**(`collectItems`)。
|
||||
- **`chrome.tabs.sendMessage` 要指定 `frameId: 0`**:页面里多个 iframe 都注入过脚本,
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user