packServer/backend/README.md
liufumingren 7b11f7052d feat(subject): 主体到期暂停设备上报,新增续期订单与支付回调
- 主体状态缓存(Redis 优先、进程内兜底):设备心跳与上报判断不再查库,续期/停用后主动失效
- 上报写接口按缓存校验期限:过期 403 subject_expired、停用 subject_disabled、主体缺失 subject_missing
- 心跳与 /api/scanner/me 返回 subject 状态,桌面端据此暂停推送并在续期后自动补传积压
- 新增续期订单(subject_orders)与接口,支付回调 POST /api/pay/notify 幂等、支持 HMAC 签名,
  另提供内部令牌模拟支付用于联调
- 顺带提交工作区中已完成的「登录协议」后端改动(agreement):与本次改动共用 router.js / config.default.js

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-10-20 18:55:57 +08:00

909 lines
75 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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 首页统计(按当前用户)
│ │ │ ├── device.js # /api/web/devices* 我的设备(列表/详情/通道/解绑/删除)
│ │ │ ├── record.js # /api/web/records 我的扫码记录(按自己设备过滤)
│ │ │ └── test.js # /api/web/test/{device-login,scan} 前端测试页的模拟接口
│ │ ├── internal/ # 运维/内部(❗需内部令牌,挂在 middleware.internalAuth() 后面)
│ │ │ ├── user.js # /api/users* 用户 CRUD(含缓存)
│ │ │ ├── wechat.js # /api/wechat/:appid/:openid、bind、tokens、解绑、用户的授权列表
│ │ │ ├── config.js # /api/configs* 系统配置读写
│ │ │ └── device.js # /api/scanners*、/api/scanner/{bind,unbind} 设备列表/详情/解绑/删除
│ │ ├── auth/ # 公开的登录接口(发码 / 查码 / 微信回调,无需令牌)
│ │ │ └── wechat.js # /api/wechat/{login,status,qrcode.svg,callback}
│ │ ├── 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)
│ │ ├── 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
│ │ ├── wechat_oauth.js # wechat_oauth
│ │ ├── sys_config.js # sys_config
│ │ ├── scanner.js # scanners
│ │ ├── scan_channel.js # scan_channels
│ │ └── scan_record.js # scan_records(去重)
│ ├── service
│ │ ├── auth.js # 登录校验(bcrypt 密码比对)+ 自助注册
│ │ ├── mail.js # 发邮件(邮箱验证码 / 重置密码链接;开发模式只写日志)
│ │ ├── verify_code.js # 邮箱验证码:生成/发送/校验/消费(Redis 存储 + 重发节流)
│ │ ├── wechat_login.js # 微信扫码登录:二维码本地生成 / 扫码状态机 / code 换 openid
│ │ ├── 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)
│ │ └── wechat.js # 微信授权数据访问
│ └── 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 # 脚本共用的连接信息解析
│ ├── init-db.js # 执行 sql 下的 SQL 文件(npm run db:init [file])
│ └── set-password.js # 创建用户/重置密码(npm run user:pass -- 账号 密码)
├── sql
│ ├── schema.sql # 建表脚本(幂等)
│ └── migrations/ # 一次性数据迁移脚本
├── 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. 建表(库 packservice 需已存在,账号 packservice 仅有该库权限)
npm run db:init
# 如果是旧版本库,按顺序补跑迁移:
# 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
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 账号密码(放 `config/config.local.js` 或环境变量) |
| `SMTP_FROM` | `云仓视频溯源系统 <no-reply@...>` | 发件人(默认取 `SITE_NAME` 作显示名) |
| `EMAIL_CODE_TTL` | `600` | 邮箱验证码有效期(秒) |
| `EMAIL_CODE_RESEND` | `60` | 同一邮箱重发验证码的间隔(秒) |
| `EMAIL_CODE_ATTEMPTS` | `5` | 同一个验证码最多校验几次(超过则作废) |
| `EMAIL_RESET_TTL` | `1800` | 重置密码链接有效期(秒,默认 30 分钟) |
| `SITE_URL` | 空 | 邮件里重置链接的站点地址(如 `https://packs.example.com`);不配则用当前请求的 host |
| `WECHAT_APPID` | 空 | 微信开放平台网站应用 appid;**不配时登录页二维码退化为本地演示码**(不会假装能用) |
| `WECHAT_SECRET` | 空 | 同上对应的 appsecret |
| `WECHAT_REDIRECT_URI` | 空 | 扫码回调地址(需与开放平台后台配置一致);不配则按当前请求 origin 拼 `/login/wechat/callback` |
| `WECHAT_API_BASE` | `https://api.weixin.qq.com` | 微信接口域名(自建网关/联调时可改) |
| `WECHAT_QR_CELL` / `WECHAT_QR_MARGIN` | `6` / `4` | 二维码 SVG 的单元格像素 / 静默区格数(⚠️ 库的 margin 参数单位是像素,代码里已按格×单元格换算;<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 | 时间戳与软删除 |
### wechat_oauth 微信授权表
一条记录 = 某用户在某 `appid` 下的一次授权,**一个用户可绑定多个微信**。
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint unsigned | 主键 |
| user_id | bigint unsigned | 关联 `users.id` |
| appid | varchar(64) | 微信 appid,与 openid 组成唯一键 |
| openid | varchar(64) | 用户在该 appid 下的 openid |
| unionid | varchar(64) | 开放平台 unionid |
| nickname / avatar | varchar | 授权时的微信资料 |
| session_key | varchar(128) | 小程序 session_key |
| access_token / refresh_token | varchar(512) | 网页授权令牌 |
| scope | varchar(64) | 授权 scope |
| token_expires_at | datetime | access_token 过期时间 |
| last_auth_at | datetime | 最近授权时间 |
| 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/wechat/{login,status,qrcode.svg}` |
| 手机确认登录 | `/wechat?spm=…` | `/api/wechat/confirm` |
| 忘记 / 重置密码 | `/forgot`、`/reset` | `/api/web/auth/{forgot,reset}` |
| 首页统计 | `/` | `/api/web/stats` |
| 设备管理 | `/devices` | `/api/web/devices*` |
| 扫码记录 | `/records` | `/api/web/records` |
| 个人中心 | `/profile` | `/api/web/me*` |
| 测试页 | `/test` | `/api/web/test/*`、`/api/wechat/{status,confirm}` |
**后端怎么把页面交出去**(`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 提示页,而不是白屏;
- **生产**:托管 `FRONTEND_DIST`(默认 `../frontend/dist`);找不到文件且请求要 HTML 时回退 `index.html`
(SPA 深链 `/devices` 刷新不会 404);dist 不存在时回 503 并提示先 `npm run build`;
- **单测**(`env=unittest`):整个中间件跳过(不连前端、也不要求 dist 存在)。
## 接口
### 按调用方分模块(目录 / 鉴权 / 路径 一一对应)
| 调用方 | 控制器目录 | 鉴权 | 典型接口 |
| --- | --- | --- | --- |
| **用户端(前端 SPA)** | `app/controller/web/` | `middleware.apiAuth()`(**user JWT**,typ=user);登录/注册/找回免令牌 | `/api/web/{auth/*,me*,stats,devices*,records,test/*}` |
| **运维 / 内部**(运维脚本、后台系统) | `app/controller/internal/` | `middleware.internalAuth()`(`X-Internal-Token` 或白名单账号的 user JWT) | `/api/users*`、`/api/configs*`、`/api/scanners*`、`/api/scanner/{bind,unbind}`、`/api/wechat/{bind,:id/tokens}` |
| **用户态**(小程序 / 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/{login,status,qrcode.svg,callback}`(`/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` / `wechat_login` / `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/users/:id/wechats` | 某用户的全部微信授权 |
| GET | `/api/wechat/:appid/:openid` | 按 appid + openid 反查授权与关联用户 |
| POST | `/api/wechat/bind` | 绑定/更新授权,body: `{"userId":1,"appid":"wx123","openid":"o_abc"}` |
| PUT | `/api/wechat/:id/tokens` | 更新 session_key / 令牌,body: `{"sessionKey":"sk","expiresIn":7200}` |
| DELETE | `/api/wechat/: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` | **设备「扫码登录 + 注册」**(参考 `/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**:返回当前设备信息(自检连通性) |
| 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: []` |
| 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**:当前中控上报的扫码记录 |
扫码上报的两个接口都**不会因为重复而报错**(幂等):完全重复的条数计入 `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, WechatOauth, 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 withWechats = await User.findOne({ where: { id: 1 }, include: [{ model: WechatOauth, as: 'wechats' }] });
// 原生 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'); // 软删除 + 清缓存
// ===== 微信授权 =====
await this.ctx.service.wechat.bind({ userId: 1, appid: 'wx123', openid: 'o_abc', nickname: '微信昵称' });
const oauth = await this.ctx.service.wechat.findByOpenid('wx123', 'o_abc'); // 带关联用户
const user = await this.ctx.service.user.findByOpenid('wx123', 'o_abc'); // 直接拿用户
// ===== 扫描器长期 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_oauth` 用 `(appid, 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` 校验通过才能建号。
- 验证码存 Redis(`packs:verify:register:<email>`,TTL `EMAIL_CODE_TTL`,默认 10 分钟);重发节流(`SET NX`,默认 60 秒);错试超过 `EMAIL_CODE_ATTEMPTS`(默认 5 次)作废;**注册成功才消费验证码**(用户名/邮箱冲突时可改完重提,不用重新收码);
- 发信走 `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 盖成「服务器内部错误」,用户看不懂);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 秒容差**:改密当秒新签发的令牌仍然可用,避免误杀);
- **扫码登录**(`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):
1. 电脑端调 `GET /api/wechat/login`(不带参数)拿 `code` + `qrUrl`,前端登录页把它画成 `<img src="/api/wechat/qrcode.svg?code=…">` → 串码登记为 `pending`;
2. 手机扫码打开前端路由 `/wechat?spm=1.0.<code>.1`:
- **配了微信** → 前端页重定向到公众号网页授权(`oauth2/authorize`,`scope=snsapi_base` 静默拿 openid,`state=<code>`)→ 微信回调后端 `GET /api/wechat/callback` → `code` 换 `openid`(`WECHAT_API_BASE`)→ 按 `(appid, openid)` 查 `wechat_oauth` 找账号 → 把 Redis 里串码的值改成**用户 id** → 再 302 回前端 `/wechat?ok=1`;
- **没配微信**(本机默认)→ 前端页给「确认登录」按钮:要求手机端**已登录**(本地有占位令牌),点确认调 `POST /api/wechat/confirm`(带 `Authorization: Bearer <user JWT>`)把串码的值改成用户 id;
3. 电脑端用 `GET /api/wechat/login?code=…&wait=60` 长轮询取结果 → `{ status:'confirmed', token, user }` 存本地即登录完成(前端登录页会自动跳首页);**取走即删(一次性)**。
- **JWT 怎么用**:`config.jwt.userExpiresIn`(env `USER_JWT_EXPIRES`,默认 7 天);前端把令牌存 localStorage,调接口时放 `Authorization: Bearer <token>`(`app/middleware/api_auth.js` 只认这个头,不读 cookie/session)。
- **长轮询(前端接口)**:`GET /api/wechat/login?code=<code>&wait=60` —— 服务端把请求挂起最多 `WECHAT_POLL_WAIT` 秒(默认 60):
- 有人扫码确认 → **立即**返回 `{ status:'confirmed', token, … }`(靠 Redis 发布订阅 `packs:wechat:login:<code>` 唤醒,不是忙轮询;`confirm()` / 微信回调写完状态后 `PUBLISH` 一次);
- 到时间还没动静 / 串码已失效 → 返回 `{ status:'refreshed', code:<新码>, spm, qrUrl, expiresIn, waited }` —— **前端直接换二维码继续轮询**,不用自己判断过期;
- `wait=0` 或不传 → 不挂起,只回 `{ status:'pending' }`(短轮询模式);
- **客户端断开就立即结束挂起**(2026-10-17 修):服务端会监听连接关闭(`res.on('close')`),浏览器导航离开(例如登录页点「返回账号密码登录」)、关页签或前端 `abort()` 时立刻停止等待并释放订阅连接,**不会白等满 `wait` 秒,也不会把串码换掉**(登录页的脚本在 `pagehide` 时会 `abort()` 当前请求);日志里能看到 `[wechat] 客户端已断开,停止等待串码 XXXXXX`;
- ⚠️ **前端要自己设超时**(服务端上限 60s,客户端建议 70s):`AbortController` / `AbortSignal.timeout(70000)`,超时就重发一次请求(或退化成短轮询);重启/热更也会断掉长连接,断了重试即可。**反代/网关要把读超时调到 > 60s**(nginx `proxy_read_timeout 90s`),否则会被代理提前切断;
```js
let code = null;
async function loop() {
const url = code ? `/api/wechat/login?code=${code}&wait=60` : '/api/wechat/login';
const ac = new AbortController();
const timer = setTimeout(() => ac.abort(), 70000); // 前端超时 > 服务端 wait
let r;
try {
r = await (await fetch(url, { signal: ac.signal })).json();
} catch (err) { // 超时/断网 → 重试
return setTimeout(loop, 800);
} finally { clearTimeout(timer); }
const d = r.data;
if (d.status === 'confirmed') return localStorage.setItem('token', d.token);
if (d.status === 'refreshed') { code = d.code; img.src = d.qrUrl; } // 换新码
if (!code) { code = d.code; img.src = d.qrUrl; } // 首次拿码
loop();
}
```
- **联调/自测(三个终端就能跑通整个扫码登录)**:
```bash
# ① 电脑端:拿登录码
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:7300/api/wechat/login?code=XBUBHP&wait=60'
# ③ 已登录的客户端(或用手机打开 /wechat?spm=1.0.XBUBHP.1):用登录码触发登录
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>",...}}
```
`POST /api/wechat/confirm` 的 **鉴权完全走 header**(`app/middleware/api_auth.js`:`Authorization: Bearer <用户JWT>`,也认 `X-Access-Token`)——**不读 session/cookie**,所以小程序 / App / SPA 直接帯令牌就行,也不写 session;它返回 401(缺令牌)/ 403(账号被禁用)/ 422(码格式不对)/ 410(码失效、已过期或已用过);`/api/*` 不过 CSRF,所以 curl 不用带 token。
- **不自动建号**:扫码只对已绑定微信的账号生效(绑定关系在 `wechat_oauth`,可用 `POST /api/wechat/bind` 写入),未绑定会提示先用账号密码登录;账号被禁用(`status != 1`)拒绝登录;
- **小程序接入**(小程序里「扫码 → 直接登录电脑端」):接口都是 JSON,**鉴权只看 header 里的 `Authorization: Bearer <用户 JWT>`,不认 cookie/session**(`app/middleware/api_auth.js`);用户 JWT 用 `USER_JWT_EXPIRES`(默认 7d)控制有效期,由登录接口/扫码登录接口下发。
```js
// 小程序侧:扫登录页上的二维码(内容 http://<域名>/wechat?spm=1.0.<码>.1)
wx.scanCode({
success (scan) {
// ① 先问一下这个码还在不在(可选,但能给出更好的提示)
wx.request({
url: `https://<域名>/api/wechat/status?spm=${encodeURIComponent(scan.result)}`,
success (r) {
// r.data.data.status: pending(待扫)/ confirmed(已被确认)/ expired(没这个码)
}
});
// ② 确认登录:把扫到的整条地址丢进来就行(接口自己抽 6 位码)
wx.request({
url: 'https://<域名>/api/wechat/confirm',
method: 'POST',
header: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + userJwt },
data: { spm: scan.result }, // 也可以传 { code: 'AB12CD' }
success (r) {
if (r.statusCode === 200 && r.data.data.status === 'confirmed') {
wx.showToast({ title: '登录成功' }); // 电脑端那台浏览器已经进系统了
} else {
wx.showToast({ title: r.data.message, icon: 'none' }); // 401/422/410 的错误原因
}
}
});
}
});
```
返回:成功 `HTTP 200 { ok:true, data:{ status:'confirmed', code, spm, user:{ id, username, nickname } } }`;
失败 `HTTP 401 status=unauthorized`(没带/过期令牌)、`422 bad_format`(码格式不对)、`410 expired`(没这个码/已过期)、`410 used`(已被用过);
- **设备专用:扫码登录 + 注册(`GET /api/device/login`,`app/controller/device.js`)**:给「设备上不好敲账号密码、甚至**出厂什么都不用配**」的场景用——
**登录即注册**:设备插上电直接要一个登录码显示在**设备屏幕上**,用已经登录的手机(小程序/网页)扫一下确认,
服务端**这才**把设备注册到那个账号名下(归属 = 确认登录的人),并把**长期 JWT** 发给设备
(默认 365 天,见 `config.jwt.deviceExpiresIn` / env `DEVICE_JWT_EXPIRES`;
设备可用 `?expiresIn=30d`(或秒数)申请**更短**的,超上限 422):
- **不需要凭据、也不需要预先注册**(与 `GET /api/wechat/login` 一样是公开接口);
- **不带 `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`**:**长轮询**(与 `/api/wechat/login` 完全同一套实现与上限 `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(已是完整网址,设备无需知道域名)
}
```
- 未配 `WECHAT_APPID`/`WECHAT_SECRET`(本机默认):二维码照旧本地生成(内容是本站 `/wechat?spm=…`),扫码面板**不显示任何说明文字**(只留二维码 + 「返回账号密码登录」),扫码后走「手机确认登录」降级路径;
- 新增/重置登录账号:`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`(不会把别人的设备扫走),无主记录(老接口注册出来的)由本次确认者认领;
- **没有 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/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/web/subjects/:id/orders` | 订单列表(成员可见,`{ total, page, pageSize, list }`) |
| POST | `/api/web/subjects/:id/orders` | 下单 `{ days, amount?, remark? }`(仅管理员)→ `{ orderNo, days, amount, status:0待支付, ... }`;`amount` 不传时按 `PAY_AMOUNT_PER_DAY` 自动算,都没配则金额为空(不校验) |
| POST | `/api/pay/notify` | **公开的渠道回调** `{ orderNo, transactionId?, amount?, channel?, paidAt? }` → `{ duplicated, order }`;订单不存在 404、金额不符 422、签名错 400 |
| POST | `/api/internal/subject-orders/:orderNo/pay` | **内部令牌**:模拟支付成功(不需要签名),方便联调/补单 |
签名:配置了 `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 '{"days":30,"amount":99}'
# 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>"
```
二维码:`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` + `subjectActive`,
不需要主体 header;所属主体过期/停用 → 403 `subject_expired` / `subject_disabled`)。
## 用户协议(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;
```
⚠️ 种子迁移里的协议正文是**占位示例**,正式上线前务必替换为法务确认后的文本。