feat: add AI school recommendation foundation

2026-06-29 21:22:53 +08:00
parent 8d4428214a
commit aeca84b260
16 changed files with 1003 additions and 12 deletions
--- a/docs/refactor/backend-capability-status.md
+++ b/docs/refactor/backend-capability-status.md
@@ -81,6 +81,7 @@
 | 知识手册 JSON 导入 | 可联调 | `/api/tenant-content/imports/*/handbook` |
 | 分数线字段/院校/专业/记录/趋势 | 可联调 | `/api/scoreline/*` |
 | 分数线 JSON 导入 | 可联调 | `/api/tenant-content/imports/preview/scoreline`、`/api/tenant-content/imports/scoreline`；支持字段、院校、专业、记录、动态字段值、逐行 issue、幂等和审计 |
+| AI 择校推荐 | 可联调 | `ai_recommendation_reports` + `/api/ai/school-recommendations*`；默认要求当前学生有有效 SVIP，后端读取学生目标地区和分数线上下文，使用 `local_rules` 生成稳定 JSON 报告并写入报告台账和审计；真实 AI provider、人工 prompt 编排和 PDF 报告渲染待补 |
 | 题目视频/批量预加载/搜索 | 可联调 | `/api/questions/*/videos`、`/api/videos/search`；付费视频列表不返回可播放 URL |
 | 视频会员播放次数 | 可联调 | `POST /api/videos/play` 支持 SVIP/视频次数校验、签名播放、次数扣减、播放日志和动态水印上下文；`POST /api/videos/progress` 支持播放开始、心跳、完成上报；租户后台媒体报表已可按视频、用户、traceId 查询播放事件、观看秒数和完成率；深度防盗链和转码级水印继续补 |
 | 视频 JSON 导入和批量绑定 | 可联调 | `/api/tenant-content/imports/preview/videos`、`/api/tenant-content/imports/videos`；支持视频元数据、资源引用、播放模式、题目绑定和题目视频标记 |
--- a/docs/refactor/blueprint-coverage.md
+++ b/docs/refactor/blueprint-coverage.md
@@ -31,7 +31,7 @@
 | 数据看板 | 可联调 | 租户 dashboard 聚合接口，收益、注册、学习、内容、激活码、反馈、趋势、24h 活跃、套餐销量和运营动态 | 预聚合 worker、缓存、慢 SQL 监控和销售转化看板 |
 | 登录认证 | 可联调 | 短信 mock、阿里云/腾讯云短信 adapter、迁移期 session、Supabase Auth JWT、微信小程序登录、微信网页登录、QQ 登录、手机号绑定/换绑、OAuth 配置表 | 真实生产账号和回调域名联调 |
 | 支付 | 可联调 | 订单、支付记录、手动确认权限保护、权益发放、租户商户配置、微信支付 JSAPI、支付宝 WAP/H5、webhook 幂等、退款状态机、退款通知、补偿 worker、资金对账导入比对、异常查询、差错工单和事件轨迹 | 官方账单自动下载、异常订单运营台、服务商/平台代收模式 |
-| AI 择校推荐 | 未开始 | 暂无 | 数据上下文、AI provider、JSON 报告 schema、PDF 报告生成 |
+| AI 择校推荐 | 部分完成 | SVIP 门禁、学生输入 schema、地区/分数线上下文、`local_rules` 稳定 JSON 报告、报告台账/列表/详情、Taro 学生端基础页 | 真实 AI provider、prompt 版本管理后台、PDF 报告生成、人工复核和运营配置 |
 | Taro 跨端 | 未开始 | 旧 Web 新 API 适配开始 | `apps/taro`、共享 API client、H5/小程序统一构建 |

 ## 接下来优先级
--- a/docs/refactor/legacy-feature-gap-matrix.md
+++ b/docs/refactor/legacy-feature-gap-matrix.md
@@ -33,7 +33,7 @@
 | 商城/SVIP | `Store.tsx`、`SvipModal.tsx` | 部分覆盖 | 套餐、订单、订单详情/状态轮询、权益、激活码预检查/兑换、优惠券领取/下单抵扣、微信支付/支付宝 provider 主链路、内部退款状态机、微信/支付宝发起退款、退款查询确认、退款通知 webhook、支付/退款补偿 worker、全额退款权益撤销、资金对账手工/API 导入比对、异常查询、差错工单和事件轨迹已有；缺微信/支付宝官方账单自动下载、异常订单运营台和前端收银台/售后体验 |
 | 个人中心 | `Profile.tsx` | 部分覆盖 | 基本资料、手机号绑定/换绑、权益、订单统计、练习历史、学习统计、签到积分、考试倒计时、趋势和勋章展示 API 已有；缺学习报告可视化 |
 | 资料下载 | `QuestionExporterPublishModal.tsx` 等 | 部分覆盖 | 资源台账、上传确认、签名下载、PDF/图片预览、动态水印上下文、worker 复检、内置安全扫描和外部 HTTP scanner 接入层已有；缺前端水印渲染、深度防盗链、真实 AV/内容安全服务联调和生命周期策略 |
