feat: add platform admin permissions

docs/refactor/multitenant-auth-security-contract.md

@@ -1,6 +1,6 @@
 # 多租户与鉴权安全契约
 
-更新时间：2026-06-29
+更新时间：2026-06-30
 
 这个系统后续要卖给同行作为题库 SaaS，因此租户隔离、鉴权、资源权限和审计是商用红线。前端可以先按迁移期接口联调，也可以按 Supabase 官方推荐使用 publishable key + RLS 的客户端能力管理 Auth/session，但正式上云验收前必须完成本文件的 P0 项。
 
@@ -8,7 +8,7 @@
 
 | 边界 | 规则 |
 | --- | --- |
-| 平台超级管理员 | 可管理全部租户、SaaS 套餐、订阅、账单、用量、公共题库 |
+| 平台超级管理员 | 按 `platform_permissions` 管理全部租户、SaaS 套餐、订阅、账单、用量、公共题库和平台审计 |
 | 租户管理员 | 只能管理自己租户的品牌、域名、成员、内容、营销、订单和 CRM |
 | 租户成员 | 按角色和 permissions 访问，例如运营、教师、销售、代理 |
 | 学生用户 | 只能访问自己所在租户下被授权的内容和自己的学习数据 |
@@ -62,7 +62,8 @@ Supabase 官方允许前端用 Data API 访问数据，但前提是 RLS、最小
 3. 平台管理员鉴权
    - `x-platform-admin-key` 已可通过 `ALLOW_PLATFORM_ADMIN_KEY=false` 禁用。
    - 已支持平台管理员 Supabase JWT，且以后端 `platform_users.primary_role='platform_admin'` 为准，不只信 JWT claim。
-   - 生产前继续补平台后台关键操作审计报表和更细权限点。
+   - 平台管理员已支持 `platform_users.platform_permissions` 细粒度权限，`{"*":true}` 为超级管理员；接口按 `platform:tenant:*`、`platform:billing:*`、`platform:audit:*`、`platform:question_bank:*` 等权限点强制校验。
+   - 生产前继续补平台后台关键操作审计报表和平台员工创建/授权 UI。
 
 4. 生产配置 fail-fast
    - `NODE_ENV=production` 时禁止默认 `AUTH_CODE_PEPPER`。
@@ -125,7 +126,7 @@ requireTenantPermission(auth, '<scope>:<action>')
 平台类接口必须满足：
 
 ```text
-requirePlatformAdmin(auth)
+requirePlatformAdmin(auth, '<platform:scope:action>')
 ```
 
 资源下载必须满足：
@@ -151,6 +152,38 @@ provider event id 幂等
 
 ## 权限点现状
 
+平台权限点：
+
+| 权限点 | 用途 |
+| --- | --- |
+| `platform:overview:read` | 查看平台总览 |
+| `platform:tenant:read` | 查看租户列表和租户详情 |
+| `platform:tenant:write` | 创建/编辑租户 |
+| `platform:tenant:status` | 变更租户状态 |
+| `platform:tenant:billing_profile` | 维护租户账务资料 |
+| `platform:plan:read` | 查看 SaaS 套餐 |
+| `platform:billing:read` | 查看平台账单、订阅候选和催缴记录 |
+| `platform:billing:write` | 创建订阅和服务费账单 |
+| `platform:billing:payment` | 确认平台服务费收款 |
+| `platform:billing:dunning` | 执行逾期处理和内部催缴 |
+| `platform:billing:notification` | 配置/查看催缴外部通知 |
+| `platform:usage:read` | 查看租户用量 |
+| `platform:usage:write` | 记录租户用量 |
+| `platform:audit:read` | 查看平台审计 |
+| `platform:audit:export` | 导出平台审计 |
+| `platform:audit:alert` | 查看/处理平台审计告警 |
+| `platform:audit:notification` | 配置/查看审计告警外部通知 |
+| `platform:question_bank:read` | 查看平台公共题库 |
+| `platform:question_bank:grant` | 授权平台公共题库 |
+
+前端平台后台启动后可调用：
+
+```text
+GET /api/platform-admin/permissions
+```
+
+响应中的 `effective` 只用于菜单和按钮可见性；真正权限仍由后端每个接口强制校验。生产 readiness 会阻断 `primary_role='platform_admin'` 但 `platform_permissions` 为空的账号，避免平台账号上线后权限不明确。
+
 当前默认角色：
 
 | 角色 | 默认权限 |