feat: add public question bank adoption

2026-06-29 03:07:57 +08:00
parent c767b87c6f
commit 7c41bf525f
15 changed files with 1324 additions and 16 deletions
--- a/docs/refactor/api-structure.md
+++ b/docs/refactor/api-structure.md
@@ -70,6 +70,7 @@ types.ts                   仅本领域使用的类型
 - `tenant-admin` 权限由 `tenant_memberships.role` 的默认权限和 `permissions` JSON 覆盖共同决定；后端接口必须校验具体权限点，不能只依赖前端菜单隐藏。
 - `referral` 是增长/客资业务域，负责邀请码、扫码事件、首绑保护、销售/代理团队归属和 CRM 入队；真实 CRM webhook 发送应由 worker 处理，API 只负责幂等入队。
 - 题库前端入口不再只依赖旧 `module_nodes/subjects/categories`；新业务主模型是 `content_entries/content_nodes/question_collections/practice_blueprints`，用于表达可视化入口、多级分类、考试意向标记、题目列表和顺序/随机/全真模拟规则。
+- 平台公共题库不能被租户前端直接跨租户读取；平台侧通过 `/api/platform-admin/question-bank-grants` 授权，租户侧通过 `/api/tenant-content/public-question-banks/adopt` 采纳为本租户题库、入口、集合和题目快照。后续版本同步必须走 worker 和审计。
 - `learning` 创建练习 session 时必须保存 `question_ids` 快照，避免随机刷题和模考过程中题目集合变化导致答题记录无法复盘。
 - 排行榜必须由后端按租户、地区、班级和可信用户上下文聚合，前端不能自行扫描答题记录、积分流水或单词进度后排名；后续高流量场景再通过 worker/materialized view 做日榜、周榜和防刷。
 - 资料、PDF、视频等对象存储资源必须先进入 `content_assets` 台账，再通过 API/Edge Function 做权限校验和签名 URL 下发；前端不能直接拼 OSS/COS/Supabase Storage 私有地址。
--- a/docs/refactor/backend-capability-status.md
+++ b/docs/refactor/backend-capability-status.md
@@ -126,6 +126,8 @@
 | 学生批量运营 | 可联调 | `/api/tenant-admin/students/bulk-upsert`、`students/status`、`classes/members/bulk-assign`、`students/notes`、`students/followups`；支持逐行结果、限量、防跨租户和教师范围校验 |
 | 平台租户/套餐/订阅/账单/用量 | 可联调 | `/api/platform-admin/*` |
 | 数据看板聚合接口 | 待补齐 | 表基础已有，缺完整 dashboard API |
+| 平台公共题库授权 | 可联调 | `/api/platform-admin/question-banks`、`question-bank-grants`；支持按 SaaS 套餐、指定租户或全部活跃租户披露平台公共题库 |
+| 租户采纳公共题库 | 可联调 | `/api/tenant-content/public-question-banks`、`public-question-banks/adopt`；租户只能看到自己订阅/授权范围内题库，采纳后生成租户自己的题库、入口、集合和题目快照，可直接进入练习 |

 ## 销售、代理、CRM

@@ -146,11 +148,13 @@
 | --- | --- | --- |
 | PocketBase schema 分析 | 可联调 | `scripts/import-pocketbase` |
 | 题目 JSON preview/import | 可联调 | 后端负责规范化、issue、幂等、审计 |
+| 公共题库采纳快照 | 可联调 | 平台授权后，租户可采纳公共题库并复制已发布题目快照；已覆盖跨租户、重复采纳和采纳后组卷测试 |
 | 单词 JSON preview/import | 可联调 | 兼容旧模板 |
 | 知识手册 JSON preview/import | 可联调 | 支持书籍/章节/小节/知识点归一化 |
 | Excel/CSV 导入 | 待补齐 | 应复用 `content_import_jobs` 管线 |
 | 分数线/视频批量导入 | 待补齐 | 应复用同一导入管线 |
 | 大批量异步导入 | 待补齐 | 需要 `apps/worker` |
