feat: add tenant role templates

docs/refactor/backend-capability-status.md

@@ -41,8 +41,8 @@
 | 微信小程序登录 | 可联调 | `/api/auth/oauth/wechat-miniapp` 已接 `code2Session`、openid/unionid 身份、session 签发和登录审计 |
 | 微信网页/QQ OAuth | 待补齐 | 目前仍是 placeholder，需要 code 换 token、回调域名、账号合并和审计 |
 | 平台管理员鉴权 | 可联调 | 已支持平台管理员 Supabase JWT；`x-platform-admin-key` 仅作本地/迁移期兼容且可通过配置禁用 |
-| 租户角色权限 | 可联调 | `tenant_memberships.role + permissions`，接口有权限点校验 |
-| 自定义角色模板 | 待补齐 | 当前有权限 JSON 覆盖，缺角色模板、菜单/模块/字段级权限配置 UI/API |
+| 租户角色权限 | 可联调 | `tenant_memberships.role + permissions + role_template_id`，接口有权限点校验 |
+| 自定义角色模板 | 可联调 | `tenant_role_templates` + `/api/tenant-admin/role-templates`，支持权限、菜单、模块、字段、数据范围配置；前端 UI 和班级/学生范围继续补 |
 
 ## 学生端题库主链路
 
@@ -113,7 +113,7 @@
 | 密钥掩码/引用 | 迁移期 | API 有掩码，生产前要做 KMS/Vault 或 envelope encryption |
 | 活动、Banner、FAQ、公告 | 可联调 | `/api/tenant-admin/banners`、`faqs`、`announcements` |
 | 激活码批次/生成/列表 | 可联调 | `/api/tenant-admin/code-batches`、`activation-codes` |
-| 成员/角色权限/审计 | 可联调 | `/api/tenant-admin/members`、`permissions`、`audit-logs` |
+| 成员/角色权限/审计 | 可联调 | `/api/tenant-admin/members`、`permissions`、`role-templates`、`audit-logs` |
 | 平台租户/套餐/订阅/账单/用量 | 可联调 | `/api/platform-admin/*` |
 | 数据看板聚合接口 | 待补齐 | 表基础已有，缺完整 dashboard API |
 

docs/refactor/backend-handoff-roadmap.md

@@ -22,7 +22,7 @@
 | --- | --- | --- | --- |
 | 多租户底座 | 可联调 | 租户、域名、品牌、设置、RLS 基础、审计、Supabase JWT/API 身份映射 | 真实云端 Auth/JWKS 回归、生产 RLS 深测 |
 | 平台后台 | 基础完成 | 租户、套餐、订阅、账单、服务费、用量 | 自动计费、平台审计、公共题库披露策略 |
-| 租户后台 | 基础完成 | 品牌、域名、支付账户、登录配置、密钥掩码、活动、兑换码、优惠券、成员权限 | 自定义角色模板、菜单/模块可见性 UI、字段级权限 |
+| 租户后台 | 可联调 | 品牌、域名、支付账户、登录配置、密钥掩码、活动、兑换码、优惠券、成员权限、角色模板、菜单/模块/字段权限配置 API | 前端权限 UI、班级/教师/学生范围权限 |
 | 题库与练习 | 可联调 | 内容入口、任意深度分类、题目集合、顺序/随机/全真模拟蓝图、组卷快照、答题、错题、收藏 | 完整模考交卷报告、专项策略、公题库采纳/授权、Excel 导入 |
 | 背单词 | 可联调 | 单元、单词、进度、收藏、统计、JSON 导入 | 复习算法、每日计划、排行榜、Excel 导入 |
 | 知识手册 | 可联调 | 科目、章节、条目、Markdown 内容、嵌套 JSON 导入 | 富文本资源、版本管理、附件/PDF 关联 |
@@ -93,7 +93,7 @@
 
 ### P2：企业级体验和增长闭环
 
-- 租户自定义角色、菜单可见、模块可见、字段级权限和权限审计。
+- 租户自定义角色模板基础 API 已完成；继续补权限配置 UI、班级/教师/学生范围权限和平台级审计报表。
 - 三套默认主题、租户主题预览、Logo/图标/分享图配置。
 - CRM worker：钉钉、飞书、企微机器人，轮询/定向分配，失败重试。
 - 销售/代理分佣结算、销售团队看板、客资跟进效果。

