From e2414c03eaf3ed98b4dd5e0766e44ef8e59de069 Mon Sep 17 00:00:00 2001 From: lik Date: Thu, 5 Nov 2026 18:56:27 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E5=BE=AE=E4=BF=A1?= =?UTF-8?q?=E6=94=AF=E4=BB=98=E5=AE=9E=E7=8E=B0=E6=96=B9=E6=A1=88=E4=B8=8E?= =?UTF-8?q?=E5=A4=9A=E7=AB=AF=E8=A7=84=E5=88=92=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/user-multi-app-plan.md | 1043 ++++++++++++++++++++++++++++++++++++ doc/wechatpay-plan.md | 433 +++++++++++++++ 2 files changed, 1476 insertions(+) create mode 100644 doc/user-multi-app-plan.md create mode 100644 doc/wechatpay-plan.md diff --git a/doc/user-multi-app-plan.md b/doc/user-multi-app-plan.md new file mode 100644 index 0000000..9233b62 --- /dev/null +++ b/doc/user-multi-app-plan.md @@ -0,0 +1,1043 @@ +# 用户多应用模型改造方案 + +| 项 | 内容 | +|---|---| +| 状态 | 已评审,待确认实施 | +| 日期 | 2026-11-05 | +| 范围 | `api/user` 的用户模型、微信登录、鉴权、用户列表;MongoDB 库 `eiot_user` | +| 目标 | 一个平台账号可在多个 app / 网站 / 小程序中拥有独立的身份、角色和授权状态 | + +## 1. 结论 + +当前 `user.app` 是一个 `Mixed` 字段,一个对象同时承载三件事: + +1. 登录身份:`app.{appId}.wxopenid` +2. 授权角色:`app.{appId}.role` +3. 应用清单:`app` 中存在某个 key + +这三类数据的生命周期不同,混在一个无 schema 的对象里,导致唯一约束、索引、权限作用域都无法表达。 + +建议: + +- **数据库层**:拆成 `user`(平台账号)、`user_app`(应用成员与授权)、`user_identity`(外部登录身份)三张表;`user` 不再保存 `app`。 +- **接口层**:不新增 v2 接口。`/user/userInfo`、登录响应继续返回**只读兼容视图** `app`,并新增只读数组 `apps`;两者都由新表组装,保证老 app 与 `api/health` 不改也能工作。`app` 在所有客户端改读 `apps` 后的下个发布周期移除。 +- **权限判定**:必须带 `appId`,只认该应用内的 `roles`,不再遍历所有应用。 +- **授权入口**:登录只授予 `user`;管理员通过 `POST /user/grant` 或运维脚本授予,登录接口不产生管理员。 +- **实施窗口**:现网只有 36 条用户,且 app 数据结构单一,是切换成本最低的时候。 + +如果明确只维护当前两个微信小程序、且不做应用权限管理,可退而求其次采用第 5.1 节的方案 A(单文档内类型化 Map),但仍然解决不了“登录过不等于已授权”和跨应用身份合并。 + +## 2. 现状 + +### 2.1 数据结构 + +`api/user/models/schema/user.js:74-77`: + +```js +// 带wxopenid +app: { + type: mongoose.Schema.Types.Mixed, + default: {} +}, +``` + +整个 Schema 还开启了 `strict: false`(`api/user/models/schema/user.js:86-89`),因此 `app` 完全不受 schema 约束。 + +现网 36 条数据的实际结构只有: + +```json +"app": { + "wxapp-escort": { + "role": ["user"], + "wxopenid": "ocHVo1..." + }, + "wxapp-escort-admin": { + "role": ["admin"], + "wxopenid": "oLvx23..." + } +} +``` + +`social.wechat.unionid` 虽有唯一稀疏索引(`api/user/models/schema/user.js:64`),但没有任何非空数据。 + +### 2.2 现网数据快照(2026-11-05) + +| 项 | 实际值 | +|---|---| +| `user` 文档总数 | 36 | +| 有 `app` 字段 | 36(全部非空) | +| `app.wxapp-escort` | 36 | +| `app.wxapp-escort-admin` | 1 | +| `role = ["user"]` | 36(`wxapp-escort`) | +| `role = ["admin"]` | 1(`wxapp-escort-admin`) | +| app 条目字段 | 只有 `role`、`wxopenid` | +| 重复 openid | 0 | +| `role` / `wxopenid` 缺失 | 0 | +| 非空 `social.wechat.unionid` | 0 | + +结论:数据本身干净,但 36/36 用户都有 `wxapp-escort`,说明 “app 里存在 key” 只能表示“登录过”,不能表示“已授权”。 + +### 2.3 代码读写点 + +| 行为 | 位置 | +|---|---| +| 定义 `app` 字段 | `api/user/models/schema/user.js:74-77` | +| 注册时写空 `app` | `api/user/handler/users.js:152-153` | +| 微信登录按 `app.{appId}.wxopenid` 查用户 | `api/user/handler/users.js:366-367` | +| 微信登录写入 `role` / `wxopenid` | `api/user/handler/users.js:384-399` | +| 鉴权遍历所有 app 的 `role` | `api/user/middleware/auth.js:73-79` | +| 管理员判定固定读 `wxapp-escort-admin` | `api/user/middleware/auth.js:101-115` | +| 用户列表按 `app.wxapp-escort` 存在性过滤 | `api/user/handler/users.js:300` | +| 用户列表角色校验写在 handler 内(`isAdmin`),路由层无声明 | `api/user/handler/users.js:293-295` | +| 唯一 token 的签发与覆盖 | `api/user/handler/users.js:96-103` | +| 删除用户时按 `social.wechat.unionid` | `api/user/models/schema/user.js:195-215` | +| 通用更新不允许写 `app` | `api/user/models/schema/user.js:141-183` | + +下游读取(过渡期需要兼容): + +- `api/health/utils/permissions.js` 直接读 `user.app["wxapp-escort-admin"].role`。 +- `ui/web_tcm/src/stores/tcm_organization.js` 读 `user.app?.tcm?.organization?.id`。 + +## 3. 问题清单 + +| 级别 | 问题 | 后果 | +|---|---|---| +| P0 | `wxopenid` 无唯一索引、无普通索引 | 登录查询全表扫;并发首次登录或手工改库可产生同 openid 多用户,`findOne` 命中不确定,可能登录到他人账号 | +| P1 | 角色校验跨应用 | `auth({ roles })` 遍历所有 app,A 应用的 admin 能通过 B 应用的校验 | +| P1 | “登录过”与“有权限”混淆 | 无法停用某应用的权限,无法审计授权来源;用户列表口径错误 | +| P2 | 身份、授权、应用参数混层 | openid、role、未来的昵称/机构号放在同一对象,任何代码都可能顺手改到权限 | +| P2 | 缺平台/登录方式维度 | 只有 appId;同一应用多端、多 appid、抖音端无法区分身份 | +| P2 | `unionid` 未落地 | 跨应用“同一个人”只能靠手机号;接第二个小程序或抖音后账号会分叉 | +| P2 | 单 token | 管理端登录会把 C 端踢下线 | +| P2 | 权限校验写在 handler 内 | 路由层看不出接口所需角色,新增接口容易漏写校验 | +| P3 | `strict: false` + 对象 key 直接用 appId | 脏数据无法约束;appId 含 `.` 或 `$` 会写坏文档 | + +## 4. 设计原则 + +1. **账号、身份、授权分离**:`user` 是平台账号;`user_identity` 是“用什么登录”;`user_app` 是“能访问哪个应用、是什么角色”。 +2. **唯一性由数据库保证**:openid 唯一、`userId + appId` 唯一,不依赖应用层“先查后插”。 +3. **权限必须带应用维度**:角色校验接口必须显式传 `appId`。 +4. **应用参数与权限分离**:应用内个人配置放 `user_app.config`,只允许非权限、非数据范围数据;需要查询/鉴权的字段必须提升为 `user_app` 顶层字段。 +5. **接口兼容优先**:数据库先改,响应形状后改;下游服务可以按自己的节奏迁移。 + +## 5. 方案对比 + +### 5.1 方案 A:单文档内类型化 Map(最小改动) + +保留在 `user` 文档内,把 `Mixed` 换成以 appId 为 key 的类型化 Map(字段建议改名 `apps`,避免和 Koa 的 `app` 混淆): + +```js +const AppMembershipSchema = new mongoose.Schema({ + platform: { type: String, enum: ["weixin", "douyin", "alipay", "web"], required: true }, + provider: { type: String, enum: ["weixin-mini", "douyin-mini", "password"], required: true }, + roles: { type: [String], default: ["user"] }, + status: { type: String, enum: ["active", "disabled"], default: "active" }, + identities: { + openid: { type: String }, + unionid: { type: String }, + }, + grant: { + by: { type: mongoose.Schema.Types.ObjectId }, + at: Date, + }, + lastLoginAt: { type: Date }, +}, { _id: false }); + +// user.js +apps: { + type: Map, + of: AppMembershipSchema, + default: () => new Map(), +}, +``` + +每个应用单独建 openid 稀疏唯一索引: + +```js +for (const appId of Object.keys(config.app)) { + UserSchema.index( + { [`apps.${appId}.identities.openid`]: 1 }, + { unique: true, sparse: true, name: `uniq_${appId}_openid` } + ); +} +``` + +优点:改动小,只动 schema + 登录/鉴权读法。 +缺点:应用数增长要不断增加索引;“已授权/已停用”仍和登录记录混在一个文档;按应用查成员/管理员只能扫文档;`Map` 仍不是授权管理的理想结构。 + +### 5.2 方案 B:成员表 + 身份表(推荐) + +```text +user (平台账号) + │ 1 + ├── N user_app (userId + appId 唯一;roles / status / 授权来源) + └── N user_identity (appId + provider + openid 唯一;unionid / platform) +``` + +优点: + +- openid 唯一性、`userId + appId` 唯一性都能直接建索引。 +- 角色查询按应用走索引;可停用、可审计、可按应用列出成员和管理员。 +- 身份与授权解耦;接抖音、Web、支付宝只是新增 identity 行,不改 user 表。 +- 支持 `unionid` 跨应用合并同一人。 + +缺点:登录和 `userInfo` 多 1-2 次查询;需要一次数据回填;响应需要组装。 + +### 5.3 选型 + +| 维度 | 方案 A | 方案 B | +|---|---|---| +| 改动量 | 小 | 中 | +| openid 唯一 | 可以(每应用一个索引) | 可以 | +| 角色按应用隔离 | 可以 | 可以 | +| 授权吊销 / 审计 | 需挤进同一文档 | 原生支持 | +| 按应用查成员 | 需扫描 | 索引查询 | +| 接抖音 / Web / 多端 | 继续加 key 和索引 | 新增 identity 行 | +| 迁移成本 | 低 | 一次性回填 36 条 | +| 长期返工 | 高 | 低 | + +按“平台级多应用权限”的目标,推荐方案 B。现网数据量只有 36 条,现在切换成本最低。 + +## 6. 推荐方案详设 + +### 6.1 应用注册表 + +新增 `api/user/models/app_registry.js`,集中维护 appId → 平台/登录方式,避免散落在登录代码里: + +```js +import config from "../conf.json" with { type: "json" }; + +export const APP_REGISTRY = { + "wxapp-escort": { platform: "weixin", provider: "weixin-mini" }, + "wxapp-escort-admin": { platform: "weixin", provider: "weixin-mini" }, + "ttapp-escort": { platform: "douyin", provider: "douyin-mini" }, + "tcm": { platform: "web", provider: "password" }, +}; + +// conf.json 配置了但注册表没登记 → 启动失败;注册表有但未配置 → 只告警 +export function assertRegistryCoverage() { + const configured = Object.keys(config.app || {}); + const missing = configured.filter((id) => !APP_REGISTRY[id]); + if (missing.length) { + throw new Error(`APP_REGISTRY 缺少 appId 元数据: ${missing.join(", ")}`); + } + const orphan = Object.keys(APP_REGISTRY).filter((id) => !configured.includes(id)); + if (orphan.length) { + console.warn(`[user] APP_REGISTRY 中未在 conf.json 配置的 appId: ${orphan.join(", ")}`); + } + return configured; +} + +export const APP_IDS = Object.keys(config.app || {}); +``` + +`api/user/app.js` 启动阶段调用一次 `assertRegistryCoverage()`,让配置缺失在部署时暴露,而不是等到有人登录该应用才报错。 + +`conf.json` 继续只放 appid / secret;app 元数据放代码里,便于评审和测试。 + +### 6.2 集合与索引 + +#### user(保持平台账号职责) + +保留现有 `profile` / `security` / `location` / `addresses` / `social` / `status` / `meta`,删除 `app`。 + +#### user_app + +```js +// api/user/models/schema/user_app.js +const UserAppSchema = new mongoose.Schema({ + userId: { type: mongoose.Schema.Types.ObjectId, required: true }, + appId: { type: String, required: true }, + roles: { type: [String], default: ["user"] }, + status: { type: String, enum: ["active", "disabled"], default: "active" }, + source: { type: String, enum: ["weixin-login", "manual", "migrated"], default: "manual" }, + // 应用内个人配置:仅存偏好/展示参数,禁止放 roles/status/orgId 等权限或数据范围字段 + // 用 Map 而不是 Mixed 对象:键级 set 会被 Mongoose 跟踪,也便于按 key / 叶子路径原子更新 + config: { + type: Map, + of: mongoose.Schema.Types.Mixed, + default: () => new Map(), + }, + configUpdatedAt: { type: Date, default: null }, + grantedBy: { type: mongoose.Schema.Types.ObjectId, default: null }, + grantedAt: { type: Date, default: null }, + lastLoginAt: { type: Date, default: null }, +}, { collection: "user_app", minimize: false }); + +UserAppSchema.index({ userId: 1, appId: 1 }, { unique: true }); +UserAppSchema.index({ appId: 1, status: 1 }); +UserAppSchema.index({ appId: 1, roles: 1 }); +``` + +#### user_identity + +```js +// api/user/models/schema/user_identity.js +const UserIdentitySchema = new mongoose.Schema({ + userId: { type: mongoose.Schema.Types.ObjectId, required: true }, + appId: { type: String, required: true }, + platform: { type: String, enum: ["weixin", "douyin", "alipay", "web"], required: true }, + provider: { type: String, enum: ["weixin-mini", "douyin-mini", "password"], required: true }, + openid: { type: String }, + unionid: { type: String }, +}, { collection: "user_identity", timestamps: true }); + +// 注意:这里不能用 sparse。appId/provider 恒存在, +// sparse 复合索引仍会把缺 openid 的文档索引成 null,导致 password 身份互相冲突。 +UserIdentitySchema.index( + { appId: 1, provider: 1, openid: 1 }, + { unique: true, partialFilterExpression: { openid: { $type: "string" } } } +); + +UserIdentitySchema.index( + { provider: 1, unionid: 1 }, + { unique: true, partialFilterExpression: { unionid: { $type: "string" } } } +); + +UserIdentitySchema.index({ userId: 1 }); +``` + +写入前必须把空字符串规范化为 `undefined`(例如 `openid || undefined`、`unionid || undefined`)。`partialFilterExpression` 只按类型过滤,空字符串仍会被索引,多个 `openid: ""` 依然会触发唯一冲突。 + +删除用户时,`delUser` 需要同时清理该用户的 `user_app` 与 `user_identity`,避免残留成员关系被新账号复用。 + +#### user_session(可选,第二阶段) + +不在本次改造必做范围。它解决“多应用/多端登录互踢”: + +```js +{ + userId, appId, tokenHash, + expiresAt, ip, device +} +// { tokenHash: 1 } unique +// { expiresAt: 1 } expireAfterSeconds: 0 +``` + +本次先保留 `security.token`,避免扩大改动面。 + +### 6.3 微信登录流程 + +替换 `api/user/handler/users.js` 的 `wxSignin` 核心逻辑(以下为伪代码,错误响应沿用现有 `ResponseUtil`): + +```js +const meta = APP_REGISTRY[appId]; +if (!meta) return badRequest(`未配置 appId: ${appId}`); + +const { openid, unionid } = sessionData; + +// 1. 先按本应用身份查 +let identity = await DBModel.UserIdentity.findOne({ appId, provider: meta.provider, openid }); +let user = identity ? await DBModel.User.findById(identity.userId) : null; + +// 1.5 过渡期兜底:新表未命中时回查旧 app 字段(P4 前旧字段仍在) +// 命中说明回填有遗漏,补写新表,避免把老用户当成新用户建重复账号 +if (!user) { + user = await DBModel.User.findOne({ [`app.${appId}.wxopenid`]: openid }); + if (user) await backfillOneFromLegacy(user, appId, openid, unionid); +} + +// 2. 跨应用:unionid 优先(微信开放平台已绑定时才有值) +if (!user && unionid) { + const samePerson = await DBModel.UserIdentity.findOne({ provider: meta.provider, unionid }); + if (samePerson) user = await DBModel.User.findById(samePerson.userId); +} + +// 3. 手机号兜底:只允许服务端验证过的手机号绑定已有账号 +if (!user && verifiedPhoneNumber) { + user = await DBModel.User.findOne({ "profile.mobile": verifiedPhoneNumber }); +} + +// 4. 仍不存在则新建平台账号(不写 app) +if (!user) { + if (!verifiedPhoneNumber && !phoneNumber) return badRequest("缺少手机号"); + // 未验证的 phoneNumber 只允许用于新建账号,不能用于合并到已有账号(见步骤 3) + user = await DBModel.User.create({ + profile: { name: name || verifiedPhoneNumber || phoneNumber, mobile: verifiedPhoneNumber || phoneNumber }, + status: { account: "normal" }, + social: { wechat: {} }, + }); +} + +// 5. 绑定身份:唯一索引兜底。user_identity 上有两个唯一索引, +// 11000 可能来自 openid,也可能来自 unionid,必须按 keyPattern 区分 +try { + await DBModel.UserIdentity.updateOne( + { appId, provider: meta.provider, openid }, + { + $setOnInsert: { userId: user._id, platform: meta.platform, provider: meta.provider }, + ...(unionid ? { $set: { unionid } } : {}), + }, + { upsert: true } + ); +} catch (err) { + if (err.code !== 11000) throw err; + + const pattern = err.keyPattern || {}; + + // unionid 冲突:该微信号已属于其他账号 + if ("unionid" in pattern && unionid) { + const owner = await DBModel.UserIdentity.findOne({ provider: meta.provider, unionid }); + if (!owner || String(owner.userId) !== String(user._id)) { + return error(ctx, "该微信已绑定其他账号", null, 409); + } + // 同一用户的并发绑定:重试一次 upsert,补齐当前 openid 记录 + await DBModel.UserIdentity.updateOne( + { appId, provider: meta.provider, openid }, + { $setOnInsert: { userId: user._id, platform: meta.platform, provider: meta.provider } }, + { upsert: true } + ); + } else { + // openid 冲突:确认是否已绑到当前用户 + const bound = await DBModel.UserIdentity.findOne({ appId, provider: meta.provider, openid }); + if (!bound || String(bound.userId) !== String(user._id)) { + return error(ctx, "该微信身份已绑定其他账号", null, 409); + } + } +} + +// 6. 保证成员关系存在,并刷新最后登录时间 +await DBModel.UserApp.updateOne( + { userId: user._id, appId }, + { + $setOnInsert: { roles: ["user"], status: "active", source: "weixin-login", grantedAt: new Date() }, + $set: { lastLoginAt: new Date() }, + }, + { upsert: true } +); + +// 7. 签发 token(保持现有单 token 逻辑) +const { raw } = await this.issueToken(user); +``` + +关键规则: + +- `unionid` 有值时才参与跨应用合并;没有时退化为手机号。 +- `openid` 已绑定其他用户时拒绝,不做静默改绑。 +- `roles` 首次写入固定为 `["user"]`;管理员角色只能由内部授权写(见 6.8)。 +- 所有写入都是 upsert + 唯一索引,不依赖“先查后插”,因此不要求 MongoDB 事务。 +- `profile.mobile` 已有单字段 `unique + sparse` 索引(`api/user/models/schema/user.js:20`),本次**不需要重复建设**。但 `sparse` 不排除空字符串,`mobile: ""` 仍会占用唯一键,写入前必须保证非空。 +- 未验证的 `phoneNumber` 只用于新建账号,不得用于合并到已有账号;合并只认 `verifiedPhoneNumber`。 +- 步骤 1.5 的 `backfillOneFromLegacy` 与 7.2 的回填脚本共用同一段 upsert 逻辑,不能各写一份;兜底命中时必须补写新表,否则每次登录都会回退到全表查旧字段。 + +### 6.4 鉴权 + +`auth()` 增加 `appId` 参数,角色只在该应用内判定: + +```js +function auth({ required = true, appId, roles } = {}) { + return async (ctx, next) => { + // ... token -> user、锁定、过期校验保持不变 + + // 只要声明了 appId,就必须存在有效成员关系:停用 / 未授权统一 403 + if (appId) { + const membership = await DBModel.UserApp.findOne({ + userId: user._id, + appId, + status: "active", + }); + if (!membership) return ResponseUtil.forbidden(ctx, "无权访问该应用"); + if (roles && roles.length > 0 && !roles.some((r) => membership.roles.includes(r))) { + return ResponseUtil.forbidden(ctx, "权限不足"); + } + ctx.state.membership = membership; + } else if (roles && roles.length > 0) { + // 角色校验必须带应用维度,缺 appId 视为路由配置错误 + return ResponseUtil.internalError(ctx, "角色校验缺少 appId"); + } + + ctx.state.user = user; + await next(); + }; +} +``` + +路由按应用绑定,不再靠“app 里有没有 key”猜: + +```js +// api/user/routes/index.js +const ADMIN_APP = "wxapp-escort-admin"; + +userRouter.post( + "/list", + auth({ appId: ADMIN_APP, roles: ["admin"] }), + this.handler.userList.bind(this.handler) +); +``` + +> 停用语义:`status: "disabled"` 只会在挂了 `appId` 的接口生效。凡是依赖“某应用可用”的接口(`/user/update`、`/user/app-config`、后续 C 端业务接口)都必须显式传 `appId`;未传 `appId` 的接口只校验平台级登录态,无法表达应用级停用。这一点必须在路由评审时逐条确认。 + +`isAdmin()` 改为只认应用内成员关系,不再提供“缺 role 即管理员”的历史兼容分支: + +```js +function isAdmin(membership) { + return !!membership + && membership.status === "active" + && membership.roles.includes("admin"); +} +``` + +`userList` 的鉴权已由路由完成,handler 内不再单独调用 `isAdmin`。 + +> 如果后续出现非管理端应用也要校验角色的接口,appId 从请求头 `X-App-Id` 取,并先用 `APP_REGISTRY` 校验,不能直接信任 body。 + +### 6.5 接口响应 + +保留 `user` 主体结构,新增 `apps`,同时输出过渡期兼容视图 `app`: + +```json +{ + "user": { + "profile": { "name": "...", "mobile": "..." }, + "apps": [ + { + "appId": "wxapp-escort", + "roles": ["user"], + "status": "active", + "config": { "theme": "dark", "notifications": { "orderStatus": true, "marketing": false } } + }, + { "appId": "wxapp-escort-admin", "roles": ["admin"], "status": "active", "config": {} } + ], + "app": { + "wxapp-escort": { "role": ["user"], "wxopenid": "ocHVo1..." }, + "wxapp-escort-admin": { "role": ["admin"], "wxopenid": "oLvx23..." } + } + } +} +``` + +- `app` 标记为 deprecated,仅由 `user_app` + `user_identity` 组装,不再从数据库读取。 +- `safe.security` 仍在 `buildLoginResponse` 中单独附原始 token。 +- `wxopenid` 在兼容视图中保留,待 `api/health` 和前端确认不再使用后移除。 + +组装逻辑放在 `sanitizeUser` 之外,避免脱敏函数依赖数据库: + +```js +// Mongoose Map 与 lean 返回的普通对象都要兼容 +function plainConfig(value) { + if (!value) return {}; + return value instanceof Map ? Object.fromEntries(value) : value; +} + +async function buildUserView(user) { + const [memberships, identities] = await Promise.all([ + DBModel.UserApp.find({ userId: user._id }).lean(), + DBModel.UserIdentity.find({ userId: user._id, openid: { $exists: true } }).lean(), + ]); + + const apps = memberships.map((m) => ({ + appId: m.appId, + roles: m.roles, + status: m.status, + config: resolveConfig(m.appId, m.config), // 合并默认值后再返回 + })); + + const legacyApp = {}; + for (const m of memberships) { + const identity = identities.find((i) => i.appId === m.appId); + legacyApp[m.appId] = { + role: m.roles, + ...(identity?.openid ? { wxopenid: identity.openid } : {}), + }; + } + + return { ...sanitizeUser(user), apps, app: legacyApp }; +} +``` + +### 6.6 用户列表 + +不再用 `{"app.wxapp-escort": {$exists: true}}`: + +```js +const filter = { appId: "wxapp-escort", status: "active" }; +const [memberships, total] = await Promise.all([ + DBModel.UserApp.find(filter).sort({ _id: 1 }).skip((page - 1) * pageSize).limit(pageSize).lean(), + DBModel.UserApp.countDocuments(filter), +]); + +const userIds = memberships.map((m) => m.userId); +const users = await DBModel.User.find({ _id: { $in: userIds } }); +``` + +`total` 现在是“该应用的有效成员数”,不再是“登录过该小程序的人数”。 + +这是本次唯一主动接受的 v1 语义变更:现网 36 人全部回填为 `active`,上线当天列表结果与现在完全一致;差异只会在引入停用之后出现。 + +### 6.7 应用内配置参数 + +`user_app.config` 保存“这个用户在这个应用里的个人配置/偏好”,例如: + +| 应用 | 可能的配置 | +|---|---| +| C 端小程序 | `theme`、`language`、订单通知开关、列表默认筛选 | +| 管理端小程序 | 每页条数、默认筛选、提示音开关 | +| tcm Web | `theme`、`language`、默认机构(仅展示用途时) | + +明确不放进 `config` 的内容: + +- `roles` / `status` / 授权来源:属于权限,已有独立字段。 +- `orgId`、`tenantId` 等**数据范围字段**:如果参与查询或越权判断,必须是 `user_app` 顶层字段并建索引,不能埋在 config 里。 +- openid / unionid / 密码:属于 `user_identity`。 +- 图片、附件:只存 URL,不存二进制。 + +#### 存储结构 + +```js +config: { + type: Map, + of: mongoose.Schema.Types.Mixed, + default: () => new Map(), +}, +configUpdatedAt: { type: Date, default: null }, +``` + +选择 `Map` 的原因: + +- 每个应用的配置项不同,用统一子 schema 会把所有应用的字段堆在一起。 +- Map 能跟踪 key 级 `set/delete`;换成普通 `Mixed` 对象后,嵌套属性修改不会被 Mongoose 自动保存。 +- 值允许嵌套对象(如 `notifications`),同时 key 由白名单约束,不接受客户端任意新增。 + +#### 每个应用声明自己的白名单 + +新增 `api/user/models/app_config.js`: + +```js +import Joi from "joi"; + +// 键默认可选,因此同一份 schema 既能校验全量,也能校验部分更新 +export const APP_CONFIG_SCHEMAS = { + "wxapp-escort": Joi.object({ + theme: Joi.string().valid("light", "dark", "system"), + language: Joi.string().valid("zh-CN", "en-US"), + notifications: Joi.object({ + orderStatus: Joi.boolean(), + marketing: Joi.boolean(), + }), + }), + + "wxapp-escort-admin": Joi.object({ + pageSize: Joi.number().integer().min(10).max(200), + defaultFilter: Joi.string().valid("all", "pending", "done"), + soundAlert: Joi.boolean(), + }), + + tcm: Joi.object({ + theme: Joi.string().valid("light", "dark", "system"), + language: Joi.string().valid("zh-CN", "en-US"), + }), +}; + +export function hasConfigSchema(appId) { + return !!APP_CONFIG_SCHEMAS[appId]; +} + +export function validateAppConfig(appId, input) { + const schema = APP_CONFIG_SCHEMAS[appId]; + if (!schema) throw new Error(`未配置 ${appId} 的 config schema`); + + const { error, value } = schema.validate(input, { abortEarly: false }); + if (error) throw new Error(error.details[0].message); + + // 单个用户的单应用配置限制 8KB,防止被当成任意存储 + if (Buffer.byteLength(JSON.stringify(value)) > 8192) { + throw new Error("应用配置过大"); + } + return value; +} +``` + +Joi 对象默认拒绝未声明 key,客户端传 `{ role: ["admin"] }` 会直接 400,无法借此改权限。 + +#### 写入接口 + +新增 `POST /user/app-config`,挂 `auth()`,只允许登录用户修改**自己的**配置: + +```js +// body: { appId, config: { theme: "dark", notifications: { marketing: false } } } +const { appId, config } = ctx.request.body; +if (!APP_REGISTRY[appId]) return ResponseUtil.badRequest(ctx, `未配置 appId: ${appId}`); +if (!hasConfigSchema(appId)) return ResponseUtil.badRequest(ctx, `该应用暂不支持配置: ${appId}`); + +const membership = await DBModel.UserApp.findOne({ + userId: user._id, + appId, + status: "active", +}); +if (!membership) return ResponseUtil.forbidden(ctx, "无权访问该应用"); + +const patch = validateAppConfig(appId, config); + +function isPlainObject(v) { + return !!v && typeof v === "object" && !Array.isArray(v) && !(v instanceof Date); +} + +// 展开为叶子路径:{ notifications: { marketing: false } } → { "notifications.marketing": false } +// 数组和标量整体替换,不做逐项合并 +function flattenLeaves(input, base = "") { + const out = {}; + for (const [k, v] of Object.entries(input)) { + const path = base ? `${base}.${k}` : k; + if (isPlainObject(v)) { + Object.assign(out, flattenLeaves(v, path)); + } else { + out[path] = v; + } + } + return out; +} + +const flat = flattenLeaves(patch); +if (Object.keys(flat).length === 0) { + return ResponseUtil.badRequest(ctx, "没有可更新的配置项"); +} + +const set = { configUpdatedAt: new Date() }; +for (const [path, value] of Object.entries(flat)) { + set[`config.${path}`] = value; // 叶子级 $set:同一对象下未传的兄弟字段保持不变 +} +await DBModel.UserApp.updateOne({ _id: membership._id }, { $set: set }); +``` + +规则: + +- 一次请求只更新传入的**叶子路径**,未传的叶子字段保持不变。 +- 嵌套对象按叶子级合并(`config.notifications.marketing` 单独写入),**不做整对象替换**——否则只改一个开关会把同对象下其他字段清掉。 +- 数组和标量整体替换。 +- 传空对象 `{}` 视为无操作,直接 400,避免写入无意义的 `configUpdatedAt`。 +- 管理员/服务端才能改的配置项不放进这个接口的 schema,另走内部授权接口。 +- 配置 key 由 Joi 白名单固定,不含 `.` 或 `$`,不会写坏文档路径。 + +#### 读取与默认值 + +默认值放代码里,数据库只保存用户改过的项: + +```js +const APP_CONFIG_DEFAULTS = { + "wxapp-escort": { theme: "system", language: "zh-CN", notifications: { orderStatus: true, marketing: false } }, + "wxapp-escort-admin": { pageSize: 100, defaultFilter: "all", soundAlert: true }, + tcm: { theme: "system", language: "zh-CN" }, +}; + +function resolveConfig(appId, stored) { + const defaults = APP_CONFIG_DEFAULTS[appId] || {}; + const current = plainConfig(stored); + const out = { ...defaults }; + for (const [key, value] of Object.entries(current)) { + // 已知嵌套对象做一层深合并:库里只存了部分字段时,默认值仍能补齐 + out[key] = isPlainObject(defaults[key]) && isPlainObject(value) + ? { ...defaults[key], ...value } + : value; + } + return out; +} +``` + +`plainConfig`、`isPlainObject` 放在 `api/user/models/app_config.js`,由写入 handler 和 `buildUserView` 共用,避免两处各写一份导致行为分叉。 + +`apps[].config` 返回合并后的结果。默认值调整后对未覆盖该 key 的用户立即生效,不用批量回填。 + +#### 写入注意事项 + +```js +// 正确:整值替换,Map 会标记修改 +membership.config.set("notifications", { orderStatus: true, marketing: false }); +await membership.save(); + +// 错误:Map 内 Mixed 值的嵌套属性修改不会被自动保存 +membership.config.get("notifications").marketing = true; +``` + +如果使用 `updateOne`,按 6.7 的叶子路径写法(`$set: { "config.notifications.marketing": false }`),既绕开 Map 的变更跟踪,也不会覆盖同一对象下的兄弟字段。不要用 `$set: { "config.notifications": {...} }` 整对象写入,除非确实要重置该对象。 + +#### 与 `orgId` 的边界 + +`web_tcm` 现在读 `user.app?.tcm?.organization?.id`: + +- 如果机构号只用于展示默认机构,放 `config.defaultOrgId`。 +- 如果机构号参与数据过滤/权限判断,新增 `user_app.orgId` 顶层字段,并建索引 `{ appId: 1, orgId: 1 }`,不要放 config。 + +过渡期兼容视图可以把 `config.defaultOrgId` 或顶层 `orgId` 映射回 `app.tcm.organization.id`;长期让前端改读 `apps[].config` / `apps[].orgId`。 + +### 6.8 授权入口 + +登录只会写入 `roles: ["user"]`,管理员角色必须有服务端授权入口,否则“下一个管理员”无法产生。最小实现是一个内部接口 + 一个运维脚本,不建管理后台。 + +`POST /user/grant`,挂 `auth({ appId: "wxapp-escort-admin", roles: ["admin"] })`: + +```js +// body: { userId, appId, action: "grant" | "revoke", roles: ["admin"] } +const { userId, appId, action } = ctx.request.body; +const targetRoles = ctx.request.body.roles || ["admin"]; + +if (!APP_REGISTRY[appId]) return ResponseUtil.badRequest(ctx, `未配置 appId: ${appId}`); +if (!targetRoles.every((r) => GRANTABLE_ROLES.includes(r))) { + return ResponseUtil.badRequest(ctx, "不支持的角色"); +} + +const operator = ctx.state.user; + +if (action === "grant") { + await DBModel.UserApp.updateOne( + { userId, appId }, + { + $addToSet: { roles: { $each: targetRoles } }, + $set: { status: "active", grantedBy: operator._id, grantedAt: new Date() }, + $setOnInsert: { source: "manual", config: {} }, + }, + { upsert: true } + ); +} else if (action === "revoke") { + // 先确认撤销后该应用仍有启用的管理员 + const remaining = await DBModel.UserApp.countDocuments({ + appId, + status: "active", + roles: "admin", + userId: { $ne: userId }, + }); + if (remaining === 0) return ResponseUtil.badRequest(ctx, "不能撤销最后一个管理员"); + + await DBModel.UserApp.updateOne( + { userId, appId }, + { + $pull: { roles: { $in: targetRoles } }, + $set: { grantedBy: operator._id, grantedAt: new Date() }, + } + ); +} else { + return ResponseUtil.badRequest(ctx, "action 只能是 grant 或 revoke"); +} +``` + +约定: + +- `GRANTABLE_ROLES = ["user", "admin"]`,白名单固定;本阶段不做自定义角色/RBAC。 +- 撤销的是角色,不删除成员记录;`status` 保持原值,便于审计。要彻底停用该应用,另走 `status: "disabled"`。 +- 撤销前校验“至少保留一个启用管理员”,避免把管理端锁死。 +- 首个管理员和紧急恢复用 `scripts/grant_admin.js`(直接写库,参数为 userId + appId),不走 HTTP。 + +## 7. 实施步骤 + +### 7.1 阶段划分 + +| 阶段 | 内容 | 可回滚 | +|---|---|---| +| P0 | 备份 `user` 集合;确认无重复 openid;把 `userList` 的 `isAdmin` 校验从 handler 上移到路由层(行为等价,便于后续换成 membership 判定) | 不需要 | +| P1 | 新增两张表的 schema、模型注册、索引;不改变任何行为 | 删除集合即可 | +| P2 | `wxSignin` 双写:新表 + 旧 `app` 字段;跑历史回填 | 旧代码仍可读旧字段 | +| P3 | 读路径切到新表:`auth`、`userList`、`userInfo` 响应;兼容 `app` 视图。无开关,直接切;发布前必须完成第 12 节 R3 的全量 diff | 重新部署旧代码 | +| P4 | 停止写旧 `app`;数据库删除 `app` 字段;`strict: true` | 需要备份恢复 | +| P5 | 下游(`api/health`、`web_tcm`)改用 `apps`;移除兼容 `app` | 可回退响应字段 | + +P1-P3 期间旧 `app` 字段保持可读,是回滚窗口。 + +### 7.2 回填脚本 + +一次性脚本,按 `_id` 分批(`cursor.batchSize(100)`),幂等: + +```js +// scripts/migrate_user_app.js +for (const user of cursor) { + for (const [appId, entry] of Object.entries(user.app || {})) { + const roles = Array.isArray(entry.role) + ? entry.role + : entry.role + ? [entry.role] + : ["user"]; + + // 未登记的 appId 不能丢弃:成员关系照常写入; + // 有 openid 时按微信小程序兜底,并告警要求补登 APP_REGISTRY + const meta = APP_REGISTRY[appId]; + const platform = meta?.platform || "weixin"; + const provider = meta?.provider || "weixin-mini"; + if (!meta) { + console.warn(`[migrate] 未知 appId=${appId},请补登 APP_REGISTRY`); + } + + await db.collection("user_app").updateOne( + { userId: user._id, appId }, + { + $setOnInsert: { + roles, + status: "active", + source: "migrated", + grantedAt: null, + }, + }, + { upsert: true } + ); + + if (entry.wxopenid) { + const unionid = entry.unionid || user.social?.wechat?.unionid || null; + const insert = { + userId: user._id, + platform, + provider, + }; + // unionid 只在有值且首次写入时设置: + // 重跑脚本不能把库里已有的 unionid 覆盖成 null + if (unionid) insert.unionid = unionid; + + await db.collection("user_identity").updateOne( + { appId, provider, openid: entry.wxopenid }, + { $setOnInsert: insert }, + { upsert: true } + ); + } + } +} +``` + +回填前后各跑一次校验: + +```js +// 每个 user.app 条目都能在 user_app 找到 +// 每个 wxopenid 都能在 user_identity 找到 +// 没有 userId + appId 重复 +// 没有 appId + provider + openid 重复 +``` + +### 7.3 索引建立顺序 + +1. 先跑重复检查。 +2. 建 `user_app`、`user_identity` 索引。 +3. 再回填数据。 +4. 回填完成后再次校验唯一性。 + +如果先回填后建索引,历史脏数据会让建索引失败,且报错只给出冲突键,不利于定位。 + +## 8. 测试与验收 + +### 8.1 自动化测试 + +在 `api/user/test/` 增加: + +| 用例 | 预期 | +|---|---| +| 新用户微信登录 | `user`、`user_identity`、`user_app` 各一条 | +| 同 openid 再次登录 | 不新增用户;`lastLoginAt` 更新 | +| 两个用户绑定同一 openid | 后者 409,前者身份不变 | +| 同一用户登录第二个应用 | 新增 `user_app`,不新增 `user` | +| A 应用 admin 访问 B 应用 admin 接口 | 403 | +| 成员 `status = disabled` 调用挂 `appId` 的接口(含未传 roles 的) | 403 | +| 普通用户调用 `/user/list` | 401/403(现实现已在 handler 内校验,切换后保持) | +| 无 membership 的登录用户访问应用接口 | 403 | +| 相同 unionid、不同 openid | 合并到同一 `user` | +| `/user/userInfo` | 同时返回 `apps`(含 `config`)和兼容 `app` | +| 写入未声明的 config key(如 `role`) | 400,权限字段不变 | +| 只传部分 config key | 只更新传入项,其余保持不变 | +| config 超过 8KB | 400 | +| 部分更新嵌套 config(只传 `notifications.marketing`) | `notifications.orderStatus` 保持原值/默认值,不被清空 | +| 更新未配置 config schema 的 appId(如 `ttapp-escort`) | 400,不是 500 | +| 不同 openid 绑定已属于他人的 unionid | 409,不做静默改绑 | +| 撤销最后一个 admin | 400 | +| 撤销后该用户调用管理接口 | 403 | +| 回填脚本执行两次 | 结果一致,无重复 | + +现有 `test/api.test.js` 中的注册、登录、更新、退出用例必须保持通过。 + +### 8.2 上线验收 + +1. 用现网管理员账号登录管理端,`/user/list` 正常且只返回 `wxapp-escort` 的有效成员。 +2. 用一个普通账号登录 C 端,响应中 `apps` 只有 `wxapp-escort`。 +3. 同一账号登录管理端后,`user_app` 新增管理员应用成员;C 端仍可正常鉴权。 +4. 人工制造重复 openid(测试库)验证唯一索引拦截。 +5. `api/health` 在过渡期读兼容 `app` 仍判定管理员正确。 + +## 9. 回滚 + +- P1:删除新建集合和模型注册,无影响。 +- P2:旧 `app` 字段仍在写入,直接回退代码即可。 +- P3:回退到旧 `auth` / `userList` / `userInfo` 实现;旧字段因 P2 双写仍然完整。 +- P4 之后:需要从备份恢复 `user` 集合。执行 P4 前必须确认 P3 已稳定运行至少一个发布周期,且下游不再依赖旧字段。 + +## 10. 风险与待确认 + +| 风险 | 处理 | +|---|---| +| MongoDB 不是副本集,无法使用多文档事务 | 全流程使用 upsert + 唯一索引,允许失败后重试;不依赖事务 | +| `jscode2session` 不返回 unionid | 代码必须允许 `unionid` 为空;跨应用合并退化为手机号 | +| `api/health` 直接读 `user.app` | 过渡期保留兼容视图;后续单独改造 `permissions.js` | +| `web_tcm` 读 `app.tcm.organization.id` | 过渡期映射 `config.defaultOrgId` 或顶层 `orgId`;长期改读 `apps[].config` | +| `conf.json` 不在版本库 | 新增 app 时需要运维同步配置;`APP_REGISTRY` 启动时校验覆盖 | +| 历史账号角色缺失(原 `isAdmin` 兼容放行) | 回填时默认 `roles: ["user"]`;管理员账号必须显式 `["admin"]`,不再保留“缺 role 即管理员” | +| 客户端仍读 `user.app` | 兼容视图保留一个发布周期,前端逐步改读 `apps` | +| 未来接入多个微信开放平台主体 | `unionid` 唯一键需追加 `openPlatformId`;单主体阶段可先按 `provider + unionid` | +| config 里混入需要索引/鉴权的字段 | 明确禁止;需要查询或数据范围的字段提升为 `user_app` 顶层字段并建索引 | +| Map 内 Mixed 值的嵌套属性被就地修改 | 文档级写入用 `config.set(key, value)` 整值替换;`updateOne` 用叶子路径 `$set: { "config..": value }` | +| 只改嵌套 config 的单个字段导致兄弟字段被清空 | 接口按叶子路径写入;读取时 `resolveConfig` 对已知嵌套对象做一层深合并 | +| 客户端借 config 写权限字段 | key 由 Joi 白名单固定,未知 key 直接 400;config 接口只改当前用户自己的成员记录 | +| 11000 可能来自 unionid 唯一索引 | catch 中按 `err.keyPattern` 区分 openid / unionid,回查归属后再决定 409 | +| 未传 `appId` 的接口无法表达应用级停用 | 依赖应用可用性的接口必须挂 `appId`,路由评审逐条确认 | +| 应用没有 config schema(如 `ttapp-escort`) | 写入接口先判 `hasConfigSchema`,返回 400 而不是抛 500 | + +待确认: + +1. 应用级停用/开通是只做 `POST /user/grant` + 运维脚本,还是需要管理后台?本次按“接口 + 脚本”实现。 +2. `tcm` Web 应用是否要纳入本次成员模型? +3. 抖音端 appId 是否确定为 `ttapp-escort`?该应用暂无 config schema,写入接口会返回 400。 +4. 跨应用合并是否只认 `unionid`,还是继续保留手机号合并(仅限服务端验证过的手机号)? +5. 多应用同时登录(不互踢)是否要在本阶段解决? + +## 11. 涉及文件清单 + +| 文件 | 改动 | +|---|---| +| `api/user/models/schema/user.js` | 删除 `app`;收紧 `strict`;`delUser` 级联清理 `user_app` / `user_identity` | +| `api/user/models/schema/user_app.js` | 新增 | +| `api/user/models/schema/user_identity.js` | 新增 | +| `api/user/models/app_registry.js` | 新增 appId → platform/provider 映射;`assertRegistryCoverage()` 启动校验 | +| `api/user/models/app_config.js` | 新增各应用的 config 白名单 schema、默认值、校验函数、`hasConfigSchema`、`plainConfig`、`isPlainObject` | +| `api/user/models/index.js` | 注册 `UserApp`、`UserIdentity` 模型 | +| `api/user/handler/users.js` | 重写 `wxSignin`;`userList` 改查成员表;新增 `buildUserView`、`appConfig`、`grant` handler | +| `api/user/middleware/auth.js` | `auth` 增加 `appId` + 应用内角色判定(传 `appId` 即校验 membership);改造 `isAdmin` | +| `api/user/routes/index.js` | `/user/list` 绑定管理端 appId 与角色;新增 `POST /user/app-config`、`POST /user/grant` | +| `api/user/app.js` | 启动阶段调用 `assertRegistryCoverage()` | +| `api/user/scripts/grant_admin.js` | 新增:首个管理员授权与紧急恢复脚本 | +| `api/user/scripts/diff_legacy_vs_new.js` | 新增:切读前全量 diff,逐用户/逐 appId/逐 openid 比对 | +| `api/user/test/*.test.js` | 补充身份、成员、权限隔离、config 部分更新、授权、回填用例 | +| `doc/wechatpay-plan.md` | 过渡期仍引用 `app`,需在 P5 一并更新 | +| `api/health/utils/permissions.js` | 过渡期不改;P5 改读 `user_app` | +| `ui/web_tcm/src/stores/tcm_organization.js` | P5 改读 `apps[].config` 或 `apps[].orgId` | + +--- + +## 12. 重构规则(v1 契约冻结) + +本次重构在**不改动现有 API 契约**的前提下替换数据模型。以下规则是实施硬约束,违反任意一条视为回归。 + +| 编号 | 规则 | 落地方式 | +|---|---|---| +| R1 | **只增不改不删**:v1 八个接口的 path、method、入参、响应字段名与语义不变;仅允许新增只读字段 `apps` | 不改路由签名;响应在 `sanitizeUser` 之后追加 `apps` | +| R2 | **适配层单点**:`app` 与 `apps` 只能由 `buildLegacyUserView()` 生成 | 禁止 handler 各自拼装;禁止把 `user_app` 原始文档直接返回 | +| R3 | **登录等价 + 兜底**:切读前必须做 openid 全量 diff;新表未命中时必须回查旧 `app` 字段,命中则补写新表;仍无才按新用户创建 | 见 6.3 步骤 1.5;发布前跑全量 diff,0 差异才允许上线 | +| R4 | **token 单一凭证**:不新增 token 类型;v1 增强不改变签发与校验逻辑 | `issueToken` / `findUserByToken` 保持不变 | +| R5 | **回填无损**:旧 `app` 的每个 key 都必须进入 `user_app`;未在 `APP_REGISTRY` 登记的 appId 不能丢弃 | 未知 appId 走兜底 platform/provider 并告警,日志列出清单 | +| R6 | **语义冻结**,唯一例外是 `/user/list` 只返回 `status = active` | 已确认:现网 36 人全为 active,上线当天结果不变 | +| R7 | **直接切读,无开关**,回滚靠重新部署 | 因此 R3 的全量 diff 是唯一发布卡点,必须完成 | +| R8 | **不新增 v2 接口**;`app` 在“所有客户端改读 `apps` 后的下个发布周期”移除 | 移除前标注 `deprecated`,响应中保留 | + +### 12.1 属于“新增”、不受 R1 限制的内容 + +- `POST /user/app-config`、`POST /user/grant`:新路径,不影响任何 v1 接口。 +- `apps[]` 及其 `config`:只读投影字段。 +- `user_app`、`user_identity` 集合与索引。 + +### 12.2 发布前检查清单 + +1. 全量 diff 脚本输出 0 差异:逐用户、逐 appId、逐 openid 比对 `userId`。 +2. 用现网 36 个 openid 各跑一次 v1 `wxsignin`(预发环境),全部命中已有 `userId`,无新建账号。 +3. 用管理员账号的 token 调 `api/health` 管理端接口,管理员判定不变。 +4. `web_tcm` 登录后 `app.tcm.role` 仍可读(若该 app 有数据)。 +5. 普通账号调 `/user/list`,仍返回 401/403。 + +### 12.3 明确不做的 + +- 不新增 v2 路径、不做请求头版本协商。 +- 不在本次引入 `user_session`,单 token 互踢行为保持现状。 +- 不改 `security.token` 的存储方式与有效期。 +- 不要求 `api/health` 或前端在本次发布同步改动。 + +--- + +附:本方案只改 `api/user` 的模型与接口,不包含会话表、权限管理后台、细粒度 RBAC。`user_session` 作为独立事项另行评估。 diff --git a/doc/wechatpay-plan.md b/doc/wechatpay-plan.md new file mode 100644 index 0000000..02665ab --- /dev/null +++ b/doc/wechatpay-plan.md @@ -0,0 +1,433 @@ +# 陪诊订单微信支付接入方案 + +> 更新时间:2026-11-05 +> 状态:资金安全评审(第二轮)+ 微信支付接入规范评审已完成,修复项已并入,待实施 +> 2026-11-05 增补:下单页可选微信支付 / 线下支付,支付方式写入订单并支持待支付期间切换(线下支付不细分现金/转账,由平台补记);支付/退款异常统一兜底,错误详情(code/message/requestId)落库 +> 2026-11-05 资金评审修复:①取消待支付订单必须关单;②回调收到支付但订单已取消时自动退款;③关单失败改为当场查单确认(不依赖本期不做的巡检);④存在未决流水时禁止改价;⑤一单多流水、商户单号不重用;⑥退款结果保留管理端手动查单兜底 +> 2026-11-05 取消规则调整:用户端只保留「取消订单」(无删除入口)。待确认且未收款取消即物理删除;已确认或已收款转 `cancel_requested`,由该单陪诊师(限本人名下)或管理员确认后正式取消,不物理删除,已收款的同步进入退款 +> 2026-11-05 接入规范评审修订:①下单显式传 `time_expire`(支付窗口有边界);②prepay 过期沿用原单号重下,仅旧流水已关闭/失效才换新号;③补收银链路超时设置;④退款未成功应答先查退款、原单号重试一次;⑤同一订单发起支付串行化,防两条在途流水;⑥回调分支补 `cancel_requested`,回调研启退款改在应答之后;⑦补后台轻量巡检查单/超时关单,回调丢失可收敛 + +## 一、背景与现状 + +- C 端小程序(`ui/wxapp_escort`)下单流程已上线:`itemorder` 提交订单 → `escort_record` 落库(`status: pending`、`payment.status: unpaid`) +- 当前收款为客服协助线下完成,支付方式由平台在收款时补记(`offline_cash` / `offline_transfer`) +- 本期目标:用户在小程序内直接完成线上微信支付,取消已支付订单自动原路退款 +- 微信支付商户号已在官方申请完成 + +**现状要点(代码侧)**: + +| 现状 | 位置 | +| --- | --- | +| `payment` 已预留 `online_wechat` 方法枚举与 `unpaid/partial/paid/refunding/refunded` 状态 | `api/health/models/schema/escort_record.js` | +| openid 已在登录时经 `jscode2session` 存入 `user.app["wxapp-escort"].wxopenid`,与小程序 appid 天然一致 | `api/user/handler/users.js` | +| 服务价格以字符串元存储(`"500.00"`),订单 `totalFee` 为数字元 | `api/health/resource/services.js` | +| 线上域名 `api.huashengtec.com`(HTTPS),nginx 同域分流 `/health → 9004`,回调地址可直接复用 | `ui/wxapp_escort/utils/config.js`、`api/health/nginx_site.txt` | + +## 二、接入要素(已确认) + +| 要素 | 结论 | 说明 | +| --- | --- | --- | +| 支付产品 | **小程序支付** | JSAPI 下单(`POST /v3/pay/transactions/jsapi`)+ `wx.requestPayment` 调起 | +| 商户角色 | **普通商户** | 直连模式,报文只带 `mchid` / `appid` | +| API 版本 | **APIv3** | JSON 报文 + RSA-SHA256 签名;APIv2 已存量维护,不新接 | +| 验签方式 | **微信支付公钥** | `PUB_KEY_ID_` 格式序列号,长期有效免轮换 | +| 支付交互 | **下单选支付方式 → 微信支付立即拉起收银台** | 下单页可选「微信支付 / 线下支付」;选微信支付则下单成功后立即调起收银台,选线下支付则直接跳订单列表。列表/详情页保留「去支付」与「修改支付方式」入口 | +| 支付时限 | **下单传 `time_expire`** | 显式给出可支付窗口,默认下单后 24 小时(且不晚于服务开始当天);取值须落在下单后 1 分钟 ~ 15 天内,超出会被微信自动调整。**窗口以下单时间为起点固定计算,不随重新发起支付延长**;到期订单不可再用微信支付,只能改线下或取消,到期流水由巡检关单 | +| 线上退款 | **本期实现** | 取消已支付订单自动调退款 API 原路退回 | +| SDK | **Node 内置 crypto 自实现** | 官方仅提供 Java/Go/PHP SDK;签名/验签/AES-GCM 解密用 `node:crypto` + `node-fetch`,无新依赖 | + +## 三、整体业务流程 + +下单时先选支付方式,两条分支: + +``` +用户下单(itemorder 选择支付方式) +├─ 微信支付 ─> createRecord(payment.payChannel=online_wechat, status=unpaid) +│ └─ 下单成功后立即发起支付(见下方链路) +└─ 线下支付 ─> createRecord(payment.payChannel=offline, status=unpaid) + └─ 直接跳订单列表,等待平台收款后补记实际收款方式 +``` + +微信支付链路: + +``` +用户(小程序) health后端 微信支付 + │ 1.点"去支付"/下单成功 │ │ + │ ─────────────────> │ POST /escort-record/:id/pay + │ │ 2.校验(本人/待支付/未付款) │ + │ │ 3.写 payment_record(created) │ + │ │ 4.JSAPI下单(金额=分, openid, time_expire, out_trade_no=订单_id-序号) + │ │ ─────────────────────> │ 返回 prepay_id(有效期2小时) + │ │ 5.更新流水 prepayId+过期时间 │ + │ │ 6.私钥签名生成 paySign │ + │ 7.返回调起支付五参数 │ <───────────────────── │ + │ <───────────────── │ │ + │ 8.wx.requestPayment 调起收银台 ───────────────────>│ + │ │ │ 用户完成支付 + │ 9.前端回调(不可信) │ │ + │ ─────────────────> │ 10.查单接口:主动调微信查单确认 │ + │ │ ─────────────────────> │ trade_state=SUCCESS + │ │ 11.更新流水 pay_success → 刷订单快照 paid + │ 12.返回支付结果 │ │ + │ <───────────────── │ │ + │ │ 13.支付成功回调(异步,权威) │ + │ │ <───────────────────── │ 验签+解密+金额校验 + │ │ 14.更新流水+订单快照,幂等应答200 │ +``` + +**回调到达时的订单状态判定(关键分支)**: + +``` +支付成功回调(验签 + 解密 + 字段校验通过) +├─ 订单 status ∈ {pending, confirmed} 且 payment.status = unpaid +│ └─ 流水 pay_success → 刷订单快照 paid,正常进入履约 +├─ 订单 status = cancel_requested(用户已申请取消、尚未确认) +│ └─ 同上:钱已到账就按已支付如实记账,不提前退款;后续确认取消时按取消流程原路退款 +└─ 订单 status = cancelled(订单已正式取消) + ├─ 流水仍落 pay_success(钱确实到账,是财务事实,不能丢) + ├─ 订单快照保持 cancelled,不刷 paid(避免「已取消订单显示已收款」) + └─ 应答 200 之后再异步发起原路全额退款(写 refund_record(processing) → 调退款接口),不在应答前调外部接口 +``` + +退款流程(取消已支付线上订单时自动触发): + +``` +用户申请取消 ──> updateStatus(cancelled) ──> status = cancel_requested + └─ 陪诊师/管理员确认取消 ──> updateStatus(cancelled) + ├─ 1.先写 refund_record(processing) ← 先落库再调接口 + ├─ 2.调微信退款 API(POST /v3/refund/domestic/refunds) + ├─ 2.1 调用异常/超时 → 先查退款确认是否受理:未受理则用同一 outRefundNo 原参数重试一次;仍失败保持 processing 转人工 + ├─ 3.订单快照 payment.status = refunding + └─ 4.退款回调(REFUND.SUCCESS) ─> refund_record(success) ─> 订单快照 refunded +``` + +### 后台巡检查单(回调丢失的唯一兜底) + +- 服务启动时注册单一定时器,**默认运行**(不靠人工开启);每 10 分钟扫一次 `payment_record.status ∈ {created, closed_unconfirmed}`,按创建时间限定在最近 7 天内,避免全表扫描 +- `created` 流水:按 `outTradeNo` 查单 + - `SUCCESS` → 按回调同一套逻辑收敛(流水 `pay_success` + 刷订单快照;订单已取消则转退款) + - `NOTPAY` 且已过 `timeExpireAt` → 关单,流水置 `closed` + - 查单失败 → 记 `lastError`,下一轮重试 +- `closed_unconfirmed` 流水:查单确认,未支付则补记 `closed`,已支付则按退款处理 + +官方开发指引的核心原则: + +- **前端回调不可信**:`requestPayment` 回调后必须以后端查单结果为准 +- **回调是权威**:验签 → AES-256-GCM 解密 → 校验 `out_trade_no` 与金额 → 落库 → 5 秒内应答 200;重复推送做幂等(已处理直接 200) +- **防重复支付**:前端按钮防抖 + 服务端以「当前有效流水」为幂等粒度(prepay_id 未过期直接复用;过期但窗口内用原单号重下;旧流水已关闭或窗口到期才换新 `outTradeNo`,唯一索引兜底) + +### 支付方式选择与流转 + +**字段拆分**:把「用户选择的支付方式意向」与「实际收款方式」分开记录,避免把还没收到的钱记成已按某方式收款。用户端只提供「微信支付 / 线下支付」两个选项;线下支付不细分现金/转账,实际收款方式由平台收款时补记为 `offline_cash` 或 `offline_transfer`。 + +| 字段 | 取值 | 含义 | 写入方 | +| --- | --- | --- | --- | +| `payment.payChannel` | `online_wechat` / `offline` | 用户下单时选择的支付渠道 | 下单时写入;待支付期间用户可自助修改 | +| `payment.method` | `""` / `online_wechat` / `offline_cash` / `offline_transfer` | 实际收款方式 | 线上支付成功后由回调写入;线下由平台收款时补记 | + +**状态矩阵**: + +| 场景 | payChannel | method | payment.status | 列表/详情展示 | +| --- | --- | --- | --- | --- | +| 选微信支付,尚未支付(含中途取消) | online_wechat | `""` | unpaid | 「待支付」+「去支付」 | +| 选微信支付,超过支付窗口未付 | online_wechat | `""` | unpaid | 「支付已超时」,无「去支付」,仅可改线下或取消 | +| 微信支付成功 | online_wechat | online_wechat | paid | 「已支付」 | +| 选线下支付,平台尚未收款 | offline | `""` | unpaid | 「线下支付,待收款」 | +| 线下收款完成,平台补记 | offline | offline_cash / offline_transfer | paid | 「已支付(现金/转账)」 | +| 线上已支付后取消 | online_wechat | online_wechat | refunding → refunded | 「退款中 / 已退款」 | +| 线下已收款后取消 | offline | offline_cash / offline_transfer | refunding | 「退款中」(线下人工退款核销) | +| 用户申请取消(已确认或已收款) | 保持原值 | 保持原值 | 保持原值 | 「待取消」,等待陪诊师/管理员确认 | + +**取消规则(用户端只保留「取消订单」按钮)**: + +- 待确认且未收款:用户取消后订单直接物理删除,无需二次确认 +- 已确认或已收款:用户取消后订单进入 `cancel_requested`(待取消),**不物理删除**;由该订单的陪诊师或管理员确认后才转为 `cancelled`,已收款的同步进入退款流程 +- `cancel_requested` 期间用户不可再次取消、不可修改支付方式;陪诊师只能确认自己名下的订单,管理员不限 +- 已取消、已完成为终态,不可再取消 + +**修改支付方式规则**: + +- 允许时机:订单 `status ∈ {pending, confirmed}` 且 `payment.status = unpaid`(未收到钱之前都可改) +- 用户端在订单详情页切换 `payChannel`:`online_wechat` ↔ `offline` +- 改回 `online_wechat` 后再次「去支付」时,**必须使用新的商户订单号**(`订单_id + "-" + 新尝试序号`),不复用已关闭的单号 +- 已支付(`paid` / `refunding` / `refunded`)、`cancel_requested` 或已进入服务中(`in_progress`)的订单,一律不可修改支付方式 + +**关单是切换与取消的前置动作**(防止旧 `prepay_id` 在 2 小时内仍被支付,造成「订单已取消 / 已改线下,钱却进来了」): + +``` +切换为线下 / 取消订单 / 支付窗口到期 +└─ 存在 payment_record(created) + ├─ 1.调用微信关单接口 + ├─ 2.关单成功 → 流水置 closed + └─ 3.关单失败 → 立即调查单接口确认(不等巡检) + ├─ trade_state = SUCCESS → 实际已付款:中止本次切换/取消, + │ 提示「订单已支付」,转入退款流程 + └─ 未支付 / 查单也失败 → 流水置 closed_unconfirmed 并放行, + 交对账核对(订单仍按用户意愿处理) +``` + +> 关单失败时「当场查单一次」是立即兜底;仍未确认的中间态由后台巡检查单收敛(见第五节)。 + +### 支付异常处理(统一兜底 + 错误落库) + +**原则**:不按异常类型做差异化业务分支,所有外部异常统一兜底、统一提示;但**错误详情必须落库**,供财务与运维排查。 + +**异常来源与处理**: + +| 阶段 | 典型异常 | 处理方式 | +| --- | --- | --- | +| JSAPI 下单 | 网络超时、连接失败、`APPID_MCHID_NOT_MATCH`、`MCHID_NOT_EXISTS`、`SIGN_ERROR`、`NO_AUTH` 等 | 记录流水 `lastError`;订单保持 `unpaid`;前端提示可重试或改用线下支付 | +| 查单 | 同上 | 记录 `lastError`;前端按最后一次已知状态展示 | +| 关单 | 同上 | 记录 `lastError`;**当场查单一次确认**,已支付则中止切换/取消并转退款(见本节关单流程) | +| 退款 | 商户余额不足、参数错误、网络异常 | 记录 `refund_record.lastError`;**超时/系统异常先查退款**:确认未受理则同一 `outRefundNo` 原参数重试一次;明确业务错误(余额不足等)直接转人工,保持 `processing` | +| 回调验签/解密/字段校验 | 验签失败、解密失败、`mchid` / `appid` / `currency` / 金额与本地不一致 | logger 记录并应答 4XX/5XX,**不落业务库**(报文不可信,不能作为数据来源) | + +**落库字段**(`payment_record` / `refund_record` 共用同一结构): + +```js +lastError: { + stage: String, // create 下单 / query 查单 / close 关单 / refund 退款 + code: String, // 网络异常固定 NETWORK_ERROR;微信侧错误取应答 code;HTTP 异常记状态码 + message: String, // 微信返回 message 或系统异常原文,截断 500 字符 + requestId: String, // 微信应答头 Request-ID,向微信侧排查时提供 + httpStatus: Number, // HTTP 状态码,网络异常时为 0 + at: Date // 发生时间 +}, +errorCount: Number, // 累计失败次数,用于识别反复失败 +lastAttemptAt: Date, // 最近一次调用时间 +``` + +**统一封装约定**(`utils/wechatpay.js`): + +- 所有微信 API 调用异常统一抛 `WechatPayError`,字段固定为 `{ stage, code, message, requestId, httpStatus }` +- 所有请求显式设置连接/读取超时(默认 5 秒);超时与连接中断按「结果不确定」处理,走查单收敛,不直接判失败 +- 网络/SDK 异常 → `code = "NETWORK_ERROR"`,`message` 保留原始错误文本 +- HTTP 非 2XX → `code` / `message` 取微信应答体,`requestId` 取响应头 +- `message` 统一截断 500 字符,避免超长文本撑库 + +**前端统一处理**: + +- `payOrder` 请求失败 → 提示「支付发起失败,请稍后重试;如持续失败可改用线下支付」 +- `wx.requestPayment` 返回 `requestPayment:fail cancel` → 提示「已取消支付」,订单保持待支付 +- 其他 fail → 先调查单兜底(可能支付已成功但网络中断),再按查单结果提示 +- 不区分错误码,不向用户暴露内部错误详情 + +## 四、数据模型设计(对账导向) + +### 设计原则:订单与支付分离,流水是事实源 + +``` +escort_record (业务订单) payment_record (支付流水) refund_record (退款流水) +├─ status: 服务履约状态 ├─ outTradeNo 商户订单号 ├─ outRefundNo 商户退款单号 +└─ payment: 汇总快照(展示用) ├─ transactionId 微信支付订单号 ├─ refundId 微信退款单号 + unpaid/paid/refunded... ├─ 金额(分)/状态机/事件时间戳 ├─ 金额(分)/状态/入账账户 + └─ 每次支付尝试一条文档 └─ 一次退款一条文档 +``` + +- **流水表为财务事实源**:状态每次变更落时间戳,链路完整可审计 +- **订单上的 `payment` 保留为汇总快照**:列表/详情展示免 join,写完流水后同步刷新 +- **金额全链路用「分」(int)**:与微信账单口径一致,杜绝元/分浮点误差,只在展示层转元;**由 `service.price` 字符串(如 `"500.00"`)直接解析为整数分**(按小数点拆位,不做 `元 × 100` 浮点运算),换算收敛在支付模块单点 + +### payment_record(支付流水) + +```js +{ + // 业务关联 + bizType: "escort", // 业务类型,后续培训报名等复用 + recordId: ObjectId, // 关联 escort_record._id + userId: ObjectId, // 付款用户(按用户查支付历史) + + // 微信侧标识(对账核心字段) + outTradeNo: String, // 商户订单号 = 订单_id + "-" + 尝试序号,唯一索引(永不重用) + attemptNo: Number, // 第几次支付尝试(从 1 起),区分同单多次发起 + transactionId: String, // 微信支付订单号,唯一稀疏索引(支付成功后回填) + prepayId: String, // 预支付会话标识 + prepayExpiresAt: Date, // prepay_id 过期时间(2小时,复用判断) + timeExpireAt: Date, // 下单传入的 time_expire(支付窗口终点) + + // 渠道信息(与微信账单核对的维度) + appid: String, + mchid: String, + tradeType: "JSAPI", + + // 金额(分) + totalFee: Number, // 应付金额 + payerTotal: Number, // 用户实付(券后,回调回填) + + // 状态机 + 事件时间戳(审计链) + status: "created", // created → pay_success / closed + // created → closed_unconfirmed(关单失败且查单未确认) + // pay_success → refunding → refunded + closeUnconfirmed: Boolean, // 关单结果不确定时置 true,进人工核对 + createdAt, prepayedAt, paidAt, closedAt, + + // 支付成功回调关键留档(审计/争议处理) + bankType: String, // 支付方式(如 OTHERS/CMB_CREDIT) + successTime: Date, // 微信侧支付完成时间 + + // 异常留档(任何外部异常都记,不区分类型,结构见第三节「支付异常处理」) + lastError: { stage, code, message, requestId, httpStatus, at }, + errorCount: Number, // 累计失败次数 + lastAttemptAt: Date, // 最近一次调用时间 + + meta: { createtime, updatetime } +} +// 索引:{ outTradeNo: 1 } unique、{ transactionId: 1 } unique sparse、 +// { recordId: 1 }、{ userId: 1, createdAt: -1 } +``` + +**流水粒度规则(一单可多条,单号不重用)**: + +- 同一订单每次重新发起支付都新建一条流水,`outTradeNo` 递增后缀(`-1`、`-2`…),**不复用已关闭的单号** +- 订单 `payment.paymentRecordId` 指向「当前有效」的那条流水;历史流水保留作为审计 +- 单条流水在 prepay_id 有效期内重复点「去支付」时直接复用,不新建 +- prepay_id 已过期但仍在支付窗口内:**沿用该流水与同一 `outTradeNo`、原下单参数重新下单**,刷新 `prepayId` / `prepayExpiresAt`,不新建流水 +- 只有该流水已 `closed`(关单成功)或已超出 `timeExpireAt`(微信侧不可再付)才新建流水换新号 +- 财务核对以 `outTradeNo` 为键:一单多次尝试对应多个未支付单号 + 至多一笔成功 + +### refund_record(退款流水) + +```js +{ + paymentId: ObjectId, // 关联 payment_record + recordId: ObjectId, // 冗余关联订单 + outTradeNo: String, // 原商户订单号(冗余) + + outRefundNo: String, // 商户退款单号 = 订单_id + "-R1",唯一索引 + refundId: String, // 微信退款单号,唯一稀疏索引 + refundAmount: Number, // 退款金额(分) + totalAmount: Number, // 原订单金额(分) + reason: String, // 退款原因(= 订单取消原因) + + status: "processing", // processing → success / abnormal / closed + userReceivedAccount: String, // 退款入账账户(回调返回,客服答疑用) + successTime: Date, + lastQueriedAt: Date, // 最近一次主动查询退款结果的时间(回调丢失时的兜底依据) + + // 异常留档(退款失败可查原因,如商户余额不足) + lastError: { stage, code, message, requestId, httpStatus, at }, + errorCount: Number, + lastAttemptAt: Date, + + meta: { createtime, updatetime } +} +``` + +### 对账场景 + +| 对账场景 | 做法 | +| --- | --- | +| 日常对账 | 下载微信**交易账单** → 按 `transactionId` / `outTradeNo` 逐笔与 `payment_record` 核对金额与状态;退款笔目对 `refund_record` | +| 状态差异 | 回调丢失导致流水停在中间态 → 后台巡检查单补齐(见第三节);T+1 再用交易账单人工核对 | +| 客诉/争议 | `bankType` + `successTime` + 完整时间戳链还原每笔交易过程 | +| 用户查"我付了哪笔" | `userId + createdAt` 索引直接查流水 | +| 退款卡单 | 退款回调丢失导致长期停在 `processing` → 管理端「查询退款结果」调退款查单接口,补写 `success` / `abnormal` | +| 关单未确认 | 流水 `closed_unconfirmed` → 按 `outTradeNo` 查单确认终态,补记 `closed`;若已支付则转退款 | + +**本期退款约束**:一笔支付只发起一次全额退款(`outRefundNo = 订单_id + "-R1"`),不支持部分退款;重试必须沿用同一 `outRefundNo`(微信对同号退款幂等返回原退款单);退款结果除回调外,由管理端手动查询兜底。 + +## 五、后端改动清单(api/health) + +| # | 文件 | 内容 | +| --- | --- | --- | +| 1 | `utils/wechatpay.js`(新增) | APIv3 请求签名、应答/回调验签(含 `WECHATPAY/SIGNTEST/` 探测流量处理)、AES-256-GCM 回调解密、JSAPI 下单/查单/关单/退款调用、调起支付 paySign 生成、Request-ID 日志;所有调用异常统一抛 `WechatPayError`(结构见第三节) | +| 2 | `models/schema/payment_record.js`(新增) | 支付流水,见第四节 | +| 3 | `models/schema/refund_record.js`(新增) | 退款流水,见第四节 | +| 4 | `handler/payment.js`(新增) | `createPayment`(校验金额 > 0 / 订单状态 / 未支付 / **未超支付窗口** → 无有效流水时新建 `outTradeNo` → 落流水 → 微信下单 → 返回五参数,prepay 有效期内复用、过期用原单号重下)、`queryPayment`(主动查单落流水+刷快照)、`paymentNotify`(验签→解密→校验 `mchid`/`appid`/`currency`/金额→按订单状态分支写流水→应答 200→已取消订单再异步发起退款)、`refundNotify`、`queryRefund`(管理端查退款结果兜底);**所有外部异常统一捕获,写入 `lastError` / `errorCount` / `lastAttemptAt` 后再返回通用错误提示**;退款异常先查退款、未受理则原单号重试一次;同一订单的 `createPayment` 按 recordId 串行(进程内锁),防止并发产生两条在途流水;模块内提供巡检函数,服务启动时注册定时器默认运行 | +| 5 | `handler/escort_record.js`(改造) | ① `createRecord`:接收用户端 `payment.payChannel`(仅 `online_wechat` / `offline`,默认 `online_wechat`),`method` 留空待支付成功或平台补记;管理员代客下单仍可指定 `method`。② `updateRecord`:为用户端放开 `payment.payChannel`,仅 `pending` / `confirmed` 且 `unpaid` 可改;**存在 `created` 流水的订单禁止修改 `payment.totalFee`**(要调价先关单)。③ 切换为线下:关单 + 失败当场查单确认,已支付则拒绝切换并转退款。④ `updateStatus` 取消:未确认且未收款 → 物理删除;已确认或已收款 → `cancel_requested`,陪诊师/管理员确认后转 `cancelled`,线上已收款订单再走退款流程;线下收款订单维持原人工退款。⑤ 金额 ≤ 0 的订单禁止发起线上支付;⑥ 支付窗口到期由巡检关单,流水置 `closed` | +| 6 | `routes/index.js` | `POST /escort-record/:id/pay`(requireAuth + createLimit 限流)、`GET /escort-record/:id/pay/status`(requireAuth)、`POST /escort-record/:id/refund/query`(requireAdmin,退款查单兜底)、`POST /pay/notify`、`POST /pay/refund-notify`(后两条**无鉴权**,微信服务器直调,靠验签保安全;注册在 `/:id` 路由之前防抢占) | +| 7 | `models/schema/escort_record.js` | `payment` 保持汇总快照角色:新增 `payChannel`(用户选择的支付渠道)与 `paymentRecordId`(指向当前有效流水);`method` 语义收窄为「实际收款方式」;其余细节字段移入流水表 | +| 8 | `conf.json` | 新增 `wechatpay` 配置段(结构占位,密钥部署时填系统级配置 `/etc/ehason/conf.json`,APIv3 密钥走环境变量,不进仓库) | + +配置段结构: + +```json +"wechatpay": { + "mchid": "", + "appid": "", + "merchantSerial": "", + "privateKeyPath": "", + "apiv3KeyEnv": "WXPAY_APIV3_KEY", + "publicKeyId": "", + "publicKeyPath": "", + "notifyBase": "https://api.huashengtec.com/health", + "payWindowHours": 24 +} +``` + +## 六、前端改动清单(ui/wxapp_escort + 管理端) + +| # | 文件 | 内容 | +| --- | --- | --- | +| 1 | `utils/api.js` | escort 段新增 `payOrder(id)`、`getPayStatus(id)` | +| 2 | `pages/escort/itemorder.js` | 新增支付方式选择(微信支付 / 线下支付,默认微信支付);提交订单时带 `payment.payChannel`。选微信支付:下单成功 → 立即 `payOrder` → `wx.requestPayment` → 查单确认 → 按结果跳转;选线下支付:下单成功后直接跳订单列表并提示线下支付 | +| 3 | `pages/escort/recordlist` / `recorddetail` | `unpaid` 订单按 `payChannel` 展示:`online_wechat` 显示「待支付」+「去支付」(超过支付窗口则显示「支付已超时」并隐藏去支付,只保留改线下 / 取消),`offline` 显示「线下支付」。详情页保留「取消订单」(无删除按钮):待确认且未收款取消即删除;已确认/已收款提示「取消申请已提交」。详情页增加「切换支付方式」入口(仅待支付可改);支付按钮防抖 | + +管理端(`ui/wxapp_escort_admin`):`pages/order/orderDetail` 需展示 `refunding` / `refunded` 与 `payChannel`,并新增「查询退款结果」按钮(调 `POST /escort-record/:id/refund/query`),用于退款回调丢失时的人工兜底;`orderEdit` 在存在未决流水时禁用金额输入。 + +## 七、关键技术点与易错点 + +1. **金额换算**:由 `service.price` 字符串按小数点拆位直接得到整数分(不经过浮点);回调中校验 `amount.total` 与流水一致,防篡改 +2. **openid 一致性**:必须用发起支付小程序自身 appid 下的 openid(现有 `user.app["wxapp-escort"].wxopenid` 满足);管理端小程序是另一个 appid,严禁串用 +3. **幂等与并发**: + - 回调可能重复、乱序推送 → 以 `outTradeNo` / `outRefundNo` 唯一索引 + 状态条件更新兜底 + - 同订单重复请求支付 → prepay_id 未过期(2 小时内)复用原支付参数,不新建流水 + - **同一订单的 `createPayment` 串行执行**(按 recordId 的进程内锁),防并发各建一条在途流水 + - 需要新建流水时一律换新 `outTradeNo`;前端支付按钮防抖 +4. **回调时效**:验签后 5 秒内应答 200/204,业务处理放应答之后(或快速完成);应答失败微信将按 15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h 重发至多 15 次 +5. **签名探测流量**:微信会不定期发送 `WECHATPAY/SIGNTEST/` 开头签名的探测请求,验签失败按规范应答 4XX/5XX + `{"code":"FAIL"}`,不得当作攻击忽略或崩溃 +6. **prepay_id 2 小时 / 支付窗口由 `time_expire` 决定**:prepay 有效期内重复点「去支付」直接复用;过期但仍在支付窗口内 → **沿用同一 `outTradeNo` 与原参数重新下单**刷新 prepay(同一业务单不因重试换号)。支付窗口(`time_expire`)到期 → 关单、流水置 `closed`,订单按失败终态处理。**prepay 过期不等于交易单失效**:不传 `time_expire` 时微信侧默认 7 天内仍可支付 +7. **调起支付签名与请求签名是两套**:`paySign` 用 `appId`/`timeStamp`/`nonceStr`/`package` 四行签名串 + 商户私钥;`appId` 必须与下单 appid 一致 +8. **服务器出网**:health 服务需能访问 `api.mch.weixin.qq.com`;`notify_url` 必须公网 HTTPS +9. **Request-ID 日志**:调微信接口时打印应答 HTTP 头 `Request-ID`,排障时提供给微信侧快速定位 +10. **支付方式切换与关单**:用户从微信支付改为线下支付、或取消订单时,若已有未支付流水,必须调用关单接口。否则旧 `prepay_id` 在 2 小时内仍可被支付,出现「已取消 / 已改线下却线上付了」的双重收款。**关单失败不能只记日志**:立即查单确认——已支付则中止切换并转退款,未确认则标 `closed_unconfirmed` 交对账 +11. **线下支付不改动现有履约链路**:`payChannel=offline` 的订单仍是 `unpaid`,平台收款后按现有管理端补记流程写入 `method` + `paidFee` + `paid`,用户端不做支付动作 +12. **错误落库不能吞异常**:支付/退款失败时先写 `lastError` 再返回通用提示;若错误字段写库本身失败,必须 `logger.error` 兜底输出完整错误(含 `requestId`),不能静默丢弃 +13. **错误信息脱敏**:`lastError.message` 只存微信返回的 `message` 与系统错误原文,不写入请求报文、私钥、openid 等敏感内容;长度截断 500 字符 +14. **已取消订单收到支付**:回调到达时订单可能已 cancelled。钱必须入账(流水落 `pay_success`),订单不能显示已收款,必须自动全额退款。这是「取消 + 关单失败 / 竞态」的必然残留,不能省;退款在**应答之后异步发起**,不占用 5 秒应答窗口 +15. **商户单号规则**:同一业务单在同一支付窗口内只留一条在途流水;prepay 过期用原 `outTradeNo` 重下,**旧单已关单或支付窗口到期后才换新号**(`订单_id` + 递增序号)。已关闭的单号永不复用 +16. **改价与流水一致性**:存在 `created` 流水时禁止修改 `totalFee`;金额变更必须先关单,否则微信侧金额与本地流水错位,对账无法核对 +17. **回调校验要全**:除 `out_trade_no` 与金额,还需校验解密报文中的 `mchid`、`appid`、`currency = CNY`,防跨商户报文或异常报文混入 +18. **快照刷新失败**:流水已 `pay_success` 但订单快照刷失败时,必须 `logger.error` 记录,并依靠下一次回调 / 查单重刷(更新按状态条件幂等覆盖) +19. **退款幂等与兜底**:`outRefundNo` 唯一索引捕获重复取消(返回「退款处理中」而非 500);退款调用超时/系统异常时**先查退款确认是否受理,未受理用原单号原参数重试一次**;退款回调丢失时用管理端「查询退款结果」补写终态 +20. **回调丢失必须由后台自己收敛**:不能只靠用户回页面或管理端手动触发。巡检随服务启动默认运行,扫在途流水查单:`SUCCESS` 按回调同一套逻辑收敛,到期仍 `NOTPAY` 则关单 + +## 八、部署前检查清单 + +**商户平台侧材料(缺一不可)**: + +- [ ] JSAPI 支付权限已开通(商户平台 → 产品中心) +- [ ] 商户号与小程序 APPID 完成授权绑定(商户平台发起 + 公众平台确认,绑定后不可解绑) +- [ ] 商户 API 证书:`apiclient_cert.pem` / `apiclient_key.pem` + 证书序列号 +- [ ] APIv3 密钥(32 位,账户中心 → API 安全) +- [ ] 微信支付公钥:`pub_key.pem` + 公钥 ID(`PUB_KEY_ID_` 开头) +- [ ] 商户号账户余额充足(退款从账户余额扣除,余额不足会直接退款失败) + +**合规(重要)**: + +- [ ] 交易类小程序须按《交易类小程序运营规范》接入**订单发货管理功能**,否则可能被公众平台限制支付权限,正式环境调不起支付 + +**服务器侧**: + +- [ ] `/etc/ehason/conf.json` 补 `wechatpay` 段;`WXPAY_APIV3_KEY` 环境变量注入 +- [ ] 出网连通 `api.mch.weixin.qq.com`;`api.huashengtec.com` HTTPS 证书有效 +- [ ] 防火墙/安全组放行微信支付回调 IP 段(支付回调与退款回调是不同 IP 段,均需放行 443 入站);有 WAF 时确认不拦截回调请求 + +## 九、验证与测试 + +1. **本地自测**:签名串构造自校验(官方签名生成/验证规范逐条比对);回调解密用官方示例报文验证;**用项目自身的签名/验签/解密能力调 `POST /v3/security/echo` 实测**(读代码无法证明签名生效) +2. **沙箱/小额联调**:1 分钱真实下单 → 支付 → 回调 → 查单 → 退款全链路 +3. **异常路径**:中途取消支付、重复回调、prepay_id 过期重下(应沿用原单号)、支付后立即取消(自动退款)、回调延迟时的查单兜底、支付方式切换(微信→线下后旧 prepay 不可再支付)、支付按钮连续点击、并发发起支付(只产生一条在途流水)、**支付窗口到期后关单**、**取消后用旧 prepay 完成支付(回调自动退款)**、**关单失败后切换(查单拦截已支付)**、**改线下再改回微信(新单号可正常支付)** +4. **失败落库验证**:模拟网络不可达(错误码 `NETWORK_ERROR`)、模拟微信业务错误(如 `NO_AUTH`)、模拟退款失败 → 检查 `payment_record` / `refund_record` 的 `lastError`(含 `code`/`message`/`requestId`)、`errorCount`、`lastAttemptAt` 是否正确写入,且接口返回的是统一提示而非内部错误详情 +5. **资金安全专项**:①取消待支付订单后用旧 prepay 完成支付 → 校验自动退款与 `refund_record`;②管理员对存在 `created` 流水的订单改价 → 应被拒绝;③同一订单多次发起支付 → 仅一条在途流水、仅一笔成功;④重复点击取消 → 返回「退款处理中」不报 500;⑤退款回调丢失 → 管理端查询补写终态;⑥金额为 0 的订单走微信 → 应被拒绝;⑦退款调用超时 → 自动查退款并原单号重试,不产生第二笔退款 +6. **兜底链路验证**:①支付成功但人为让回调丢失 → 巡检在下一轮查单补单,订单转 paid;②回调验签失败 → 应答 4XX,随后由巡检收敛;③支付窗口到期未付 → 巡检查单为 `NOTPAY` 后关单,流水置 `closed` +7. 上线前按官方《接入质量检查清单》逐项核对 + +## 十、后续迭代项(本期不做) + +- 下载交易账单/资金账单 API 的自动对账任务(字段已对齐,随时可加;**本期经确认不做**,由巡检查单 + 人工下载账单对账兜底) +- 巡检的多频率退避与告警(本期固定 10 分钟一轮,够用) +- 退款 `ABNORMAL`(用户银行卡作废/冻结)自动发起异常退款(本期转人工,资金停留在退款中间账户由财务处理) +- 主备域名自动切换(本期只连主域名 `api.mch.weixin.qq.com`,接受单通道风险) +- 部分退款 / 多次退款(本期一单一退,`outRefundNo` 固定 `-R1`) +- 培训报名(training_application)复用 payment_record 接入支付