+| 公共题库版本同步 | 待补齐 | 当前采纳为快照复制；后续需 worker 做增量同步、冲突处理、版本升级通知和租户自改保护 |

 ## 当前验证

--- a/docs/refactor/backend-handoff-roadmap.md
+++ b/docs/refactor/backend-handoff-roadmap.md
@@ -21,9 +21,9 @@
 | 模块 | 当前状态 | 已经具备 | 上线前还要补 |
 | --- | --- | --- | --- |
 | 多租户底座 | 可联调 | 租户、域名、品牌、设置、RLS 基础、审计、Supabase JWT/API 身份映射 | 真实云端 Auth/JWKS 回归、生产 RLS 深测 |
-| 平台后台 | 基础完成 | 租户、套餐、订阅、账单、服务费、用量 | 自动计费、平台审计、公共题库披露策略 |
+| 平台后台 | 基础完成 | 租户、套餐、订阅、账单、服务费、用量、公共题库授权 | 自动计费、平台审计、公共题库版本同步 |
 | 租户后台 | 可联调 | 品牌、域名、支付账户、登录配置、密钥掩码、活动、兑换码、优惠券、成员权限、角色模板、菜单/模块/字段权限配置 API | 前端权限 UI、班级/教师/学生范围权限 |
-| 题库与练习 | 可联调 | 内容入口、任意深度分类、题目集合、顺序/随机/全真模拟蓝图、组卷快照、答题、错题、收藏、模考报告、排行榜 | 专项策略、公题库采纳/授权、Excel 导入、排行榜防刷/预聚合 |
+| 题库与练习 | 可联调 | 内容入口、任意深度分类、题目集合、顺序/随机/全真模拟蓝图、组卷快照、答题、错题、收藏、模考报告、排行榜、公共题库采纳快照 | 专项策略、公共题库版本同步、Excel 导入、排行榜防刷/预聚合 |
 | 背单词 | 可联调 | 单元、单词、进度、收藏、统计、每日计划、JSON 导入、排行榜 | Excel 导入、更细复习参数 |
 | 知识手册 | 可联调 | 科目、章节、条目、Markdown 内容、嵌套 JSON 导入 | 富文本资源、版本管理、附件/PDF 关联 |
 | 分数线 | 可联调 | 院校、专业、动态字段、记录、年份、趋势、后台维护 | 批量导入、复杂筛选、AI 择校上下文 |
@@ -86,7 +86,7 @@
 - 退款、对账、支付补偿任务和异常订单处理。
 - XPay 或其它实际支付网关 adapter。
 - 阿里云/腾讯云短信、微信小程序登录、微信网页登录、QQ 登录。
- 公共题库/地区题库授权，租户按 SaaS 套餐购买地区、科目和题库范围。
+- 公共题库/地区题库版本同步，租户按 SaaS 套餐购买地区、科目和题库范围的更细计费策略。
 - Excel/CSV、分数线、视频批量导入。
 - 视频会员播放次数、播放日志、防盗链、水印。
 - 数据看板 API：收益、注册趋势、答题次数、收入趋势、题型分布、题目总量、套餐销量、24h 活跃。
--- a/docs/refactor/implementation-status.md
+++ b/docs/refactor/implementation-status.md
@@ -24,7 +24,7 @@
 | 模块 | 数据模型 | PocketBase 导入 | API | 自动化测试 | 当前状态 |
 | --- | --- | --- | --- | --- | --- |
 | 多租户隔离 | 已建 `tenants`、`tenant_domains`、`tenant_branding`、`tenant_settings`、RLS 基础 | 部分支持 | 租户解析、品牌、域名、支付账户、登录 provider、平台建租户已实现 | 核心 API 集成测试含租户隔离断言 | 基础可用，正式 JWT/RLS 权限闭环未完成 |
