feat: add tenant theme templates

2026-06-29 18:05:30 +08:00
parent a68b4ab9e3
commit ee578af1f6
16 changed files with 1239 additions and 24 deletions
--- a/docs/refactor/taro-frontend-integration.md
+++ b/docs/refactor/taro-frontend-integration.md
@@ -23,7 +23,7 @@ F:\project\参考\旧题库项目\src
 1. 从 `window.location.host` 获取当前域名。
 2. 调用 `GET /api/tenant/resolve?host=<host>`。
 3. 保存 `tenant.id`、`tenant.slug`、`branding`、`features`、`publicConfig`。
-4. 初始化主题、Logo、页面标题、功能开关。
+4. 使用 `branding.theme` 和 `branding.publicAssets` 初始化主题、Logo、分享图、页面标题、功能开关。
 5. 检查本地 session token，调用 `GET /api/auth/me`。
 6. 如果未登录，进入登录页；如果已登录，加载个人中心和首页数据。

@@ -119,6 +119,87 @@ TARO_APP_SUPABASE_PUBLISHABLE_KEY
 | 429 | 倒计时重试，例如短信冷却 |
 | 500 | 展示系统异常并上报日志 |

+## 租户主题与品牌契约
+
+学生端、租户后台、平台后台启动时都通过 `GET /api/tenant/resolve` 获取已发布主题。响应中的 `branding.theme` 是已发布 token，`branding.publicAssets` 是公开素材引用，前端可以安全消费；租户后台草稿不会出现在公开解析响应里。
+
+主题 token 示例：
+
+```json
+{
+  "primaryColor": "#2563eb",
+  "accentColor": "#0f766e",
+  "backgroundColor": "#f8fafc",
+  "surfaceColor": "#ffffff",
+  "textColor": "#0f172a",
+  "borderRadius": 8,
+  "buttonRadius": 8,
+  "layoutDensity": "comfortable"
+}
+```
+
+公开素材示例：
+
+```json
+{
+  "logoUrl": "/assets/tenant/logo.png",
+  "shareImageUrl": "https://static.example.com/share.png",
+  "iconSet": "focus",
+  "shareCardStyle": "study"
+}
+```
+
+前端处理规则：
+
+- 只读取 `/api/tenant/resolve` 返回的已发布主题来渲染学生端和公开页面。
+- 租户后台主题草稿只调用 `GET /api/tenant-admin/theme` 展示，不能让学生端读取草稿。
+- 不允许前端把任意 CSS、HTML、JS 或远程脚本当作主题执行；后端已经限制主题为颜色、半径、安全 CSS 变量、图标 token 和 HTTPS/站内公开素材。
+- Logo、分享图、启动图等长期素材后续应从后台上传进入 `content_assets` 或静态公共资源，再把公开 URL/路径写入主题 `publicAssets`。
+- 小程序端用 `branding.publicAssets.shareImageUrl` 作为分享图时，仍要遵守微信平台对图片尺寸、域名和 HTTPS 的要求。
+
+租户后台主题配置接口：
+
+```text
+GET  /api/tenant-admin/theme-templates
+GET  /api/tenant-admin/theme
+POST /api/tenant-admin/theme/preview
+POST /api/tenant-admin/theme/publish
+```
+
+权限：
+
+```text
+tenant:theme:read
+tenant:theme:write
+```
+
+`POST /api/tenant-admin/theme/preview` 只保存草稿：
+
+```json
+{
+  "templateCode": "focus",
+  "theme": {
+    "primaryColor": "#123abc",
+    "accentColor": "#f59e0b"
+  },
+  "publicAssets": {
+    "logoUrl": "/assets/tenant/logo.png",
+    "iconSet": "focus",
+    "shareCardStyle": "study"
+  }
+}
+```
+
+`POST /api/tenant-admin/theme/publish` 发布草稿：
+
+```json
+{
+  "useDraft": true
+}
+```
+
+发布成功后，下一次 `GET /api/tenant/resolve` 会返回新主题。主题预览和发布都会写入租户审计日志，越权角色会返回 `TENANT_PERMISSION_REQUIRED`。
+
 ## 全局状态建议

 | Store | 内容 |
@@ -176,6 +257,7 @@ tenant:<tenantId>:theme
 | 个人中心 | `GET/PATCH /api/profile/me`、`POST /api/profile/check-in`、`GET /api/profile/score-events`、`GET /api/profile/exam-countdowns`、`GET /api/profile/badges` |
 | 销售分享 | `/api/referral/resolve`、`track-event`、`bind` |
 | 租户数据看板 | `GET /api/tenant-admin/dashboard?timeRange=30d&regionId=...` |
