1058 lines
46 KiB
Markdown
1058 lines
46 KiB
Markdown
# 用户多应用模型改造方案
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| 状态 | 已实施(P1-P3 完成;P4 未做、P5 部分完成),2026-11-06 按代码回填 |
|
||
| 日期 | 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" },
|
||
"web-escort-admin": { platform: "web", provider: "password" },
|
||
"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<String, Mixed>` 的原因:
|
||
|
||
- 每个应用的配置项不同,用统一子 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.<a>.<b>": 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` |
|
||
| `api/user/scripts/create_web_admin.js` | Web 后台管理员初始化脚本:P2 前写旧 `app`,P4 后改写入 `user_app`(`appId=web-escort-admin`) |
|
||
|
||
---
|
||
|
||
## 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` 或前端在本次发布同步改动。
|
||
|
||
---
|
||
|
||
## 13. 与陪诊业务(管理员代客下单)的联动决策
|
||
|
||
`doc/escort-admin-sync-plan.md` 的 B3(管理员代客下单)已定案采用「档案锚定」归属,与本方案的安全约束互洽,记录如下,避免实施时重新讨论:
|
||
|
||
1. **health 侧不新增按 userId 查询用户的接口。** 管理员建单时订单归属取所选健康档案的 `profile.userId`,不传、也不信任管理员传入的 userId。这与 `api/health/utils/user_service.js` 中「user 服务不接受按 userId 明文查询」的既有约束一致。
|
||
2. **档案无归属时订单 `userId` 留空,后期补。** `escort_record.userId` 非必填;补归属由管理员在 health 侧订单编辑完成(`RECORD_FIELDS` 已含 `userId`),不依赖 user 服务。留空订单对 C 端不可见(按 userId 查询不命中),补齐后客户才可见。
|
||
3. **补归属不依赖账号合并,也不新增接口。** 管理端通过 `POST /user/list`(已实现为「`wxapp-escort` 有效成员」口径,支持 keyword 且返回 `total`)人工核对客户,确认后把 `userId` 写入档案或订单;unionid / 手机号合并只影响账号归并,与补归属无关。
|
||
4. **`web-escort-admin`(Web 后台)如后续支持代客下单,沿用同一规则**:档案锚定、不传 userId、无归属留空。
|
||
5. 本节为业务层约定,不改动 R1-R8 任何契约。
|
||
|
||
---
|
||
|
||
附:本方案只改 `api/user` 的模型与接口,不包含会话表、权限管理后台、细粒度 RBAC。`user_session` 作为独立事项另行评估。
|