-| 刷题题库 | 已建题库、题目、题目版本、内容入口、任意深度分类树、考试意向标记、题目集合、练习蓝图、导入任务台账 | 已支持核心映射，JSON 导入可落到新入口/节点/集合 | 题目列表、内容入口、分类树、集合题目、顺序/随机/全真模拟 session、答题提交、租户后台题目录入/更新、JSON 预览/导入已实现 | 核心 API 集成测试含导航、组卷、导入断言 | 新题库导航和组卷基础闭环可跑，完整交卷评分报告、Excel 导入、公题库采纳/授权仍需补齐 |
+| 刷题题库 | 已建题库、题目、题目版本、内容入口、任意深度分类树、考试意向标记、题目集合、练习蓝图、导入任务台账、公共题库授权/采纳表 | 已支持核心映射，JSON 导入可落到新入口/节点/集合 | 题目列表、内容入口、分类树、集合题目、顺序/随机/全真模拟 session、答题提交、租户后台题目录入/更新、JSON 预览/导入、平台公共题库授权、租户采纳快照已实现 | 核心 API 集成测试含导航、组卷、导入、公共题库授权和采纳后组卷断言 | 新题库导航和组卷基础闭环可跑，公共题库采纳快照可联调；Excel 导入、公共题库全量/增量版本同步仍需补齐 |
 | 错题本 | 已建 `wrong_questions` | 已支持旧错题归一化 | 错题列表、答题自动入错题、移出错题已实现 | 仅烟测 | 基础功能已实现，复习计划和统计未完成 |
 | 收藏夹 | 已建 `favorite_questions` | 已支持旧收藏归一化 | 收藏/取消收藏、收藏列表已实现 | 仅烟测 | 基础功能已实现 |
 | 用户订阅/题库会员/SVIP | 已建 `orders`、`payments`、`entitlements`、`svip_plans`、激活码 | 已映射旧 SVIP/会员权益 | 下单、订单详情/状态轮询、手工支付确认权限保护、微信/支付宝支付、激活码预检查/兑换、优惠券抵扣、零元订单自动开通、权益查询已实现 | API 集成测试 | 商城主链路可联调，退款/对账/支付补偿和异常订单处理待补 |
@@ -259,7 +259,7 @@ platform-admin:
 为了先把旧项目核心业务补齐，再进入支付/短信等商用关键模块，建议按下面顺序继续：

 1. 完善内容导入和文件上传：Excel/CSV、分数线、视频导入，接真实 OSS/COS/Supabase Storage 签名，并把 JSON 导入扩展为异步 worker。
-2. 补地区/公共题库披露策略、租户套餐地区限制、主题模板系统。
+2. 补公共题库版本同步 worker、租户套餐地区/科目/题库范围限制、主题模板系统。
 3. 补学习统计增强：排行榜防刷/预聚合、断点续练、专项练习策略和更细题型分析。
 4. 补视频商用控制：SVIP 权限、签名 URL、防盗链、水印、播放次数扣减。
 5. 补 AI 择校推荐报告、排行榜防刷/预聚合、勋章自动发放。
--- a/docs/refactor/legacy-feature-gap-matrix.md
+++ b/docs/refactor/legacy-feature-gap-matrix.md
@@ -46,7 +46,7 @@
 | 销售/代理管理 | 部分覆盖 | referral/team/stats 有；缺分佣比例、结算单、审核、导出 |
 | 班级/教师管理 | 已覆盖 | 班级、班级成员、教师/班主任/助教/学生范围权限已有；可视化 UI 和更细数据范围组合待补 |
 | 数据看板 | 部分覆盖 | 表基础有；缺收益、注册、答题、活跃、套餐销量等聚合 API |
-| 地区管理 | 部分覆盖 | 地区和内容入口已有；缺按 SaaS 套餐限制地区/题库授权的完整流程 |
+| 地区管理 | 部分覆盖 | 地区和内容入口已有；平台公共题库已可按 SaaS 套餐/租户授权并由租户采纳；还缺更完整的全国/单地区套餐 UI 和版本同步策略 |
 | 品牌配置 | 已覆盖 | 需要前端做预览和主题发布体验 |
 | 自定义域名 | 已覆盖 | 生产需补 DNS 校验、证书状态、回源校验 |
 | 主题系统 | 部分覆盖 | 当前 theme JSON 可用；缺三套平台主题模板和素材管理 |
