liufumingren b2eea28001 feat(微信网关): 扫码登录 / 绑定微信 / 工作台扫码登入,废弃自建登录码
对接 https://gateway.gztbyc.com:二维码与「扫码确认」由网关提供,本服务只负责
申请临时码 → 验签收通知 → 落地自己的业务。

- 新增 service/wx_gateway.js + controller/gateway/notify.js(POST /api/wechat-gateway/notify,验签 401 / 会话过期 200 ignored)
- 新增 controller/web/wx_gateway.js(登录二维码 / 长轮询 / SVG+GIF / 个人中心绑定与解绑)
- 新表 wechat_gateway_bindings(uk(app_key, openid)):一个微信只绑一个账号,解绑是软删,
  再绑定走 restore 复用(否则会撞唯一键报 Validation error)
- 「这个微信已绑别的账号」策略:原账号正常 → 拒绝并提示对方账号名;原账号禁用/已删 → 直接改绑;
  拿不到原账号 → 运维接口 GET/DELETE /api/internal/wechat-bindings 强制解绑
- 主体成员改为「扫码绑定」:管理员出二维码 → 成员微信扫码 → 已有账号直接继承(自动建的临时账号删掉),
  没有账号则由服务端建号并绑成其登录方式;subject_members.temp_user_id 记录临时账号
- 废弃自建登录码:删除 GET /api/wechat/login(6 位串码)与 workstations.login_code(迁移 20261028121000),
  工作台改扫码登入,成员绑定码与 /wechat?bind= 手机确认页下线
- 前端:登录页/个人中心/主体成员/工作台全部切到网关;桌面端登录窗改网关二维码 + 长轮询
- 测试:wx-gateway.test.js 覆盖登录/绑定/解绑-再绑/禁用账号改绑/运维强制解绑/成员绑定/工作台登入

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-10-29 17:20:05 +08:00

263 lines
12 KiB
JavaScript
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.