docs/refactor/backend-progress.md

@@ -14,10 +14,11 @@
   - `commerce`：订单、支付确认、激活码兑换、权益查询。
   - `referral`：销售/代理邀请码、首绑客资保护、销售统计、团队关系、CRM 队列。
   - `platform-admin`：平台方租户管理、SaaS 套餐、订阅、账单、服务费收款、使用量。
-  - `tenant-admin`：租户资料、品牌、公开设置、域名、支付账户、登录 provider、私密密钥掩码、活动内容、激活码批次、优惠券、成员管理、权限矩阵、审计查询。
+  - `tenant-admin`：租户资料、品牌、公开设置、域名、支付账户、登录 provider、私密密钥掩码、活动内容、激活码批次、优惠券、成员管理、角色模板、权限矩阵、审计查询。
   - `tenant-content`：租户后台内容入口、任意深度分类树、考试意向标记、题目集合、练习蓝图、题目、视频、分数线、单词、知识手册、资料资源、题目/单词/知识手册 JSON 导入维护。
   - `tenant`：域名/租户解析。
 - 鉴权上下文已支持 Supabase Auth JWT 和迁移期 `tk_` session 双入口，JWT 通过 `auth.users.id -> platform_users.auth_user_id -> tenant_memberships` 映射业务用户和租户；平台管理员 JWT 已可访问平台后台。
+- 租户自定义角色模板已落库：`tenant_role_templates` 支持权限、菜单、模块、字段和数据范围配置，成员可通过 `role_template_id` 绑定模板。
 - `learning` 已接入商用访问控制：免费用户每日题量、SVIP 范围、SVIP-only 内容、答题 session 快照保护由后端强制执行。
 - `src/services/supabaseApi.ts` 已加入新 API 客户端方法，供旧 Web 逐步替换和后续 Taro 复用。
 - 已新增 `npm run db:smoke-seed`，用于 `supabase:reset` 后恢复最小烟测数据。

docs/refactor/frontend-handoff-index.md

@@ -36,10 +36,11 @@
 - H5 可以直接用 Supabase Auth access token 调 `apps/api`；后端已支持 JWT 验签和业务用户映射。
 - H5 可以优先验证 `@supabase/supabase-js` 管理 Auth session；微信小程序端先验证运行时兼容性，业务数据默认仍走 `apps/api`。
 - 可以接入租户品牌、主题、功能开关和域名/小程序参数解析。
+- 租户后台可以接入角色模板 API：`/api/tenant-admin/role-templates`，用于运营、教师、销售、代理等自定义菜单/模块/字段可见性。
 
 ## 不能误认为已商用完成的部分
 
-- 生产鉴权已具备 Supabase JWT API 入口，但仍要做真实云端 Auth/JWKS 回归、RLS 深测和自定义角色权限细化；前端不要继续使用 `x-user-id`。
+- 生产鉴权已具备 Supabase JWT API 入口，自定义角色模板基础 API 已可用；仍要做真实云端 Auth/JWKS 回归、RLS 深测和班级/学生范围权限细化，前端不要继续使用 `x-user-id`。
 - 不要把“Supabase 支持前端 Data API”误解为“本项目所有业务表都由 Taro 直写”；订单、支付、权益、租户后台、导入、CRM、私有资源必须走 RPC、`apps/api`、Edge Function 或 worker 这类后端命令层。
 - 真实短信、微信登录、QQ 登录、微信支付、支付宝支付 provider 还未正式接完。
 - 对象存储已完成签名 provider，但 PDF 预览、防盗链、视频水印、上传后校验还要补。

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

@@ -149,11 +149,17 @@ provider event id 幂等
 | agent | 兑换码/优惠券只读、本人的客资 |
 | student | 无后台权限 |
 