@@ -73,10 +73,10 @@
 | 功能 | 新后端状态 | 待补齐 |
 | --- | --- | --- |
 | 创建/管理租户 | 已覆盖 | 平台后台页面待做 |
-| SaaS 套餐 | 已覆盖 | 需要和地区/题库授权策略打通 |
+| SaaS 套餐 | 部分覆盖 | 已和公共题库授权打通；后续继续补地区数量、科目范围、存储/学生数等组合套餐限制 |
 | 年费/服务费账单 | 已覆盖 | 真实支付/开票/催缴流程待补 |
 | 租户用量记录 | 已覆盖 | 自动采集 worker 待补 |
-| 公共题库/地区题库 | 部分覆盖 | question_banks 有 source_scope；缺平台披露策略、SaaS 套餐授权、租户采纳/复制/版本同步 |
+| 公共题库/地区题库 | 部分覆盖 | 已有平台公共题库列表、授权、租户可采纳列表、采纳快照复制、采纳后练习组卷；缺全量/增量版本同步、冲突处理和运营 UI |
 | 跨租户运营看板 | 部分覆盖 | overview 有基础；缺完整 BI 聚合 |
 | 租户安全审计 | 部分覆盖 | audit logs 有；缺平台级审计报表 |

@@ -99,7 +99,7 @@
 2. 账号设置完整流：头像上传、绑定/更换手机号、微信/QQ 账号合并、密码/邮箱能力。
 3. 题库导出：PDF/Word/JSON 导出、水印、导出审计和权限控制。
 4. 导入扩展：Excel/CSV、分数线、视频批量导入和大批量异步 worker。
-5. 公共题库商业化：平台公共/地区题库披露、租户采纳、套餐授权、版本同步。
+5. 公共题库商业化：平台公共/地区题库授权和租户快照采纳已完成基础闭环；还需版本同步、租户自改冲突处理和运营后台 UI。
 6. CRM/销售结算：真实 CRM worker、轮询/定向分配、分佣规则、结算单、审核和导出。
 7. 题目反馈增强：处理通知、消息提醒、问题聚合统计和内容修复闭环。
 8. 积分活动增强：积分兑换、活动任务、连续签到奖励规则和风控。
@@ -118,7 +118,7 @@
 2. 对象存储 PDF 预览、视频深度防盗链、动态水印。
 3. Excel/CSV、分数线、视频批量导入。
 4. 数据看板和销售/代理分佣结算。
-5. 公共题库授权、租户采纳和版本同步。
+5. 公共题库版本同步、租户采纳后的更新策略和同步 worker。

 ### P2：增强体验

--- a/docs/refactor/next-development-todo.md
+++ b/docs/refactor/next-development-todo.md
@@ -21,6 +21,7 @@
 - 学生运营管理：学生批量 upsert、禁用/恢复、批量分班、备注、跟进任务已完成接口和集成测试；后续补批量 CRM 推送和自动学习督导。
 - 旧题库运营缺口已补一批：考试日期/倒计时、题目反馈/纠错处理、每日签到积分和积分流水、学习排行榜已完成接口和集成测试。
 - 旧商城体验已补齐主链路：订单详情、订单状态轮询、激活码预检查、自用激活码拒绝、优惠券前台领取、下单抵扣、零元订单自动支付开通权益，且手工支付确认已限制为租户后台 `tenant:payment:write` 权限。
+- 公共题库商业化基础闭环已完成：平台公共题库可由平台管理员按 SaaS 套餐/指定租户/全部活跃租户授权；租户内容管理员只能看到自己被授权的公共题库，并可采纳为本租户题库、内容入口、题目集合和题目快照，采纳后可直接进入练习 session。
 - 本地验证：`npm run check:refactor` 已通过。

 当前更适合进入前端联调前阅读的总览文档：
@@ -72,9 +73,9 @@
   - 大批量导入异步 worker、重试、导入后校验。

 4. 公共题库和租户授权
