From 686b3609cfb488238aaf5a9c4b77a0d5ad944b2b Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 30 Jun 2026 19:04:30 +0800 Subject: [PATCH] feat: add ai recommendation exports --- README.md | 2 +- apps/api/src/features/ai/index.ts | 2 + apps/api/src/features/ai/routes.ts | 272 ++++++++++++++++++ .../src/pages/student/ai-school/index.tsx | 41 +++ apps/taro/src/services/ai.ts | 17 ++ docs/refactor/backend-capability-status.md | 2 +- docs/refactor/backend-handoff-roadmap.md | 4 +- docs/refactor/blueprint-coverage.md | 2 +- docs/refactor/frontend-handoff-index.md | 3 +- docs/refactor/legacy-feature-gap-matrix.md | 4 +- docs/refactor/next-development-todo.md | 4 +- docs/refactor/taro-frontend-integration.md | 8 +- scripts/api-integration-test.js | 31 ++ 13 files changed, 380 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index df153d56..45a8843c 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ - 题库导出已完成服务端结构化 payload、PDF/Word 二进制 worker、每日一练基础导出和每日一练 ZIP 图片素材包；后续还要补更精细试卷模板、多模板排版和导出操作台体验。 - 优惠券复杂规则和核销报表已可联调，包含状态启停、活动分组、最低订单金额、优惠封顶、单用户限次、首单限制、适用套餐/地区、核销明细和活动报表；Taro 租户营销中心已接优惠券规则表单、筛选、核销明细和报表第一版。 - 勋章管理、手动发放、签到连续天数、积分阈值、反馈解决、积分活动任务、练习次数、单词掌握和模考成绩系统触发勋章已可联调；积分活动任务、积分兑换商品、兑换订单、优惠券兑换履约、租户后台配置和用户站内通知第一版已完成，Taro 学生个人中心已接积分任务/兑换/积分明细和消息中心第一版，租户营销中心已接积分任务/兑换操作台和用户通知查看第一版。学生激励默认以后台配置勋章自动发放为主，排行榜默认不开启也不在学生端默认请求。后续还要补更细活动效果看板、外部微信订阅消息/短信推送、分佣真实打款 provider、发票、批量凭证上传、CRM 富卡片模板、失败告警、死信运营台、销售转化看板、公共题库版本通知和冲突处理操作台。 -- `apps/taro` 已建立 Taro 4 React 跨端前端地基，包含 H5 学生端、租户后台、平台后台三套构建入口、租户解析、统一 API client 和 Supabase Auth client 初始化；学生端第一批页面已接入登录、首页、题库、练习、背单词、知识手册、分数线、AI 择校推荐、资料、独立消息中心和个人中心，已新增 `RichContent` 安全渲染组件用于题干、选项、解析、知识手册和逐题复盘，H5 端已用 KaTeX 渲染 `$...$`、`$$...$$`、`\(...\)`、`\[...\]` 公式，私有题图可用 `asset:`/`content_asset:` 资源引用走短期预览签名，已升级背单词为今日计划/单元学习/收藏练习、学习概览、掌握率、收藏数、计划拆分、卡片翻转、发音、美/英音切换和本地位置恢复第一版，知识手册已接章节内搜索、安全文本摘要高亮和目录定位第一版，分数线已接目标地区默认筛选、院校/专业/年份 chip、租户动态字段筛选、结果字段 chip 和趋势摘要第一版，资料页已补齐预览/下载的短签名、水印 traceId 和强制水印容器第一版，个人中心已接学习报告、14 天趋势、题型表现、最近练习、男女预设头像选择、积分任务/兑换/积分明细和消息中心摘要第一版，独立消息中心已接状态/类型筛选、批量已读、归档/忽略和站内安全跳转第一版；学生端不默认请求排行榜，仅在租户显式开启 `enableLeaderboard` 并完成压测后进入独立排行榜页或活动页；租户后台第一批页面已接入工作台、数据看板、学生/班级、题库内容、营销中心、财务运营和租户设置，学生运营页已接跟进看板、学习督导自动化、督导规则保存和批量 CRM 推送第一版，营销中心已接 CRM、分佣结算、优惠券规则/核销报表、积分任务/兑换操作台和用户通知查看第一版，财务运营已接退款状态机、官方账单任务、对账异常、差错工单和调整凭证第一版，设置页已接主题模板、草稿预览/发布、角色模板和成员绑定第一版；平台后台已接入工作台、租户管理、账务中心、公共题库授权、平台员工管理，以及创建租户、租户详情、状态变更、账务资料维护、平台员工创建/编辑/禁用恢复、权限点勾选、平台审计查询/CSV 导出、开放审计告警确认/解决、审计告警外部通知渠道/事件状态摘要、订阅、订阅账单候选/dry-run/批量生成、自动计费 worker 生成结果查看、收款、逾期预览/催缴记录、催缴外部通知渠道/事件摘要、用量和题库授权第一版写操作。 +- `apps/taro` 已建立 Taro 4 React 跨端前端地基，包含 H5 学生端、租户后台、平台后台三套构建入口、租户解析、统一 API client 和 Supabase Auth client 初始化；学生端第一批页面已接入登录、首页、题库、练习、背单词、知识手册、分数线、AI 择校推荐、资料、独立消息中心和个人中心，已新增 `RichContent` 安全渲染组件用于题干、选项、解析、知识手册和逐题复盘，H5 端已用 KaTeX 渲染 `$...$`、`$$...$$`、`\(...\)`、`\[...\]` 公式，私有题图可用 `asset:`/`content_asset:` 资源引用走短期预览签名，已升级背单词为今日计划/单元学习/收藏练习、学习概览、掌握率、收藏数、计划拆分、卡片翻转、发音、美/英音切换和本地位置恢复第一版，知识手册已接章节内搜索、安全文本摘要高亮和目录定位第一版，分数线已接目标地区默认筛选、院校/专业/年份 chip、租户动态字段筛选、结果字段 chip 和趋势摘要第一版，AI 择校已接报告生成、历史报告和 Markdown/HTML 导出第一版，资料页已补齐预览/下载的短签名、水印 traceId 和强制水印容器第一版，个人中心已接学习报告、14 天趋势、题型表现、最近练习、男女预设头像选择、积分任务/兑换/积分明细和消息中心摘要第一版，独立消息中心已接状态/类型筛选、批量已读、归档/忽略和站内安全跳转第一版；学生端不默认请求排行榜，仅在租户显式开启 `enableLeaderboard` 并完成压测后进入独立排行榜页或活动页；租户后台第一批页面已接入工作台、数据看板、学生/班级、题库内容、营销中心、财务运营和租户设置，学生运营页已接跟进看板、学习督导自动化、督导规则保存和批量 CRM 推送第一版，营销中心已接 CRM、分佣结算、优惠券规则/核销报表、积分任务/兑换操作台和用户通知查看第一版，财务运营已接退款状态机、官方账单任务、对账异常、差错工单和调整凭证第一版，设置页已接主题模板、草稿预览/发布、角色模板和成员绑定第一版；平台后台已接入工作台、租户管理、账务中心、公共题库授权、平台员工管理，以及创建租户、租户详情、状态变更、账务资料维护、平台员工创建/编辑/禁用恢复、权限点勾选、平台审计查询/CSV 导出、开放审计告警确认/解决、审计告警外部通知渠道/事件状态摘要、订阅、订阅账单候选/dry-run/批量生成、自动计费 worker 生成结果查看、收款、逾期预览/催缴记录、催缴外部通知渠道/事件摘要、用量和题库授权第一版写操作。 - 根目录已清理为新 Supabase SaaS monorepo 编排层；旧 PocketBase/React 项目和旧构建产物仅保留在 `参考/` 目录作为迁移参考，不进入 Git 提交。 更完整的进度看这些文档： diff --git a/apps/api/src/features/ai/index.ts b/apps/api/src/features/ai/index.ts index 44db5471..393b13ed 100644 --- a/apps/api/src/features/ai/index.ts +++ b/apps/api/src/features/ai/index.ts @@ -1,6 +1,7 @@ import type { RouteDefinition } from '../../core/router.js'; import { generateSchoolRecommendationRoute, + schoolRecommendationReportExportRoute, schoolRecommendationReportDetailRoute, schoolRecommendationReportsRoute, } from './routes.js'; @@ -8,5 +9,6 @@ import { export const aiRoutes: RouteDefinition[] = [ ['GET', '/api/ai/school-recommendations', schoolRecommendationReportsRoute], ['GET', '/api/ai/school-recommendations/detail', schoolRecommendationReportDetailRoute], + ['GET', '/api/ai/school-recommendations/export', schoolRecommendationReportExportRoute], ['POST', '/api/ai/school-recommendations/generate', generateSchoolRecommendationRoute], ]; diff --git a/apps/api/src/features/ai/routes.ts b/apps/api/src/features/ai/routes.ts index 0b789689..9657fc3b 100644 --- a/apps/api/src/features/ai/routes.ts +++ b/apps/api/src/features/ai/routes.ts @@ -1,3 +1,4 @@ +import crypto from 'node:crypto'; import { HttpError, type RequestContext } from '../../core/http.js'; import { intParam, readJsonBody, stringParam, tenantIdFrom, userIdFrom } from '../../core/request.js'; import { query, queryOne, transaction } from '../../core/db.js'; @@ -66,6 +67,24 @@ interface RecommendationCandidate { tags: string[]; } +interface SchoolRecommendationReportRow { + id: string; + tenantId: string; + userId: string; + regionId: string | null; + status: string; + provider: string; + model: string | null; + promptVersion: string; + inputPayload: JsonObject; + contextPayload: JsonObject; + resultPayload: JsonObject; + errorMessage: string | null; + generatedAt: string | null; + createdAt: string; + updatedAt: string; +} + const RISK_PREFERENCES = new Set(['safe', 'balanced', 'sprint']); const PROMPT_VERSION = 'school-recommendation-v1'; const LOCAL_MODEL = 'local-scoreline-rules-v1'; @@ -95,6 +114,51 @@ function boundedText(value: unknown, maxLength: number) { return text.slice(0, maxLength); } +function textValue(value: unknown, fallback = '') { + if (value === null || value === undefined) return fallback; + if (typeof value === 'object') return JSON.stringify(value); + return String(value); +} + +function numberValue(value: unknown) { + const parsed = Number(value); + return Number.isFinite(parsed) ? parsed : null; +} + +function arrayValue(value: unknown) { + return Array.isArray(value) ? value : []; +} + +function htmlEscape(value: unknown) { + return textValue(value) + .replace(/&/g, '&') + .replace(//g, '>') + .replace(/"/g, '"') + .replace(/'/g, '''); +} + +function markdownText(value: unknown) { + return textValue(value).replace(/[<>]/g, ''); +} + +function contentBase64AndHash(content: string) { + const buffer = Buffer.from(content, 'utf8'); + return { + contentBase64: buffer.toString('base64'), + sha256: crypto.createHash('sha256').update(buffer).digest('hex'), + sizeBytes: buffer.length, + }; +} + +function reportExportFormat(value: string) { + const format = value || 'markdown'; + if (!['markdown', 'html'].includes(format)) { + throw new HttpError(400, 'format must be markdown or html', 'AI_REPORT_EXPORT_FORMAT_INVALID'); + } + return format as 'markdown' | 'html'; +} + function normalizeRiskPreference(value: unknown) { const riskPreference = nullableString(value) || 'balanced'; if (!RISK_PREFERENCES.has(riskPreference)) { @@ -402,6 +466,176 @@ function reportSelectSql() { `; } +function riskLabel(value: unknown) { + const labels: Record = { + safe: '稳妥', + balanced: '均衡', + sprint: '冲刺', + unknown: '未知', + }; + return labels[textValue(value)] || '未知'; +} + +function directionLabel(value: unknown) { + const labels: Record = { + up: '上升', + down: '下降', + flat: '稳定', + unknown: '样本不足', + }; + return labels[textValue(value)] || '样本不足'; +} + +function reportFileTimestamp(value: string | null | undefined) { + const source = value ? new Date(value) : new Date(); + const valid = Number.isFinite(source.getTime()) ? source : new Date(); + return valid.toISOString().slice(0, 19).replace(/[-:T]/g, ''); +} + +function buildReportMarkdown(report: SchoolRecommendationReportRow) { + const result = objectValue(report.resultPayload); + const input = objectValue(report.inputPayload); + const coverage = objectValue(result.dataCoverage); + const recommendations = arrayValue(result.recommendedSchools).map(objectValue); + const actionPlan = arrayValue(result.actionPlan); + const disclaimers = arrayValue(result.disclaimers); + + const lines = [ + '# AI 择校推荐报告', + '', + `生成时间：${markdownText(report.generatedAt || report.createdAt)}`, + `报告编号：${markdownText(report.id)}`, + `推荐偏好：${riskLabel(input.riskPreference)}`, + input.estimatedScore !== undefined ? `预估分：${markdownText(input.estimatedScore)}` : '', + input.constraints ? `限制条件：${markdownText(input.constraints)}` : '', + '', + '## 结论摘要', + markdownText(result.summary || '暂无摘要'), + '', + `整体方案：${riskLabel(result.riskLevel)}`, + '', + '## 推荐院校', + ].filter(Boolean); + + recommendations.forEach((candidate, index) => { + const trend = objectValue(candidate.scorelineTrend); + const tags = arrayValue(candidate.tags).map(markdownText).filter(Boolean); + lines.push( + '', + `### ${index + 1}. ${markdownText(candidate.schoolName || '未知院校')}${candidate.majorName ? ` · ${markdownText(candidate.majorName)}` : ''}`, + `风险档位：${riskLabel(candidate.riskLevel)} · 置信度：${Math.round((numberValue(candidate.confidence) || 0) * 100)}%`, + `最新年份：${markdownText(candidate.latestYear ?? '未知')} · 最新参考线：${markdownText(candidate.latestScore ?? '未知')} · 差值：${markdownText(candidate.scoreGap ?? '未知')}`, + `均值参考：${markdownText(candidate.averageScore ?? '未知')} · 趋势：${directionLabel(trend.direction)}`, + `理由：${markdownText(candidate.reason || '暂无理由')}`, + tags.length ? `标签：${tags.join('、')}` : '', + ); + }); + + if (!recommendations.length) { + lines.push('', '暂无可推荐院校。'); + } + + lines.push('', '## 行动计划'); + actionPlan.forEach((item, index) => { + lines.push(`${index + 1}. ${markdownText(item)}`); + }); + if (!actionPlan.length) lines.push('暂无行动计划。'); + + lines.push('', '## 数据覆盖'); + lines.push(`地区：${markdownText(coverage.regionName || coverage.regionId || report.regionId || '未知')}`); + lines.push(`分数线样本：${markdownText(coverage.scorelineRecordCount ?? 0)}`); + lines.push(`候选组数：${markdownText(coverage.schoolMajorGroupCount ?? recommendations.length)}`); + const years = arrayValue(coverage.years).map(markdownText).filter(Boolean); + if (years.length) lines.push(`覆盖年份：${years.join('、')}`); + + lines.push('', '## 免责声明'); + disclaimers.forEach(item => { + lines.push(`- ${markdownText(item)}`); + }); + if (!disclaimers.length) { + DISCLAIMER.forEach(item => lines.push(`- ${markdownText(item)}`)); + } + + return `${lines.filter(line => line !== '').join('\n')}\n`; +} + +function buildReportHtml(report: SchoolRecommendationReportRow) { + const result = objectValue(report.resultPayload); + const input = objectValue(report.inputPayload); + const coverage = objectValue(result.dataCoverage); + const recommendations = arrayValue(result.recommendedSchools).map(objectValue); + const actionPlan = arrayValue(result.actionPlan); + const disclaimers = arrayValue(result.disclaimers).length ? arrayValue(result.disclaimers) : DISCLAIMER; + const rows = recommendations.map((candidate, index) => { + const trend = objectValue(candidate.scorelineTrend); + const tags = arrayValue(candidate.tags).map(htmlEscape).filter(Boolean); + return ` +
+

${index + 1}. ${htmlEscape(candidate.schoolName || '未知院校')}${candidate.majorName ? ` · ${htmlEscape(candidate.majorName)}` : ''}

+

${riskLabel(candidate.riskLevel)} · 置信度 ${Math.round((numberValue(candidate.confidence) || 0) * 100)}%

+

最新年份：${htmlEscape(candidate.latestYear ?? '未知')} · 最新参考线：${htmlEscape(candidate.latestScore ?? '未知')} · 差值：${htmlEscape(candidate.scoreGap ?? '未知')}

+

均值参考：${htmlEscape(candidate.averageScore ?? '未知')} · 趋势：${directionLabel(trend.direction)}

+

${htmlEscape(candidate.reason || '暂无理由')}

+ ${tags.length ? `

${tags.join(' / ')}

` : ''} +
+ `; + }).join('\n'); + const years = arrayValue(coverage.years).map(htmlEscape).filter(Boolean); + + return ` + + + + AI 择校推荐报告 + + + +
+

AI 择校推荐报告

+

生成时间：${htmlEscape(report.generatedAt || report.createdAt)} · 报告编号：${htmlEscape(report.id)}

+

推荐偏好：${riskLabel(input.riskPreference)}${input.estimatedScore !== undefined ? ` · 预估分：${htmlEscape(input.estimatedScore)}` : ''}

+ ${input.constraints ? `

限制条件：${htmlEscape(input.constraints)}

` : ''} +
+

结论摘要

+

${htmlEscape(result.summary || '暂无摘要')}

+

整体方案：${riskLabel(result.riskLevel)}

+
+

推荐院校

+ ${rows || '

暂无可推荐院校。

'} +

行动计划

+
    ${actionPlan.map(item => `
  1. ${htmlEscape(item)}
    2. `).join('') || '
  2. 暂无行动计划。
    3. '}
+

数据覆盖

+

地区：${htmlEscape(coverage.regionName || coverage.regionId || report.regionId || '未知')} · 分数线样本：${htmlEscape(coverage.scorelineRecordCount ?? 0)} · 候选组数：${htmlEscape(coverage.schoolMajorGroupCount ?? recommendations.length)}${years.length ? ` · 覆盖年份：${years.join('、')}` : ''}

+

免责声明

+
    ${disclaimers.map(item => `
  • ${htmlEscape(item)}
    • `).join('')}
+
+ + +`; +} + +function buildReportExport(report: SchoolRecommendationReportRow, format: 'markdown' | 'html') { + const content = format === 'html' ? buildReportHtml(report) : buildReportMarkdown(report); + const encoded = contentBase64AndHash(content); + const extension = format === 'html' ? 'html' : 'md'; + return { + reportId: report.id, + format, + fileName: `school-recommendation-${reportFileTimestamp(report.generatedAt || report.createdAt)}-${report.id.slice(0, 8)}.${extension}`, + mimeType: format === 'html' ? 'text/html; charset=utf-8' : 'text/markdown; charset=utf-8', + contentText: content, + ...encoded, + }; +} + export async function generateSchoolRecommendationRoute(ctx: RequestContext) { const body = await readJsonBody(ctx); const tenantId = await tenantIdFrom(ctx); @@ -544,3 +778,41 @@ export async function schoolRecommendationReportDetailRoute(ctx: RequestContext) if (!item) throw new HttpError(404, 'AI recommendation report not found', 'AI_REPORT_NOT_FOUND'); return { item }; } + +export async function schoolRecommendationReportExportRoute(ctx: RequestContext) { + const tenantId = await tenantIdFrom(ctx); + const userId = await userIdFrom(ctx); + const reportId = stringParam(ctx, 'reportId'); + const format = reportExportFormat(stringParam(ctx, 'format')); + if (!reportId) throw new HttpError(400, 'reportId is required', 'AI_REPORT_ID_REQUIRED'); + + const item = await queryOne( + ` + ${reportSelectSql()} + where tenant_id = $1 and user_id = $2 and id = $3::uuid and status = 'generated' + limit 1 + `, + [tenantId, userId, reportId], + ); + if (!item) throw new HttpError(404, 'AI recommendation report not found', 'AI_REPORT_NOT_FOUND'); + + const exportItem = buildReportExport(item, format); + await query( + ` + insert into public.audit_logs (tenant_id, actor_user_id, action, target_type, target_id, details) + values ($1, $2, 'ai.school_recommendation.exported', 'ai_recommendation_report', $3, $4::jsonb) + `, + [ + tenantId, + userId, + item.id, + JSON.stringify({ + format, + sha256: exportItem.sha256, + sizeBytes: exportItem.sizeBytes, + }), + ], + ); + + return { item: exportItem }; +} diff --git a/apps/taro/src/pages/student/ai-school/index.tsx b/apps/taro/src/pages/student/ai-school/index.tsx index 15eb96fc..ba40358b 100644 --- a/apps/taro/src/pages/student/ai-school/index.tsx +++ b/apps/taro/src/pages/student/ai-school/index.tsx @@ -1,6 +1,8 @@ import { useEffect, useState } from 'react'; +import Taro from '@tarojs/taro'; import { Button, Input, Picker, Text, Textarea, View } from '@tarojs/components'; import { + exportSchoolRecommendationReport, generateSchoolRecommendation, loadSchoolRecommendationReports, type SchoolRecommendationReport, @@ -22,6 +24,24 @@ function recommendationRows(report: SchoolRecommendationReport | null) { return report?.resultPayload?.recommendedSchools || []; } +function saveExportFile(fileName: string, content: string, mimeType: string) { + if (process.env.TARO_ENV === 'h5' && typeof window !== 'undefined' && typeof document !== 'undefined') { + const blob = new Blob([content], { type: mimeType }); + const url = window.URL.createObjectURL(blob); + const link = document.createElement('a'); + link.href = url; + link.download = fileName; + link.rel = 'noopener noreferrer'; + document.body.appendChild(link); + link.click(); + link.remove(); + window.URL.revokeObjectURL(url); + return; + } + Taro.setClipboardData({ data: content }); + Taro.showToast({ title: '报告内容已复制', icon: 'none' }); +} + export default function StudentAiSchoolPage() { const [profile, setProfile] = useState(null); const [reports, setReports] = useState([]); @@ -30,6 +50,7 @@ export default function StudentAiSchoolPage() { const [constraints, setConstraints] = useState(''); const [riskIndex, setRiskIndex] = useState(0); const [loading, setLoading] = useState(false); + const [exporting, setExporting] = useState(''); const [error, setError] = useState(''); useEffect(() => { @@ -65,6 +86,22 @@ export default function StudentAiSchoolPage() { } } + async function handleExport(format: 'markdown' | 'html') { + if (!current?.id) return; + setExporting(format); + setError(''); + try { + const payload = await exportSchoolRecommendationReport(current.id, format); + if (!payload.item?.contentText) throw new Error('后端未返回报告内容'); + saveExportFile(payload.item.fileName, payload.item.contentText, payload.item.mimeType); + if (process.env.TARO_ENV === 'h5') Taro.showToast({ title: '报告已导出', icon: 'success' }); + } catch (nextError) { + setError(nextError instanceof Error ? nextError.message : '导出失败'); + } finally { + setExporting(''); + } + } + const rows = recommendationRows(current); return ( @@ -123,6 +160,10 @@ export default function StudentAiSchoolPage() { {riskLabel(current.resultPayload.riskLevel)}方案 {current.resultPayload.summary} + + + + {rows.map(item => ( diff --git a/apps/taro/src/services/ai.ts b/apps/taro/src/services/ai.ts index 38843acf..0670bad9 100644 --- a/apps/taro/src/services/ai.ts +++ b/apps/taro/src/services/ai.ts @@ -63,6 +63,17 @@ export interface SchoolRecommendationReport { updatedAt: string; } +export interface SchoolRecommendationExport { + reportId: string; + format: 'markdown' | 'html'; + fileName: string; + mimeType: string; + contentBase64: string; + contentText?: string; + sha256: string; + sizeBytes: number; +} + export async function generateSchoolRecommendation(input: GenerateSchoolRecommendationInput) { return apiRequest<{ item?: SchoolRecommendationReport }>('/api/ai/school-recommendations/generate', { method: 'POST', @@ -81,3 +92,9 @@ export async function loadSchoolRecommendationReport(reportId: string) { query: { reportId }, }); } + +export async function exportSchoolRecommendationReport(reportId: string, format: 'markdown' | 'html' = 'markdown') { + return apiRequest<{ item?: SchoolRecommendationExport }>('/api/ai/school-recommendations/export', { + query: { reportId, format }, + }); +} diff --git a/docs/refactor/backend-capability-status.md b/docs/refactor/backend-capability-status.md index cae01f5f..09863d93 100644 --- a/docs/refactor/backend-capability-status.md +++ b/docs/refactor/backend-capability-status.md @@ -84,7 +84,7 @@ | 知识手册 JSON 导入 | 可联调 | `/api/tenant-content/imports/*/handbook` | | 分数线字段/院校/专业/记录/趋势 | 可联调 | `/api/scoreline/*`；`records` 支持 `field.`、`min.`、`max.` 动态字段筛选，只允许 `scoreline_fields.is_filter=true` 且字段名安全的字段参与查询 | | 分数线 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 报告渲染待补 | +| AI 择校推荐 | 可联调 | `ai_recommendation_reports` + `/api/ai/school-recommendations*`；默认要求当前学生有有效 SVIP，后端读取学生目标地区和分数线上下文，使用 `local_rules` 生成稳定 JSON 报告并写入报告台账和审计；已支持本人报告 Markdown/HTML 导出、hash、审计和跨用户拒绝；真实 AI provider、人工 prompt 编排和 PDF worker 渲染待补 | | 题目视频/批量预加载/搜索 | 可联调 | `/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`；支持视频元数据、资源引用、播放模式、题目绑定和题目视频标记 | diff --git a/docs/refactor/backend-handoff-roadmap.md b/docs/refactor/backend-handoff-roadmap.md index fe907169..2cad462a 100644 --- a/docs/refactor/backend-handoff-roadmap.md +++ b/docs/refactor/backend-handoff-roadmap.md @@ -34,7 +34,7 @@ | 销售/代理/CRM | 可联调 | 邀请码、首绑保护、团队关系、销售统计、CRM 配置/队列、钉钉/飞书/企微 worker、分佣规则、成员分佣比例、订单/激活码归因、结算生成、审核和打款状态；Taro 营销中心已接第一版操作台 | 小程序码真实生成、CRM 分配策略、结算导出、真实打款、凭证、财务复核和销售转化看板 | | 内容导入 | 可联调 | 题目、单词、知识手册、分数线、视频 JSON/CSV/Excel preview/import、issue、job/detail、审计、幂等、`executionMode=async`、imports worker、导入后复检、模板下载、字段映射 API、字段映射覆盖白名单校验、PocketBase JSON dry-run 报告；Taro 租户内容页已接上传/粘贴预览、模板文件下载、字段别名编辑、同步/异步执行、异步轮询和复检详情第一版 | 真实数据 dry-run 执行验收、抽样校验和导入性能压测 | | 数据看板 | 可联调 | 租户 dashboard 聚合接口，收益、注册、学习、内容、激活码、反馈、趋势、24h 活跃、套餐销量和运营动态 | 预聚合 worker、缓存、慢 SQL 监控和销售转化看板 | -| AI 择校推荐 | 可联调 | `ai_recommendation_reports`、SVIP 门禁、学生输入 schema、地区/分数线上下文、`local_rules` 稳定 JSON、报告列表/详情和 Taro 学生端基础页 | 真实 AI provider、prompt 版本管理、租户后台配置、报告 PDF 渲染和人工复核流程 | +| AI 择校推荐 | 可联调 | `ai_recommendation_reports`、SVIP 门禁、学生输入 schema、地区/分数线上下文、`local_rules` 稳定 JSON、报告列表/详情、Markdown/HTML 导出和 Taro 学生端基础页 | 真实 AI provider、prompt 版本管理、租户后台配置、报告 PDF worker 渲染和人工复核流程 | | Taro 前端 | 地基已建 | `apps/taro` 已有 Taro 4 React 工程、H5 三入口、租户解析、统一 API client、Supabase Auth client 初始化；学生端、租户后台和平台后台均已有第一批真实 API 页面；学生端已接地区选择、刷题答题卡、后端权威断点续练、本地进度恢复、模拟倒计时、主观题后端自评、阅读理解/案例分析多小题作答、错题/收藏复习、题目反馈、视频解析、练习/模考报告、收银台、订单详情、售后入口和男女预设头像选择第一版；平台后台已接关键写操作、租户详情、账务资料编辑、平台员工列表/创建/编辑/禁用恢复、平台审计查询和 CSV 导出、开放审计告警展示/确认/解决、审计告警外部通知渠道/事件状态摘要、订阅账单候选预览/dry-run/批量生成、自动计费生成结果查看、逾期预览、催缴记录和催缴外部通知摘要第一版，租户工作台已接权限驱动模块入口，租户学生运营页已接创建/更新、禁用/恢复、批量导入、批量分班、备注、跟进任务、学习督导预览/生成和保存每日规则第一版，租户内容页已接公共题库采纳/同步、冲突查看、单条/批量采纳平台或保留本地、导入问题、字段模板预览/下载、上传/粘贴预览、字段别名覆盖、同步/异步导入、异步轮询和复检详情第一版；租户设置页已接角色模板和成员绑定操作台第一版；租户营销中心已接 CRM 配置保存、队列筛选、分佣规则、成员比例、订单明细、结算生成/审核/标记线下打款、积分任务/兑换和积分风控摘要第一版 | 长题干/公式图片混排体验、更细数据范围 UI、学习督导触达联动、平台审计告警升级策略、平台催缴通知配置操作台细节、小程序兼容验证和端到端测试 | ## 前端接入建议 @@ -97,7 +97,7 @@ - 三套默认主题、租户主题预览、Logo/图标/分享图配置。 - CRM worker：钉钉、飞书、企微机器人发送、签名、失败重试已落地；Taro 营销中心已能配置 CRM 和查看队列；继续补轮询/定向分配、富卡片、失败告警和死信运营台。 - 销售/代理分佣基础闭环已接 Taro 第一版；继续补销售团队看板、客资跟进效果、结算导出、真实打款、凭证和财务复核。 -- AI 择校推荐：`local_rules` JSON 报告地基已完成；继续补真实 AI provider、prompt 版本、租户后台配置、PDF 报告生成和人工复核。 +- AI 择校推荐：`local_rules` JSON 报告、本人报告 Markdown/HTML 导出地基已完成；继续补真实 AI provider、prompt 版本、租户后台配置、PDF worker 报告生成和人工复核。 - 性能压测、慢 SQL 审查、备份恢复演练、灰度发布和回滚预案。 ## 后端完成判定 diff --git a/docs/refactor/blueprint-coverage.md b/docs/refactor/blueprint-coverage.md index 5ac40142..2673431e 100644 --- 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、微信/支付宝官方账单下载 worker、资金对账导入比对、异常查询、差错工单和事件轨迹 | 异常订单运营台、真实生产账单格式验收、服务商/平台代收模式 | -| AI 择校推荐 | 部分完成 | SVIP 门禁、学生输入 schema、地区/分数线上下文、`local_rules` 稳定 JSON 报告、报告台账/列表/详情、Taro 学生端基础页 | 真实 AI provider、prompt 版本管理后台、PDF 报告生成、人工复核和运营配置 | +| AI 择校推荐 | 部分完成 | SVIP 门禁、学生输入 schema、地区/分数线上下文、`local_rules` 稳定 JSON 报告、报告台账/列表/详情、Markdown/HTML 导出、Taro 学生端基础页 | 真实 AI provider、prompt 版本管理后台、PDF worker 报告生成、人工复核和运营配置 | | Taro 跨端 | 部分完成 | `apps/taro` 已有 Taro 4 React 工程、H5 学生端/租户后台/平台后台三套构建入口、统一 API client、Supabase Auth client、H5 `runtime-config.json` 运行时配置、学生端第一批学习页面、租户后台第一批运营页面、平台后台第一批管理页面 | 小程序真机兼容、支付/分享容器、公式真机验收、题图资源字段化、端到端测试和更完整 UI 打磨 | ## 接下来优先级 diff --git a/docs/refactor/frontend-handoff-index.md b/docs/refactor/frontend-handoff-index.md index 9fbd91b3..d56dea81 100644 --- a/docs/refactor/frontend-handoff-index.md +++ b/docs/refactor/frontend-handoff-index.md @@ -84,11 +84,12 @@ | 背单词 | `apps/taro/src/pages/student/vocabulary/index.tsx` | `vocabulary-units`、`vocabulary-words`、`vocabulary/review-plan`、`vocabulary/review`、`vocabulary/favorites`、`vocabulary/stats`；已接今日计划、单元学习、收藏练习、学习概览、掌握率、计划拆分、收藏数、卡片翻转、发音、美/英音切换、本地进度恢复和单词跳转 | | 知识手册 | `apps/taro/src/pages/student/handbook/index.tsx` | `handbook-subjects`、`handbook-chapters`、`handbook-entries`；已接 RichContent 阅读渲染、章节内搜索、安全文本摘要高亮和目录定位第一版 | | 分数线 | `apps/taro/src/pages/student/scoreline/index.tsx` | `scoreline/fields`、`scoreline/schools`、`scoreline/majors`、`scoreline/years`、`scoreline/records`、`scoreline/trend`；已接目标地区默认筛选、院校/专业/年份 chip、租户动态字段过滤、结果字段 chip 和趋势摘要第一版 | +| AI 择校 | `apps/taro/src/pages/student/ai-school/index.tsx` | `ai/school-recommendations/generate`、`ai/school-recommendations`、`ai/school-recommendations/detail`、`ai/school-recommendations/export`；已接 SVIP 报告生成、历史报告、Markdown/HTML 导出第一版 | | 资料 | `apps/taro/src/pages/student/assets/index.tsx` | `assets`、`assets/preview`、`assets/download`；已接短期签名、过期信息、可见水印覆盖、traceId 展示和强制水印资源外部预览限制 | | 消息中心 | `apps/taro/src/pages/student/notifications/index.tsx` | `profile/notifications`、`profile/notifications/status`；已接未读/已读/归档/全部筛选、类型筛选、批量已读、单条已读、归档、忽略和学生端站内路径白名单跳转 | | 个人中心 | `apps/taro/src/pages/student/profile/index.tsx` | `profile/me`、`PATCH profile/me.avatarPreset`、`check-in`、`score-events`、`badges`、`exam-countdowns`、`svip-plans`、`orders`、`entitlements`、`activation-codes`、`learning/stats`、`learning/trend`、`practice-sessions/history`、`profile/activity-tasks`、`profile/activity-tasks/claim`、`profile/exchange-items`、`profile/exchange-items/redeem`、`profile/notifications`、`profile/notifications/status`；已接学习报告、练习趋势、最近练习、男女预设头像选择、会员订单、激活码、积分任务/兑换/积分明细和消息中心第一版 | -当前页面主要用于打通接口和路由。学生端第一版学习闭环已经覆盖“选地区 -> 进题库 -> 创建 session -> 答题卡/答题/主观题自评/复合题多小题/收藏/反馈/视频 -> 交卷报告逐题复盘 -> 错题/收藏复习”，背单词已经覆盖“单元 -> 今日计划/全单元/收藏练习 -> 学习概览/掌握率/收藏数 -> 卡片翻转 -> 发音 -> 认识/再记上报 -> 本地恢复”，知识手册已经覆盖“科目 -> 章节 -> 章节内搜索 -> 目录定位 -> RichContent 阅读”，分数线已经覆盖“目标地区 -> 院校/专业/年份 -> 租户动态字段筛选 -> 结果字段 chip -> 趋势摘要”，资料页已经覆盖“列表 -> 申请预览/下载短签名 -> 展示水印 traceId -> H5 水印容器预览或确认下载”，个人中心已经覆盖“基础资料 -> 学习报告 -> 14 天趋势 -> 题型表现 -> 最近练习 -> 勋章/签到 -> 会员/订单/激活码 -> 积分任务/兑换/明细 -> 消息摘要”，独立消息中心已经覆盖“筛选 -> 已读/归档/忽略 -> 站内安全跳转”，会员闭环已经覆盖“选套餐 -> 领优惠券 -> 下单 -> 创建支付参数 -> 状态轮询 -> 订单详情/售后入口”。`apps/taro/src/components/RichContent.tsx` 是学生端题干、选项、解析和知识手册的统一安全渲染组件：它只支持受控 Markdown 图片、基础表格、粗体、代码和被 parser 识别出的公式 token；H5 端用 KaTeX 渲染 `$...$`、`$$...$$`、`\(...\)`、`\[...\]`，私有题图可用 `asset:`、`content_asset:` 或 `/asset/` 资源引用向后端申请短期预览签名。知识手册搜索摘要使用纯文本片段高亮，不把搜索词拼成 HTML 注入正文。组件不执行导入内容中的任意 HTML/JS，也会拒绝 `javascript:`、`data:` 等危险图片地址。后续 UI 需要继续按旧题库视觉和 Taro H5/小程序限制优化，并重点补小程序公式真机验收、题图资源字段化、小程序分享/支付容器体验。 +当前页面主要用于打通接口和路由。学生端第一版学习闭环已经覆盖“选地区 -> 进题库 -> 创建 session -> 答题卡/答题/主观题自评/复合题多小题/收藏/反馈/视频 -> 交卷报告逐题复盘 -> 错题/收藏复习”，背单词已经覆盖“单元 -> 今日计划/全单元/收藏练习 -> 学习概览/掌握率/收藏数 -> 卡片翻转 -> 发音 -> 认识/再记上报 -> 本地恢复”，知识手册已经覆盖“科目 -> 章节 -> 章节内搜索 -> 目录定位 -> RichContent 阅读”，分数线已经覆盖“目标地区 -> 院校/专业/年份 -> 租户动态字段筛选 -> 结果字段 chip -> 趋势摘要”，AI 择校已经覆盖“SVIP 生成报告 -> 历史报告 -> Markdown/HTML 导出或小程序复制报告文本”，资料页已经覆盖“列表 -> 申请预览/下载短签名 -> 展示水印 traceId -> H5 水印容器预览或确认下载”，个人中心已经覆盖“基础资料 -> 学习报告 -> 14 天趋势 -> 题型表现 -> 最近练习 -> 勋章/签到 -> 会员/订单/激活码 -> 积分任务/兑换/明细 -> 消息摘要”，独立消息中心已经覆盖“筛选 -> 已读/归档/忽略 -> 站内安全跳转”，会员闭环已经覆盖“选套餐 -> 领优惠券 -> 下单 -> 创建支付参数 -> 状态轮询 -> 订单详情/售后入口”。`apps/taro/src/components/RichContent.tsx` 是学生端题干、选项、解析和知识手册的统一安全渲染组件：它只支持受控 Markdown 图片、基础表格、粗体、代码和被 parser 识别出的公式 token；H5 端用 KaTeX 渲染 `$...$`、`$$...$$`、`\(...\)`、`\[...\]`，私有题图可用 `asset:`、`content_asset:` 或 `/asset/` 资源引用向后端申请短期预览签名。知识手册搜索摘要使用纯文本片段高亮，不把搜索词拼成 HTML 注入正文。组件不执行导入内容中的任意 HTML/JS，也会拒绝 `javascript:`、`data:` 等危险图片地址。后续 UI 需要继续按旧题库视觉和 Taro H5/小程序限制优化，并重点补小程序公式真机验收、题图资源字段化、小程序分享/支付容器体验。 ## 已落地的 Taro 租户后台页面 diff --git a/docs/refactor/legacy-feature-gap-matrix.md b/docs/refactor/legacy-feature-gap-matrix.md index b3202a58..573bc80d 100644 --- 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 导入比对、微信/支付宝官方账单下载 worker、异常查询、差错工单和事件轨迹、异常订单运营台、人工调整凭证复核报表已有；Taro 学生收银台/订单详情和租户财务运营台第一版已接；仍缺更完整售后体验、真实生产账单抽样验收和生产账号联调 | | 个人中心 | `Profile.tsx` | 部分覆盖 | 基本资料、手机号绑定/换绑、男女预设头像、权益、订单统计、练习历史、学习统计、签到积分、积分活动任务、积分兑换、考试倒计时、趋势、勋章展示和站内通知 API 已有；Taro 个人中心已接学习报告、男女预设头像选择、积分任务、积分兑换、积分明细、消息筛选/已读/归档第一版；后端登录和导入链路不会保存微信/QQ/旧系统头像 URL，产品不支持学生头像上传；继续补账号合并和更细学习建议 | | 资料下载 | `QuestionExporterPublishModal.tsx` 等 | 部分覆盖 | 资源台账、上传确认、签名下载、PDF/图片预览、动态水印上下文、Taro 学生端水印 traceId 预览/下载确认、worker 复检、内置安全扫描和外部 HTTP scanner 接入层已有；仍缺深度防盗链、真实 AV/内容安全服务联调、转码/CDN 级水印和生命周期策略 | -| AI 择校推荐 | 业务规划新增 | 部分覆盖 | 已有 SVIP 门禁、学生输入 schema、地区/分数线上下文、稳定 JSON 输出、报告台账、审计和 Taro 学生端基础页；真实 AI provider、prompt 版本管理后台、报告 PDF 渲染和更细推荐算法待补 | +| AI 择校推荐 | 业务规划新增 | 部分覆盖 | 已有 SVIP 门禁、学生输入 schema、地区/分数线上下文、稳定 JSON 输出、报告台账、审计、Markdown/HTML 导出和 Taro 学生端基础页；真实 AI provider、prompt 版本管理后台、报告 PDF worker 渲染和更细推荐算法待补 | | 题目反馈 | `02-API接口.md` 用户反馈 | 部分覆盖 | 学生提交、本人列表、租户后台处理、状态事件、反馈奖励积分、站内通知和租户反馈运营聚合报表已覆盖；Taro 个人中心消息中心可查看反馈处理/奖励通知，租户营销中心已接 30 天反馈运营摘要；仍缺外部订阅消息/短信提醒和内容修复闭环 | | 签到积分 | `Profile.tsx`、`02-API接口.md` | 部分覆盖 | 每日签到、连续签到基础、积分流水、重复签到幂等、签到/积分阈值自动发放勋章、积分活动任务、积分兑换商品、优惠券兑换履约、租户后台配置和积分风控只读报表已覆盖；学生激励默认以勋章自动发放为主，排行榜不默认开启；后续补更细活动效果看板和更多系统触发任务 | | 排行榜 | `leaderboard.pb.js`、`02-API接口.md` | 可选活动能力 | 已有刷题数、积分、背单词、模考最高分排行榜，支持租户/地区/班级范围和当前用户排名；租户默认关闭，学生端默认不请求、不展示；日常学习激励以后台勋章自动发放为主。后续仅在租户明确购买/开启活动并压测后补防刷、日/周榜预聚合、运营后台排名看板 | @@ -103,7 +103,7 @@ 5. 导入扩展：题目/单词/知识手册/分数线/视频已支持 JSON、CSV 和 Excel 预览导入，并可用 `executionMode=async` 进入 imports worker；导入后复检、导入任务详情、模板下载按钮、字段映射 API、Taro 字段别名编辑、异步轮询和 PocketBase JSON dry-run 报告已补，仍缺真实数据执行验收。 6. 公共题库商业化：平台公共/地区题库授权、租户快照采纳、手动同步、自动同步 worker、同步通知、冲突查询、租户自改冲突保护和单条/批量冲突处理已完成基础闭环；还需生产定时调度、失败告警和更完整运营后台消息。 7. CRM/销售结算：CRM worker、跟进分配策略、学生批量 CRM 推送、跟进效果统计、分佣规则、结算单、审核、打款状态、导出和凭证复核基础闭环已完成；仍缺富卡片模板、失败告警、死信运营台、真实打款 provider、发票和销售结算看板。 -8. AI 择校推荐增强：后端 `local_rules` 地基、SVIP 门禁、报告列表/详情和 Taro 基础页已完成；仍缺真实 AI provider、prompt 编排、PDF 报告和后台运营配置。 +8. AI 择校推荐增强：后端 `local_rules` 地基、SVIP 门禁、报告列表/详情、本人报告 Markdown/HTML 导出和 Taro 基础页已完成；仍缺真实 AI provider、prompt 编排、PDF worker 报告和后台运营配置。 9. 题目反馈增强：站内通知后端第一版已完成；仍缺前端消息中心、外部订阅消息/短信提醒、问题聚合统计和内容修复闭环。 10. 积分活动增强：积分兑换、活动任务、优惠券兑换履约、后台配置和积分风控只读报表第一阶段已完成；仍缺活动效果看板和更细系统任务触发。 11. 勋章增强：后台维护、手动发放、签到/积分/反馈/活动任务/练习次数/单词掌握/模考成绩自动发放和发放站内通知已有；仍缺前端运营配置体验和更完整活动效果看板。 diff --git a/docs/refactor/next-development-todo.md b/docs/refactor/next-development-todo.md index 9a8a7246..0dcefac5 100644 --- a/docs/refactor/next-development-todo.md +++ b/docs/refactor/next-development-todo.md @@ -166,8 +166,8 @@ - 继续补 CRM/站内通知/企微/飞书/钉钉的触达联动、督导效果归因，以及更细导入模板体验。 13. AI 择校推荐 - - 已完成 `ai_recommendation_reports` 报告台账、SVIP 门禁、学生输入 schema、地区/分数线上下文、`local_rules` 稳定 JSON 输出、报告列表/详情接口和 Taro 学生端基础页。 - - 继续补真实 AI provider adapter、租户级 `app_private.tenant_secrets(secret_scope='ai')` 密钥联调、prompt 版本管理、运营后台配置、报告 PDF 渲染和人工复核流程。 + - 已完成 `ai_recommendation_reports` 报告台账、SVIP 门禁、学生输入 schema、地区/分数线上下文、`local_rules` 稳定 JSON 输出、报告列表/详情接口、本人报告 Markdown/HTML 导出和 Taro 学生端基础页。 + - 继续补真实 AI provider adapter、租户级 `app_private.tenant_secrets(secret_scope='ai')` 密钥联调、prompt 版本管理、运营后台配置、报告 PDF worker 渲染和人工复核流程。 ### P2 运营体验和企业交付 diff --git a/docs/refactor/taro-frontend-integration.md b/docs/refactor/taro-frontend-integration.md index 7ec8a31c..11ada44b 100644 --- a/docs/refactor/taro-frontend-integration.md +++ b/docs/refactor/taro-frontend-integration.md @@ -3062,7 +3062,7 @@ GET /api/platform-admin/dunning-notification-events?invoiceId=&limit= ## AI 择校推荐接入 -AI 择校推荐是学生端 SVIP 功能，前端只调用 `apps/api`，不要在 H5/小程序内保存任何 AI provider key、prompt secret 或服务端模型配置。当前后端默认使用 deterministic `local_rules` provider，基于学生目标地区和 `scoreline_records` 生成稳定 JSON 报告；后续真实 AI provider 仍保持同一接口和 JSON schema。 +AI 择校推荐是学生端 SVIP 功能，前端只调用 `apps/api`，不要在 H5/小程序内保存任何 AI provider key、prompt secret 或服务端模型配置。当前后端默认使用 deterministic `local_rules` provider，基于学生目标地区和 `scoreline_records` 生成稳定 JSON 报告；已提供 Markdown/HTML 报告导出第一版。后续真实 AI provider 仍保持同一接口和 JSON schema。 生成报告： @@ -3131,6 +3131,8 @@ POST /api/ai/school-recommendations/generate ```http GET /api/ai/school-recommendations?regionId=&limit=20 GET /api/ai/school-recommendations/detail?reportId= +GET /api/ai/school-recommendations/export?reportId=&format=markdown +GET /api/ai/school-recommendations/export?reportId=&format=html ``` 前端渲染建议： @@ -3139,7 +3141,9 @@ GET /api/ai/school-recommendations/detail?reportId= - `recommendedSchools` 是服务端已排序结果，前端不要重新按分数线做业务排序。 - `disclaimers` 必须展示在报告底部或导出 PDF 中。 - 报告详情只能展示当前登录学生自己的报告，遇到 `AI_REPORT_NOT_FOUND` 按“报告不存在或无权访问”处理。 -- 当前 Taro 基础页在 `pages/student/ai-school/index`，service 在 `src/services/ai.ts`。 +- 导出接口只允许本人已生成报告，返回 `fileName/mimeType/contentText/contentBase64/sha256/sizeBytes`；H5 可用 `Blob` 下载，微信小程序可复制 `contentText` 或后续交给文件系统保存。 +- 当前 Taro 基础页在 `pages/student/ai-school/index`，service 在 `src/services/ai.ts`，已接 Markdown/HTML 导出按钮。 +- 当前导出是轻量报告交付，不是最终 PDF；PDF 建议后续走 worker 渲染并发布到 `content_assets`，继续沿用本人报告权限和审计。 ## 租户后台前端建议 diff --git a/scripts/api-integration-test.js b/scripts/api-integration-test.js index 42407e93..4d5e1719 100644 --- a/scripts/api-integration-test.js +++ b/scripts/api-integration-test.js @@ -3206,6 +3206,30 @@ async function testAiSchoolRecommendationAfterSvip() { }); assert.equal(detail.item?.id, generated.item.id, 'AI report detail should load own report'); + const markdownExport = await request('/api/ai/school-recommendations/export', { + query: { reportId: generated.item.id, format: 'markdown' }, + }); + assert.equal(markdownExport.item?.format, 'markdown', 'AI report export should support markdown'); + assert.ok(markdownExport.item?.fileName?.endsWith('.md'), 'AI markdown export should return a markdown filename'); + assert.ok(markdownExport.item?.sha256, 'AI report export should include content hash'); + const markdownReport = Buffer.from(markdownExport.item?.contentBase64 || '', 'base64').toString('utf8'); + assert.ok(markdownReport.includes('AI 择校推荐报告'), 'AI markdown export should include report title'); + assert.ok(markdownReport.includes('烟测学院'), 'AI markdown export should include recommended school'); + assert.ok(markdownReport.includes('免责声明'), 'AI markdown export should include disclaimers'); + assert.ok(!markdownReport.includes('secret'), 'AI markdown export should not leak provider secrets'); + + const htmlExport = await request('/api/ai/school-recommendations/export', { + query: { reportId: generated.item.id, format: 'html' }, + }); + assert.equal(htmlExport.item?.format, 'html', 'AI report export should support html'); + assert.ok(Buffer.from(htmlExport.item?.contentBase64 || '', 'base64').toString('utf8').includes(''), 'AI html export should return HTML content'); + + const invalidExportFormat = await request('/api/ai/school-recommendations/export', { + query: { reportId: generated.item.id, format: 'pdf' }, + expectStatus: 400, + }); + assert.equal(invalidExportFormat.code, 'AI_REPORT_EXPORT_FORMAT_INVALID', 'AI report export should reject unsupported formats'); + const otherStudentDenied = await request('/api/ai/school-recommendations/detail', { userId: SECOND_STUDENT_USER_ID, query: { reportId: generated.item.id }, @@ -3213,6 +3237,13 @@ async function testAiSchoolRecommendationAfterSvip() { }); assert.equal(otherStudentDenied.code, 'AI_REPORT_NOT_FOUND', 'students must not read other students AI reports'); + const otherStudentExportDenied = await request('/api/ai/school-recommendations/export', { + userId: SECOND_STUDENT_USER_ID, + query: { reportId: generated.item.id, format: 'markdown' }, + expectStatus: 404, + }); + assert.equal(otherStudentExportDenied.code, 'AI_REPORT_NOT_FOUND', 'students must not export other students AI reports'); + const partnerTenantDenied = await request('/api/ai/school-recommendations/generate', { tenantId: PARTNER_TENANT_ID, method: 'POST',