- 主体状态缓存(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>
909 lines
75 KiB
Markdown
909 lines
75 KiB
Markdown
# 云仓视频溯源系统(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;
|
||
```
|
||
|
||
⚠️ 种子迁移里的协议正文是**占位示例**,正式上线前务必替换为法务确认后的文本。
|