packServer/backend/README.md
liufumingren dd9482a3fe 注册 / 找回密码:先判邮箱占用 + 每邮箱每天最多 10 封
后端
- 新增 service/mail_quota.js:每个邮箱每天最多 config.email.dailyLimit(默认 10,EMAIL_DAILY_LIMIT)封,
  注册验证码与找回密码**共用**额度;按北京时间切日,key TTL 到次日 0 点;
  发信失败 / 被 60 秒节流拦下会还回额度;超限返回 429 daily_limit「… 请明天再试」
- service.user.findByEmail() / emailExists():LOWER(email) 查询(大小写不敏感)+ paranoid:false
  (软删除账号仍占用邮箱),单测环境无 sequelize 时退化为等值查询
- register/code:先判邮箱已占用 → 409 email_taken(含「忘记密码可找回」提示),一封邮件都不发;
  发送失败/超限统一返回 429 + status(daily_limit / send_failed)
- register:提交时再判一次邮箱占用(防发码后被抢注)
- forgot:改用 findByEmail(大小写/软删除一致),日额度与注册共用,超限 429
- 单测:新增「邮箱已使用不发信」「每日 10 封上限(注册/找回)」4 个用例;fake-redis 补 decr

前端
- 登录页获取验证码:先做邮箱格式校验,并展示后端 409/429 的具体文案
- 忘记密码页:邮箱格式校验 + 小写归一,429 文案直接显示

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-10-21 18:03:31 +08:00

