# 用户多应用模型改造方案 | 项 | 内容 | |---|---| | 状态 | 已评审,待确认实施 | | 日期 | 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` 作为独立事项另行评估。