-   - 平台公共题库/地区题库。
-   - 按 SaaS 套餐限制地区、科目、题库范围。
-   - 租户采纳、复制、授权、版本同步策略。
+   - 已完成平台公共题库/地区题库的基础授权、租户采纳和题目快照复制。
+   - 继续补按 SaaS 套餐限制地区数量、科目范围、题库范围的更细计费策略。
+   - 继续补公共题库版本同步 worker、租户自改冲突处理、同步失败重试和运营后台 UI。

 5. 视频会员控制
   - 已完成视频 SVIP 权限、播放次数扣减、签名播放和播放日志。
@@ -192,5 +193,5 @@
 2. 云服务器部署 Supabase/PostgreSQL 和 API，配置对象存储生产环境变量，跑 `check:refactor` 的远程等价测试。
 3. 导出现有 PocketBase 数据，做完整 dry-run 迁移。
 4. 开始 `apps/taro`，先接租户解析、首页、题库、背单词、知识手册。
-5. 并行补对象存储、真实登录、退款对账、CRM worker 和公共题库授权。
+5. 并行补对象存储、真实登录、退款对账、CRM worker 和公共题库版本同步 worker。
 6. 前后端联调通过后，再做支付、权限、数据导入、资料下载、视频播放的商用验收。
--- a/docs/refactor/taro-frontend-integration.md
+++ b/docs/refactor/taro-frontend-integration.md
@@ -181,6 +181,7 @@ tenant:<tenantId>:theme
 | 租户教师 | `GET /api/tenant-admin/teachers` |
 | 租户考试日期 | `GET/PUT /api/tenant-admin/exam-dates` |
 | 租户反馈处理 | `GET /api/tenant-admin/feedbacks`、`POST /api/tenant-admin/feedbacks/status`、`GET /api/tenant-admin/feedbacks/events` |
+| 公共题库采纳 | `GET /api/tenant-content/public-question-banks`、`POST /api/tenant-content/public-question-banks/adopt` |

 ## 练习访问控制契约

@@ -521,6 +522,59 @@ content_entries
 - 教师可以为范围内学生创建备注和跟进任务，但是否能禁用学生、批量导入、查看手机号由后端权限和字段权限决定；前端只按返回值渲染。
 - H5 自定义域名下要注意缓存隔离，不能把 A 租户主题缓存用到 B 租户。

+## 公共题库采纳对接
+
+平台超级管理员后台使用：
+
+```text
+GET /api/platform-admin/question-banks
+GET /api/platform-admin/question-bank-grants
+PUT /api/platform-admin/question-bank-grants
+```
+
+授权参数建议：
+
+```json
+{
+  "sourceQuestionBankId": "<平台公共题库ID>",
+  "grantScope": "plans",
+  "allowedPlanCodes": ["starter_yearly", "pro_yearly"],
+  "status": "active"
+}
+```
+
+`grantScope` 可选：
+
+- `plans`：按 SaaS 套餐授权。
+- `tenants`：指定租户授权。
+- `mixed`：套餐和指定租户同时生效。
+- `all_active_tenants`：所有有效订阅租户可见。
+
+租户内容后台使用：
+
+```text
+GET /api/tenant-content/public-question-banks
+POST /api/tenant-content/public-question-banks/adopt
+```
+
+采纳请求：
+
+```json
+{
+  "grantId": "<授权ID>",
+  "entryName": "天津专升本公共题库",
+  "collectionName": "天津专升本公共题目",
+  "copyLimit": 500
+}
+```
+
+前端处理规则：
+
+- 租户只能看到后端判定为已授权的公共题库，不要在前端用套餐码自行过滤。
+- 采纳成功后后端会生成本租户自己的 `questionBankId`、`entryId`、`collectionId` 和题目快照，学生端直接按普通 `/api/catalog/content-entries`、`question-collections`、`practice-sessions` 接入。
+- 重复采纳返回 `QUESTION_BANK_ALREADY_ADOPTED`，前端展示“已采纳”即可。
+- 当前版本是快照复制；平台公共题库后续更新不会自动进入租户题库，后续会由 worker 做版本同步、冲突处理和租户确认。
+
 ## 登录对接

 ### 短信登录