1185 lines
95 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 云仓视频溯源系统(pack-service)
> 中文名(前端页面/邮件里显示的那个)在 **`config.siteName`** 里,默认「云仓视频溯源系统」,可用环境变量 `SITE_NAME` 覆盖 ——
> 要改名只改这一处(邮件用 `app.config.siteName`)。
> `pack-service` 只作为**技术标识**保留:npm 包名、JWT `issuer`、日志目录、`egg-scripts --title`。
基于 **Egg.js 3** 的**纯接口服务**(⚠️ **不再渲染任何页面**:模板引擎已移除,`/` 这一侧由
`app/middleware/frontend.js` 反代给前端 dev server 或托管 `../frontend/dist`),
数据库 **MySQL(Sequelize ORM)**,缓存与登录码用 **Redis**。
> 页面在隔壁 **`../frontend/`**(Vite + Vue3 + TS SPA);两个服务的端口与启动方式见仓库根目录的 `README.md`。
> 业务场景:**设备(扫描枪 / 中控)扫码登录** —— 设备屏幕显示二维码,已登录的手机确认一下;
> 服务端在**确认那一刻**才把设备注册到那个账号名下,并下发**长期 JWT**(默认 1 年,库里存 `jti` 可随时撤销),
> 之后设备调本服务的接口都靠这枚令牌鉴权。**只有这一条身份链路**(没有 sn + secret 那套)。
## 环境要求
- Node.js >= 18(Egg 3 要求 >= 14.20,建议用 18/20 LTS)
- MySQL 5.7+ / 8.x
- Redis 5+
## 目录结构
```
packService/backend
├── app
│ ├── controller # **按「谁在调」分模块**(Egg 支持多级目录 → controller.internal.user)
│ │ ├── home.js # GET /api/info 服务信息(公共)
│ │ ├── health.js # GET /health 健康检查(公共)
│ │ ├── web/ # **用户端(前端 SPA)**:user JWT(typ=user),只能动自己的数据
│ │ │ ├── auth.js # /api/web/auth/{login,register,register/code,forgot,reset}
│ │ │ ├── profile.js # /api/web/me [/password] 我的资料 / 改密码
│ │ │ ├── stats.js # /api/web/stats 首页统计(按当前用户)
│ │ │ ├── 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 # 脚本共用的连接信息解析
│ ├── db-deploy.js # **部署/升级一次执行**:建库 + 基线表 + 全部未执行迁移(npm run db:deploy [--check])
│ ├── init-db.js # 执行单个 SQL 文件(npm run db:init [file]),给历史补丁用
│ ├── backfill-snapshot.js # 一次性回填:老扫码记录补工作台快照
│ ├── dedupe-scan-records.js # 一次性去重:24 小时内同一运单只留一条
│ └── set-password.js # 创建用户/重置密码(npm run user:pass -- 账号 密码)
├── database
│ ├── config.cjs # sequelize-cli 配置(与运行时同一份连接信息)
│ └── migrations/ # Sequelize 迁移(按文件名顺序,SequelizeMeta 记账,只跑没跑过的)
├── sql
│ ├── schema.sql # 基线表(幂等,db:deploy 第 1 步执行)
│ └── migrations/ # 历史一次性 SQL 补丁(仅老库需要,保留不删)
├── test
│ ├── utils/fake-redis.js # 单测用的内存版 Redis
│ └── utils/internal.js # 内部接口鉴权 header(X-Internal-Token)
└── package.json
```
## 快速开始
```bash
# 1. 安装依赖
npm install
# 2. 填写本机连接信息:编辑 config/config.local.js(该文件已被 .gitignore 忽略)
# - mysql.client.password = MySQL(127.0.0.1:3307,账号 packservice) 的密码
# - redis.client.password / db = Redis 的密码(无密码写 null)与库序号(本机用 1)
# 也可以改用环境变量 MYSQL_PASSWORD / REDIS_PASSWORD / REDIS_DB
# 3. 建表 / 升级(**部署时只需这一条**:建库(有权限时) + 基线表 + 所有未执行的迁移,可反复执行)
npm run db:deploy
# npm run db:deploy -- --check # 只检查还剩哪些迁移没执行(CI / 上线前确认,不改库)
# 老版本的库照常补跑遗留 SQL 补丁(这些脚本都保留在 sql/migrations,新库不需要):
# npm run db:init sql/migrations/20261016_rebuild_users.sql # users 表结构重建
# npm run db:init sql/migrations/20261016_add_user_password.sql # 增加 password_hash
# npm run db:init sql/migrations/20261016_devices_to_scanners.sql # 删掉旧的 devices 表(改用 scanners)
# npm run db:init sql/migrations/20261016_add_user_email.sql # users 增加 email(可当登录账号)
# npm run db:init sql/migrations/20261017_add_user_password_changed_at.sql # users 增加 password_changed_at(改密后旧 JWT 失效)
# 4. 建一个登录账号(不存在会直接创建,密码 bcrypt 入库)
npm run user:pass -- admin 123456 管理员
# 5. 启动(默认 http://127.0.0.1:7300)
# 登录页:http://127.0.0.1:7300/login(用上面的账号登录)
npm run dev
# 想临时换端口:egg-bin dev --port 7400,或 $env:PORT=7400; npm run dev(默认端口在 config/config.default.js)
# 生产模式
npm start # egg-scripts 后台启动
npm stop
```
验证:
```bash
curl -I http://127.0.0.1:7300/login # 200:反代到前端 dev server(前端没起则 502 提示页)
curl http://127.0.0.1:7300/health
curl http://127.0.0.1:7300/api/users # 401:内部接口要令牌(X-Internal-Token 或管理员 user JWT)
curl -H 'X-Internal-Token: <INTERNAL_TOKEN>' http://127.0.0.1:7300/api/users # 200
```
> 后端只管接口:页面在 `../frontend/`(`npm run dev` 起在 7301)。
> 联调推荐**只开后端地址** `http://127.0.0.1:7300`(dev 环境自动把页面请求反代给前端);也可以直接开前端 7301(Vite 把 `/api` 反代到 7300)。
## 部署 / 升级(库结构)
**一次执行**,幂等,可反复跑:
```bash
cd backend
npm install
npm run db:deploy # ① 建库(有权限时) ② 基线表 sql/schema.sql ③ 全部未执行的 database/migrations
npm run db:deploy -- --check # 只检查(列出未执行的迁移;有 pending 时退出码 1),适合上线前/CI 卡一道
```
### 生产库迁移(本地执行,目标 = 生产库)
生产 MySQL 账号是 `packservice@localhost`,只能从服务器本机登录,所以脚本会先建 **SSH 隧道**再跑同一套迁移:
```bash
npm run db:check:prod # 只检查生产库还有哪些迁移没执行(不改库)
npm run db:deploy:prod # 基线表 + 全部未执行迁移(幂等,可反复跑)
```
- 连接信息来自本机 `config/env.prod.sh`(`MYSQL_*`),SSH 信息来自 `config/deploy.config.local.cjs`;
- 隧道:`127.0.0.1:<随机端口> → <服务器>:127.0.0.1:3306`,执行完自动关闭;
- 显式设置的 `MYSQL_*` 环境变量优先于 `config.local.js`(不会被本机开发库密码覆盖)。
规则(**所有迁移脚本都保留在仓库里,不删不改**):
| 位置 | 作用 | 什么时候跑 |
|---|---|---|
| `sql/schema.sql` | 基线 6 张表(`CREATE TABLE IF NOT EXISTS`,幂等) | 每次 `db:deploy` 第 2 步自动跑 |
| `database/migrations/*.js` | 全部结构变更 / 数据回填(`SequelizeMeta` 记账) | 每次 `db:deploy` 第 3 步自动跑,**只跑没跑过的** |
| `sql/migrations/*.sql` | 历史一次性补丁(重建 users、加列、删旧 devices 表) | **仅老库升级时手动补跑**,新库已包含最终结构,重复执行会 `Duplicate column` |
| `scripts/backfill-snapshot.js`、`scripts/dedupe-scan-records.js` | 一次性数据修复(需带参数,可 `--dry-run`) | 按需手动,不是部署必跑 |
执行顺序固定为「基线表 → 迁移(按文件名升序)」,所以新库和老库走同一条命令,结果一致;
连接信息与运行时同源(环境变量 > `config/config.prod.js`(`EGG_SERVER_ENV=prod`)> `config/config.local.js` > 默认值)。
> 生产库如果由 DBA 预建、且应用账号没有建库权限,`db:deploy` 会打印一行「跳过建库」后继续,不影响后续迁移。
## 发布到服务器(npm run deploy)
参考 `D:\wms` 的双实例蓝绿发布:`v1` / `v2` 两个目录轮流发布,新实例健康检查(`/health`)通过后才切 Nginx upstream,再停旧实例;失败会回滚 `current.md` 并保留旧实例继续服务。
### 一次性准备
1. 本机:Node 18+、git、tar(Win10/11 自带 bsdtar)、OpenSSH Client(`ssh` / `scp`)。
2. 填写发布配置 `config/deploy.config.local.cjs`(该文件已被 `.gitignore` 忽略;若缺失可从模板复制):
```powershell
cd backend
# 已存在则直接编辑;缺失时:
Copy-Item config/deploy.config.example.cjs config/deploy.config.local.cjs
```
3. 服务器目录结构(首次发布时脚本会自动建 `v1` / `v2` / `.deploy` / `shared-config`):
```
/www/wwwroot/packService/
├── current.md # 内容只能是 v1 或 v2
├── nginx-upstream.conf # 只有一行:proxy_pass http://127.0.0.1:7301;(API 端口)
├── front.conf # nginx 前端静态 + /api、/health 反代 + /download 静态(自动维护)
├── frontend/ # 前端构建产物(nginx 直接托管)
├── frontend.prev/ # 上一版前端(回退用)
├── download/ # 安装包分发(nginx 直接托管)
│ ├── version.json # 桌面端版本信息(不缓存,客户端写死这个地址)
│ ├── desktop/ # 桌面端 MSI(长缓存)
│ └── android_client/ # Android APK + version.json
├── shared-config/ # 服务端私有配置(不随发布包走)
│ └── env.prod.sh # 启动前 source 的环境变量
├── v1/ v2/ # 两个后端发布目录
└── .deploy/ # incoming / backups / state
```
站点 vhost 里只需要 include 一次前端/反代配置:
```nginx
server {
server_name pack.example.com;
# 前端静态 + /api、/health 反代 + /download 静态,全部由 front.conf 维护
include /www/wwwroot/packService/front.conf;
}
```
> `front.conf` 由 `npm run deploy` 自动生成;`nginx-upstream.conf` 里的端口在发布健康检查通过后切换。
> 首次发布前先创建 `current.md`(内容 `v1` 或 `v2`);发布总是部署到**另一个**目录。
> 生产站点强制 HTTPS:vhost 里对 `$scheme != https` 直接 `return 301 https://$host$request_uri`,
> 且 `front.conf` 的每个带 `add_header` 的 location 都会重复声明 `Strict-Transport-Security`
> (nginx 的 `add_header` 一旦在 location 内出现,就不再继承 server 级配置)。
4. **服务端私有配置放在 `shared-config/`,不要改版本目录里的 `config.default.js`**
(后者是仓库代码,每次发布都会被覆盖)。`shared-config/env.prod.sh` 会在启动前被 `source`,
每次发布也会把 `shared-config/config.prod.js`、`config.local.js`(若存在)复制进目标版本目录。
```bash
# /www/wwwroot/packService/shared-config/env.prod.sh(chmod 600)
export JWT_SECRET='由 openssl rand -hex 32 生成的随机串'
export MYSQL_HOST='127.0.0.1'
export MYSQL_PORT='3306'
export MYSQL_PASSWORD='...'
export REDIS_HOST='127.0.0.1'
export REDIS_PASSWORD='...'
```
本项目已经准备好两份生产 env:
| 文件 | 用途 | 是否提交 |
|---|---|---|
| `backend/config/env.prod.sh` | 后端运行时变量(`JWT_SECRET`、`MYSQL_*`、`REDIS_*`、`SITE_URL`) | **否**(gitignore,本机权威副本,发布前自动上传到 `shared-config/`) |
| `frontend/.env.production` | 前端构建变量(`VITE_*`,不含密钥) | 是 |
> 改后端 env 后执行 `npm run deploy` 会自动上传并生效;改前端 env 后同样重新发布即可(`deploy` 会重新构建前端)。
> 生产环境 `config.default.js` 会强制要求 `JWT_SECRET` 环境变量,缺少会启动失败(健康检查不通过,自动保留旧实例)。
5. 可选:安装提交前检查钩子(禁止提交私有配置 / 运行期产物 / 版本记录):
```bash
npm run setup:hooks
```
### 常用命令
| 命令 | 说明 |
|---|---|
| `npm run deploy:precheck` | 检查本地工具、SSH、远端目录 / Node / Nginx / 当前实例健康状态 |
| `npm run deploy` | 构建前端 → 打包 → 上传 → 解压安装 → 启动新实例 → 健康检查 → 切 Nginx → 停旧实例 |
| `npm run deploy:verify` | 查看当前版本 / 备份并冒烟探测 `/`、`/health`、`/download/version.json` |
| `npm run deploy:version` | 查看远端活跃版本与最近一次发布记录(`--history=20` 看历史) |
| `npm run deploy:smoke` | 只做冒烟探测 |
| `npm run deploy:inspect` | 只看 `.deploy` 状态与备份清单 |
| `npm run rollback` | 蓝绿回退到上一个版本目录(不重新解压,秒级切换) |
| `npm run rollback -- --backup=backup-<时间戳>.tar.gz` | 用指定备份包恢复当前活跃目录 |
| `npm run deploy:cleanup-backups -- backup-xxx.tar.gz` | 删除指定备份包 |
发布说明:
- 前端构建产物单独上传到 `deployRoot/frontend`,由 **nginx 直接托管**(SPA 回退到 `index.html`);上一版保留在 `frontend.prev`,`npm run rollback` 会连前端一起切回。
nginx 前端/反代配置由发布脚本写入 `deployRoot/front.conf`;Egg 只提供 `/api`、`/health`(`FRONTEND_ENABLE=false`)。
`buildFrontend: false` 时跳过前端构建与发布(适合前端完全独立部署)。
- 生产发布**不含「测试页」**:前端 `TestView` 只在 dev 构建里注册路由与菜单(生产包不会产出该 chunk),
后端 `/api/web/test/*` 只在 `env != prod` 时注册,生产请求直接 404。
- 发布包只包含 git 跟踪的源码;版本目录里的 `config/config.prod.js`、`config/config.local.js`、`app/public/download`、`app/public/version` 在清理前暂存、解压后放回,随后再用 `shared-config/` 里的同名配置覆盖,保证所有版本配置一致。
- 启动前会 `source shared-config/env.prod.sh`(`JWT_SECRET`、`MYSQL_*`、`REDIS_*` 等);**不要编辑版本目录里的 `config.default.js`**,它属于仓库代码,会被每次发布覆盖。
- 每次发布会在 `.deploy/backups/` 留一份旧代码备份(默认保留最近 5 个;`node_modules` / `logs` / `run` / `temp`、安装包目录和服务端私有配置不进备份,它们本身会被保留)。
- 需要发布时顺带升级库结构,把 `config/deploy.config.local.cjs` 里的 `remoteDbDeploy` 改成 `true`(远端会先 source `shared-config/env.prod.sh`,再以 `EGG_SERVER_ENV=prod` 执行 `npm run db:deploy`;连接信息来自 `MYSQL_*` 环境变量或 `config.prod.js`)。
### 桌面端正式包(单独发布,不动后端)
改桌面端时只需要发安装包,**不用重新发布后端**:
```bash
cd backend
npm run desktop:build # 只构建(dry-run),产物在 desktop/installer/out
npm run desktop:publish # 构建 + 上传 + 刷新 nginx
npm run desktop:publish -- --version=1.0.90 --notes="修复 xxx"
npm run desktop:publish -- --skip-nginx
```
- 版本默认取本地已有最高版本 + 1(补丁号),也可用 `--version=` 指定;
- 构建复用 `desktop/installer/build.ps1 -Environment Production`;
- 上传到 `deployRoot/download/desktop/`(MSI),`version.json` 传到 `deployRoot/download/`
(路径不能改:老客户端写死 `/download/version.json`;先传 MSI,再原子替换 `version.json`);
- nginx 的 `/download/` 静态托管该目录:`version.json` 不缓存,MSI 长缓存;
- `desktop/installer/package.config.json` 的 Production `serverBaseUrl` 必须是 `https://`,安装包内嵌的接口 / 下载地址会跟着变;
- **谷歌插件一起打进包**:`extension/` 发布到 `<安装目录>\extension`,菜单「工具 → 复制谷歌插件地址」给出该 Windows 路径;
- 不会重启 Egg、不会重新发布后端、不会跑数据库迁移;
- 前置:.NET 8 SDK、WiX 5.0.2(`dotnet tool install --global wix --version 5.0.2`)、`desktop/native/ffmpeg/ffmpeg.exe`。
下载地址:`<desktopBaseUrl>/download/desktop/YuncangTraceSetup-<版本>.msi`
更新信息:`<desktopBaseUrl>/download/version.json`
### Android 设备端正式包(单独发布,不动后端)
```bash
cd backend
npm run android:build # 只构建(dry-run),产物在 backend/android_client/out
npm run android:publish # 构建 + 上传 + 刷新 nginx
npm run android:publish -- --version=1.0.2 --notes="扫码上报更稳"
npm run android:publish -- --skip-nginx
```
- 构建复用 `backend/android_client/build.ps1 -Environment Production`(配置在 `backend/android_client/package.config.json`,和桌面端同一套路);
- 版本默认取已有 APK / version.json 的最高版本 +1 补丁号;`versionCode` 由 `x.y.z` 换算(`major*10000+minor*100+patch`);
- 上传到 `deployRoot/download/android_client/`:APK + `version.json`(nginx 对 `version.json` 单独关缓存);
- 签名读 `AndroidStation/keystore.properties` + `keystore/*.jks`(**不入库**,发布机必须自行备份);
- 前置:JDK 17(`JAVA_HOME`,或自动找 `%LOCALAPPDATA%\Programs\EclipseAdoptium\jdk-*` / Android Studio 的 `jbr`)、
Android SDK(`AndroidStation/local.properties` 的 `sdk.dir` 或 `ANDROID_HOME`)。
下载地址:`<androidBaseUrl>/download/android_client/YuncangScan-<版本>.apk`
更新信息:`<androidBaseUrl>/download/android_client/version.json`
## 单元测试
```bash
npm test # 无需本机启动 MySQL / Redis
npm run cov
```
### 本地端口
- 后端默认监听 **7300**:`config.cluster.listen.port = Number(PORT || 7300)`,临时换口用 `PORT=7400 npm run dev`(PowerShell:`$env:PORT=7400; npm run dev`);
- **二维码 / 邮件链接会自动跟随端口**:二维码内容是 `ctx.origin` 拼的 `http://<当前访问的 host:port>/wechat?spm=1.0.<码>.1`,在哪个端口打开登录页,扫出来就是那个地址,不用改配置;邮件里的重置链接同理(`config.email.siteUrl || ctx.origin`),只有显式配了 `SITE_URL` 才需要跟着改;
- 想同时跑两个实例(例如一边联调一边自测),给其中一个换端口 + 分日志:`$env:PORT=7400; $env:LOG_DIR='logs-test'; npm run dev`;
- 多个实例共用同一套 MySQL / Redis(都读 `config/config.local.js`);
- `npm test` 是单测(不监听固定端口),和上面的端口不冲突;
- `config/plugin.unittest.js` 在测试环境关闭 `sequelize` 与 `redis` 插件(这两个插件在启动时都会连库);
- 测试中用 `mock(app, 'model', fakeModel)` / `mock(app, 'redis', fakeRedis)` 注入假实现,因此 CI 上不依赖外部服务。
## 环境变量
不配置时使用默认值(`127.0.0.1:3307` / 账号 `packservice` / 库名 `packservice`,密码为空需在 `config/config.local.js` 填)。
| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `MYSQL_HOST` | `127.0.0.1` | MySQL 地址 |
| `MYSQL_PORT` | `3307` | MySQL 端口 |
| `MYSQL_USER` | `packservice` | 用户名(**大小写敏感**) |
| `MYSQL_PASSWORD` | 空 | 密码,本地放 `config/config.local.js` |
| `MYSQL_DATABASE` | `packservice` | 库名 |
| `MYSQL_POOL_SIZE` | `10` | Sequelize 连接池上限(`pool.max`) |
| `REDIS_HOST` | `127.0.0.1` | Redis 地址 |
| `REDIS_PORT` | `6379` | Redis 端口 |
| `REDIS_PASSWORD` | 空(`null`) | 密码,无密码时必须为空 |
| `REDIS_DB` | `0` | 库序号 |
| `CACHE_PREFIX` | `packs:` | 业务缓存 key 前缀 |
| `CACHE_TTL` | `300` | 默认缓存过期(秒) |
| `JWT_SECRET` | 开发默认值 | 扫描器 JWT 签名密钥,**生产未设置会启动失败** |
| `SITE_NAME` | `云仓视频溯源系统` | 站点/产品中文名(页面标题、侧边栏品牌、邮件主题与正文都用它) |
| `SCANNER_JWT_EXPIRES` | `365d` | 扫描器长期 JWT 默认有效期(`jsonwebtoken` 语法,如 `30d` / `720h`) |
| `DEVICE_JWT_EXPIRES` | 同 `SCANNER_JWT_EXPIRES` | `/api/device/login` 下发令牌的**默认时长 + 上限**;设备可用 `?expiresIn=30d` 申请更短的,不能更长 |
| `DEVICE_REFRESH_EXPIRES` | `730d` | 刷新令牌有效期(`POST /api/device/refresh` 轮换时顺延) |
| `REGISTER_ENABLED` | `true` | 是否允许登录页自助注册(`false`/`0`/`no`/`off` 关闭;**生产建议关掉**,用 `npm run user:pass` 建号) |
| `SMTP_HOST` | 空 | SMTP 主机;**不配就走开发模式**(验证码只写日志 + 注册页回显,不发真邮件) |
| `SMTP_PORT` | `465` | SMTP 端口 |
| `SMTP_SECURE` | `true` | 是否用 TLS(465 用 true,587 用 false) |
| `SMTP_USER` / `SMTP_PASSWORD` | 空 | SMTP 账号 / 密码(QQ 邮箱填「授权码」,不是登录密码;放 `shared-config/env.prod.sh` 或环境变量) |
| `SMTP_FROM` | `云仓视频溯源系统 <no-reply@...>` | 发件人(默认取 `SITE_NAME` 作显示名) |
| `EMAIL_CODE_TTL` | `600` | 邮箱验证码有效期(秒) |
| `EMAIL_CODE_RESEND` | `60` | 同一邮箱重发验证码的间隔(秒) |
| `EMAIL_CODE_ATTEMPTS` | `5` | 同一个验证码最多校验几次(超过则作废) |
| `EMAIL_DAILY_LIMIT` | `10` | **每个邮箱每天最多发几封邮件**(注册验证码 + 找回密码共用,超出提示「明天再试」) |
| `EMAIL_RESET_TTL` | `1800` | 重置密码链接有效期(秒,默认 30 分钟) |
| `SITE_URL` | 空 | 邮件里重置链接的站点地址(如 `https://packs.example.com`);不配则用当前请求的 host |
| `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}` |
> 「测试页」只在 `vite dev` / 本地开发构建里存在:生产构建不产出 `TestView` 的 chunk,
> 路由与左侧菜单也一并去掉;后端 `/api/web/test/*` 只在 `env != prod` 时注册(生产请求返回 404)。
**后端怎么把页面交出去**(`app/middleware/frontend.js`,只接管「非 `/api`、`/health`」的 GET/HEAD 请求):
- **开发**(`env=local`):**反代**到 `FRONTEND_DEV_SERVER`(默认 `http://127.0.0.1:7301`,即 `frontend/ && npm run dev`),
包含 HMR 的 WebSocket 升级 —— 所以联调只开 `http://127.0.0.1:7300` 一个地址就够(前端热更新照常生效);
前端没起来时会回一个 502 提示页,而不是白屏;
- **生产**:本仓库的发布脚手架默认由 **nginx 直接托管** `deployRoot/frontend`,Egg 侧用 `FRONTEND_ENABLE=false` 关闭页面托管(只出 `/api`、`/health`);安装包由 nginx 静态托管 `deployRoot/download`。
如果仍想让 Egg 托管(例如没有 nginx),设置 `FRONTEND_ENABLE=true` 并在启动时用 `FRONTEND_DIST` 指向构建产物;找不到文件且请求要 HTML 时回退 `index.html`(SPA 深链不会 404)。
- **单测**(`env=unittest`):整个中间件跳过(不连前端、也不要求 dist 存在)。
## 接口
### 按调用方分模块(目录 / 鉴权 / 路径 一一对应)
| 调用方 | 控制器目录 | 鉴权 | 典型接口 |
| --- | --- | --- | --- |
| **用户端(前端 SPA)** | `app/controller/web/` | `middleware.apiAuth()`(**user JWT**,typ=user);登录/注册/找回免令牌 | `/api/web/{auth/*,me*,stats,devices*,records,test/*}` |
| **运维 / 内部**(运维脚本、后台系统) | `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` 校验通过才能建号。
- **发码前先判邮箱是否已被占用**:`service.user.findByEmail()` 用 `LOWER(email) = ?` 查(**大小写不敏感**)+ `paranoid: false`(软删除账号仍占唯一键),命中就直接 409 `email_taken`「该邮箱已被使用…」,**一封邮件都不发**;提交注册时再判一次(防止发码后被别人抢先注册);
- 验证码存 Redis(`packs:verify:register:<email>`,TTL `EMAIL_CODE_TTL`,默认 10 分钟);重发节流(`SET NX`,默认 60 秒);错试超过 `EMAIL_CODE_ATTEMPTS`(默认 5 次)作废;**注册成功才消费验证码**(用户名/邮箱冲突时可改完重提,不用重新收码);
- **每日发信上限**:`packs:mailquota:<email>:<yyyy-MM-dd>`(`service/mail_quota.js`),**同一邮箱每天最多 `EMAIL_DAILY_LIMIT`(默认 10)封**,注册验证码与找回密码**共用**这个额度;超出返回 429 `daily_limit`「该邮箱今天已发送 10 封邮件,达到上限,请明天再试」;按北京时间(UTC+8)切日,key 的 TTL 到当天 24 点自动过期。发信失败 / 被 60 秒节流拦下会把额度还回去;
- 发信走 `app/service/mail.js`:**未配 `SMTP_HOST` 时是开发模式**(验证码写服务端日志 + 在接口返回里带 `code`,前端直接提示,仅本地/测试);配上 `SMTP_HOST/PORT/USER/PASSWORD/FROM` 后自动改用 nodemailer 真发信(依赖懒加载);
- 验证码逻辑不抛异常,统一返回 `{ ok, message }`,失败都是接口报错(Redis 不可用会提示“验证码服务暂不可用”而不是 500);
- **邮箱找回密码(发重置链接)**:前端「忘记密码?」页 → `POST /api/web/auth/forgot` 生成带令牌的链接并**发到邮箱** → 邮件里的链接打开前端 `/reset?token=...` 设置新密码 → `POST /api/web/auth/reset` 改哈希(**不自动登录**,要求用新密码再登一次)。
- **只存 Redis(缓存),不落库**:`users` 表没有 token/过期时间列,也没有 reset 表(实测确认);重启 Redis / 清 `packs:reset:*` 会让未用的链接立即失效;
- 三个 key(`app/service/password_reset.js`,前缀 `config.cache.prefix`):
| key | 值 | TTL(实测) |
| --- | --- | --- |
| `packs:reset:token:<sha256(令牌)>` | 用户 id | `EMAIL_RESET_TTL`,默认 **1800s(30 分钟)** |
| `packs:reset:user:<用户id>` | 该用户**当前最新**令牌的摘要 | 同上(用「旧链接立刻失效」) |
| `packs:reset:sent:<用户id>` | `1` | `EMAIL_CODE_RESEND`,默认 **60 秒**(重发节流) |
- **Redis 里只存令牌的 sha256 摘要,不存原文**(泄库也拿不到可用的链接;令牌本身是 `randomBytes(32)` 的 64 位 hex);
- **有效期是固定的 30 分钟**(不滑动:`verify()` 不续期);**一次性**:重置成功后 `consume()` 删掉令牌;**重新申请会让旧链接立刻失效**(同一用户只保留最新一条);校验失败的提交(密码太短/两次不一致/令牌不对)**不会**消费令牌;
- **重发节流 60 秒**:命中时 `/forgot` 返回 **429** + `{ ok:false, status:'throttled', message:'重置链接已发送,请 60 秒后再试' }`(⚠️ 2026-10-17 修:以前抛 500,被 error_handler 盖成「服务器内部错误」,用户看不懂);
- **每日发信上限(与注册验证码共用额度)**:同一邮箱每天最多 `EMAIL_DAILY_LIMIT`(默认 10)封,超出返回 **429** + `{ status:'daily_limit', message:'该邮箱今天已发送 10 封邮件,达到上限,请明天再试' }`,**不生成令牌也不发信**(防止被反复点击骚扰收件人 / 刷爆 SMTP 配额);按北京时间(UTC+8)切日;
- 用户按邮箱查也走 `service.user.findByEmail()`(**大小写不敏感 + 含软删除**),避免换个大小写就绕过额度或漏发;Redis 写失败/发信失败 → **503** + `status:'unavailable' | 'mail'`;
- **防账号枚举**:邮箱格式不对才报错;邮箱未注册或账号被禁用时,提示与成功完全一致(“如果该邮箱已注册,链接已经发出”),并且不发信;
- 邮件正文由 `service.mail.sendResetLink()` 生成(与验证码同一套开发模式/SMTP 逻辑:未配 `SMTP_HOST` 时链接写日志 + 接口返回 `url`,前端直接给个可点链接,方便本地点开);
- 链接地址默认取当前请求的 host,正式部署建议配 `SITE_URL`(有反代/多域名时更可靠);
- **改密 / 重置密码后旧令牌立即失效(2026-10-17 已做)**:`users` 新增 `password_changed_at`(迁移 `sql/migrations/20261017_add_user_password_changed_at.sql`;老数据为 NULL = 不限制);`service.user.setPassword()`(注册/重置/脚本)与 `auth.changePassword()` 写这个时间;`middleware/api_auth.js` 与 `middleware/internal_auth.js` 比对 JWT 的 `iat`:**iat 秒 < 改密秒 → 401** `{ status:'password_changed', message:'密码已修改,请重新登录' }`(**留 1 秒容差**:改密当秒新签发的令牌仍然可用,避免误杀);
- **扫码登录**(`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` | 成员列表(任何成员都能看,只读;带 `isCreator` 标记创建者) |
| POST | `/api/web/subjects/:id/members` | 按姓名快速添加成员 `{ name }`(**仅管理员**,此时还没绑账号) |
| DELETE | `/api/web/subjects/:id/members/:memberId` | 移除成员(**仅管理员**;不能删创建者/管理员/自己,管理员要先取消管理员) |
| PUT | `/api/web/subjects/:id/members/:memberId/role` | 设/取消管理员 `{ role: 1\|2 }`(**仅管理员**;一个主体可多名管理员,创建者恒为管理员不能降级,不能改自己) |
| POST | `/api/web/subjects/:id/members/:memberId/bind-code` | 生成成员绑定码(**仅管理员**,`{ code, bindUrl, qrUrl, expiresIn }`,10 分钟有效) |
| GET | `/api/subject/member-bind?code=` | 绑定码状态(**公开**,手机扫码页轮询) |
| POST | `/api/subject/member-bind/confirm` | 手机端确认绑定 `{ code }`(需 user JWT)→ 该账号成为成员 |
角色规则(`subject_members.role`):
- **一个主体可以有多个管理员**(`role=1` 没有唯一约束);`subjects.admin_user_id` 只是**创建者**,同样恒为管理员;
- 成员管理(加成员 / 发绑定码 / 设·取消管理员 / 移除)**只有管理员能做**,普通成员只能看成员列表(只读);
- 创建者不能降级、不能移除;不能改自己的角色、不能删自己(避免管理员把自己锁死);
- 管理员不能直接移除,需先「取消管理员」;给**未绑定账号**的成员设为管理员,绑定后即为管理员。
### 续期套餐与订单(支付回调驱动)
**续期不再是「自己输入天数」**:前端先选套餐(天数 + 定价都在库里),点「生成订单」只落一笔**待支付**订单,
**不会立刻续期**;只有支付渠道回调确认后才把主体期限顺延(幂等,重复回调不重复续期)。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/web/subject-plans` | 上架套餐 `{ list: [{ id, code, name, days, price, originalPrice, tag, description, pricePerDay }] }`(任何登录用户可读) |
| GET | `/api/web/subjects/:id/orders` | 订单列表(成员可见,`{ total, page, pageSize, list }`) |
| POST | `/api/web/subjects/:id/orders` | **选套餐下单** `{ planId, remark? }`(仅管理员)→ `{ orderNo, planId, planName, days, amount, status:0待支付, pending:true, … }`;**金额只认套餐价**,前端传的 `amount/days` 一律忽略 |
| GET | `/api/web/subjects/:id/orders/:orderNo` | 单笔订单(续期弹窗每 2s 轮询支付状态,`pending=false` 即停止) |
| POST | `/api/web/subjects/:id/orders/:orderNo/close` | 关闭待支付订单(仅管理员;已支付 → 409) |
| POST | `/api/pay/notify` | **公开的渠道回调** `{ orderNo, transactionId?, amount?, channel?, paidAt? }` → `{ duplicated, order }`;订单不存在 404、金额不符 422、签名错 400 |
| POST | `/api/internal/subject-orders/:orderNo/pay` | **内部令牌**:模拟支付成功(不需要签名),方便联调/补单 |
订单会快照 `plan_id / plan_code / plan_name`,套餐后续改价或下架都不影响历史订单对账。
套餐表 `subject_plans`(迁移 `20261021180000-create-subject-plans` 内置三档,改价直接改库、不用发版):
| code | 天数 | 价格 | 备注 |
|---|---|---|---|
| `p30` | 30 | ¥99 | 短期试用 / 临时项目 |
| `p180` | 180 | ¥499 | 角标「推荐」,划线价 ¥594(≈¥2.77/天) |
| `p365` | 365 | ¥899 | 角标「最划算」,划线价 ¥1204(≈¥2.46/天) |
签名:配置了 `PAY_CALLBACK_SECRET` 时,回调必须带
`X-Pay-Sign = hex(HMAC-SHA256(secret, "orderNo\ntransactionId\namount"))`;
未配置密钥且 `PAY_MOCK=true` 时允许不带签名直接回调(开发/测试默认开启;**生产默认关闭**,
需要显式设 `PAY_MOCK=true`,否则回调返回 503 `pay_not_configured`)。
续期规则与 `PUT /api/web/subjects/:id` 的 `extendDays` 一致:**未过期在原到期时间上顺延,已过期从当前时间起算**;
回调成功后会主动失效主体状态缓存,设备下一次上报/心跳立即看到新期限。
**模拟一次付费续期**(本地/测试):
```bash
# 1) 选套餐下单(需要主体管理员用户令牌)
curl -X POST http://127.0.0.1:7300/api/web/subjects/1/orders \
-H "Authorization: Bearer <user-jwt>" -H "Content-Type: application/json" \
-d '{"planId":1}'
# 2a) 模拟渠道回调(PAY_MOCK=true 时不需要签名)
curl -X POST http://127.0.0.1:7300/api/pay/notify \
-H "Content-Type: application/json" \
-d '{"orderNo":"<上一步的 orderNo>","transactionId":"TXN-1","amount":99}'
# 2b) 或者走运维接口(内部令牌)
curl -X POST http://127.0.0.1:7300/api/internal/subject-orders/<orderNo>/pay \
-H "X-Internal-Token: <INTERNAL_TOKEN>"
```
二维码:`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` 限定范围
- **业务数据只给主体管理员**:设备 / 录像机 / 摄像头 / 工作台 / 扫码记录这些接口在 `subjectAuth` 之后
再挂 `middleware.subjectAdmin()`,普通成员一律 **403** `{ status: 'subject_forbidden' }`
(判定与 `subjectService.ensureAdmin` 一致:创建者或 `role=1`)。
前端同步:左侧菜单只对管理员显示这几项,路由 `meta.adminOnly` 会把成员挡回首页;
`/api/web/stats` 与 `/api/web/pack-query` **不拦**(首页概览 / 桌面端打包查询普通成员也要用)。
- 登录(`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;
```
⚠️ 种子迁移里的协议正文是**占位示例**,正式上线前务必替换为法务确认后的文本。
## 微信小程序登录(2026-10-20)
独立的小程序登录模块:`code2Session` 换 openid → 按 openid 找绑定账号 → 未绑定则自动建账号。
### 数据表
| 表 | 用途 |
|---|---|
| `wechat_mp_accounts` | 小程序 openid 与平台账号的绑定:`(appid, openid)` 唯一,`user_id` 为空表示已解绑;另存 unionid / session_key / 最近登录 |
与公众号的 `wechat_oauth` 分开:小程序是「一个 openid 对一个平台账号」,解绑只清 `user_id`,记录保留。
### 配置
| 环境变量 | 说明 |
|---|---|
| `WX_MP_APPID` / `WX_MP_SECRET` | 小程序后台「开发设置」里的 AppID / AppSecret(**必须配齐才会真调微信**) |
| `WX_MP_MOCK` | 生产要允许 mock 时显式设为 `true`;本地/单测未配 AppID 时默认允许 mock |
| `WECHAT_API_BASE` | 微信接口地址(默认 `https://api.weixin.qq.com`,联调可改网关) |
mock 模式:请求里 `code` 传 `mock:<openid>` 可直接指定 openid(固定账号,方便联调);
传其它 code 时按 `sha1(code)` 推导 openid。
### 接口
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/web/auth/wechat/login` | 公开;`{ code, userInfo?, client?, agreements? }` → 令牌 + 用户 + 主体列表 + `firstTime` + `wechat` 绑定信息 |
| POST | `/api/web/auth/wechat/bind` | 需令牌;把当前微信绑到已有账号(openid 已属他人 → 409) |
| GET | `/api/web/auth/wechat/bindings` | 需令牌;当前账号的微信绑定列表 |
| DELETE | `/api/web/auth/wechat/bindings/:id` | 需令牌;解绑(若是唯一登录方式 → 422,先设密码) |
登录细节:
- 未绑定过的 openid → 自动创建平台账号:用户名 `wx_<openid 尾 12 位>`(重名加随机后缀)、
随机密码(等于没有密码,需要用「找回密码」设置后才能密码登录),`firstTime: true`;
- 已绑定 → 复用原账号,校验 `users.status`(禁用 → 403);
- 与账号密码登录共用协议校验:`client='mini_program'` 未同意当前协议版本 → **428** `agreement_required`;
- 签发令牌 / 记录同意 / 带主体列表的逻辑在 `app/service/login.js`(两种登录共用)。