@@ -1,6 +1,6 @@
# 后台管理多账号与 Tab 访问权限方案
更新时间：`2026-07-14 `
更新时间：`2026-07-23 `
## 1. 文档定位
@@ -10,12 +10,12 @@
## 2. 当前基线与目标
当前后台由 `GENARRATIVE_ADMIN_USERNAME` 、`GENARRATIVE_ADMIN_PASSWORD` 提供唯一管理员账号，`apps/admin-web/src/app/adminRoutes.ts` 定义 18 个一级 Tab， `server-rs/crates/api-server/src/modules/admin.rs` 中的后台路由只校验统一的管理员 JWT。
当前后台由 `GENARRATIVE_ADMIN_USERNAME` 、`GENARRATIVE_ADMIN_PASSWORD` 提供唯一管理员账号，`apps/admin-web/src/app/adminRoutes.ts` 定义 15 个可分配业务 Tab，并另有 owner-only 的“账号管理”Tab； `server-rs/crates/api-server/src/modules/admin.rs` 中的后台路由只校验统一的管理员 JWT。
改造后的目标如下：
1. 现有环境变量账号升级为 `owner` ，仍由部署环境提供，不迁移、不复制到 SpacetimeDB。
2. owner 始终拥有全部 18 个业务 Tab 权限，并独占“账号管理”Tab 和账号管理 API。
2. owner 始终拥有全部 15 个业务 Tab 权限，并独占“账号管理”Tab 和账号管理 API。
3. owner 可以创建、修改、启停 member； `admin_account` 。
4. member 按一级 Tab 分配权限；获得一个 Tab 权限即获得该页面内全部读写能力，页面内部二级 Tab、弹窗和操作区继承一级权限。
5. member JWT 每次请求都重新读取当前账号并校验 `enabled` 、`token_version` 和实时权限，权限、密码或启停变更应立即让旧 JWT 失效。
@@ -26,7 +26,7 @@
- owner 用户名和密码继续读取 `GENARRATIVE_ADMIN_USERNAME` 、`GENARRATIVE_ADMIN_PASSWORD` 。
- owner 是环境变量构造的虚拟账号，不写入 `admin_account` ，不允许通过后台改名、改密、禁用或删除。
- owner 始终拥有本文列出的全部 18 个可分配权限，不能在前端取消，也不从数据库加载权限。
- owner 始终拥有本文列出的全部 15 个可分配权限，不能在前端取消，也不从数据库加载权限。
- “账号管理”是 owner-only 能力。它可以作为新增一级路由 `accounts` / `#accounts` 展示，但 `accounts` 不进入 `ADMIN_TAB_PERMISSIONS` ，不能写入 member 的 `permissions_json` 。
- owner 会话返回 `accountRole = "owner"` 、`roles = ["admin", "owner"]` ；账号管理权限必须根据服务端确认的 `accountRole` 判断，不能只相信前端角色字符串。
- owner 配置缺失时，后台整体保持未启用状态；不能依赖数据库中的 member 绕过 owner 引导配置启动后台。
@@ -41,7 +41,7 @@
## 4. 权限标识
`ADMIN_TAB_PERMISSIONS` 必须是 shared-contracts 与 admin-web 共用的闭合集合，值与现有 `AdminRouteId` 一致。18 个可分配权限如下，顺序同时作为前端寻找“第一可访问项”的稳定顺序：
`ADMIN_TAB_PERMISSIONS` 必须是 shared-contracts 与 admin-web 共用的闭合集合，值与现有 `AdminRouteId` 一致。15 个可分配权限如下，顺序同时作为前端寻找“第一可访问项”的稳定顺序：
| permission id | 一级 Tab | hash |
| --- | --- | --- |
@@ -60,9 +60,6 @@
| `editor-generation-pricing` | 模型定价 | `#editor-generation-pricing` |
| `editor-showcase` | 精选审核 | `#editor-showcase` |
| `editor-assets` | 素材查询 | `#editor-assets` |
| `creation-announcement` | 入口公告 | `#creation-announcement` |
| `creation-entry` | 入口开关 | `#creation-entry` |
| `work-visibility` | 作品可见性 | `#work-visibility` |
权限数组必须去重并按上表顺序规范化后保存。保存时拒绝未知值和 `accounts` ；读取旧数据时遇到未知值应忽略并记录告警，绝不能将未知值解释为全权限。空数组合法，表示 member 可以登录但没有业务页面权限。
@@ -83,7 +80,7 @@
| `username` | `String` | `unique` ；登录名，创建后不可修改；按 `trim + ASCII lowercase` 规范化 |
| `display_name` | `String` | 展示名，去除首尾空白后 1 至 64 字符 |
| `password_hash` | `String` | Argon2id PHC 字符串；只在内部登录查询中返回给 api-server，永不进入 HTTP DTO、日志或前端状态 |
| `permissions_json` | `String` | 规范化后的 Tab permission JSON；只允许第 4 节 18 个值，空数组为 `[]` |
| `permissions_json` | `String` | 规范化后的 Tab permission JSON；只允许第 4 节 15 个值，空数组为 `[]` |
| `enabled` | `bool` | 是否允许登录和继续使用现有 JWT |
| `token_version` | `u64` | 初始为 `1` ；权限、密码或启停状态发生有效变化时加 `1` |
| `created_by` | `String` | 创建者后台 subject；当前只能是 owner subject |
@@ -163,7 +160,7 @@ accountRole: "owner" | "member"
tabPermissions: string[]
```
owner 返回全部 18 个 permission id； `GET /admin/api/me` 同样执行逐请求校验并返回实时权限，供刷新页面后恢复导航。
owner 返回全部 15 个 permission id； `GET /admin/api/me` 同样执行逐请求校验并返回实时权限，供刷新页面后恢复导航。
后台所有面向运营展示的管理员身份统一使用 `displayName` 。审计表继续保存稳定 subject，例如 owner subject 或 `admin-account-<uuid>` ； `admin_account` 批量解析显示名称，同时兼容历史用户名记录。已无法解析的历史主体统一展示“已停用管理员”，前端不得直接渲染 `operatorUserId` 、账号 ID 或登录用户名代替显示名称。对写接口，显示名目录必须在主事务前加载，或在主事务成功后降级为占位文案；不得因二次读取失败把已提交写入伪装成失败。
@@ -196,10 +193,6 @@ owner 返回全部 18 个 permission id；
| `GET` | `/admin/api/tracking/event-keys` | `tracking OR tasks` |
| `GET` | `/admin/api/database/tables` | `tables` |
| `GET` | `/admin/api/database/tables/{table_name}/rows` | `tables` |
| `GET` | `/admin/api/creation-entry/config` | `gray-release OR creation-announcement OR creation-entry` |
| `POST` | `/admin/api/creation-entry/config` | `creation-entry` |
| `POST` | `/admin/api/creation-entry/config/banners` | `creation-announcement` |
| `POST` | `/admin/api/creation-entry/config/interactions` | `creation-entry` |
| `GET` | `/admin/api/feature-gates` | `gray-release` |
| `PUT` | `/admin/api/feature-gates` | `gray-release` |
| `GET` | `/admin/api/editor-generation-pricing` | `editor-generation-pricing` |
@@ -212,8 +205,6 @@ owner 返回全部 18 个 permission id；
| `GET` | `/admin/api/editor-showcase/campaign` | `editor-showcase` |
| `POST` | `/admin/api/editor-showcase/campaign` | `editor-showcase` |
| `POST` | `/admin/api/editor-showcase/campaign/image-upload-ticket` | `editor-showcase` |
| `GET` | `/admin/api/works/visibility` | `work-visibility` |
| `POST` | `/admin/api/works/visibility` | `work-visibility` |
| `GET` | `/admin/api/profile/redeem-codes` | `redeem` |
| `POST` | `/admin/api/profile/redeem-codes` | `redeem` |
| `POST` | `/admin/api/profile/redeem-codes/disable` | `redeem` |
@@ -231,17 +222,18 @@ owner 返回全部 18 个 permission id；
| `POST` | `/admin/api/profile/recharge-refunds/execute` | `recharge-orders` |
| `POST` | `/admin/api/profile/recharge-refunds/register` | `recharge-orders` |
| `POST` | `/admin/api/profile/recharge-refunds/manual-review/resolve` | `recharge-orders` |
| `GET` | `/admin/api/profile/users/detail` | `tables OR tracking OR recharge-orders OR editor-showcase OR editor-assets OR work-visibility ` |
| `GET` | `/admin/api/profile/users/detail` | `tables OR tracking OR recharge-orders OR editor-showcase OR editor-assets` |
| `POST` | `/admin/api/profile/wallet-restriction` | `recharge-orders` |
| `GET` | `/admin/api/accounts` | owner-only |
| `POST` | `/admin/api/accounts` | owner-only |
| `PUT` | `/admin/api/accounts/{account_id}` | owner-only |
三 个共享读取接口必须按 OR 规则实现，不能为了复用简单中间件扩大成“任意 member 可访问”：
两 个共享读取接口必须按 OR 规则实现，不能为了复用简单中间件扩大成“任意 member 可访问”：
- `/admin/api/assets/read-url` 只服务素材查询和精选审核。
- `/admin/api/profile/users/detail` 只服务当前实际包含用户详情入口的表查询、埋点数据、充值管理、精选审核、 素材查询和作品可见性 页面。
- `GET /admin/api/creation-entry/config` 同时为灰度发布、入口公告和入口开关提供页面初始化数据；写操作仍按具体页面单独收紧。
- `/admin/api/profile/users/detail` 只服务当前实际包含用户详情入口的表查询、埋点数据、充值管理、精选审核和 素材查询页面。
`gray-release` 页面只调用 `GET/PUT /admin/api/feature-gates` ；旧 `/admin/api/creation-entry/config*` 已退役，不能再作为灰度页面初始化依赖。页面固定目标只登记现役功能，其他通用 gate 仍可通过 Gate Key 直接管理。
## 10. 账号管理 HTTP 契约
@@ -303,7 +295,7 @@ accounts: Array<{
### 11.1 路由与导航
- `adminRoutes` 增加权限元数据；18 个业务路由使用同名 permission id。
- `adminRoutes` 增加权限元数据；15 个业务路由使用同名 permission id。
- `accounts` 路由只在 `admin.accountRole === "owner"` 时加入侧栏和移动底栏，不属于 member 可分配列表。
- member 导航只渲染 `admin.tabPermissions` 包含的业务路由。页面组件也必须只在当前路由已授权时挂载，避免隐藏导航后仍发起无权限 API。
- owner 渲染全部业务路由和账号管理路由。
@@ -315,13 +307,13 @@ accounts: Array<{
1. 当前 hash 对应可访问路由时保持不变。
2. hash 未知、属于无权限业务 Tab，或 member 访问 `#accounts` 时，使用 `replaceState` 回落到按第 4 节顺序找到的第一可访问业务 Tab。
3. member 权限为空时，不回落 Dashboard；渲染独立的零权限空态，只保留账号信息和退出登录，不挂载任何业务页，也不发起业务 API。
4. owner 的默认项仍可保持 Dashboard；账号管理不改变 18 个业务路由的排序。
4. owner 的默认项仍可保持 Dashboard；账号管理不改变 15 个业务路由的排序。
后端返回 `403` 时，前端重新请求 `/me` 获取实时权限并执行上述回落。即使前端状态陈旧或被篡改，后端权限 middleware 仍必须拒绝越权请求。
### 11.3 账号管理页
- 权限编辑器展示 18 个明确的 checkbox，每项使用现有 Tab 中文名称；不能展示或提交 `accounts` 。
- 权限编辑器展示 15 个明确的 checkbox，每项使用现有 Tab 中文名称；不能展示或提交 `accounts` 。
- 创建和编辑使用独立弹窗或抽屉，不在列表下方追加表单。
- 编辑时密码字段默认空，空表示请求中省略 `password` ；页面永不展示现有密码或 hash。
- 停用使用开关并二次确认。保存成功后以 API 返回 account snapshot 更新列表。
@@ -391,12 +383,12 @@ spacetime publish <database> \
- 权限、密码、启停更新各自会递增 `token_version` ；同一次请求修改多项只递增一次；仅改展示名不递增。
- member 被停用、改密或改权限后，旧 JWT 下一次请求返回 401；重新登录后获得实时权限。
- API-to-Tab 矩阵逐路由覆盖 `modules/admin.rs` ，每条路由至少测试 owner 成功、具备权限的 member 成功、缺权限 member 返回 403。
- 三 个共享读取接口分别覆盖每个允许 permission 的成功用例，以及无关 permission 的 403 用例。
- 两 个共享读取接口分别覆盖每个允许 permission 的成功用例，以及无关 permission 的 403 用例。
- owner-only 账号 API 对任意 member 都返回 403，即使其 `permissions_json` 被污染为包含 `accounts` 。
### 14.2 前端
- owner 看到 18 个业务 Tab 和账号管理；member 只看到被分配的业务 Tab。
- owner 看到 15 个业务 Tab 和账号管理；member 只看到被分配的业务 Tab。
- 每个一级 Tab 内的二级 Tab、弹窗和写操作继承一级权限并正常使用，不出现“页面可见但内部 API 403”的错误映射。
- 直接输入无权限 hash 自动替换为第一可访问项，不短暂挂载无权限页面。
- 当前 Tab 权限被 owner 收回后，下一请求触发重新登录；新会话恢复后落到第一可访问项。