-| AI 择校推荐 | 业务规划新增 | 未覆盖 | 需设计学生输入 schema、地区数据上下文、AI JSON 输出、PDF 报告 |
+| AI 择校推荐 | 业务规划新增 | 部分覆盖 | 已有 SVIP 门禁、学生输入 schema、地区/分数线上下文、稳定 JSON 输出、报告台账、审计和 Taro 学生端基础页；真实 AI provider、prompt 版本管理后台、报告 PDF 渲染和更细推荐算法待补 |
 | 题目反馈 | `02-API接口.md` 用户反馈 | 部分覆盖 | 学生提交、本人列表、租户后台处理、状态事件、反馈奖励积分已覆盖；缺处理通知、前端消息提醒和批量统计 |
 | 签到积分 | `Profile.tsx`、`02-API接口.md` | 部分覆盖 | 每日签到、连续签到基础、积分流水、重复签到幂等已覆盖；缺积分兑换、活动任务和更完整的运营规则 |
 | 排行榜 | `leaderboard.pb.js`、`02-API接口.md` | 部分覆盖 | 已有刷题数、积分、背单词、模考最高分排行榜，支持租户/地区/班级范围和当前用户排名；后续补防刷、日/周榜预聚合、运营后台排名看板 |
@@ -102,9 +102,10 @@
 5. 导入扩展：题目/单词/知识手册/分数线/视频已支持 JSON、CSV 和 Excel 预览导入，并可用 `executionMode=async` 进入 imports worker；导入后复检、导入任务详情、模板下载按钮、字段映射 API、Taro 字段别名编辑、异步轮询和 PocketBase JSON dry-run 报告已补，仍缺真实数据执行验收。
 6. 公共题库商业化：平台公共/地区题库授权、租户快照采纳、手动同步、自动同步 worker、同步通知、冲突查询、租户自改冲突保护和单条/批量冲突处理已完成基础闭环；还需生产定时调度、失败告警和更完整运营后台消息。
 7. CRM/销售结算：CRM worker、跟进分配策略、分佣规则、结算单、审核、打款状态、导出和凭证复核基础闭环已完成；仍缺富卡片模板、失败告警、死信运营台、真实打款 provider、发票和销售结算看板。
-8. 题目反馈增强：处理通知、消息提醒、问题聚合统计和内容修复闭环。
-9. 积分活动增强：积分兑换、活动任务、连续签到奖励规则和风控。
-10. 勋章增强：后台维护和手动发放已有；仍缺按学习行为、签到、积分、活动任务自动发放，以及发放通知。
+8. AI 择校推荐增强：后端 `local_rules` 地基、SVIP 门禁、报告列表/详情和 Taro 基础页已完成；仍缺真实 AI provider、prompt 编排、PDF 报告和后台运营配置。
+9. 题目反馈增强：处理通知、消息提醒、问题聚合统计和内容修复闭环。
+10. 积分活动增强：积分兑换、活动任务、连续签到奖励规则和风控。
+11. 勋章增强：后台维护和手动发放已有；仍缺按学习行为、签到、积分、活动任务自动发放，以及发放通知。

 ### P0：前端联调到云端前

--- a/docs/refactor/next-development-todo.md
+++ b/docs/refactor/next-development-todo.md
@@ -138,10 +138,8 @@
   - 继续补批量 CRM 推送、学习督导自动化、跟进效果统计和更细导入模板体验。

 13. AI 择校推荐
-   - 地区考试数据上下文。
-   - 学生输入 schema。
-   - AI 返回 JSON schema。
-   - 报告渲染和 PDF 生成。
+   - 已完成 `ai_recommendation_reports` 报告台账、SVIP 门禁、学生输入 schema、地区/分数线上下文、`local_rules` 稳定 JSON 输出、报告列表/详情接口和 Taro 学生端基础页。
+   - 继续补真实 AI provider adapter、租户级 `app_private.tenant_secrets(secret_scope='ai')` 密钥联调、prompt 版本管理、运营后台配置、报告 PDF 渲染和人工复核流程。

 ### P2 运营体验和企业交付

--- a/docs/refactor/taro-frontend-integration.md
+++ b/docs/refactor/taro-frontend-integration.md
@@ -2055,7 +2055,9 @@ ACTIVATION_CODE_REGION_MISMATCH
   - 手册目录和阅读。
 9. `pages/scoreline/index`
   - 动态字段筛选和趋势。
-10. `pages/profile/index`
+10. `pages/ai-school/index`
+   - SVIP AI 择校推荐、报告历史和 JSON 报告渲染。
+11. `pages/profile/index`
   - 会员、订单、激活码、学习数据、勋章。

 ## 当前 Taro 实现进度
