packServer/backend/README.md
liufumingren 78cee0fe1a feat(doc): 首页登录分流 + 文档站(简易 CMS / 静态 HTML / sitemap)
- 首页:`/` 未登录原地显示登录页(不再跳 /login),已登录直接进 `/dashboard`;
  看板路由由 `/` 迁到 `/dashboard`,侧边栏「首页」与无权限回跳同步;
  桌面端「工具 → 打开配置页」的 `/?token=` 免登录仍然可用
- 文档站:`/doc/**` 由后端整站生成静态 HTML(顶部分类 tab 全局切换、左侧栏目 → 内容页、
  右侧本页目录);`/sitemap.txt` 新链接追加到末尾,下架 / 删除的会被清理
- 平台管理 · 文档管理(`/admin/doc`):分类 / 栏目 / 内容页(Markdown)简易 CMS,
  内容页有编辑表单与列表,保存后自动重生成目录与静态页面
- 登录页右下角、顶栏(登录后)、看板右上角新增进入文档站的链接
- 部署:nginx 模板为 `/doc`、`/doc/`、`/sitemap.txt` 增加反代(否则会落到 SPA 回退);
  Vite dev server 增加同名代理;`middleware/frontend.js` 排除这些路径
- 登录页插画改为内联 SVG(沿用工作区已有的未提交改动)
- 测试:新增 Markdown 渲染单测;后端 218 个用例通过,前端 typecheck / build 通过

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-07 20:33:46 +08:00

1499 lines
128 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.

