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