+| 租户主题模板 | `GET /api/tenant-admin/theme-templates`、`GET /api/tenant-admin/theme`、`POST /api/tenant-admin/theme/preview`、`POST /api/tenant-admin/theme/publish` |
 | 租户班级 | `GET/PUT /api/tenant-admin/classes`、`POST /api/tenant-admin/classes/disable` |
 | 班级成员 | `GET/PUT /api/tenant-admin/classes/members`、`POST /api/tenant-admin/classes/members/remove`、`POST /api/tenant-admin/classes/members/bulk-assign` |
 | 租户学生 | `GET/PUT /api/tenant-admin/students`、`POST /api/tenant-admin/students/bulk-upsert`、`POST /api/tenant-admin/students/status` |
@@ -1750,7 +1832,7 @@ npm run build:taro:h5:platform
 下一批前端开发重点：

 - 学生端：地区选择、题目视频播放、题目反馈、错题/收藏专题页、模考交卷报告、收银台、订单详情和售后入口已接第一版；下一批继续补刷题细节 UI、小程序支付容器和分享场景。
- 租户后台：工作台已接权限驱动模块入口；学生运营页已接学生创建/更新、禁用/恢复、批量导入、批量分班、学生备注、跟进任务和完成跟进第一版；题库内容页已接公共题库采纳/同步、冲突查看、单条/批量采纳平台或保留本地、导入问题、模板预览/下载、异步任务轮询和导入后复检第一版；营销中心已接 CRM 配置保存、CRM 队列按状态查看、分佣默认规则、成员分佣比例、分佣订单明细、结算单生成、审核通过/驳回和标记线下打款第一版；租户设置页已接角色模板创建、编辑、停用、权限点、菜单、模块、字段、基础数据范围、成员搜索/新建、成员绑定模板、成员状态和额外权限覆盖第一版；下一批继续补更精细的学生导入模板体验、CRM 分配策略、真实打款/导出/凭证和更细数据范围 UI。
+- 租户后台：工作台已接权限驱动模块入口；学生运营页已接学生创建/更新、禁用/恢复、批量导入、批量分班、学生备注、跟进任务和完成跟进第一版；题库内容页已接公共题库采纳/同步、冲突查看、单条/批量采纳平台或保留本地、导入问题、模板预览/下载、异步任务轮询和导入后复检第一版；营销中心已接 CRM 配置保存、CRM 队列按状态查看、分佣默认规则、成员分佣比例、分佣订单明细、结算单生成、审核通过/驳回和标记线下打款第一版；租户设置页已接主题模板、草稿预览、发布、角色模板创建、编辑、停用、权限点、菜单、模块、字段、基础数据范围、成员搜索/新建、成员绑定模板、成员状态和额外权限覆盖第一版；下一批继续补更精细的学生导入模板体验、CRM 分配策略、真实打款/导出/凭证、更细数据范围 UI 和主题素材库。
 - 平台后台：租户创建、状态变更、订阅开通、账单生成、人工收款确认、用量录入、公共题库授权编辑已接第一版；继续补租户详情/编辑、平台审计、自动计费和批量账单操作。
 - 小程序：验证 `Taro.login`、微信支付、分享 scene/referral、Supabase client 兼容性；如不稳定，保留 `apps/api/auth/*` 作为小程序登录适配层。

@@ -1765,6 +1847,7 @@ npm run build:taro:h5:platform
 - 用户与成员权限
 - 班级/教师/学生：`/api/tenant-admin/classes`、`classes/members`、`students`、`teachers`、`students/notes`、`students/followups`
 - 角色模板与成员：`GET/PUT /api/tenant-admin/role-templates`、`POST /api/tenant-admin/role-templates/disable`、`GET/PUT /api/tenant-admin/members`、`POST /api/tenant-admin/members/disable`；当前 Taro 租户设置页已提供第一版创建、编辑、停用、权限点、菜单、模块、字段、基础数据范围、成员绑定模板和成员状态配置。
+- 主题模板：`GET /api/tenant-admin/theme-templates`、`GET /api/tenant-admin/theme`、`POST /api/tenant-admin/theme/preview`、`POST /api/tenant-admin/theme/publish`；当前 Taro 租户设置页已提供第一版模板选择、主色/强调色、Logo/分享图、安全草稿预览和发布。
 - 内容入口/分类树/题目集合/练习蓝图
 - 题目/单词/知识手册/分数线/视频维护
 - 题目/单词/知识手册/分数线/视频 JSON/CSV/Excel 导入 preview/import/issues、字段映射、模板下载和导入后复检