@@ -2076,6 +2078,7 @@ pages/student/order-detail/index
 pages/student/vocabulary/index
 pages/student/handbook/index
 pages/student/scoreline/index
+pages/student/ai-school/index
 pages/student/assets/index
 pages/student/profile/index
 ```
@@ -2088,6 +2091,7 @@ src/services/learning.ts   练习 session、答题、收藏、错题/收藏复
 src/services/commerce.ts   套餐、优惠券、下单、支付参数、订单详情、权益、激活码
 src/services/profile.ts    个人中心、地区目标、签到、反馈、勋章、倒计时
 src/services/video.ts      题目视频列表、播放签名
+src/services/ai.ts         AI 择校推荐生成、报告列表、报告详情
 src/services/tenantAdmin.ts 租户后台看板、权限矩阵、成员、学生创建/批量导入/分班/备注/跟进、内容、营销、设置、角色模板写操作、公共题库采纳/同步/单条和批量冲突处理、导入详情/复检、CRM 配置/队列、分佣规则/成员比例/订单/结算
 src/services/platformAdmin.ts 平台后台租户、套餐账单、用量、公共题库授权
 ```
@@ -2110,6 +2114,87 @@ npm run build:taro:h5:platform
 - 平台后台：租户创建、状态变更、订阅开通、账单生成、人工收款确认、用量录入、公共题库授权编辑已接第一版；继续补租户详情/编辑、平台审计、自动计费和批量账单操作。
 - 小程序：验证 `Taro.login`、微信支付、分享 scene/referral、Supabase client 兼容性；如不稳定，保留 `apps/api/auth/*` 作为小程序登录适配层。

+## AI 择校推荐接入
+
+AI 择校推荐是学生端 SVIP 功能，前端只调用 `apps/api`，不要在 H5/小程序内保存任何 AI provider key、prompt secret 或服务端模型配置。当前后端默认使用 deterministic `local_rules` provider，基于学生目标地区和 `scoreline_records` 生成稳定 JSON 报告；后续真实 AI provider 仍保持同一接口和 JSON schema。
+
+生成报告：
+
+```http
+POST /api/ai/school-recommendations/generate
+```
+
+请求体：
+
+```json
+{
+  "regionId": "<regionId>",
+  "estimatedScore": 210,
+  "riskPreference": "balanced",
+  "constraints": "优先考虑计算机相关专业",
+  "recommendationLimit": 5
+}
+```
+
+`riskPreference` 支持 `safe`、`balanced`、`sprint`。`regionId` 不传时后端会使用 `/api/profile/me` 中学生档案的目标地区。后端会校验该地区属于当前租户，并要求当前学生有有效 SVIP；无权限时返回 `AI_SVIP_REQUIRED`。
+
+响应核心结构：
+
+```json
+{
+  "item": {
+    "id": "<reportId>",
+    "status": "generated",
+    "provider": "local_rules",
+    "model": "local-scoreline-rules-v1",
+    "promptVersion": "school-recommendation-v1",
+    "resultPayload": {
+      "schemaVersion": "school-recommendation-report-v1",
+      "summary": "基于当前地区历年分数线...",
+      "riskLevel": "balanced",
+      "recommendedSchools": [
+        {
+          "schoolId": "<schoolId>",
+          "schoolName": "烟测学院",
+          "majorId": "<majorId>",
+          "majorName": "计算机科学与技术",
+          "latestYear": 2026,
+          "latestScore": 188,
+          "scoreGap": 22,
+          "riskLevel": "safe",
+          "confidence": 0.9,
+          "reason": "预估分与最新参考线差值约 22 分...",
+          "scorelineTrend": {
+            "years": [2026],
+            "scores": [188],
+            "direction": "unknown"
+          },
+          "tags": ["稳妥", "趋势不足", "样本较少"]
+        }
+      ],
+      "actionPlan": [],
+      "disclaimers": [],
+      "dataCoverage": {}
+    }
+  }
+}
+```
+
+报告历史：
+
+```http
+GET /api/ai/school-recommendations?regionId=<regionId>&limit=20
+GET /api/ai/school-recommendations/detail?reportId=<reportId>
+```
+
+前端渲染建议：
+
+- `resultPayload.schemaVersion` 必须等于 `school-recommendation-report-v1`，未知版本先降级为只展示 summary 和原始 JSON。
+- `recommendedSchools` 是服务端已排序结果，前端不要重新按分数线做业务排序。
+- `disclaimers` 必须展示在报告底部或导出 PDF 中。
+- 报告详情只能展示当前登录学生自己的报告，遇到 `AI_REPORT_NOT_FOUND` 按“报告不存在或无权访问”处理。
+- 当前 Taro 基础页在 `pages/student/ai-school/index`，service 在 `src/services/ai.ts`。
+
 ## 租户后台前端建议

 租户后台可以先做 H5 管理台，也可以后续使用 Taro H5 复用部分组件。优先页面：