+已支持租户自定义角色模板：
+
+- `tenant_role_templates` 保存租户内模板，成员通过 `tenant_memberships.role_template_id` 绑定。
+- 权限判断顺序：成员 `permissions` 显式覆盖 > 角色模板 `permissions` > 系统角色默认权限。
+- 模板可保存 `menuPermissions`、`modulePermissions`、`fieldPermissions`、`dataScope`，供 Taro/管理台做菜单、模块、字段可见性和数据范围 UI。
+- 模板含 `*`、`tenant_owner`、`tenant_admin` 等管理员级能力时，只有租户 owner 可创建或授予；普通租户管理员不能自造全权限模板。
+- 角色模板创建、更新、禁用都会写入 `audit_logs`。
+
 后续要补：
 
-- 租户自定义角色模板。
-- 菜单级、模块级、字段级权限。
-- 权限变更审计。
+- 前端角色模板配置 UI。
 - 班级/教师/学生范围权限。
 
 ## 上线前安全验收清单

docs/refactor/next-development-todo.md

@@ -30,7 +30,7 @@
 1. 生产鉴权
    - 已支持 Supabase Auth JWT 和迁移期 `tk_` session 双入口；JWT 通过 `auth.users.id -> platform_users.auth_user_id -> tenant_memberships` 映射业务身份。
    - 已覆盖学生、租户管理员、平台管理员、错租户、坏签名、禁用 legacy header 的 API 集成测试。
-   - 继续补真实云端 Auth/JWKS 回归、RLS 深测、自定义角色模板和菜单/模块/字段级权限。
+   - 已补自定义角色模板、菜单/模块/字段级配置 API；继续补真实云端 Auth/JWKS 回归、RLS 深测和班级/学生范围权限。
    - 前端联调时禁止继续使用 `x-user-id`；`x-tenant-id` 只作为租户上下文，不能作为身份依据。
 
 2. 对象存储
@@ -97,9 +97,9 @@
 ### P2 运营体验和企业交付
 
 1. 自定义角色
-   - 租户内角色模板。
-   - 菜单可见、模块可见、字段级权限。
-   - 权限变更审计。
+   - 已完成租户内角色模板、菜单可见、模块可见、字段级权限和权限变更审计基础 API。
+   - 继续补租户后台可视化配置 UI。
+   - 继续补班级/教师/学生范围权限。
 
 2. 主题系统
    - 平台默认三套主题。

docs/refactor/taro-frontend-integration.md

@@ -437,7 +437,7 @@ content_entries
 - 支付渠道从后端返回或租户配置读取，不在页面硬编码。
 - 小程序分享路径必须带 tenantCode 和 referral code。
 - 用户首绑归属由后端保护，前端不要提供“换绑销售”入口。
-- 管理后台菜单按 `GET /api/tenant-admin/permissions` 和用户权限渲染。
+- 管理后台菜单按 `GET /api/tenant-admin/permissions` 返回的 `current.permissions`、`current.templatePermissions`、`current.menuPermissions`、`current.modulePermissions` 渲染；接口权限仍以后端校验为准。
 - H5 自定义域名下要注意缓存隔离，不能把 A 租户主题缓存用到 B 租户。
 
 ## 登录对接
@@ -602,13 +602,14 @@ GET /api/commerce/entitlements
 - 品牌/主题/域名/公开设置
 - 支付账户/登录 provider/密钥引用
 - 用户与成员权限
+- 角色模板：`GET/PUT /api/tenant-admin/role-templates`、`POST /api/tenant-admin/role-templates/disable`
 - 内容入口/分类树/题目集合/练习蓝图
 - 题目/单词/知识手册/分数线/视频维护
 - JSON 导入 preview/import/issues
 - Banner/FAQ/公告/激活码/优惠券
 - 销售/代理/CRM 队列
 
-租户后台不应在前端自行决定权限；隐藏菜单只是体验优化，接口仍会校验权限。
+租户后台不应在前端自行决定权限；隐藏菜单只是体验优化，接口仍会校验权限。角色模板用于让租户配置“运营、教师、销售、代理”等自定义后台体验，成员绑定模板后，前端按模板的菜单/模块/字段权限渲染，后端按 permission keys 执行真正的访问控制。
 
 ## 联调顺序