'use strict';
const { Controller } = require('egg');
/**
* 取设备自报信息(**全部可选**,不带也能用)
* 设备上**不需要预先注册/预先配密钥**:发码与轮询时把自己的序列号等信息带上,
* 服务端在「确认登录成功」那一步才用它建记录。
*/
function deviceInfo(ctx) {
const q = ctx.query;
return {
sn: String(q.sn || '').trim() || null,
name: q.name || '',
vendor: q.vendor || null,
model: q.model || null,
firmware: q.firmware || null,
};
}
/**
* 合并设备信息:本次请求里带了就用请求的(空值不算),没带就用发码时暂存的那份
* (建记录发生在确认/换码那一刻,设备只在发码时带过 sn/名称也能生效)
*/
function mergeInfo(fromQuery, stashed) {
const info = Object.assign({}, stashed || {});
for (const [ key, value ] of Object.entries(fromQuery)) {
if (value !== null && value !== '' && value !== undefined) info[key] = value;
}
return info;
}
/**
* 令牌时长:默认 `config.jwt.deviceExpiresIn`(env `DEVICE_JWT_EXPIRES`,默认 365d),
* 设备可以用 `?expiresIn=30d`(或 `3600` 秒)申请**更短**的;超过上限直接 422
* (要整体放宽就改配置,不让单个设备自己把令牌拉长)
* @return {{spec:string|number, seconds:number}} spec 用于回显,seconds 用于签发
*/
function resolveTokenDuration(ctx) {
const { jwt } = ctx.app.config;
const current = String(jwt.deviceExpiresIn || jwt.scannerExpiresIn || '365d');
const max = ctx.service.jwt.parseDuration(current);
const raw = String(ctx.query.expiresIn || '').trim();
if (!raw) return { spec: current, seconds: max };
const seconds = ctx.service.jwt.parseDuration(raw);
if (!seconds) {
ctx.throw(422, 'expiresIn 格式不对(支持 30d / 12h / 90m / 3600 这类写法)');
}
if (max && seconds > max) {
ctx.throw(422, `expiresIn 不能超过服务端上限 ${current}(要放宽请改 DEVICE_JWT_EXPIRES)`);
}
return { spec: /^\d+$/.test(raw) ? Number(raw) : raw, seconds };
}
/**
* 设备(扫描器)专用接口
*
* **登录即注册**:设备出厂后什么都不用配,插上电调本接口拿到一个登录码显示出来,
* 用已经登录的手机(小程序/网页)扫一下确认,服务端这才把设备**注册**到那个账号名下,
* 并把**长期 JWT**(默认 365 天,见 `config.jwt.scannerExpiresIn`)发给设备。
* 不会再出现「先注册出一条无主记录、回头再绑定」的顺序问题。
*/
class DeviceController extends Controller {
/**
* 登录码相关的响应字段(**带完整域名**)
*
* 设备常常**不知道本站域名**(或只知道内网 IP),所以这里直接把「二维码里该编什么」算好给它:
* - `qrContent`:二维码要编码的**完整**网址 `http://<域名>/wechat?spm=…`,直接拿去生成二维码;
* - `qrImageUrl`:本站现成 SVG 二维码的**完整**地址(设备不会画二维码时可直接拉这张图;内容与本接口一致);
* - `qrUrl`:同上的相对路径(老字段,给只需要相对路径的客户端用);
* - `origin`:本次用的域名(调试/纯文本展示用)。
*
* 域名优先取 `SITE_URL`(`config.email.siteUrl`,有反代/多域名/内网设备而对端要走公网时建议配上),
* 没配就用设备请求时的 origin(也就是设备访问服务用的那个地址)。
* @param {string} code 登录码
*/
qrFields(code) {
const { ctx } = this;
const base = String(ctx.app.config.email.siteUrl || ctx.origin || '').replace(/\/+$/, '');
const path = `/api/wechat/qrcode.svg?code=${encodeURIComponent(code)}`;
return {
code,
spm: ctx.service.wechatLogin.spm(code),
origin: base,
qrContent: ctx.service.wechatLogin.qrContent({ code, origin: base }),
qrImageUrl: `${base}${path}`,
qrUrl: path,
};
}
/**
* GET /api/device/login —— 设备专用「扫码登录 + 注册/绑定」(扫码确认,区别是下发**长期** JWT)
*
* 设备信息(`?sn=` 设备序列号、`name` / `vendor` / `model` / `firmware`)**都是可选的**:
* **发码时带上最省事**(服务端会暂存,确认/换码时沿用),轮询时再带上(补齐/覆盖)也行;
* 不带 SN 时服务端在注册那一步生成一个(`DEV-…`)并返回给设备保存。
*
* 三种用法(**不需要任何凭据**,公开接口):
* 1. **不带 `code`**:发一张新登录码(登记为 pending)→ `{ status:'pending', expiresIn, code, spm,
* origin, qrContent, qrImageUrl, qrUrl, device:{ sn, name } }`;**此时还没有注册任何东西**;
* 2. **带 `code=&wait=N`**:**长轮询**(挂起最多 `WECHAT_POLL_WAIT` 秒,默认 60)——
* 手机用 `POST /api/wechat/confirm` 确认后**立即**返回;
* 到时间没人扫 / 码失效 → `refreshed` + 一张新码(设备换二维码后继续轮询,参数照旧带上);
* 设备断开 → 服务端立刻停止等待(`aborted`,不写响应、也不换码);
* 3. **带 `code` 不带 `wait`**:短轮询,只查一次。
*
* **确认成功后**(就是「注册」发生的时刻,归属 = 扫码确认的那个用户):
* - 该 SN 没有记录 → **新建**:绑到该用户,`firstTime: true`;
* - 该 SN 已有记录且**无主**(或曾被软删)→ 由确认者**认领**(复活),`firstTime: false`;
* - 该 SN **已绑定到别的账号** → 403,拒绝(避免把别人的设备扫走);设备被禁用 → 403;
* - 换发长期 JWT(`jti` 轮换 → 设备上一次的令牌立即失效),返回 `token` / `expiresIn` / `expiresAt`。
*
* **令牌时长**:默认 `config.jwt.deviceExpiresIn`(env `DEVICE_JWT_EXPIRES`,默认 365d);
* 设备可用 `?expiresIn=30d`(或秒数,如 `3600`)申请**更短**的,超过上限返回 422
* (要整体放宽改 `DEVICE_JWT_EXPIRES`,不允许单个设备把令牌拉长)。
*
* 返回 `data.status`:
* - `pending`(已发码,等扫码)/ `confirmed`(成功:`token` + `sn` + `firstTime` + `expiresAt` + `scanner` + `user`)
* - `refreshed`(码没了/等超时:`code`/`spm`/`qrContent`… 是新的一张,直接换二维码)
* - 失败:403(SN 已被别人绑定 / 设备被禁用)、422(`expiresIn` 格式不对或超上限、`code` 格式不对)
*/
async login() {
const { ctx } = this;
const svc = ctx.service.wechatLogin;
const info = deviceInfo(ctx);
const tokenDuration = resolveTokenDuration(ctx);
const raw = String(ctx.query.code || '').trim();
// ① 没带 code:发一张新码给设备显示(**公开接口,不需要先注册**)
if (!raw) {
const code = await svc.newCode();
// 设备自报信息暂存一份(可选):确认成功那一刻才是建记录的时机,这样漏传也能沿用
await svc.saveDeviceInfo(code, info);
ctx.body = {
ok: true,
data: Object.assign(
{ status: 'pending', expiresIn: svc.stateTtl },
this.qrFields(code),
{ device: { sn: info.sn, name: info.name || null } },
),
};
return;
}
// ② 带 code:校验格式后长轮询(长度/字符集与登录页的码一致)
const code = raw.toUpperCase();
const expect = Number(ctx.app.config.wechat.codeLength || 6);
if (!new RegExp(`^[0-9A-Z]{${expect}}$`).test(code)) {
ctx.status = 422;
ctx.body = { ok: false, message: `code 格式不对(${expect} 位数字 + 字母)` };
return;
}
// 设备端不需要用户 JWT,所以只取「谁确认了」,长期令牌由这里自己签发
const result = await svc.awaitLogin(code, { wait: ctx.query.wait, withToken: false });
if (result.status === 'aborted') {
// 设备断开了(重启/换页):没什么可回的,也不用写响应
ctx.respond = false;
return;
}
if (result.status === 'refreshed') {
// 换码:把设备信息接着存在新码上(否则下一轮拿到新码时 sn/名称就丢了)
const kept = mergeInfo(info, await svc.takeDeviceInfo(code));
await svc.saveDeviceInfo(result.code, kept);
ctx.body = {
ok: true,
data: Object.assign(
{ status: 'refreshed', expiresIn: svc.stateTtl, waited: result.waited || 0 },
this.qrFields(result.code),
{ device: { sn: kept.sn || null, name: kept.name || null } },
),
};
return;
}
if (result.status !== 'confirmed') {
// pending:码还在,继续等就行(顺带把完整二维码地址再给一次,设备可随时重画)
ctx.body = {
ok: true,
data: Object.assign(
{ status: result.status, expiresIn: await svc.ttlOf(code) },
this.qrFields(code),
{ device: { sn: info.sn, name: info.name || null } },
),
};
return;
}
// ③ 有人确认了 —— **这一步才注册/绑定**(归属就是确认登录的人),并换发长期 JWT
const user = result.user;
const merged = mergeInfo(info, await svc.takeDeviceInfo(code));
// 设备可以在发码时带上 `?subjectId=` 指定要进哪个主体(不传则用确认人可进入的第一个主体)
const wantedSubjectId = Number(ctx.query.subjectId || merged.subjectId || 0) || null;
const data = await ctx.service.scanner.loginByScan(Object.assign({}, merged, {
userId: user.id,
subjectId: wantedSubjectId,
ip: ctx.ip,
expiresIn: tokenDuration.seconds,
}));
ctx.logger.info('[device] %s 扫码登录成功(%s),归属账号 %s',
data.sn, data.firstTime ? '首次注册' : '已注册/认领', user.username || user.id);
ctx.body = {
ok: true,
data: {
status: 'confirmed',
firstTime: data.firstTime, // true = 本次扫码才注册出这条记录
sn: data.sn,
token: data.token,
tokenType: data.tokenType,
expiresIn: tokenDuration.spec, // 实际生效的时长(数字=秒;字符串=与配置同款写法)
expiresAt: data.tokenExpiresAt || null, // 令牌到期时间(绝对时间,方便设备直接排期重扫)
scanner: {
id: data.id,
sn: data.sn,
name: data.name || null,
userId: data.userId || null,
status: data.status,
lastSeenAt: data.lastSeenAt || null,
},
user: {
id: user.id,
username: user.username || null,
nickname: user.nickname || null,
email: user.email || null,
phone: user.phone || null,
avatar: user.avatar || null,
},
},
};
}
/**
* POST /api/device/refresh —— 用刷新令牌换新的访问令牌(**无需访问令牌**)
*
* body: `{ refreshToken, sn? }`;也认 header `X-Refresh-Token`。
*
* 后台扫码服务在访问令牌快过期(或已 401)时调用,成功后:
* - 拿到新的长期 JWT(旧 JWT 的 jti 已轮换 → 立即失效)
* - 拿到新的刷新令牌(旧刷新令牌立即失效,必须覆盖保存)
* 响应:`{ ok:true, data:{ sn, token, tokenType, expiresIn, refreshToken, refreshExpiresIn, refreshExpiresAt } }`
*/
async refresh() {
const { ctx } = this;
const body = ctx.request.body || {};
const refreshToken = String(body.refreshToken || ctx.get('X-Refresh-Token') || '').trim();
const sn = body.sn || ctx.query.sn || null;
const data = await ctx.service.scanner.refreshToken({ refreshToken, sn, ip: ctx.ip });
ctx.logger.info('[device] %s 刷新令牌成功', data.sn);
ctx.body = { ok: true, data };
}
}
module.exports = DeviceController;