# 云仓视频溯源系统(pack-service)
> 中文名(前端页面/邮件里显示的那个)在 **`config.siteName`** 里,默认「云仓视频溯源系统」,可用环境变量 `SITE_NAME` 覆盖 ——
> 要改名只改这一处(邮件用 `app.config.siteName`)。
> `pack-service` 只作为**技术标识**保留:npm 包名、JWT `issuer`、日志目录、`egg-scripts --title`。
基于 **Egg.js 3** 的**纯接口服务**(⚠️ **不再渲染任何页面**:模板引擎已移除,`/` 这一侧由
`app/middleware/frontend.js` 反代给前端 dev server 或托管 `../frontend/dist`),
数据库 **MySQL(Sequelize ORM)**,缓存与登录码用 **Redis**。
> 页面在隔壁 **`../frontend/`**(Vite + Vue3 + TS SPA);两个服务的端口与启动方式见仓库根目录的 `README.md`。
> 业务场景:**设备(扫描枪 / 中控)扫码登录** —— 设备屏幕显示二维码,已登录的手机确认一下;
> 服务端在**确认那一刻**才把设备注册到那个账号名下,并下发**长期 JWT**(默认 1 年,库里存 `jti` 可随时撤销),
> 之后设备调本服务的接口都靠这枚令牌鉴权。**只有这一条身份链路**(没有 sn + secret 那套)。
## 环境要求
- Node.js >= 18(Egg 3 要求 >= 14.20,建议用 18/20 LTS)
- MySQL 5.7+ / 8.x
- Redis 5+
## 目录结构
```
packService/backend
├── app
│ ├── controller # **按「谁在调」分模块**(Egg 支持多级目录 → controller.internal.user)
│ │ ├── home.js # GET /api/info 服务信息(公共)
│ │ ├── health.js # GET /health 健康检查(公共)
│ │ ├── web/ # **用户端(前端 SPA)**:user JWT(typ=user),只能动自己的数据
│ │ │ ├── auth.js # /api/web/auth/{login,register,register/code,forgot,reset}
│ │ │ ├── profile.js # /api/web/me [/password] 我的资料 / 改密码
│ │ │ ├── stats.js # /api/web/stats 首页统计(今日/昨日/近 N 天)
│ │ │ ├── device.js # /api/web/devices* 我的设备(列表/详情/通道/解绑/删除)
│ │ │ ├── record.js # /api/web/records 我的扫码记录(按自己设备过滤)
│ │ │ ├── admin_member.js # /api/web/admin/members[/:id]、/me 平台管理员名单(❗需平台管理员)
│ │ │ ├── admin_subject.js # /api/web/admin/subjects[/:id] 所有主体 + 改授权到期时间
│ │ │ ├── admin_order.js # /api/web/admin/orders[/:orderNo/confirm] 所有订单 + 确认订单
│ │ │ ├── admin_plan.js # /api/web/admin/plans[/:id] 续期套餐(改价 / 改天数 / 上下架)
│ │ │ ├── admin_extension.js # /api/web/admin/extension Chrome 插件集中配置(❗需平台管理员)
│ │ │ ├── admin_doc.js # /api/web/admin/doc/* 文档站 CMS(分类 / 栏目 / 内容页,❗需平台管理员)
│ │ │ ├── doc.js # GET /doc/**、/sitemap.txt 文档站(公开,直接回生成好的静态 HTML)
│ │ │ ├── extension.js # /api/web/extension/config 插件读取的配置(公开只读,无令牌)
│ │ │ └── test.js # /api/web/test/{device-login,scan} 前端测试页的模拟接口(仅非生产环境注册)
│ │ ├── internal/ # 运维/内部(❗需内部令牌,挂在 middleware.internalAuth() 后面)
│ │ │ ├── user.js # /api/users* 用户 CRUD(含缓存)
│ │ │ ├── wechat.js # /api/internal/wechat-bindings* 网关绑定排查 / 强制解绑
│ │ │ ├── config.js # /api/configs* 系统配置读写
│ │ │ └── device.js # /api/scanners*、/api/scanner/{bind,unbind} 设备列表/详情/解绑/删除
│ │ ├── auth/ # 公开的登录接口(发码 / 查码,无需令牌)
│ │ │ └── wechat.js # /api/wechat/{status,qrcode.svg} 设备扫码登录的码
│ │ ├── client/ # 小程序 / Win 客户端 / SPA(user JWT,typ=user)
│ │ │ └── wechat.js # /api/wechat/confirm
│ │ └── device/ # 设备(长期 JWT,typ=scanner)
│ │ ├── auth.js # /api/device/login 扫码登录+注册(登录即注册,下发长期 JWT)
│ │ ├── self.js # /api/scanner/{me,heartbeat} 自检 / 保活
│ │ └── scan.js # /api/scan/* 中控上报通道 / 扫码记录(去重)
│ ├── middleware
│ │ ├── api_auth.js # **用户端接口鉴权(只认 header 令牌,不看 cookie/session)**
│ │ ├── internal_auth.js # **运维/内部接口鉴权**(X-Internal-Token 或白名单账号的 user JWT)
│ │ ├── platform_admin.js # **平台管理员校验**(admin_members 启用 / INTERNAL_ADMIN_IDS;给 /api/web/admin/*)
│ │ ├── scanner_auth.js # 扫描器 JWT 鉴权(Authorization: Bearer <token>)
│ │ ├── frontend.js # **前端入口**:dev 反代前端 dev server / 生产托管 frontend/dist(SPA 回退)
│ │ └── error_handler.js # 异常统一成 JSON(4xx 原消息 / 5xx 只回「服务器内部错误」)
│ ├── model
│ │ ├── user.js # users
│ │ ├── admin_member.js # admin_members(平台管理员)
│ │ ├── sys_config.js # sys_config
│ │ ├── scanner.js # scanners
│ │ ├── scan_channel.js # scan_channels
│ │ ├── scan_record.js # scan_records(去重)
│ │ ├── doc_category.js # doc_categories(文档分类 = 顶部 tab)
│ │ ├── doc_section.js # doc_sections(分类下的一级栏目)
│ │ └── doc_article.js # doc_articles(内容页,Markdown 原文)
│ ├── service
│ │ ├── auth.js # 登录校验(bcrypt 密码比对)+ 自助注册
│ │ ├── admin_member.js # 平台管理员:名单维护 + isAdmin(admin_members / INTERNAL_ADMIN_IDS)
│ │ ├── mail.js # 发邮件(邮箱验证码 / 重置密码链接;开发模式只写日志)
│ │ ├── verify_code.js # 邮箱验证码:生成/发送/校验/消费(Redis 存储 + 重发节流)
│ │ ├── wechat_login.js # 设备扫码登录:二维码本地生成 / 串码状态机 / 长轮询
│ │ ├── password_reset.js # 找回密码:重置令牌生成/校验/消费(Redis 存摘要 + 旧链接失效 + 重发节流)
│ │ ├── cache.js # Redis 封装(JSON 序列化 / 过期 / cache-aside / 降级)
│ │ ├── config.js # 配置读写(带 Redis 缓存)
│ │ ├── jwt.js # 令牌签发 / 校验(HS256 + typ + jti,见下文)
│ │ ├── scanner.js # 设备记录:扫码登录即注册 + 绑定/解绑/心跳(只认长期 JWT)
│ │ ├── scan.js # 中控通道上报 / 扫码入库去重 / 扫码查询
│ │ ├── health.js # MySQL / Redis 连通性探测
│ │ ├── user.js # 用户数据访问(app.model.User)
│ │ ├── wx_gateway.js # 微信登录网关:临时码 / 验签 / 会话长轮询 / 绑定关系
│ │ ├── doc.js # 文档站 CMS:分类 / 栏目 / 内容页的增删改查(写完自动重生成)
│ │ └── doc_site.js # 文档站生成:把库里的内容渲染成 /doc/** 静态 HTML + /sitemap.txt
│ ├── lib
│ │ └── markdown.js # 极简 Markdown → HTML(先转义再拼标签,附文章内目录)
│ └── router.js
├── config
│ ├── config.default.js # 统一配置(连接 / 端口 / 安全 / 前端入口 / 内部鉴权)
│ ├── config.local.js # 本机密码等(已 gitignore,仅 env=local 加载)
│ ├── config.unittest.js # 单测用的固定内部令牌
│ ├── plugin.js # 只开 sequelize / redis
│ └── plugin.unittest.js # 单测环境关闭 DB 相关插件
├── scripts
│ ├── db-config.js # 脚本共用的连接信息解析
│ ├── db-deploy.js # **部署/升级一次执行**:建库 + 基线表 + 全部未执行迁移(npm run db:deploy [--check])
│ ├── init-db.js # 执行单个 SQL 文件(npm run db:init [file]),给历史补丁用
│ ├── backfill-snapshot.js # 一次性回填:老扫码记录补工作台快照
│ ├── dedupe-scan-records.js # 一次性去重:24 小时内同一运单只留一条
│ └── set-password.js # 创建用户/重置密码(npm run user:pass -- 账号 密码)
├── database
│ ├── config.cjs # sequelize-cli 配置(与运行时同一份连接信息)
│ └── migrations/ # Sequelize 迁移(按文件名顺序,SequelizeMeta 记账,只跑没跑过的)
├── sql
│ ├── schema.sql # 基线表(幂等,db:deploy 第 1 步执行)
│ └── migrations/ # 历史一次性 SQL 补丁(仅老库需要,保留不删)
├── test
│ ├── utils/fake-redis.js # 单测用的内存版 Redis
│ └── utils/internal.js # 内部接口鉴权 header(X-Internal-Token)
└── package.json
```
## 快速开始
```bash
# 1. 安装依赖
npm install
# 2. 填写本机连接信息:编辑 config/config.local.js(该文件已被 .gitignore 忽略)
# - mysql.client.password = MySQL(127.0.0.1:3307,账号 packservice) 的密码
# - redis.client.password / db = Redis 的密码(无密码写 null)与库序号(本机用 1)
# 也可以改用环境变量 MYSQL_PASSWORD / REDIS_PASSWORD / REDIS_DB
# 3. 建表 / 升级(**部署时只需这一条**:建库(有权限时) + 基线表 + 所有未执行的迁移,可反复执行)
npm run db:deploy
# npm run db:deploy -- --check # 只检查还剩哪些迁移没执行(CI / 上线前确认,不改库)
# 老版本的库照常补跑遗留 SQL 补丁(这些脚本都保留在 sql/migrations,新库不需要):
# npm run db:init sql/migrations/20261016_rebuild_users.sql # users 表结构重建
# 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:7300)
# 登录页:http://127.0.0.1:7300/login(用上面的账号登录)
npm run dev
# 想临时换端口:egg-bin dev --port 7400,或 $env:PORT=7400; npm run dev(默认端口在 config/config.default.js)
# 生产模式
npm start # egg-scripts 后台启动
npm stop
```
验证:
```bash
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:7300`(dev 环境自动把页面请求反代给前端);也可以直接开前端 7301(Vite 把 `/api` 反代到 7300)。
## 部署 / 升级(库结构)
**一次执行**,幂等,可反复跑:
```bash
cd backend
npm install
npm run db:deploy # ① 建库(有权限时) ② 基线表 sql/schema.sql ③ 全部未执行的 database/migrations
npm run db:deploy -- --check # 只检查(列出未执行的迁移;有 pending 时退出码 1),适合上线前/CI 卡一道
```
### 生产库迁移(本地执行,目标 = 生产库)
生产 MySQL 账号是 `packservice@localhost`,只能从服务器本机登录,所以脚本会先建 **SSH 隧道**再跑同一套迁移:
```bash
npm run db:check:prod # 只检查生产库还有哪些迁移没执行(不改库)
npm run db:deploy:prod # 基线表 + 全部未执行迁移(幂等,可反复跑)
```
- 连接信息来自本机 `config/env.prod.sh`(`MYSQL_*`),SSH 信息来自 `config/deploy.config.local.cjs`;
- 隧道:`127.0.0.1:<随机端口> → <服务器>:127.0.0.1:3306`,执行完自动关闭;
- 显式设置的 `MYSQL_*` 环境变量优先于 `config.local.js`(不会被本机开发库密码覆盖)。
规则(**所有迁移脚本都保留在仓库里,不删不改**):
| 位置 | 作用 | 什么时候跑 |
|---|---|---|
| `sql/schema.sql` | 基线 6 张表(`CREATE TABLE IF NOT EXISTS`,幂等) | 每次 `db:deploy` 第 2 步自动跑 |
| `database/migrations/*.js` | 全部结构变更 / 数据回填(`SequelizeMeta` 记账) | 每次 `db:deploy` 第 3 步自动跑,**只跑没跑过的** |
| `sql/migrations/*.sql` | 历史一次性补丁(重建 users、加列、删旧 devices 表) | **仅老库升级时手动补跑**,新库已包含最终结构,重复执行会 `Duplicate column` |
| `scripts/backfill-snapshot.js`、`scripts/dedupe-scan-records.js` | 一次性数据修复(需带参数,可 `--dry-run`) | 按需手动,不是部署必跑 |
执行顺序固定为「基线表 → 迁移(按文件名升序)」,所以新库和老库走同一条命令,结果一致;
连接信息与运行时同源(环境变量 > `config/config.prod.js`(`EGG_SERVER_ENV=prod`)> `config/config.local.js` > 默认值)。
> 生产库如果由 DBA 预建、且应用账号没有建库权限,`db:deploy` 会打印一行「跳过建库」后继续,不影响后续迁移。
## 发布到服务器(npm run deploy)
参考 `D:\wms` 的双实例蓝绿发布:`v1` / `v2` 两个目录轮流发布,新实例健康检查(`/health`)通过后才切 Nginx upstream,再停旧实例;失败会回滚 `current.md` 并保留旧实例继续服务。
### 一次性准备
1. 本机:Node 18+、git、tar(Win10/11 自带 bsdtar)、OpenSSH Client(`ssh` / `scp`)。
2. 填写发布配置 `config/deploy.config.local.cjs`(该文件已被 `.gitignore` 忽略;若缺失可从模板复制):
```powershell
cd backend
# 已存在则直接编辑;缺失时:
Copy-Item config/deploy.config.example.cjs config/deploy.config.local.cjs
```
3. 服务器目录结构(首次发布时脚本会自动建 `v1` / `v2` / `.deploy` / `shared-config`):
```
/www/wwwroot/packService/
├── current.md # 内容只能是 v1 或 v2
├── nginx-upstream.conf # 只有一行:proxy_pass http://127.0.0.1:7301;(API 端口)
├── front.conf # nginx 前端静态 + /api、/health 反代 + /download 静态(自动维护)
├── frontend/ # 前端构建产物(nginx 直接托管)
├── frontend.prev/ # 上一版前端(回退用)
├── download/ # 安装包分发(nginx 直接托管)
│ ├── version.json # 桌面端版本信息(不缓存,客户端写死这个地址)
│ ├── desktop/ # 桌面端 MSI + EXE(长缓存)
│ └── android_client/ # Android APK + version.json
├── shared-config/ # 服务端私有配置(不随发布包走)
│ └── env.prod.sh # 启动前 source 的环境变量
├── v1/ v2/ # 两个后端发布目录
└── .deploy/ # incoming / backups / state
```
站点 vhost 里只需要 include 一次前端/反代配置:
```nginx
server {
server_name pack.example.com;
# 前端静态 + /api、/health 反代 + /download 静态,全部由 front.conf 维护
include /www/wwwroot/packService/front.conf;
}
```
> `front.conf` 由 `npm run deploy` 自动生成;`nginx-upstream.conf` 里的端口在发布健康检查通过后切换。
> 首次发布前先创建 `current.md`(内容 `v1` 或 `v2`);发布总是部署到**另一个**目录。
> 生产站点强制 HTTPS:vhost 里对 `$scheme != https` 直接 `return 301 https://$host$request_uri`,
> 且 `front.conf` 的每个带 `add_header` 的 location 都会重复声明 `Strict-Transport-Security`
> (nginx 的 `add_header` 一旦在 location 内出现,就不再继承 server 级配置)。
4. **服务端私有配置放在 `shared-config/`,不要改版本目录里的 `config.default.js`**
(后者是仓库代码,每次发布都会被覆盖)。`shared-config/env.prod.sh` 会在启动前被 `source`,
每次发布也会把 `shared-config/config.prod.js`、`config.local.js`(若存在)复制进目标版本目录。
```bash
# /www/wwwroot/packService/shared-config/env.prod.sh(chmod 600)
export JWT_SECRET='由 openssl rand -hex 32 生成的随机串'
export MYSQL_HOST='127.0.0.1'
export MYSQL_PORT='3306'
export MYSQL_PASSWORD='...'
export REDIS_HOST='127.0.0.1'
export REDIS_PASSWORD='...'
```
本项目已经准备好两份生产 env:
| 文件 | 用途 | 是否提交 |
|---|---|---|
| `backend/config/env.prod.sh` | 后端运行时变量(`JWT_SECRET`、`MYSQL_*`、`REDIS_*`、`SITE_URL`) | **否**(gitignore,本机权威副本,发布前自动上传到 `shared-config/`) |
| `frontend/.env.production` | 前端构建变量(`VITE_*`,不含密钥) | 是 |
> 改后端 env 后执行 `npm run deploy` 会自动上传并生效;改前端 env 后同样重新发布即可(`deploy` 会重新构建前端)。
> 生产环境 `config.default.js` 会强制要求 `JWT_SECRET` 环境变量,缺少会启动失败(健康检查不通过,自动保留旧实例)。
5. 可选:安装提交前检查钩子(禁止提交私有配置 / 运行期产物 / 版本记录):
```bash
npm run setup:hooks
```
### 常用命令
| 命令 | 说明 |
|---|---|
| `npm run deploy:precheck` | 检查本地工具、SSH、远端目录 / Node / Nginx / 当前实例健康状态 |
| `npm run deploy` | 构建前端 → 打包 → 上传 → 解压安装 → 启动新实例 → 健康检查 → 切 Nginx → 停旧实例 |
| `npm run deploy:verify` | 查看当前版本 / 备份并冒烟探测 `/`、`/health`、`/download/version.json` |
| `npm run deploy:version` | 查看远端活跃版本与最近一次发布记录(`--history=20` 看历史) |
| `npm run deploy:smoke` | 只做冒烟探测 |
| `npm run deploy:inspect` | 只看 `.deploy` 状态与备份清单 |
| `npm run rollback` | 蓝绿回退到上一个版本目录(不重新解压,秒级切换) |
| `npm run rollback -- --backup=backup-<时间戳>.tar.gz` | 用指定备份包恢复当前活跃目录 |
| `npm run deploy:cleanup-backups -- backup-xxx.tar.gz` | 删除指定备份包 |
发布说明:
> ⚠️ `npm run deploy` **只发后端 + 前端 + nginx**:桌面端安装包(`npm run desktop:publish`)和
> Chrome 插件(`npm run extension:publish`)是**两条独立命令**,不会跟着 deploy 走(Edge 扩展已上架商店,
> 这条 `.crx` + `updates.xml` 链路现在只给内网/离线分发用)。
> 三者的远端目录互不重叠(`/download/desktop/`、`/download/extension/`),可以各自单独发布。
- 前端构建产物单独上传到 `deployRoot/frontend`,由 **nginx 直接托管**(SPA 回退到 `index.html`);上一版保留在 `frontend.prev`,`npm run rollback` 会连前端一起切回。
nginx 前端/反代配置由发布脚本写入 `deployRoot/front.conf`;Egg 只提供 `/api`、`/health`(`FRONTEND_ENABLE=false`)。
`buildFrontend: false` 时跳过前端构建与发布(适合前端完全独立部署)。
- 生产发布**不含「测试页」**:前端 `TestView` 只在 dev 构建里注册路由与菜单(生产包不会产出该 chunk),
后端 `/api/web/test/*` 只在 `env != prod` 时注册,生产请求直接 404。
- 发布包只包含 git 跟踪的源码;版本目录里的 `config/config.prod.js`、`config/config.local.js`、`app/public/download`、`app/public/version` 在清理前暂存、解压后放回,随后再用 `shared-config/` 里的同名配置覆盖,保证所有版本配置一致。
- 启动前会 `source shared-config/env.prod.sh`(`JWT_SECRET`、`MYSQL_*`、`REDIS_*` 等);**不要编辑版本目录里的 `config.default.js`**,它属于仓库代码,会被每次发布覆盖。
- 每次发布会在 `.deploy/backups/` 留一份旧代码备份(默认保留最近 5 个;`node_modules` / `logs` / `run` / `temp`、安装包目录和服务端私有配置不进备份,它们本身会被保留)。
- 需要发布时顺带升级库结构,把 `config/deploy.config.local.cjs` 里的 `remoteDbDeploy` 改成 `true`(远端会先 source `shared-config/env.prod.sh`,再以 `EGG_SERVER_ENV=prod` 执行 `npm run db:deploy`;连接信息来自 `MYSQL_*` 环境变量或 `config.prod.js`)。
### 桌面端正式包(单独发布,不动后端)
改桌面端时只需要发安装包,**不用重新发布后端**:
```bash
cd backend
npm run desktop:build # 只构建(dry-run),产物在 desktop/installer/out
npm run desktop:publish # 构建 + 上传 + 刷新 nginx
npm run desktop:publish -- --version=1.0.90 --notes="修复 xxx"
npm run desktop:publish -- --skip-nginx
npm run desktop:publish -- --target=Msi # 只出 MSI(不发 EXE)
```
- `--target=Both|Msi|Exe` 直接透传给 `desktop/installer/build.ps1 -Target`;
⚠️ 客户端版本 `≤ 1.0.151` 有个 bug:优先下载 EXE,却拿 version.json 里的 `md5`(**MSI 的**)去校验,
必然报「安装包 MD5 不一致」。**给这些客户端发的第一个修复版必须只出 MSI**
(`--target=Msi`,此时 version.json 里没有 `downloadUrlExe`,老客户端会回落到 MSI + `md5`,能正常升级),
等它们升上来之后再恢复 `Both`。
- 版本默认取本地已有最高版本 + 1(补丁号),也可用 `--version=` 指定;
- 构建复用 `desktop/installer/build.ps1 -Environment Production`;
- 上传到 `deployRoot/download/desktop/`(MSI + EXE),`version.json` 传到 `deployRoot/download/`
(路径不能改:老客户端写死 `/download/version.json`;先传安装包,再原子替换 `version.json`);
- nginx 的 `/download/` 静态托管该目录:`version.json` 不缓存,安装包长缓存;
- `desktop/installer/package.config.json` 的 Production `serverBaseUrl` 必须是 `https://`,安装包内嵌的接口 / 下载地址会跟着变;
- **浏览器插件一起打进包**:`extension/` 发布到 `<安装目录>\extension`(开发者模式加载用);
正式分发:Edge 走加载项商店、Chrome 走开发者模式,客户端**不再写企业策略**(见下节);
- 不会重启 Egg、不会重新发布后端、不会跑数据库迁移;
### Chrome 插件正式包(.crx + updates.xml)
```bash
cd backend
npm run extension:bundle # 只压缩源码 → extension/dist(esbuild,体积约 1/3)
npm run extension:build # 压缩 + 打包(dry-run),产物在 extension/out
npm run extension:publish # 压缩 + 打包 + 上传 + 刷新 nginx
npm run extension:zip # 压缩 + 出商店上传包(extension/out/*.zip)
npm run extension:publish -- --version=1.2.0 --skip-nginx
```
- **打进去的是 `extension/dist`(压缩产物)**,不是源码:`build-extension.cjs` 用 esbuild 逐文件 minify
(不合并文件,`importScripts('lib/rules.js')` 与各处路径原样有效);桌面端 `build.ps1` 在
`dotnet publish` 前也会自动跑一遍,csproj 打的同样是 `dist`;
- 只做 minify、不做混淆:MV3 的 CSP 禁止 `eval`/`new Function`,Chrome/Edge 商店也要求代码可读;
- 用本机 Chrome/Edge 的 `--pack-extension` 打包(找不到浏览器时用 `--browser=<路径>` 指定);
- 产物:`YuncangTraceExtension-<version>.crx`、`updates.xml`、`extension-id.txt`;
- 上传到 `deployRoot/download/extension/`;nginx 对 **`updates.xml` 关缓存**(浏览器靠它自动升级),
`.crx` 文件名带版本号、走长缓存;
- 扩展 ID 由 `extension/keys/key.pem` 决定(首次运行自动生成,**必须备份**,换了 ID 就变);
- ⚠️ 客户端**已不再**用企业策略装自建 CRX:Edge 扩展上架商店后该功能已下线,桌面端没有
「一键写策略」的入口。这条 `updates.xml` + `.crx` 链路保留给**内网/离线分发**;
- 正式分发:Edge 用桌面端「工具 → 安装浏览器插件(Edge 应用商店)」点「获取」;
Chrome 用「工具 → 复制插件路径(Chrome / 开发者模式)」到 `chrome://extensions` 加载已解压的扩展程序;
- 前置:.NET 8 SDK、WiX 5.0.2(`dotnet tool install --global wix --version 5.0.2`)、Inno Setup 6(`winget install --id JRSoftware.InnoSetup`,出 EXE 用)、`desktop/native/ffmpeg/ffmpeg.exe`。
下载地址:`<desktopBaseUrl>/download/desktop/YuncangTraceSetup-<版本>.exe`(新客户端优先)
`<desktopBaseUrl>/download/desktop/YuncangTraceSetup-<版本>.msi`(老客户端只认这个)
更新信息:`<desktopBaseUrl>/download/version.json`
### Android 设备端正式包(单独发布,不动后端)
```bash
cd backend
npm run android:build # 只构建(dry-run),产物在 backend/android_client/out
npm run android:publish # 构建 + 上传 + 刷新 nginx
npm run android:publish -- --version=1.0.2 --notes="扫码上报更稳"
npm run android:publish -- --skip-nginx
```
- 构建复用 `backend/android_client/build.ps1 -Environment Production`(配置在 `backend/android_client/package.config.json`,和桌面端同一套路);
- 版本默认取已有 APK / version.json 的最高版本 +1 补丁号;`versionCode` 由 `x.y.z` 换算(`major*10000+minor*100+patch`);
- 上传到 `deployRoot/download/android_client/`:APK + `version.json`(nginx 对 `version.json` 单独关缓存);
- 签名读 `AndroidStation/keystore.properties` + `keystore/*.jks`(**不入库**,发布机必须自行备份);
- 前置:JDK 17(`JAVA_HOME`,或自动找 `%LOCALAPPDATA%\Programs\EclipseAdoptium\jdk-*` / Android Studio 的 `jbr`)、
Android SDK(`AndroidStation/local.properties` 的 `sdk.dir` 或 `ANDROID_HOME`)。
下载地址:`<androidBaseUrl>/download/android_client/YuncangScan-<版本>.apk`
更新信息:`<androidBaseUrl>/download/android_client/version.json`
### 前端顶栏的下载入口(2026-10-29)
网页端**所有页面**的右上角都有两个下载按钮(`frontend/src/components/AppLayout.vue`,**与权限无关**,登录后就能看到):
- 「桌面端 vX.Y.Z」→ `version.json` 里的 `downloadUrlExe`(EXE)/ `downloadUrl`(MSI,老客户端)
- 「Android 扫码台 vX.Y.Z」→ `version.json` 里的 `downloadUrl`(APK)
版本信息由 `frontend/src/api/download.ts` 直接 `fetch` 两个 `version.json`(**注意:这两个路径返回的是
`version.json` 原文,不是 `{ ok, data }` 包装**,所以没走 `api/client`);还没发布过安装包时按钮置灰、点击提示,
不会跳到 404。nginx 里这两个路径是精确 `location` 反代到 Egg 的,安装包目录才是静态托管。
## 单元测试
```bash
npm test # 无需本机启动 MySQL / Redis
npm run cov
```
### 本地端口
- 后端默认监听 **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 上不依赖外部服务。
## 环境变量
不配置时使用默认值(`127.0.0.1:3307` / 账号 `packservice` / 库名 `packservice`,密码为空需在 `config/config.local.js` 填)。
| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `MYSQL_HOST` | `127.0.0.1` | MySQL 地址 |
| `MYSQL_PORT` | `3307` | MySQL 端口 |
| `MYSQL_USER` | `packservice` | 用户名(**大小写敏感**) |
| `MYSQL_PASSWORD` | 空 | 密码,本地放 `config/config.local.js` |
| `MYSQL_DATABASE` | `packservice` | 库名 |
| `MYSQL_POOL_SIZE` | `10` | Sequelize 连接池上限(`pool.max`) |
| `REDIS_HOST` | `127.0.0.1` | Redis 地址 |
| `REDIS_PORT` | `6379` | Redis 端口 |
| `REDIS_PASSWORD` | 空(`null`) | 密码,无密码时必须为空 |
| `REDIS_DB` | `0` | 库序号 |
| `CACHE_PREFIX` | `packs:` | 业务缓存 key 前缀 |
| `CACHE_TTL` | `300` | 默认缓存过期(秒) |
| `JWT_SECRET` | 开发默认值 | 扫描器 JWT 签名密钥,**生产未设置会启动失败** |
| `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 端口 |
| `SMTP_SECURE` | `true` | 是否用 TLS(465 用 true,587 用 false) |
| `SMTP_USER` / `SMTP_PASSWORD` | 空 | SMTP 账号 / 密码(QQ 邮箱填「授权码」,不是登录密码;放 `shared-config/env.prod.sh` 或环境变量) |
| `SMTP_FROM` | `云仓视频溯源系统 <no-reply@...>` | 发件人(默认取 `SITE_NAME` 作显示名) |
| `EMAIL_CODE_TTL` | `600` | 邮箱验证码有效期(秒) |
| `EMAIL_CODE_RESEND` | `60` | 同一邮箱重发验证码的间隔(秒) |
| `EMAIL_CODE_ATTEMPTS` | `5` | 同一个验证码最多校验几次(超过则作废) |
| `EMAIL_DAILY_LIMIT` | `10` | **每个邮箱每天最多发几封邮件**(注册验证码 + 找回密码共用,超出提示「明天再试」) |
| `EMAIL_RESET_TTL` | `1800` | 重置密码链接有效期(秒,默认 30 分钟) |
| `SITE_URL` | 空 | 邮件里重置链接的站点地址(如 `https://packs.example.com`);不配则用当前请求的 host |
| `WX_GATEWAY_BASE` | `https://gateway.gztbyc.com` | **微信登录网关**地址(登录页扫码 / 绑定微信 / 工作台扫码登入) |
| `WX_GATEWAY_APP_KEY` | 空 | 网关应用的 appKey(`gwk_…`);**不配 = 未开通**,扫码接口 503 |
| `WX_GATEWAY_APP_SECRET` | 空 | 网关应用的 appSecret(`gws_…`),**只放服务端**(验证回调签名) |
| `WX_GATEWAY_POLL_WAIT` / `WX_GATEWAY_SCENE_TTL` / `WX_GATEWAY_NOTIFY_SKEW` | `55` / `660` / `300` | 网关扫码的长轮询上限(秒)/ 本地会话有效期(秒)/ 通知时间戳容差(秒) |
| `WECHAT_QR_CELL` / `WECHAT_QR_MARGIN` | `6` / `4` | 二维码 SVG 的单元格像素 / 静默区格数(⚠️ 库的 margin 参数单位是像素,代码里已按格×单元格换算;<4 格会影响扫码) |
| `PAY_MOCK` / `PAY_CALLBACK_SECRET` | 开发默认开 / 空 | 模拟支付回调(免签名)/ 回调签名密钥(`X-Pay-Sign`) |
| `PAY_AMOUNT_PER_DAY` | `0` | 每天默认价格(0 = 不校验金额,内部测试用) |
| `PAY_ORDER_TTL` | `7200` | **待支付订单有效期(秒)**:超时自动关闭,之后的回调/手工确认一律 409(与微信扫码支付二维码 2 小时有效期对齐) |
| `WXPAY_APP_ID` / `WXPAY_MCH_ID` / `WXPAY_API_KEY` | 空 | **微信 Native 扫码支付**凭证(appid / 商户号 / APIv2 密钥);缺任意一项 = 未开通,下单只建单不出二维码 |
| `WXPAY_NOTIFY_URL` | 空 | 支付回调地址(公网 https,不带参数);不配则用 `SITE_URL` + `/api/pay/wechat/notify` |
| `WXPAY_ENABLED` / `WXPAY_SIGN_TYPE` / `WXPAY_API_BASE` / `WXPAY_TIMEOUT` | `true` / `MD5` / `https://api.mch.weixin.qq.com` / `8000` | 临时停用 / 签名类型(`MD5` 或 `HMAC-SHA256`)/ 接口地址(切沙箱)/ 超时(毫秒) |
| `WXPAY_BODY` / `WXPAY_QR_CELL` / `WXPAY_QR_MARGIN` | 空 / `6` / `4` | 商品描述前缀(默认站点名)/ 二维码单元格像素 / 静默区格数 |
| `WECHAT_STATE_TTL` | `600` | 扫码串码(二维码)有效期(秒)——设备扫码登录用 |
| `WECHAT_CODE_LENGTH` | `6` | 扫码串码长度(数字 + 大写字母,去掉了 0/O/1/I 等易混字符) |
| `WECHAT_SPM_PATTERN` | `1.0.{code}.1` | 二维码地址里的 spm 格式(`{code}` 会被替换成串码) |
| `USER_JWT_EXPIRES` | `7d` | 扫码登录接口下发的**用户 JWT** 有效期 |
| `WECHAT_POLL_WAIT` | `60` | 设备扫码登录的长轮询最多挂起多少秒(前端自己的超时建议再 +10s;反代注意 `proxy_read_timeout` 要大于它) |
Windows PowerShell 示例:
```powershell
$env:MYSQL_PASSWORD = 'your-pass'; $env:REDIS_PASSWORD = 'your-pass'; npm run dev
```
## 数据表
六张表统一约定:`BIGINT UNSIGNED` 自增主键、`created_at` / `updated_at`、`deleted_at`(软删除,Sequelize `paranoid: true`)、`status` 状态位。
### users 用户表
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint unsigned | 主键 |
| username | varchar(64) | 登录名,唯一,可空(纯微信登录可不设) |
| nickname | varchar(64) | 昵称 |
| email | varchar(128) | 邮箱,**唯一、可空**;注册可选填,**可当登录账号**(入库统一转小写) |
| avatar | varchar(255) | 头像 |
| phone | varchar(20) | 手机号,唯一 |
| gender | tinyint unsigned | 0 未知 / 1 男 / 2 女 |
| 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 | 时间戳与软删除 |
### sys_config 系统配置表
`group_name` + `config_key` 唯一定位一条配置,`value_type` 决定 `config_value` 的解析方式(`string` / `number` / `boolean` / `json`)。
> 注意:本表用软删除,若建唯一索引会被已删除的记录占用,导致同 key 无法重建,因此**唯一性由 service 层保证**(先查后写),表上只建普通索引。
### scanners 设备表
设备(条码/二维码扫描枪、中控)**扫码登录时自动注册**,`user_id` 为空表示尚未绑定账号
(设备归哪个账号由「扫码确认」的人决定,也可由管理员解绑)。
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint unsigned | 主键 |
| user_id | bigint unsigned | 绑定的用户 id,未绑定为 NULL |
| sn | varchar(64) | 设备 SN,唯一(设备唯一标识;设备不传时由服务端生成 `DEV-…`) |
| name / model / vendor / firmware | varchar | 名称、型号、厂商、固件/客户端版本 |
| 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 | 最近注册、最近登录、最近心跳时间 |
| created_at / updated_at / deleted_at | datetime | 时间戳与软删除 |
设备接入流程(**只有一条链路**):
1. **拿令牌(也就是注册)**:`GET /api/device/login`(公开,无需任何凭据):
- ① 不带参数 → 返回登录码 + 二维码地址(`qrContent` / `qrImageUrl`),**此时库里还没有任何记录**;
- ② 手机用 `POST /api/wechat/confirm` 确认(已登录用户);
- ③ 设备带 `?code=&wait=60` 长轮询 → **这一边才注册**:按 SN 建/取记录、绑定到确认登录的账号,并拿到长期 JWT;
2. **用令牌**:之后所有请求带 `Authorization: Bearer <JWT>`;`GET /api/scanner/me` 自检、`POST /api/scanner/heartbeat` 保活(刷新 `last_seen_at`)、`/api/scan/*` 上报;
3. **令牌到期 / 设备重装**:再扫一次码即可(不需要密钥:设备屏幕出码、人确认一下)—— 记录已存在时不重复建,只换发新令牌;
4. **换人使用(设备转让)**:先由原账号在 `/scanners` 解绑(或管理侧 `POST /api/scanner/unbind`),新使用人再扫码登录即可认领;
5. SN 曾经被**删除**过也能继续用同一个 SN:扫码登录会把那条**软删除**的记录**复活**(id 不变、`deleted_at` 清空)—— 软删行仍占着 `sn` 唯一键,不复活就会撞键。
> 历史变更:早期的 `POST /api/scanner/register`(自己注册拿 sn+secret)与 `POST /api/scanner/login`(sn+secret 换令牌)
> **已下线**(跟扫码登录重复,而且会先建出一条 `user_id = NULL` 的无主记录);设备身份现在**只有长期 JWT 一种**。
#### 设备通讯用的长期 JWT
- 算法 HS256,`issuer = pack-service`、`audience = scanner`,payload 含 `sub`(设备 id)/ `sn` / `typ: 'scanner'` / `jti`;
- 有效期:默认 **365 天**(`config.jwt.deviceExpiresIn`,env `DEVICE_JWT_EXPIRES`,不配就跟 `SCANNER_JWT_EXPIRES` 走);设备可用 `?expiresIn=30d`(或秒数)申请**更短**的,超上限 422;
- **可撤销**:每次扫码登录都会生成新的 `jti` 写库(`scanners.token_jti`),旧令牌因 `jti` 不匹配立即 401;把 `status` 置 0 也可让令牌失效(403);
- 令牌本体不落库(只存 `jti`);列表/详情/`me` 等响应都不返回 `token_jti`(`app/service/scanner.js` 的 `sanitize()` 兜底清洗);
- 签名密钥取 `config.jwt.secret`(来自 `JWT_SECRET`),生产环境未设置会直接启动失败。
令牌取用顺序:`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 上报):一台中控可接多个扫码设备,
每个扫码设备对应一个通道,中控把 **通道 id + 通道名** 上报上来,**一个通道一行**。
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint unsigned | 主键 |
| scanner_id | bigint unsigned | 上报的中控(= `scanners.id`) |
| channel_id | varchar(64) | 通道 id(中控上报,**同一中控内唯一**) |
| channel_name | varchar(128) | 通道名(中控上报) |
| last_report_at | datetime | 最近一次上报时间 |
| status | tinyint unsigned | 1 正常 / 0 停用 |
| created_at / updated_at / deleted_at | datetime | 时间戳与软删除 |
- 唯一键 `(scanner_id, channel_id)`:同一中控重复上报同一个通道 = 更新通道名与 `last_report_at`,不会重复建行;
- 因为 `channel_id` 只在同一中控内唯一,所以关联/去重都必须带上 `scanner_id`;
- 用软删除:曾被停用(`deleted_at` 非空)的通道再次上报时会自动「复活」;
- **全量对账(`replace: true`)**:桌面端的通道列表存在本地(`channels.json`),与本机设备是否在线无关 →
`replace: true` 时该中控下**不在列表里**的通道会被软删,`workstation_scan_channels` 里对应绑定物理删除,
返回 `{ removed, unbound }`;`channels: []` + `replace: true` 表示"通道已全部删除"。不带 `replace` 的老客户端行为不变;
- **忽略 `channel_id = 'DESKTOP'`**:旧版桌面端会多报一个「本机中控」占位通道(从未有真实数据),
迁移 `20261019230000-remove-legacy-desktop-channel` 已清掉历史行,`reportChannels()` 也会直接跳过,避免老客户端重新写回。
### scan_records 扫码记录表
中控上报的扫码流水:**条码 + 扫描时间 + 通道 id**,需要**去重存储**。
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint unsigned | 主键 |
| scanner_id | bigint unsigned | 上报的中控(= `scanners.id`) |
| channel_id | varchar(64) | 通道 id |
| 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 关闭):软删除会让记录占用唯一键,导致同一条扫码数据再也无法入库;
> 需要清理请按时间物理删除:`DELETE FROM scan_records WHERE scan_time < ?`。
## 页面(在前端项目里)
⚠️ **后端不再渲染页面**:`app/view/`、nunjucks、session、CSRF 都已移除,`app/controller/page/` 也删掉了。
登录 / 注册 / 找回密码 / 扫码确认 / 首页 / 设备管理 / 扫码记录 / 个人中心 / 测试页
全都在 **`../frontend/`**(Vite + Vue3 + TS 的 SPA)里,通过下面的 JSON 接口通讯:
| 页面 | 前端路由 | 用到的接口 |
| --- | --- | --- |
| 登录 / 注册 / 扫码 | `/login` | `/api/web/auth/*`、`/api/web/auth/wechat-gateway/*` |
| 手机确认登录 | `/wechat?spm=…` | `/api/wechat/confirm` |
| 忘记 / 重置密码 | `/forgot`、`/reset` | `/api/web/auth/{forgot,reset}` |
| 首页统计 | `/` | `/api/web/stats`(`?days=7|14|30` 近 N 天;`?period=today|yesterday` 切到今日 / 昨日,趋势变按小时) |
| 设备管理 | `/devices` | `/api/web/devices*` |
| 扫码记录 | `/records` | `/api/web/records` |
| 个人中心 | `/profile` | `/api/web/me*` |
| 测试页(**仅开发构建**,生产不打包) | `/test` | `/api/web/test/*`、`/api/wechat/{status,confirm}` |
> 「测试页」只在 `vite dev` / 本地开发构建里存在:生产构建不产出 `TestView` 的 chunk,
> 路由与左侧菜单也一并去掉;后端 `/api/web/test/*` 只在 `env != prod` 时注册(生产请求返回 404)。
**后端怎么把页面交出去**(`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:7300` 一个地址就够(前端热更新照常生效);
前端没起来时会回一个 502 提示页,而不是白屏;
- **生产**:本仓库的发布脚手架默认由 **nginx 直接托管** `deployRoot/frontend`,Egg 侧用 `FRONTEND_ENABLE=false` 关闭页面托管(只出 `/api`、`/health`);安装包由 nginx 静态托管 `deployRoot/download`。
如果仍想让 Egg 托管(例如没有 nginx),设置 `FRONTEND_ENABLE=true` 并在启动时用 `FRONTEND_DIST` 指向构建产物;找不到文件且请求要 HTML 时回退 `index.html`(SPA 深链不会 404)。
- **单测**(`env=unittest`):整个中间件跳过(不连前端、也不要求 dist 存在)。
## 接口
### 按调用方分模块(目录 / 鉴权 / 路径 一一对应)
| 调用方 | 控制器目录 | 鉴权 | 典型接口 |
| --- | --- | --- | --- |
| **用户端(前端 SPA)** | `app/controller/web/` | `middleware.apiAuth()`(**user JWT**,typ=user);登录/注册/找回免令牌 | `/api/web/{auth/*,me*,stats,devices*,records,test/*}`;`/api/web/admin/*` 额外要 `middleware.platformAdmin()` |
| **运维 / 内部**(运维脚本、后台系统) | `app/controller/internal/` | `middleware.internalAuth()`(`X-Internal-Token` 或白名单账号的 user JWT) | `/api/users*`、`/api/configs*`、`/api/scanners*`、`/api/scanner/{bind,unbind}`、`/api/internal/wechat-bindings*` |
| **用户态**(小程序 / Win 客户端) | `app/controller/client/` | `middleware.apiAuth()`(**user JWT**,typ=user) | `/api/wechat/confirm` |
| **设备**(扫描枪 / 中控) | `app/controller/device/` | `middleware.scannerAuth()`(**device JWT**,typ=scanner) | `/api/device/login`、`/api/scanner/{me,heartbeat}`、`/api/scan/*` |
| **公开登录接口** | `app/controller/auth/` | 无 | `/api/wechat/{status,qrcode.svg}`、`/api/wechat-gateway/notify`(设备发码 `GET /api/device/login` 也无需凭据) |
| 公共 | `home.js` / `health.js` | 无 | `/api/info`、`/health` |
- **小程序与 Win 客户端共用 `client/` 那一套**:它们身份相同(都是「某个登录用户」),业务接口不该复制两份;要区分用途用 header(如 `X-Client: miniapp|win`)或令牌里的自定义声明,别用路径分叉。
- **令牌层是硬隔离**:`verifyUser()` 只认 `typ: 'user'`(默认 7d),`verifyScanner()` 只认 `typ: 'scanner'`(默认 365d)——用户令牌调设备接口、设备令牌调用户接口都直接 401。
(⚠️ 两个 `verify*` 都必须比对 `typ`:用户令牌与设备令牌用的是同一把密钥,不比对的话用户令牌就能当设备令牌用。)
- **前端只能碰自己的数据**:`/api/web/devices*`、`/api/web/records`、`/api/web/stats` 的过滤条件一律取令牌里的 `userId`,前端传的 `userId`/`deviceId` 越权一概 404(不泄露别人有没有这台设备)。
- **服务层不按调用方分**:`app/service/` 按**领域**拆文件(`scanner` / `scan` / `user` / `config` / `wechat_login` / `wx_gateway` / `jwt` / `cache` / `mail` / `verify_code` / `password_reset`),因为设备与内部接口会共用同一个领域服务(如 `service.scanner` 既被 `device/*` 也被 `internal/device.js` 调用);`app/model/` 按表拆。
- Egg 支持多级目录:`app/controller/internal/user.js` → `controller.internal.user`(路由里就是这么引用的),`typings/` 会自动重新生成。
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/info` | 服务信息(JSON) |
| GET | `/health` | 健康检查,MySQL 或 Redis 不可用时返回 503 |
| GET | `/api/users?page=1&pageSize=20&keyword=&status=` | 用户分页(keyword 模糊匹配昵称/登录名/手机号) |
| GET | `/api/users/:id` | 用户详情(Redis 缓存 → 回源数据库) |
| POST | `/api/users` | 新增,body: `{"username":"zhangsan","nickname":"张三","phone":"13800000000"}` |
| PUT | `/api/users/:id` | 更新(清除该用户缓存) |
| DELETE | `/api/users/:id` | 软删除(清除该用户缓存) |
| GET | `/api/internal/wechat-bindings?openid=&userId=` | 微信登录网关的绑定关系(含已解绑的)+ 账号状态 |
| DELETE | `/api/internal/wechat-bindings/:id` | **强制解绑**(不校验归属;微信绑在前员工账号上时用) |
| GET | `/api/configs?group=wechat` | 配置列表(管理用,含禁用项) |
| GET | `/api/configs/:group/:key` | 取单个配置值(带 Redis 缓存) |
| GET | `/api/configs/:group` | 取分组内所有启用配置 |
| PUT | `/api/configs` | 新增/更新(幂等),body: `{"groupName":"wechat","configKey":"appid","configValue":"wx123"}` |
| DELETE | `/api/configs/:group/:key` | 软删除(清缓存) |
| GET | `/api/device/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**:返回当前设备信息(自检连通性) |
| POST | `/api/scanner/heartbeat` | **需 JWT**:保活,刷新 `last_seen_at`;返回 `serverTime` + **`subject`(主体状态,读缓存)**,设备据此判断是否已续期 |
| GET | `/api/scanners?page=&pageSize=&keyword=&userId=&status=` | 设备列表(带绑定账号;管理侧) |
| GET | `/api/scanners/:id` | 扫描器详情 |
| DELETE | `/api/scanners/:id` | 软删除扫描器 |
| POST | `/api/scan/channels` | **需扫描器 JWT**(主体过期/停用 → 403 `subject_expired` / `subject_disabled`):中控上报通道,body: `{ channels: [{ channelId, channelName }], replace?: boolean }`(单条也可)→ `{ created, updated, invalid, errors, removed, unbound }`。`replace: true` = 全量对账:本中控下不在列表里的通道软删并解绑工作台,允许 `channels: []`(**虚拟通道 `CAM-` 前缀豁免**,见面单摄像头) |
| GET | `/api/scan/channels?page=&pageSize=&keyword=&status=` | **需扫描器 JWT**:当前中控已登记的通道 |
| POST | `/api/scan/records` | **需扫描器 JWT**(主体过期/停用 → 403 `subject_expired` / `subject_disabled`):中控上报扫码,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**:当前中控上报的扫码记录 |
| GET | `/api/scanner/label-cameras` | **需扫描器 JWT**:本机该跑的**面单摄像头识别配置** → `{ revision, items, channels, warnings, scannedAt }`。返回本主体、启用中工作台(**散单和团购都支持**)里被设为面单摄像头的绑定;`items[]` 带 `workstationId/Name`、**`wsType`(1 散单 / 2 团购)**、`channelId/Name`(**本机的扫码通道**;工作台没接扫码枪时是**虚拟通道** `CAM-<工作台id>`,见下)、`virtualChannel`(true = 虚拟通道)、`cameraId/Name`、`cameraChannelNo`、`streamType`、`nvr{host,port,username,password}`。`channels[]` 是本机所有被工作台绑定的通道 + `wsType`(含虚拟通道),设备端用它决定**扫码枪**那条路的记录规则(散单取第一次、团购取最后一次)。`revision` 是内容指纹(含密码和通道模式),变了设备端就重建识别任务。RTSP 路径**不在这里拼**(要按录像机「首个数字通道号」换算,只有设备端问得到)。读接口,不挂 `subjectActive` |
| PUT | `/api/web/workstations/:id/cameras/:cameraId/label` | 设置/取消面单摄像头(`{ isLabelCamera: true/false }`,不传按设置)。**散单、团购都可以**;一台工作台最多一路,设新的会先清旧的;取消时顺手清理虚拟通道 |
扫码上报的两个接口都**不会因为重复而报错**(幂等):完全重复的条数计入 `duplicated`,
**同一运单号 24 小时内重复扫描的只保留一条**:时间更新就覆盖(`updated`),更旧的上报忽略(`suppressed`);
单条非法(缺条码 / 时间非法 / 超长)会被跳过并计入 `invalid` + `errors`;整体为空数组才返回 422。
上报还支持 `records` 传 JSON 字符串(部分设备端会这么塞);上报成功会顺手刷新中控心跳与通道的 `last_report_at`,
遇到未登记的通道会自动补建一行(`channel_name` 留空,同时记 WARN 日志)。
**主体期限与设备上报**:设备所属主体过期/停用时,`POST /api/scan/records`、`POST /api/scan/channels`
返回 **403**(`status` = `subject_expired` / `subject_disabled`),设备端应**暂停推送但保留本地积压**;
`POST /api/scanner/heartbeat` 不受期限拦截,返回体里的 `subject.expired` 是恢复依据 —— 续期后最多 1 分钟
设备就会自动恢复并补传(服务端按 设备+通道+条码+秒 去重,整批重发安全)。
主体状态走 `service/subject_state.js` 缓存(Redis 优先,不可用时退化为进程内 TTL),
**心跳与上报判断都不额外查库**;续期/停用后由写库方主动失效缓存(`SUBJECT_STATE_CACHE_TTL`,默认 30 秒)。
统一响应格式:成功 `{ "ok": true, "data": ... }`;失败 `{ "ok": false, "message": "..." }`(由 `app/middleware/error_handler.js` 保证 4xx/5xx 也返回 JSON);
**接口路径写错(没匹配到路由)也是 JSON**:`404 { ok:false, message:'接口不存在' }`(不会再返 HTML 404 页把客户端的 JSON 解析弄挂)。
扫描器 JWT 鉴权结果:缺令牌 / 签名不对 / 已过期 / `jti` 已被轮换 / 扫描器不存在 → **401**;扫描器被禁用 → **403**。
## 用法速查
```js
// ===== MySQL:Sequelize 模型(定义在 app/model/*.js)=====
// 通过 app.model.User / this.app.model.User / ctx.model.User 访问
const { User, Scanner, SysConfig } = this.app.model;
await User.findByPk(1); // 主键查询
await User.findOne({ where: { username: 'zhangsan' } });
await User.findAll({ where: { status: 1 }, limit: 10, offset: 0, order: [[ 'id', 'DESC' ]] });
const { rows, count } = await User.findAndCountAll({ limit: 10 }); // 分页
await User.create({ username: 'zhangsan', nickname: '张三' }); // 新增(自动写 created_at/updated_at)
await User.update({ status: 0 }, { where: { id: 1 } }); // 更新
await User.destroy({ where: { id: 1 } }); // 删除(paranoid 模型 = 软删除)
await User.destroy({ where: { id: 1 }, force: true }); // 物理删除
// 关联查询:一个用户的多台设备
const withScanners = await User.findOne({ where: { id: 1 }, include: [{ model: Scanner, as: 'scanners' }] });
// 原生 SQL / 事务
const [rows2] = await this.app.model.query('SELECT 1 AS ok');
await this.app.model.transaction(async t => {
await User.create({ nickname: 'a' }, { transaction: t });
await User.create({ nickname: 'b' }, { transaction: t });
});
// 操作符:const { Op } = require('sequelize');
// ===== 系统配置:带 Redis 缓存,写入自动失效 =====
const appid = await this.ctx.service.config.get('wechat', 'appid'); // value_type=number/json/boolean 会自动转换
await this.ctx.service.config.set({ groupName: 'wechat', configKey: 'appid', configValue: 'wx123' });
const groupConfig = await this.ctx.service.config.getGroup('wechat'); // { appid: 'wx123', ... }
await this.ctx.service.config.remove('wechat', 'appid'); // 软删除 + 清缓存
// ===== 微信绑定(网关绑定关系,app/service/wx_gateway.js)=====
const binding = await this.ctx.service.wxGateway.findBinding({ appKey, openid: 'o_abc' }); // 带用户
await this.ctx.service.wxGateway.forceUnbind(12); // 运维强制解绑
// ===== 扫描器长期 JWT(app/service/jwt.js)=====
const jwtToken = this.ctx.service.jwt.signScanner(scanner, { jti: 'uuid' }); // 签发
this.ctx.service.jwt.verifyScanner(jwtToken); // 校验(失败直接 401)
this.ctx.service.jwt.expiresAtOf(jwtToken); // 取过期时间(Date)
// ===== 设备业务(app/service/scanner.js)=====
// 扫码登录(注册 + 绑定 + 发令牌,一步到位;userId = 扫码确认的那个人)
const login = await this.ctx.service.scanner.loginByScan({
sn: 'SN-001', // 设备自报的 SN(不传则服务端生成 DEV-…)
name: '1 号线扫描枪',
userId: 1, // 来自 POST /api/wechat/confirm 的确认人
expiresIn: undefined, // 可选:秒数;不传用 config.jwt.deviceExpiresIn
});
login.token; // 长期 JWT(365d)
login.firstTime; // true = 本次才注册出这条记录
await this.ctx.service.scanner.heartbeat(scanner, this.ctx.ip); // 心跳:刷新 last_seen_at
await this.ctx.service.scanner.unbind({ sn: 'SN-001' }); // 管理侧解绑
// ===== 扫码信息(app/service/scan.js,scanner = 中控实例)=====
// 1. 中控上报通道(一个通道一行,重复上报只更新通道名)
await this.ctx.service.scan.reportChannels(scanner, [
{ channelId: 'CH-1', channelName: '1 号打包口' },
]);
// → { received, created, updated, invalid, errors, channels }
// 2. 中控上报扫码结果(同一中控+通道+条码+扫描时间(秒) 自动去重)
const ingested = await this.ctx.service.scan.ingest(scanner, [
{ barcode: '6901234567890', scanTime: '2026-10-16 10:20:30', channelId: 'CH-1' },
{ barcode: '6901234567890', scanTime: '2026-10-16 10:20:30', channelId: 'CH-1' }, // 重复 → 只入库一次
]);
// → { received: 2, inserted: 1, duplicated: 1, invalid: 0, unknownChannels: [] }
// 3. 查询(都带分页;记录默认按 scan_time 倒序)
await this.ctx.service.scan.listChannels({ scannerId: scanner.id, keyword: '' });
await this.ctx.service.scan.listRecords({ scannerId: scanner.id, channelId: 'CH-1', barcode: '690' , startTime: '2026-10-16', endTime: '2026-10-17' });
// 时间解析:'2026-10-16 10:20:30' / '2026-10-16T10:20:30' / 10 位秒时间戳 / 13 位毫秒时间戳 都支持(毫秒会被截断)
// ===== Redis:app.redis 即 ioredis 实例 =====
await this.app.redis.set('k', 'v');
await this.app.redis.setex('k', 60, 'v');
await this.app.redis.get('k');
// 项目封装(见 app/service/cache.js)
await this.ctx.service.cache.set('user:1', { id: 1 }, 60);
await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
```
## 说明
- MySQL 通过 `egg-sequelize@6`(Sequelize 6 + mysql2)访问,模型放在 `app/model/`,表结构以 `sql/schema.sql` 为准(未开启 `sequelize.sync`,避免误改表);需要同步表结构时可在启动钩子里显式调用 `app.model.sync()`。
- **Sequelize 是启动强依赖**:插件在 `beforeStart` 里会 `authenticate()`,连不上数据库时应用启动会失败(重试 3 次后退出);Redis 用 `egg-redis@2`(ioredis),配置了 `client.weakDependent: true`,Redis 不可用不阻塞启动。
- 时间统一按 `timezone: '+08:00'` 处理;表名/字段名下划线映射、created_at/updated_at 命名在 `config.sequelize.define` 中配置。
- 用户/微信授权/系统配置的 `deleted_at` 为软删除:普通查询自动过滤,需物理删除时加 `force: true`。
- `wechat_gateway_bindings` 用 `(app_key, openid)` 唯一键防重;`sys_config` 的唯一性在 service 层保证(原因见「数据表」一节的说明)。
- 所有异常经 `app/middleware/error_handler.js` 处理:`/api/*`、`/health`(或声明了 `Accept: application/json` 的请求)统一返回 `{ ok:false, message }`(4xx 原消息、5xx 只回「服务器内部错误」);其它请求返回一行纯文本(正常情况下它们都被 `middleware/frontend.js` 接走了)。
- **没有模板 / 会话 / CSRF**:`app/view/`、`egg-view-nunjucks`、`egg-session-redis`、`config.view`、`config.session` 全部已删除;接口一律 header 令牌鉴权,`config.security.csrf.enable = false`(没有基于 cookie 的表单了,CSRF 保护已无意义)。
- **前端的页面与样式在 `../frontend/src/`**:公共样式 `styles/main.css`(卡片 / 表单 / 表格 / 分页 / 徽标),每个页面一个 `views/*.vue`;接口调用统一走 `api/client.ts`(自动带令牌、401 清令牌)+ `api/web.ts`(按接口分组)。
- 登录密码用 `bcryptjs` 哈希(`app/service/auth.js`,成本因子 10);用户查询默认 `exclude: ['passwordHash']`,任何接口/模板都不会输出哈希。
- **自助注册**(接口):前端登录页「注册」tab → `POST /api/web/auth/register/code`(发邮箱验证码)→ `POST /api/web/auth/register` → `service.auth.register()`(`user.create` + `setPassword`,用户名/邮箱/手机号重复在 service 层抛 409,接口翻成友好文案)→ 成功直接下发用户 JWT(前端存本地即登录);**邮箱必填**,格式校验后**统一小写入库**;
- **登录账号支持 用户名 / 手机号 / 邮箱**(`service.user.findByAccount()` 的 `Op.or` 同时匹配 `username` / `phone` / `email`);邮箱也能在个人中心修改(同样格式校验 + 小写归一 + 唯一性检查);用户列表的 `keyword` 也搜邮箱;
- 注册开关 `config.register.enable`(环境变量 `REGISTER_ENABLED`,默认开):关掉后发码与注册接口都返回 403「注册已关闭」;这是面向内部管理的服务,**上线建议关闭**并用 `npm run user:pass` 建号;
- **注册必须验证邮箱**(邮箱必填):两步——`POST /api/web/auth/register/code` 发 6 位验证码 → `POST /api/web/auth/register` 带 `code` 校验通过才能建号。
- **发码前先判邮箱是否已被占用**:`service.user.findByEmail()` 用 `LOWER(email) = ?` 查(**大小写不敏感**)+ `paranoid: false`(软删除账号仍占唯一键),命中就直接 409 `email_taken`「该邮箱已被使用…」,**一封邮件都不发**;提交注册时再判一次(防止发码后被别人抢先注册);
- 验证码存 Redis(`packs:verify:register:<email>`,TTL `EMAIL_CODE_TTL`,默认 10 分钟);重发节流(`SET NX`,默认 60 秒);错试超过 `EMAIL_CODE_ATTEMPTS`(默认 5 次)作废;**注册成功才消费验证码**(用户名/邮箱冲突时可改完重提,不用重新收码);
- **每日发信上限**:`packs:mailquota:<email>:<yyyy-MM-dd>`(`service/mail_quota.js`),**同一邮箱每天最多 `EMAIL_DAILY_LIMIT`(默认 10)封**,注册验证码与找回密码**共用**这个额度;超出返回 429 `daily_limit`「该邮箱今天已发送 10 封邮件,达到上限,请明天再试」;按北京时间(UTC+8)切日,key 的 TTL 到当天 24 点自动过期。发信失败 / 被 60 秒节流拦下会把额度还回去;
- 发信走 `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(缓存),不落库**:`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 盖成「服务器内部错误」,用户看不懂);
- **每日发信上限(与注册验证码共用额度)**:同一邮箱每天最多 `EMAIL_DAILY_LIMIT`(默认 10)封,超出返回 **429** + `{ status:'daily_limit', message:'该邮箱今天已发送 10 封邮件,达到上限,请明天再试' }`,**不生成令牌也不发信**(防止被反复点击骚扰收件人 / 刷爆 SMTP 配额);按北京时间(UTC+8)切日;
- 用户按邮箱查也走 `service.user.findByEmail()`(**大小写不敏感 + 含软删除**),避免换个大小写就绕过额度或漏发;Redis 写失败/发信失败 → **503** + `status:'unavailable' | 'mail'`;
- **防账号枚举**:邮箱格式不对才报错;邮箱未注册或账号被禁用时,提示与成功完全一致(“如果该邮箱已注册,链接已经发出”),并且不发信;
- 邮件正文由 `service.mail.sendResetLink()` 生成(与验证码同一套开发模式/SMTP 逻辑:未配 `SMTP_HOST` 时链接写日志 + 接口返回 `url`,前端直接给个可点链接,方便本地点开);
- 链接地址默认取当前请求的 host,正式部署建议配 `SITE_URL`(有反代/多域名时更可靠);
- **改密 / 重置密码后旧令牌立即失效(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 秒容差**:改密当秒新签发的令牌仍然可用,避免误杀);
- **扫码登录(微信登录网关,2026-10-28 起)**:登录页右上角三角形的扫码面板改为对接
[微信登录网关](https://gateway.gztbyc.com/#/docs)。**不再自己发 6 位串码、也不再依赖自家公众号回调**
(旧的 `GET /api/wechat/login` 已删除;`/api/wechat/{qrcode.svg,status}` 只剩**设备扫码登录**在用)。
- **配置**(`config.wxGateway`,全部走 env):`WX_GATEWAY_BASE`(默认 `https://gateway.gztbyc.com`)、
`WX_GATEWAY_APP_KEY` / `WX_GATEWAY_APP_SECRET`(网关管理台建应用时拿,**只放服务端**)、
`WX_GATEWAY_POLL_WAIT`(长轮询上限,默认 55s)、`WX_GATEWAY_SCENE_TTL`(本地会话 TTL,默认 660s)、
`WX_GATEWAY_NOTIFY_SKEW`(通知时间戳容差,默认 300s)、`WX_GATEWAY_TIMEOUT`(调网关超时,默认 8s)。
**不配 appKey/appSecret → 扫码相关接口 503(`未开通微信扫码登录`),前端据此提示**;
- **网关管理台里必须把「服务端通知地址」配成** `https://<本站域名>/api/wechat-gateway/notify`
(= `config.wxGateway.notifyPath`),这是扫码结果回到本站的唯一通道;
- **完整时序**(`service/wx_gateway.js`):
1. 前端 `POST /api/web/auth/wechat-gateway/qrcode` → 服务端向网关 `POST {网关}/api/auth/temp-code`
(header 带 `X-App-Key` / `X-App-Secret`)拿**临时码 + 授权页地址**,同时把「这次扫码要干什么」
写进本地会话(Redis `packs:wxgw:sess:<state>`;`state` 是我们自己的 32 位 hex,原样带给网关);
2. 前端把 `qrUrl`(`/api/wechat-gateway/qrcode.svg?state=…`)当图片显示 —— 二维码**仍然是本地画**
(`qrcode-generator`,零外链资源),内容就是网关给的 `pageUrl`;桌面端(WPF)用同一张图的 GIF 版
(`/api/wechat-gateway/qrcode.gif?state=…`);
3. 用户用**手机微信**扫码 → 网关页点确认 → 网关静默授权(`snsapi_base`)拿 openid →
**带签名 POST** 我们的 `notifyPath`(`event` / `appKey` / `openid` / `bindCode` / `state` / `timestamp` / `nonce` / `sign`);
4. 服务端验签(密钥是 `sha256(appSecret)` 的十六进制,签名串 `appKey.userId.bindCode.timestamp.nonce`;
时间戳偏差 > 5 分钟直接 401)→ 按 `openid` 查 `wechat_gateway_bindings` 找到平台账号 →
把结果写回会话并 `PUBLISH` 唤醒长轮询(验签失败 401;会话已过期返回 **200 + `{ignored:'session_expired'}`**,
免得网关白重试);
5. 前端 `GET /api/web/auth/wechat-gateway/login?state=&wait=55` 拿到 `{ status:'confirmed', token, user }`
—— **令牌是这一步当场签发的**,Redis 里不落令牌;
- **长轮询语义**(`awaitSession()`):`pending`(还在等,继续轮询)/ `confirmed`(成功,**取走即删**)/
`failed`(附 `message`,例如「这个微信还没绑定平台账号」)/ `expired`(会话没了 → 前端重新申请一张继续轮询);
客户端断开(切面板 / 关页签)→ 服务端立刻停止等待(`aborted`,不写响应);前端自己设 70s 超时;
- **不自动建号**:只有「已经绑定微信」的账号能扫码登录;绑定入口在个人中心(见下一条);
- **绑定微信(个人中心,2026-10-28 新增)**:`POST /api/web/me/wechat/qrcode`(需令牌)申请 `scene=bind` 的网关二维码,
手机确认后网关回调 → 写 `wechat_gateway_bindings`:
- `UNIQUE(app_key, openid)`:一个微信只能绑一个账号;同一账号也只留一个微信(换绑要先解绑);
- `GET /api/web/me/wechat/bindings` → `{ list, enabled }`(`enabled=false` = 服务端没配网关,前端整块灰掉);
- `GET /api/web/me/wechat/status?state=&wait=` 长轮询绑定结果(`binding` 里是落库后的绑定关系);
- `DELETE /api/web/me/wechat/bindings/:id` 解绑(只能删自己的,找不到 404);
- 表结构:`wechat_gateway_bindings`(迁移 `20261028120000`):网关用的公众号 appid 我们并不掌握,
只有 `app_key` + `openid`,所以单独一张表(旧的 `wechat_oauth` / `wechat_mp_accounts` 已于 `20261029100000` 删除);
- **设备专用:扫码登录 + 注册(`GET /api/device/login`,`app/controller/device.js`)**:给「设备上不好敲账号密码、甚至**出厂什么都不用配**」的场景用——
**登录即注册**:设备插上电直接要一个登录码显示在**设备屏幕上**,用已经登录的手机(小程序/网页)扫一下确认,
服务端**这才**把设备注册到那个账号名下(归属 = 确认登录的人),并把**长期 JWT** 发给设备
(默认 365 天,见 `config.jwt.deviceExpiresIn` / env `DEVICE_JWT_EXPIRES`;
设备可用 `?expiresIn=30d`(或秒数)申请**更短**的,超上限 422):
- **不需要凭据、也不需要预先注册**(公开接口);
- **不带 `code`**:发一张新登录码(此时**库里还没有任何记录**),返回
`{ status:'pending', expiresIn, code, spm, origin, qrContent, qrImageUrl, qrUrl, device:{ sn, name } }`
—— **域名不用设备自己拼**:`qrContent` 就是二维码里该编的**完整**网址(`http://<域名>/wechat?spm=…`),
`qrImageUrl` 是完整地址的现成 SVG(设备不会画二维码就直接拉这张图),`qrUrl` 是它的相对路径,`origin` 是本次用的域名;
域名取 `SITE_URL`(`config.email.siteUrl`)——有反代/多域名、或**设备走内网而扫码的手机要走公网**时建议配上;没配就用设备请求时的 origin(设备访问服务用的那个地址);
- **设备信息(可选)**:`?sn=`(设备序列号)、`name` / `vendor` / `model` / `firmware`;**发码时带上最省事**
(服务端暂存 `packs:device:info:<code>`,确认/换码时沿用),轮询时再带(补齐/覆盖)也行;不带 SN 时服务端注册那一步生成一个 `DEV-…` 并返回给设备保存;
- **带 `?code=&wait=N`**:**长轮询**(上限 `WECHAT_POLL_WAIT`,默认 60s):
- 手机确认 → **立即**返回 `{ status:'confirmed', firstTime, sn, token, tokenType, expiresIn, expiresAt, scanner, user }`;
- 到时间没人扫 / 码已失效 → `{ status:'refreshed', code:<新码>, spm, qrContent, qrImageUrl, … }`(设备换二维码后继续轮询);
- 设备断开(重启/换页)→ 服务端**立刻**停止等待(`aborted`,不写响应、也不换码);
- 不带 `wait` 就是短轮询,只查一次(`pending` 时还带 `expiresIn` 剩余秒数);
- **确认仍走现有接口** `POST /api/wechat/confirm`(**不为设备新增确认接口**);用的也是同一套 6 位串码,
所以设备码同样能被 `GET /api/wechat/status` 查、也能被手机上的 `/wechat?spm=…` 页面消费;
- **确认成功(就是「注册」发生的时刻,`service/scanner.js` 的 `loginByScan()`)**:
- 该 SN 没有记录 → **新建**:绑到确认的用户,`firstTime: true`(记录是在确认那一刻才建的);
- 该 SN 已有记录且**无主**(历史数据里的 `user_id = NULL`)或**曾被软删** → 由确认者**认领**(软删的 `restore()` 复活),`firstTime: false`;
- 该 SN **已绑定到别的账号** → **403**,拒绝(避免扫一下就把别人的设备换绑走);设备被禁用(`status=0`)→ 403;
- 无论哪条路径都会换发长期 JWT(`jti` 轮换 → 设备上一次的令牌立即失效);
- 登录码**一次性**:被设备取走即删除(同一张码不能给第二台设备用,浏览器页面长轮询与设备长轮询谁先取走算谁的);
- 联调(**新设备不需要先注册**;第三终端是已登录的手机/小程序):
```bash
# ① 设备发码(拿 code / qrContent / qrImageUrl 显示二维码;带上自己的 SN 与名称)
curl -s 'http://127.0.0.1:7300/api/device/login?sn=SN-NEW-01&name=门口扫码枪'
# ② 设备挂长轮询(有人确认就立即返回;参数带上也行)
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:7300/api/wechat/confirm \
-H 'Authorization: Bearer <用户JWT>' -H 'Content-Type: application/json' \
-d '{"code":"<登录码>"}'
# → ② 立即返回 {"data":{"status":"confirmed","firstTime":true,"sn":"SN-NEW-01",
# "token":"<长期JWT>","expiresIn":"365d","expiresAt":"...","scanner":{...},"user":{...}}}
```
- 设备端逻辑(伪代码,轮询到 `refreshed` 就换二维码继续):
```js
const sn = localStorage.getItem('sn') || 'SN-NEW-01'; // 设备自己的序列号(可固定)
let code = null;
for (;;) {
const url = code
? `/api/device/login?code=${code}&wait=60&sn=${sn}`
: `/api/device/login?sn=${sn}&name=门口扫码枪`;
const r = await (await fetch(url)).json();
const d = r.data;
if (d.status === 'confirmed') {
saveToken(d.token); // 长期 JWT(365d),后续请求带 Authorization: Bearer
saveSn(d.sn); // 服务端确认的 SN(没自带 SN 时以这个为准)
break;
}
code = d.code; // pending / refreshed 都带回可用的码
showQrcode(d.qrContent); // 直接编 qrContent(已是完整网址,设备无需知道域名)
}
```
- 新增/重置登录账号:`npm run user:pass -- <账号> <密码> [昵称]`。
- 设备身份**只有长期 JWT 一种**:列表/详情/`me` 接口**不会**返回 `token_jti`(`sanitize()` 兜底);`secret_hash` 是历史字段(已不再写入)。
- **软删除的行仍占着唯一键**:`scanners.sn` 是唯一键而 `deleted_at` 的软删行还在库里,所以扫码登录(`loginByScan()`)**带上已删除的一起查**,命中就把那条记录**复活**(`restore()`,与 `scan.js` 里通道的处理一致),否则 `create` 会撞唯一键;
- 前端「设备管理」页的解绑/删除按钮调 `POST /api/web/devices/:id/unbind` 与 `DELETE /api/web/devices/:id`;前端「测试页」提交后直接展示结果(含长期 JWT),刷新页签不会重复建设备(同 SN = 同一台,只换发令牌);
- 扫描器接口 `/api/scanner/{me,heartbeat}` 走 `app/middleware/scanner_auth.js` 的 JWT 鉴权;接口里的“缺令牌→401 / 被禁用→403 / jti 被轮换→401”语义见上文「扫描器通讯用的长期 JWT」;
- 设备扫码登录 `GET /api/device/login` **不需要任何凭据、也不需要设备预先注册**:发码只写 Redis(库里不建任何东西),
确认成功那一刻(就是「注册」时刻)才按 SN 建/取记录、绑定到确认登录的用户、发长期 JWT;确认环节复用
`POST /api/wechat/confirm` 与同一套 6 位串码(`service/wechatLogin`),**不新增确认接口、不新增 Redis key 空间**;
`SN 已属于其他账号 → 403`(不会把别人的设备扫走),无主记录(老接口注册出来的)由本次确认者认领;
- **扫码登入工作台**:二维码按需生成(网关一次性临时码),手机微信确认后由网关回调落 `workstation_login_records`;
旧的工作台登录码(`WSC-`)与 `POST /api/web/workstation-login` **已废弃**(见下文「工作台成员登录」);
- **没有 CSRF**:后端已关掉 CSRF(`config.security.csrf.enable = false`),页面表单/会话都没了;扫描器用 JWT 调 JSON 接口不会遇到 403;
- 扫码去重放在**数据库唯一键 + 服务层预过滤**两层:唯一键 `(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`);令牌就是上一张卡片发下来的那枚,重新扫码登录会换新令牌(旧令牌立即失效);
- 前端「测试页」的「模拟扫码授权(AJAX)」卡片:一个输入框(填登录码,或直接贴 `/wechat?spm=…` 整条地址)+「查状态」「请求登录」两个按钮,**AJAX 调接口并把返回的 JSON 原样显示,不跳转**:
- 「查状态」→ `GET /api/wechat/status?code=…`(无需登录):`pending`(待扫码)/ `confirmed`(已被确认)/ `expired`(没这个码);
- 「请求登录」→ `POST /api/wechat/confirm`(`{ code }`):`data.status='confirmed'` 即授权成功,电脑端正在长轮询的请求会**立即**完成登录;已用过/不存在/格式错分别返回 `used` / `expired` / `bad_format`;
- **鉴权完全模仿小程序**:AJAX 把用户 JWT 放在 `Authorization: Bearer` 头里(`fetch` 不带 `credentials`),页面上也把这枚令牌显示出来方便贴到小程序里调试;
- **鉴权总览**:`/api/web/*`、`/api/wechat/confirm` 走 `app/middleware/api_auth.js`(**只认 header 里的用户令牌**),其中 `/api/web/admin/*` 再叠一层 `app/middleware/platform_admin.js`(平台管理员);`/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/{status,qrcode.svg}`、`/api/wechat-gateway/notify`、`/api/device/login` 与 `/api/web/auth/*`;另外 `/doc/**`、`/sitemap.txt` 是文档站的静态页面(公开,不走 SPA,见「文档站」一节);
- 密码等敏感信息放 `config/config.local.js`(已 gitignore)或环境变量,不要写进 `config.default.js`。
- 生产环境请修改 `config/config.default.js` 中的 `config.keys`。
## 平台管理员与平台管理台(2026-10-29)
两种「管理员」互不相干,别混:
| | 谁 | 能干什么 | 存在哪 |
|---|---|---|---|
| **主体管理员** | 某个主体里的 `role=1` 成员 | 只管**自己那个主体**:成员、设备、录像机、工作台、扫码记录、续期下单 | `subject_members.role` / `subjects.admin_user_id` |
| **平台管理员** | 平台的运营/管理人员 | 看**所有**主体与订单、改授权到期时间、**确认订单**、加别的平台管理员 | `admin_members`(+ `INTERNAL_ADMIN_IDS` 内置名单) |
### 数据表
| 表 | 说明 |
|---|---|
| `admin_members` | 平台管理员:`user_id`(唯一,账号 id)+ `name`(显示名,不填取昵称/用户名)+ `role`(1 超级管理员 / 2 管理员)+ `status`(1 启用 / 0 停用)+ `remark`;软删除 |
迁移 `20261029120000-create-admin-members`:
- 建表 + `uk_admin_members_user`(`user_id` 唯一)+ `idx_admin_members_status`;
- **把内置管理员先塞进来**(`users.username='admin'`,没有就 `id=1`),保证升级后立刻能用;
- ⚠️ 软删的行仍占着 `user_id` 唯一索引,所以「查重 / 加回来」必须带 `paranoid: false`(`service/admin_member.js` 已处理:命中软删行就 `restore()`)。
### 谁是平台管理员(`middleware/platform_admin.js`)
满足其一即可,`ctx.state.platformAdmin` 记录通过方式:
1. `admin_members` 里 `status=1` 的行(**页面可自助维护**);
2. `config.internal.adminIds`(env `INTERNAL_ADMIN_IDS`,默认 `[1]`)——**内置 / 救急入口**:
就算把页面上的管理员全删了,也还能用它登录把入口加回来(前端会标「内置」且不给移除按钮)。
不通过 → **403** `{ status: 'not_platform_admin' }`。这些接口都要 **user JWT**(`apiAuth` 之后才校验)。
### 接口(`/api/web/admin/*`,全部要求平台管理员)
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/web/admin/me` | 当前账号是不是平台管理员 → `{ admin, builtin, user }`(前端决定要不要显示「平台管理」菜单) |
| GET | `/api/web/admin/members` | 平台管理员列表(表里的 + 内置名单里表里没有的,后者 `id=null`、`builtin=true`) |
| POST | `/api/web/admin/members` | 添加 `{ account, name?, role?, remark? }`;`account` = 用户名 / 手机号 / 邮箱。账号不存在 404、已是管理员 409、账号被禁用 409 |
| DELETE | `/api/web/admin/members/:id` | 移除(软删;**不能移除自己**,也不能把最后一个启用的管理员删光) |
| GET | `/api/web/admin/subjects?page=&pageSize=&keyword=&status=&expired=` | **所有主体**(带成员数 / 管理员账号 / 是否过期);`keyword` 模糊匹配主体名或备注;`expired=1\|0` 只看已过期 / 未过期 |
| PUT | `/api/web/admin/subjects/:id` | **改授权到期时间**:`{ expireAt: '2027-01-01T00:00:00+08:00' }` 直接设(可设成过去 = 立即到期),或 `{ extendDays: 30 }` 顺延(未过期从原到期时间算、已过期从现在算);也可顺带改 `remark` / `status` |
| GET | `/api/web/admin/orders?page=&pageSize=&keyword=&status=&subjectId=` | **所有订单**(带主体名 / 下单人);`keyword` 模糊匹配订单号、套餐名、主体名;`status=0\|1\|2` |
| POST | `/api/web/admin/orders/:orderNo/confirm` | **确认订单**(线下收款 / 手工补单):与支付回调走**同一套** `service.subjectOrder.payNotify()`,所以「标记已支付 + 主体顺延 + 失效主体状态缓存 + 幂等」完全一致,只是渠道记成 `manual`、流水号 `ADMIN-<时间戳>` |
| GET | `/api/web/admin/plans` | **全部续期套餐**(含已下架)`{ list, total }`,每项带 `statusText` / `pricePerDay` |
| POST | `/api/web/admin/plans` | 新建套餐 `{ code?, name, days, price, originalPrice?, tag?, description?, sort?, status? }`;`code` 留空按天数生成(如 `p30`),重复 409;天数 1~3650、金额非负 |
| PUT | `/api/web/admin/plans/:id` | 修改套餐(只改传了的字段;`code` 创建后不可改);常见用法:改价 `{ price: 129 }`、上下架 `{ status: 0 }` |
| DELETE | `/api/web/admin/plans/:id` | 删除套餐(软删)。历史订单已快照 `plan_code / plan_name / days / amount`,不受影响;只想停售用 `status=0` 下架 |
用户端 `GET /api/web/subject-plans` 只返回 `status=1` 的套餐,续期金额只按库里的 `price` 算 —— 所以改价 / 改天数**改完即生效、不用发版**。
改授权到期时间后必须失效主体状态缓存(`subjectState.invalidate`),否则设备心跳 / 上报最多要等一个 TTL 才看到新期限 —— `service/subject.js#setExpireAt()` 已经做了。
### Chrome 插件配置(集中下发)
插件**只拉取执行**,配置存在 `sys_config`(`group='extension'`, `config_key='config'`, `value_type=json`),不新建表。
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| GET | `/api/web/admin/extension` | 平台管理员 | 当前配置(含 `version` / `updatedAt` / 已生成的正则 `pattern`) |
| PUT | `/api/web/admin/extension` | 平台管理员 | 保存 `{ enabled, hosts, prefixes, minDigits, maxDigits, urlTemplate, appUrlTemplate, downloadUrl }`;**不收 `pattern`**,正则由服务端拼;成功后 `version + 1` |
| GET | `/api/web/extension/config` | 公开(可选 `?key=`) | 插件读的副本;`config.extension.appKey`(env `EXTENSION_APP_KEY`)非空时要求 key 一致 |
- 单号正则 = `\b(?:<前缀用 \| 连接>)\d{min,max}\b`(`service/extension_config.js#buildPattern`),前缀只允许大写字母/数字、1~8 位、最多 50 个;
- `hosts` 是插件生效站点(glob,支持 `*.abc.com`);留空按 `['*']` 处理;
- 插件每 **5 分钟**拉一次,靠 `version` 判断要不要更新(版本没变不写存储);`GET /api/web/extension/config` 的返回在 Redis 缓存 **1 小时**(`extension:config:public`),后台 `PUT` 保存时立刻删缓存 —— 提交即生效,平时又不会每 5 分钟回源一次;
- **发布新安装包不用清缓存**:安装包地址由插件每次直接读 nginx 的 `/download/version.json`(nginx 对这个路径是 no-cache),不进这份 1 小时缓存;`service/extensionConfig.invalidate()` 留给运维/发布脚本需要时手工调用;
- `downloadUrl` **不用配**:插件同步时优先读 `GET /download/version.json`,永远用最新发布版本
(后台页面已不提供这个输入框;配置里的值只在 version.json 拉不到时兜底);
- 生产若配了 `CORS_ORIGINS` 白名单,记得把 `chrome-extension://<扩展ID>` 加进去(默认 `*` 不用管)。
## 文档站(简易 CMS,2026-11-07)
文档站是**静态 HTML**:内容存在库里,保存时由 `service/docSite` 整站渲染到 `run/doc-site/`(`run/` 被 gitignore),
`controller/web/doc.js` 只负责回文件(文件不存在时按需重新生成,部署后不用手工跑构建)。
- 层级:**分类**(文档站顶部 tab)→ **栏目**(侧边栏分组)→ **内容页**(Markdown,`lib/markdown.js` 渲染);
- 页面地址:`/doc/`、`/doc/<分类编码>/`、`/doc/<分类编码>/<文章 slug>.html`;
- 新链接按顺序追加到 `/sitemap.txt` 末尾(下架 / 删除的会被清掉);
- `middleware/frontend.js` 已把 `/doc/**`、`/sitemap.txt` 从 SPA 里排除;Vite dev server 也把它们反代给后端;
- 生成目录 / sitemap 的站点根地址:`config.docSite.baseUrl`(env `SITE_BASE_URL`),不配就用触发请求的 origin。
### 接口(`/api/web/admin/doc/*`,全部要求平台管理员)
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/web/admin/doc/tree` | 分类 → 栏目 → 内容页(树;文章不带正文,带 `url` / `statusText`) |
| POST | `/api/web/admin/doc/categories` | 新增分类 `{ code?, name, description?, sort?, status? }`;`code` 留空自动 `cat1`、`cat2`… |
| PUT | `/api/web/admin/doc/categories/:id` | 修改分类(`code` 创建后不可改,其余只改传了的字段) |
| DELETE | `/api/web/admin/doc/categories/:id` | 删除分类(栏目与内容页一起软删,页面与 sitemap 一并移除) |
| POST | `/api/web/admin/doc/sections` | 新增栏目 `{ categoryId, name, sort?, status? }` |
| PUT | `/api/web/admin/doc/sections/:id` | 修改栏目(传 `categoryId` 可换分类,底下内容页跟着走) |
| DELETE | `/api/web/admin/doc/sections/:id` | 删除栏目(内容页一起软删) |
| GET | `/api/web/admin/doc/articles/:id` | 单篇(含 Markdown 正文) |
| POST | `/api/web/admin/doc/articles` | 新增内容页 `{ sectionId, title, slug?, summary?, content?, sort?, status? }`;`slug` 留空自动 `a1`、`a2`… |
| PUT | `/api/web/admin/doc/articles/:id` | 修改内容页(`slug` 创建后不可改;`status=0` 作草稿,不生成页面) |
| DELETE | `/api/web/admin/doc/articles/:id` | 删除内容页 |
| POST | `/api/web/admin/doc/rebuild` | 手动整站重生成(排查用,返回页面数与 sitemap 条数) |
公开读取(无令牌):`GET /doc/**`、`GET /sitemap.txt`。
### 前端(`frontend/`)
左侧菜单在**平台管理员**登录后会多出一组「平台管理」(`components/AppLayout.vue`):
| 菜单 | 路由 | 页面 | 干什么 |
|---|---|---|---|
| 主体管理 | `/admin/subjects` | `views/AdminSubjectsView.vue` | 所有主体;「改到期时间」弹窗支持**直接选时间**或**顺延 N 天**(+7 / +30 / +90 / +1 年快捷按钮) |
| 订单管理 | `/admin/orders` | `views/AdminOrdersView.vue` | 所有订单;待支付的可以「确认订单」(二次确认后立即续期) |
| 套餐管理 | `/admin/plans` | `views/AdminPlansView.vue` | 续期套餐的新增 / 改价 / 改天数 / 上下架 / 删除(下单只按这里的售价算钱) |
| 管理员 | `/admin/members` | `views/AdminMembersView.vue` | 平台管理员列表 + 添加(按账号)+ 移除 |
| 插件配置 | `/admin/extension` | `views/AdminExtensionView.vue` | Chrome 插件的单号前缀 / 生效站点 / 跳转模板 |
| 文档管理 | `/admin/doc` | `views/AdminDocView.vue` | 文档站 CMS:分类(顶部 tab)→ 栏目 → 内容页(Markdown),保存即重生成静态页面 |
- 是否显示这组菜单靠 `GET /api/web/admin/me`(`composables/usePlatformAdmin.ts`;非管理员 403 静默当 false);
- 路由带 `meta.platformAdmin`,不是平台管理员会被守卫踢回首页(`?denied=1`);
- 这些页面 `allowNoSubject: true` —— 平台管理员可能一个主体都没有,不能因为「没主体」被挡走。
## 主体(租户)体系(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` |
| `workstation_login_records` | 工作台成员登录记录:谁在什么时候登入 / 下线了哪台工作台(见「工作台成员登录」) |
| 业务表 | `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` | 成员列表(任何成员都能看,只读;带 `isCreator` 标记创建者) |
| POST | `/api/web/subjects/:id/members` | 按姓名快速添加成员 `{ name }`(**仅管理员**,此时还没绑账号) |
| DELETE | `/api/web/subjects/:id/members/:memberId` | 移除成员(**仅管理员**;不能删创建者/管理员/自己,管理员要先取消管理员) |
| PUT | `/api/web/subjects/:id/members/:memberId/role` | 设/取消管理员 `{ role: 1\|2 }`(**仅管理员**;一个主体可多名管理员,创建者恒为管理员不能降级,不能改自己) |
| POST | `/api/web/subjects/:id/members/:memberId/bind-qr` | 生成「扫码绑定」二维码(**仅管理员**,走微信登录网关)→ `{ memberId, memberName, state, pageUrl, qrUrl, expiresIn }`;成员已绑**真实账号**时 409 |
| GET | `/api/web/subjects/:id/members/:memberId/bind-qr/status?state=&wait=` | 长轮询绑定结果(**仅管理员**)→ `{ status, memberName?, boundName?, autoCreated?, message? }`(`pending` / `confirmed` / `failed` / `expired`) |
| POST | `/api/web/subjects/:id/members/:memberId/unbind` | 解除成员的账号绑定(**仅管理员**;绑错了/手机换人时用,自动建的临时账号会一并删除) |
角色规则(`subject_members.role`):
- **一个主体可以有多个管理员**(`role=1` 没有唯一约束);`subjects.admin_user_id` 只是**创建者**,同样恒为管理员;
- 成员管理(加成员 / 扫码绑定 / 解除绑定 / 设·取消管理员 / 移除)**只有管理员能做**,普通成员只能看成员列表(只读);
- 创建者不能降级、不能移除;不能改自己的角色、不能删自己(避免管理员把自己锁死);
- 管理员不能直接移除,需先「取消管理员」;给**未绑定账号**的成员设为管理员,绑定后即为管理员。
### 成员扫码绑定(微信登录网关,2026-10-28)
管理员点「扫码绑定」出一张网关二维码,成员用**手机微信**扫码确认后按两种情形落地(`service/subject.js#bindMemberWithWechat`):
- **这个微信已经是某个平台账号的登录方式**(`wechat_gateway_bindings` 里有它)→ 成员**直接继承**那个账号;
如果成员之前挂着一个自动建的临时账号,那个账号会被软删(连它的微信绑定一起清掉),`subject_members.temp_user_id` 置空;
- **这个微信还没有平台账号** → 服务端**自动给这名成员建一个账号**(用户名 `member<成员id>`、随机密码、昵称=成员姓名),
把微信绑成它的登录方式,并记在 `temp_user_id` 上;此后这名成员可以直接微信扫码登录;
- 例外(都会变成会话里的 `failed`,弹窗直接显示原因):微信绑定的账号被禁用、这个账号已经是本主体成员(`subject_members` 唯一键)、
成员已绑**其他真实账号**(先「解除绑定」再扫)。
旧的「6 位绑定码 + `/wechat?bind=<码>` 手机确认页」**已删除**(`/api/subject/member-bind*` 一并移除),
`/api/wechat/qrcode.svg?mode=member` 的 `mode` 参数也一起去掉。
### 续期套餐与订单(支付回调驱动)
**续期不再是「自己输入天数」**:前端先选套餐(天数 + 定价都在库里),点「生成订单」只落一笔**待支付**订单,
**不会立刻续期**;只有支付渠道回调确认后才把主体期限顺延(幂等,重复回调不重复续期)。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/web/subject-plans` | 上架套餐 `{ list: [{ id, code, name, days, price, originalPrice, tag, description, pricePerDay }] }`(任何登录用户可读) |
| GET | `/api/web/subjects/:id/orders` | 订单列表(成员可见,`{ total, page, pageSize, list }`) |
| POST | `/api/web/subjects/:id/orders` | **选套餐下单** `{ planId, remark? }`(仅管理员)→ `{ orderNo, planId, planName, days, amount, status:0待支付, pending:true, payExpireAt, expired:false, reused, codeUrl, qrImage, payable, … }`;**金额只认套餐价**,前端传的 `amount/days` 一律忽略。同一主体 + 同一套餐还有**没超时**的待支付单时直接返回**原订单**(`reused:true`,连二维码一起,不重复建单);已超时则先关单再新建 |
| GET | `/api/web/subjects/:id/orders/:orderNo` | 单笔订单(续期弹窗每 2s 轮询支付状态,`pending=false` 即停止;超时会被就地关闭成 `status=2`;顺带节流查单,回调丢了也能补入账) |
| POST | `/api/web/subjects/:id/orders/:orderNo/close` | 关闭待支付订单(仅管理员;已支付 → 409;先在微信侧关单,若发现「其实已付」就入账而不是关单) |
| POST | `/api/pay/notify` | **公开的渠道回调** `{ orderNo, transactionId?, amount?, channel?, paidAt? }` → `{ duplicated, order }`;订单不存在 404、金额不符 422、签名错 400、**超时失效 409** |
| POST | `/api/pay/wechat/notify` | **微信支付结果通知**(公开,XML 进出,APIv2 密钥验签);回 `{ return_code, return_msg }` |
| POST | `/api/internal/subject-orders/:orderNo/pay` | **内部令牌**:模拟支付成功(不需要签名),方便联调/补单;超时订单同样 409 |
**待支付订单 2 小时自动失效**(`config.pay.orderTtl`,env `PAY_ORDER_TTL`,默认 `7200` 秒):
支付截止时间 = `created_at + TTL`,响应里的 `payExpireAt` / `expired` / `pending` 就是给前端做倒计时和停止轮询用的
(`pending=false` 表示不用再轮询;`expired` 只在「还是待支付但已过截止时间」时为 true,
正常读一次就会被就地关成 `status=2`,这时看 `status` / `statusText` 即可)。超时订单会被置为 `status=2`(已关闭),
**之后再到支付回调 / 手工确认,一律 409「订单已超时失效,请重新下单」**(与微信扫码支付二维码 2 小时有效期一致)。
关单有三个触发点,互相兜底:
1. 定时任务 `app/schedule/subject_order_expire.js`(每分钟一次,`type: worker`,逻辑幂等);
2. 读路径(订单详情 / 订单列表 / 平台订单列表)读到超时订单随手关掉;
3. `payNotify()` 进门先判一次(含事务内兜底),避免回调与关单并发时把已失效订单续期。
订单会快照 `plan_id / plan_code / plan_name`,套餐后续改价或下架都不影响历史订单对账。
套餐表 `subject_plans`(迁移 `20261021180000-create-subject-plans` 内置三档;改价 / 改天数 / 上下架走后台**平台管理 → 套餐管理**(`/api/web/admin/plans`),不用发版):
| code | 天数 | 价格 | 备注 |
|---|---|---|---|
| `p30` | 30 | ¥99 | 短期试用 / 临时项目 |
| `p180` | 180 | ¥499 | 角标「推荐」,划线价 ¥594(≈¥2.77/天) |
| `p365` | 365 | ¥899 | 角标「最划算」,划线价 ¥1204(≈¥2.46/天) |
签名:配置了 `PAY_CALLBACK_SECRET` 时,回调必须带
`X-Pay-Sign = hex(HMAC-SHA256(secret, "orderNo\ntransactionId\namount"))`;
未配置密钥且 `PAY_MOCK=true` 时允许不带签名直接回调(开发/测试默认开启;**生产默认关闭**,
需要显式设 `PAY_MOCK=true`,否则回调返回 503 `pay_not_configured`)。
续期规则与 `PUT /api/web/subjects/:id` 的 `extendDays` 一致:**未过期在原到期时间上顺延,已过期从当前时间起算**;
回调成功后会主动失效主体状态缓存,设备下一次上报/心跳立即看到新期限。
**模拟一次付费续期**(本地/测试):
```bash
# 1) 选套餐下单(需要主体管理员用户令牌)
curl -X POST http://127.0.0.1:7300/api/web/subjects/1/orders \
-H "Authorization: Bearer <user-jwt>" -H "Content-Type: application/json" \
-d '{"planId":1}'
# 2a) 模拟渠道回调(PAY_MOCK=true 时不需要签名)
curl -X POST http://127.0.0.1:7300/api/pay/notify \
-H "Content-Type: application/json" \
-d '{"orderNo":"<上一步的 orderNo>","transactionId":"TXN-1","amount":99}'
# 2b) 或者走运维接口(内部令牌)
curl -X POST http://127.0.0.1:7300/api/internal/subject-orders/<orderNo>/pay \
-H "X-Internal-Token: <INTERNAL_TOKEN>"
```
### 微信 Native 扫码支付(原生扫码 / APIv2)
`service/wxpay.js` 负责和微信打交道,订单侧只认「已支付」这个结果:
1. 下单:`POST /api/web/subjects/:id/orders` → 建单后**同一请求内**调【统一下单】拿 `code_url`,
落库到 `subject_orders.code_url` / `prepay_id`,并把二维码在**服务端本地**画成 SVG
(响应里的 `qrImage` 是 data URL,零外链,前端直接 `<img :src>`);
2. 扫码支付:用户微信扫码 → 输入密码 → 微信回调 `POST /api/pay/wechat/notify`(XML)→ 验签 → `payNotify()` 续期;
3. 兜底:前端每 2s 轮询订单详情,`detail()` 会用【查询订单】主动查一次单(同订单 10s 节流),
回调丢了也能补入账;
4. 失效:`code_url` 有效期 2 小时,与 `PAY_ORDER_TTL`(默认 7200 秒)一致;订单超时关闭时
会先调【关闭订单】把微信侧一起关掉(若发现「其实已付」则改为入账,不会把已付款订单关掉)。
**复用未支付订单**:同一主体 + 同一套餐还有没超时的待支付单时,下单接口直接返回**原订单**
(`reused: true`,二维码、`payExpireAt` 都不变),不会重复建单;等它超时关单后再下单才建新单。
前端据此只展示剩余支付时间。
**配置**(由发布脚本把 `config/env.prod.sh` 上传到服务器 `shared-config/`,仓库里先留空):
```bash
export WXPAY_APP_ID='' # Native 支付用的 appid(已关联到商户号)
export WXPAY_MCH_ID='' # 商户号
export WXPAY_API_KEY='' # APIv2 密钥(下单签名 + 回调验签)
# 可选:WXPAY_NOTIFY_URL(默认 https://<SITE_URL>/api/pay/wechat/notify)、WXPAY_ENABLED=false
```
⚠️ 三项缺任意一项 = **未开通**:订单照常创建,只是没有二维码(`qrImage: null`、`payable: false`),
前端提示联系管理员。回调地址必须公网可访问、不带参数,并放行 `POST /api/pay/wechat/notify`。
成员绑定不再用 6 位码:改用微信登录网关的二维码,见上文「成员扫码绑定」(`POST /api/web/subjects/:id/members/:memberId/bind-qr`)。
### 主体上下文(统一处理)
- 业务接口除 `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` 限定范围
- **业务数据只给主体管理员**:设备 / 录像机 / 摄像头 / 工作台 / 扫码记录这些接口在 `subjectAuth` 之后
再挂 `middleware.subjectAdmin()`,普通成员一律 **403** `{ status: 'subject_forbidden' }`
(判定与 `subjectService.ensureAdmin` 一致:创建者或 `role=1`)。
前端同步:左侧菜单只对管理员显示这几项,路由 `meta.adminOnly` 会把成员挡回首页;
`/api/web/stats` 与 `/api/web/pack-query` **不拦**(首页概览 / 桌面端打包查询普通成员也要用)。
**`GET /api/web/nvrs/:id/credential` 也不拦**:按运单回放/下载录像要凭据,是打包现场日常动作,
普通成员可以取,但范围由 `nvr.credentialOf(id, subjectId)` 限定在当前主体(别的主体一律 404);
其余 `/nvrs` 管理接口仍然只给管理员。
- 登录(`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-gateway/qrcode.gif?state=` | 桌面端(WPF)登录二维码的 **GIF**(不能渲染 SVG;`online.png` 不需要) |
**「一个主体只允许一台设备在线」**:`activate` 会把同主体下**其他**设备的 `token_jti` 全部轮换(旧 JWT 立即失效),
并在返回的 `kicked` 里列出被踢的设备;同一 SN 重复开启只是换发令牌,不会新建记录。
设备令牌用于设备侧上报:`POST /api/scan/channels`、`POST /api/scan/records`(`scannerAuth` + `subjectActive`,
不需要主体 header;所属主体过期/停用 → 403 `subject_expired` / `subject_disabled`)。
### 面单摄像头 & 虚拟通道(`CAM-<工作台id>`)
工作台的**面单摄像头**(`workstation_cameras.is_label_camera = 1`,一台工作台最多一路,散单/团购都能设)
由桌面端拉 RTSP 识别条码,识别结果按「该工作台 + 本机通道」上报。记录规则按工作台类型分流
(下发里的 `wsType`):**散单取第一次 + 立即上报,团购和扫码枪一样静默 5 秒取最后一次**。
工作台**没接扫码枪**(没绑本机通道)也能用:`GET /api/scanner/label-cameras` 会顺手给它一条
**虚拟通道**,规则如下(实现在 [app/lib/virtual-channel.js](app/lib/virtual-channel.js)):
| 项 | 规则 |
|---|---|
| 通道 id | `CAM-<工作台id>`,与设备上报的真实通道(纯数字 / `DESKTOP`)不会冲突 |
| 通道名 | `面单摄像头·<摄像头名>` |
| 创建 | 设备拉配置时幂等自愈(`label_scan.ensureVirtualChannel`),并绑到该工作台(回放定位靠 `scanner+channel → 工作台`) |
| 清理 | 取消面单摄像头、绑上真实扫码通道、删除工作台时自动清掉(`workstation.releaseVirtualChannel`) |
| 对账豁免 | `POST /api/scan/channels` 的 `replace: true` **不动** `CAM-` 前缀的通道(设备列表里永远没有它) |
| 前端 | 工作台详情里标记「虚拟」,不给解绑;人工绑定通道列表里也不出现 |
| 播报 | 虚拟通道没有对应的安卓扫码工位,所以**不会**通知安卓端播报 |
#### 变更怎么通知到设备(`labelScan.refresh`)
设备端只有「启动拉一次 + 每分钟兜底」,秒级生效靠**服务端主动推**:
| 触发点 | 位置 |
|---|---|
| 设置/取消面单摄像头 | `workstation.setLabelCamera` |
| 解绑摄像头(可能是面单那路)/ 删除摄像头 | `workstation.unbindCamera`、`camera.remove`、`camera.batchRemove` |
| 摄像头停用/改名 | `camera.update` |
| 绑定/解绑上报通道(面单结果落点变了) | `workstation.bindScanChannels`、`unbindScanChannel` |
| 工作台改名/改类型/停用/删除 | `workstation.update`、`workstation.remove` |
实现:`labelScan.notifyChanged(subjectId)` 给本主体**每台启用中的设备**入队一条
`labelScan.refresh` edge 任务(`edge_task.enqueue`)。设备收到只是被「叫醒」,真正的配置仍以
`GET /api/scanner/label-cameras` 为准;入队失败只记日志(配置已落库,不能因为通知失败回滚)。
## 工作台成员登录(2026-10-24)
成员用**手机微信**扫管理员生成的二维码登入工作台(2026-10-28 起走微信登录网关,旧的 `WSC-` 登录码已废弃)。这张表同时回答两件事:
「**现在**这台工作台上是谁」和「**某张运单打包时**是谁」。
### 数据表
| 表 / 字段 | 说明 |
|---|---|
| ~~`workstations.login_code`~~ | **已废弃**(迁移 `20261028121000` 删除):扫码登入改走微信登录网关,二维码按需生成、一次有效 |
| `workstations.last_active_at` | 最后活跃时间(扫码上报 / 有人登录时刷新) |
| `workstations.idle_timeout_sec` | 多少秒不活跃自动下线所有成员(团购默认 3600、散单默认 1800) |
| `workstation_login_records` | 一次登录一行:`subject_id` / `workstation_id` / `user_id`(+ `member_id`)/ `name` / `type`(1 扫码登录,预留扩展)/ `login_code`(历史字段,新记录为空)/ `login_at` / `logout_at` / `status`(1 在线 0 下线)/ `logout_reason` / `login_ip` |
- 索引:`(workstation_id, login_at)`(运单回放定位「当时谁在线」)、`(workstation_id, status)`、`(user_id, status)`、`(subject_id, login_at)`、`status`(定时任务扫在线)。
- `name` 记登录当时的名字:**是工作台所属主体的成员 → 成员姓名(= 工号)**;不是成员 → 用户自己设置的昵称。
- `logout_reason`:`manual` 手动下线 / `offline_all` 一键全部下线 / `reset_code`(旧版重置登录码,仅历史)/ `idle_timeout` 长时间不活跃 / `relogin` 同一个人重新登录 / `workstation_deleted` 工作台被删除。
### 接口
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/web/workstations/:id/login-qr` | **生成扫码登入二维码**(微信登录网关,`scene=login`)→ `{ workstationId, state, pageUrl, qrUrl, expiresIn }`;二维码一次有效 |
| GET | `/api/web/workstations/:id/login-qr/status?state=&wait=25` | 长轮询扫码结果 → `{ status, workstation?, member?, name?, record? }`(`pending` / `confirmed` / `failed`+`message` / `expired`);手机确认后网关回调落登录记录,**同一账号重复登录旧记录按 `relogin` 下线** |
| GET | `/api/web/workstations/:id/members?status=1&startTime=&endTime=&page=&pageSize=` | 成员列表(`status=1` 只看在线,不传 = 含历史;`startTime/endTime` 按**登录时间**过滤)→ `{ list, total, page, pageSize, onlineCount }` |
| POST | `/api/web/workstations/:id/members/:recordId/offline` | 手动下线某条在线记录(幂等,已下线返回 `alreadyOffline: true`) |
| POST | `/api/web/workstations/:id/members/offline-all` | 把该工作台**所有在线成员下线**(`offline_all`)→ `{ id, offline }` |
| GET | `/api/web/pack-query?code=` | 每条 `records[].packers` = 该次扫码时还在线的人(`[{ id, userId, memberId, name, loginAt, logoutAt }]`) |
鉴权:`/login-qr`、`/login-qr/status`、`/members`、`/offline`、`/offline-all` 与工作台其它接口一致(`apiAuth` + `subjectAuth` + `subjectAdmin`)。
登入本身发生在**网关回调**(`/api/wechat-gateway/notify`,公开但必须验签)里:`openid` → `wechat_gateway_bindings` → 平台账号 →
`workstationLogin.loginByUser()`(主体停用 → 403、过期 → 403、工作台停用 → 403 都会变成会话里的 `failed` + 原因)。
⚠️ 旧接口 `POST /api/web/workstation-login`(`{ code }`)与 `POST /:id/login-code/reset` **已删除**。
### 自动下线
- 扫码上报(`POST /api/scan/records`)成功后刷新相关工作台的 `last_active_at`;有人登录也会刷新。
- 定时任务 `app/schedule/workstation_idle_offline.js` **每分钟**扫一次还在线的记录:
`now - (last_active_at || 该工作台最晚一条在线记录的 login_at) >= idle_timeout_sec`
→ 把该工作台所有在线记录下线(`idle_timeout`)。从没上报过条码的工作台按「最晚登录时间」算,
不会出现「刚建的工作台永远不下线」;工作台已删除则按 `workstation_deleted` 收尾。
- 默认值:团购 3600 秒、散单 1800 秒;`POST/PUT /api/web/workstations` 的 `idleTimeoutSec` 可改(60~86400 秒)。
只切类型且没传 `idleTimeoutSec` 时,自动套用新类型的默认值。
### 运单打包人员
`GET /api/web/pack-query` 的 `records[].packers` 来自 `workstation_login_records`:
`login_at <= 扫码时间 <= (logout_at ?? 现在)`(**按秒比较**,兼容设备上报的秒级扫码时间),
同一时刻多人同时在线就是多人打包(数组,可能为空)。
## 用户协议(2026-10-20)
三张表(迁移 `20261020220000-create-agreement-tables`,示例数据 `20261020221000-seed-user-agreement`):
| 表 | 用途 |
|---|---|
| `agreements` | 协议定义:`code` / `name` / `required` / `current_version_id` |
| `agreement_versions` | 版本正文:`version` / `content` / `content_type` / `status` / `published_at` |
| `user_agreements` | 用户同意记录:`user_id + agreement_id + version_id` 唯一,另存版本号快照与来源/IP/UA |
接口:
- `GET /api/agreements/current`(公开)→ 当前启用的协议 + 已发布版本正文(登录前展示)
- `POST /api/web/auth/login` 增加 `client` / `agreements`:
- `client='mini_program'` 时,必须带 `agreements: [{ code, versionId }]` 且版本等于当前版本,
否则 **428** `{ ok:false, status:'agreement_required', data:{ agreements } }`;
- 登录成功后按 `user_id + agreement_id + version_id` 落库(同一版本重复登录只更新 `agreed_at` / 来源),响应里带 `agreements`。
- 强制范围由 `AGREEMENT_ENFORCE` 控制:默认 `mini_program`(只拦小程序客户端);`all` = 所有客户端;`off` = 不校验(仍记录主动提交的同意)。
没有管理界面,发布新版本直接执行 SQL(示例):
```sql
SET @aid = (SELECT id FROM agreements WHERE code = 'user_agreement');
INSERT INTO agreement_versions
(agreement_id, version, title, summary, content, content_type, status, published_at, effective_at, created_at, updated_at)
VALUES
(@aid, '1.1.0', '用户协议', '更新说明', '新的协议正文', 'text', 1, NOW(), NOW(), NOW(), NOW());
SET @vid = LAST_INSERT_ID();
UPDATE agreements SET current_version_id = @vid, updated_at = NOW() WHERE id = @aid;
```
发布后,小程序下次登录会收到 428 → 自动拉新正文、要求重新阅读并勾选;旧版本的同意记录保留。
查某个用户同意过哪些版本:
```sql
SELECT agreement_id, version_id, version, source, agreed_at
FROM user_agreements WHERE user_id = ? ORDER BY agreed_at DESC;
```
⚠️ 种子迁移里的协议正文是**占位示例**,正式上线前务必替换为法务确认后的文本。
## 已下线:小程序微信一键登录(2026-10-29 移除)
自建的「小程序 code2Session 一键登录」已经整体下线,微信侧的接入统一走下面的**微信登录网关**:
- 删除的表:`wechat_mp_accounts`(小程序 openid ↔ 平台账号)、`wechat_oauth`(自建公众号网页授权 + 运维手工维护的绑定关系);
- 删除的接口:`POST /api/web/auth/wechat/{login,bind}`、`GET /api/web/auth/wechat/bindings`、`DELETE /api/web/auth/wechat/bindings/:id`、
`GET /api/users/:id/wechats`、`GET /api/wechat/:appid/:openid`、`POST /api/wechat/bind`、`PUT /api/wechat/:id/tokens`、`DELETE /api/wechat/:id`;
- 删除的代码:`app/service/{wechat,wechat_mp}.js`、`app/controller/web/wechat_mp.js`、`app/model/{wechat_oauth,wechat_mp_account}.js`、
`service/user.js#findByOpenid`、`service/wechatLogin.js#{login,exchangeCode,oauthAuthorizeUrl}`、`GET /api/wechat/callback`;
- 删除的环境变量:`WECHAT_APPID` / `WECHAT_SECRET` / `WECHAT_REDIRECT_URI` / `WECHAT_API_BASE` / `WX_MP_APPID` / `WX_MP_SECRET` / `WX_MP_MOCK`;
- 迁移:`20261029100000-drop-legacy-wechat-tables.js`(`down` 会按原结构重建两张空表)。
现在小程序只支持**账号密码登录**;`/api/wechat/{status,qrcode.svg}` + `POST /api/wechat/confirm` 仅剩**设备扫码登录**在用。
## 微信登录网关(扫码登录 / 绑定微信 / 工作台扫码登入,2026-10-28)
对接 [gateway.gztbyc.com](https://gateway.gztbyc.com/#/docs):二维码与「扫码确认」都由网关提供,
本服务只负责 **申请临时码 → 验签收通知 → 落地自己的业务**。
### 环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
| `WX_GATEWAY_BASE` | `https://gateway.gztbyc.com` | 网关地址(本地联调可指向假网关) |
| `WX_GATEWAY_APP_KEY` | 空 | 网关应用标识(`gwk_…`);**空 = 未开通**,扫码接口一律 503 |
| `WX_GATEWAY_APP_SECRET` | 空 | 网关应用密钥(`gws_…`),**只放服务端**,用来验证回调签名 |
| `WX_GATEWAY_POLL_WAIT` | `55` | 长轮询最长挂起秒数(前端再留 70s 自己的超时) |
| `WX_GATEWAY_SCENE_TTL` | `660` | 本地扫码会话有效期(秒,比网关临时码的 10 分钟略长) |
| `WX_GATEWAY_NOTIFY_SKEW` | `300` | 通知 `timestamp` 允许偏差(秒) |
| `WX_GATEWAY_TIMEOUT` | `8000` | 调网关接口的超时(毫秒) |
⚠️ **网关管理台必须把「服务端通知地址」配成** `https://<本站域名>/api/wechat-gateway/notify`。
### 接口
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| POST | `/api/wechat-gateway/notify` | **签名** | 网关回调(`X-Gateway-*` / body 里的 `sign`);验签失败 401,会话过期 200 + `{ignored:'session_expired'}` |
| POST | `/api/web/auth/wechat-gateway/qrcode` | 公开 | 申请登录二维码 → `{ state, pageUrl, qrUrl, expiresIn }`;没配网关 503 |
| GET | `/api/web/auth/wechat-gateway/login?state=&wait=` | 公开 | 长轮询 → `{ status, token?, user?, message? }`(`pending` / `confirmed` / `failed` / `expired`) |
| GET | `/api/wechat-gateway/qrcode.svg?state=` | 公开 | 会话里那张二维码的 **SVG**(本地画,零外链) |
| GET | `/api/wechat-gateway/qrcode.gif?state=` | 公开 | 同一张二维码的 **GIF**(桌面端 WPF 不能渲染 SVG) |
| POST | `/api/web/me/wechat/qrcode` | user JWT | 申请「绑定微信」二维码(`scene=bind`)→ 同上结构 |
| GET | `/api/web/me/wechat/status?state=&wait=` | user JWT | 长轮询绑定结果 → `{ status, binding? , message? }` |
| GET | `/api/web/me/wechat/bindings` | user JWT | `{ list, enabled }`(`enabled=false` = 没配网关) |
| DELETE | `/api/web/me/wechat/bindings/:id` | user JWT | 解绑(只能删自己的;找不到 404) |
| GET | `/api/internal/wechat-bindings?openid=&userId=` | 内部令牌 | 运维查绑定(**含已解绑的**),带账号状态(禁用/已删除) |
| DELETE | `/api/internal/wechat-bindings/:id` | 内部令牌 | **强制解绑**任意绑定(微信绑在前员工账号上时兜底) |
| POST | `/api/web/workstations/:id/login-qr` | + 主体管理员 | 二维码(`scene=login`,`purpose=workstation`)→ 见「工作台成员登录」 |
| GET | `/api/web/workstations/:id/login-qr/status?state=&wait=` | + 主体管理员 | 长轮询扫码登入结果 |
| POST | `/api/web/subjects/:id/members/:memberId/bind-qr` | + 主体管理员 | 二维码(`scene=bind`,`purpose=member`)→ 见「成员扫码绑定」 |
| GET | `/api/web/subjects/:id/members/:memberId/bind-qr/status?state=&wait=` | + 主体管理员 | 长轮询成员绑定结果 |
### 实现要点
- 会话存 Redis(`packs:wxgw:sess:<state>`,`state` 是我们自己的 32 位 hex,原样传给网关):
`{ status, purpose, scene, pageUrl, tempCode, payload }`;没有 Redis 时退化为进程内 Map(**只适合本地/单测**,
多实例部署必须用 Redis,否则回调与轮询可能落在不同实例)。
- 长轮询用 Redis 发布订阅(`packs:wxgw:chan:<state>`)唤醒:先 `SUBSCRIBE` 再查状态,避免「刚查完就被确认」漏掉;
客户端断开(`res` 的 `close`)会立刻结束等待,不白占连接。
- 验签:`HMAC-SHA256(key = sha256hex(appSecret), msg = appKey.userId.bindCode.timestamp.nonce)`,
与 `crypto.timingSafeEqual` 比较;`appKey` 必须是本应用的,`timestamp` 与当前时间差 > `WX_GATEWAY_NOTIFY_SKEW` 直接拒绝。
- 落地:
- `purpose=login` → `openid` 查 `wechat_gateway_bindings` → 会话里只放 `userId`,**令牌等轮询时再签**;
- `purpose=bind` → 写/更新绑定关系(一个 openid 只能绑一个账号,一个账号只绑一个微信);
- `purpose=workstation` → `workstationLogin.loginByUser()` 落 `workstation_login_records`(失败原因写回会话);
- `purpose=member` → `subject.bindMemberWithWechat()`:微信已有平台账号就直接继承(自动建的临时账号删除),
没有就自动给这名成员建号并把微信绑成它的登录方式(见「成员扫码绑定」)。
- 未绑定微信时 `failed` 的文案是「请先用账号密码登录,在『个人中心 → 微信绑定』绑好后重新扫码」。
### 「这个微信已经绑了别的账号」怎么处理
绑定时按「原绑定账号是否还能用」分三种情况(`handleBind` / `upsertBinding`):
| 情况 | 处理 |
|---|---|
| 原账号**正常**(`users.status = 1`) | 拒绝,会话里给 `failed`:「这个微信已经绑定了其他账号(<昵称/用户名>):请用那个账号登录后在『个人中心 → 微信绑定』解绑,或联系管理员处理」。**不会**静默改绑——微信绑定就是登录凭证,不能让拿到微信的人抢走别人的账号 |
| 原账号**已禁用或已删除** | 绑定已经"用不了",直接把微信**改绑**到当前账号(复用同一条 `wechat_gateway_bindings` 记录),日志 `[wx-gateway] 微信 … 原绑定账号 … 不可用,改绑到 userId=…` |
| 本人拿不到原账号(前员工 / 手机换人) | 运维用 `GET /api/internal/wechat-bindings?openid=` 查到这条绑定,再 `DELETE /api/internal/wechat-bindings/:id` **强制解绑**;之后该微信可以重新绑给别人(解绑是软删,下次绑定会 `restore` 复用这条记录) |
> 成员扫码绑定(`purpose=member`)遇到「微信已绑账号」时**不改绑**:微信是谁的就绑到谁身上(继承那个账号);
> 只有那个账号被禁用时才 `failed` 提示联系管理员,管理员可以先「强制解绑」再让成员重扫。
- 单测不走真网关:`mock(app, 'httpclient', ...)` 假装临时码接口,再用 `service.wxGateway.signOf(body)` 造合法签名
直接打 `/api/wechat-gateway/notify`(见 `test/app/controller/wx-gateway.test.js`)。