# AI 学情分析接口契约（前端已接入，后端待实现）

青马学员档案里的「AI 学情分析」入口复用现有 AI 流式链路（`utils/ai-stream.ts`），
后端需要新增一个与 `activityOutlineGen` / `manuscriptGen` 同构的端点。

## 1. 端点

| 用途 | 方法 | 路径 |
| --- | --- | --- |
| 流式分析（页面实际调用） | POST | `/api/ai/qmgcStudentAnalysis/stream` |
| 一次性返回（调试/他端） | POST | `/api/ai/qmgcStudentAnalysis` |

响应格式与现有 AI 链路一致：

- `/stream` 返回 `text/event-stream`，每帧一个 `data:` 行，帧内容为 JSON；
- 正文帧：`{ "answer": "<markdown 片段>" }`，也兼容 `{ "notice": "<片段>" }`；
- 心跳/占位帧：`{ "loading": "true" }`，前端忽略；
- 结束帧：`{ "answer": "__END__" }`；
- 失败时可用 `{ "answer": "<片段>", "reset": "true" }` 覆盖已推内容，
  末帧 `status: "failed"`，前端会显示统一失败文案。

## 2. 入参

```json
{
  "studentId": 123,
  "focus": "thought | difficulty | advice | undefined",
  "context": {
    "studentName": "张三",
    "studentNo": "20230001",
    "collegeName": "第一临床医学院",
    "className": "临床医学 2023 级 1 班",
    "batch": "2026 年第 1 期",
    "stage": "study",
    "totalScore": 86,
    "materialCount": 5,
    "scoredMaterialCount": 4,
    "taskDoneCount": 6,
    "taskTotal": 8,
    "materialTexts": ["【学习心得】……"],
    "taskTexts": ["完成线上团课（已完成）"],
    "scoreTexts": ["理论/课堂表现：90 分"]
  }
}
```

`context` 是前端已加载数据的摘要，后端实现了按 `studentId` 自行取数后可以忽略它；
保留它是为了后端聚合尚未覆盖某类数据时，AI 仍能拿到培养材料正文。

`focus` 为空表示综合维度；调度到 Dify 时可映射成不同的提示词变量。

## 3. 数据口径

第一期可用的输入只有青马域已有数据：

- `gxmu_qmgc_material`：培养材料标题与正文、评分与评语；
- 学员任务分配记录：任务标题、完成状态；
- `gxmu_qmgc_score`：考核维度、评分项、得分与评语。

**系统目前没有考勤、签到、课堂互动类数据。** 需求原文提到的「课堂互动数据」
在采集入口落地前不参与分析，前端弹窗里已明确向教师提示这一点。后续若新增采集，
在 `context` 中补充对应摘要字段即可，无需改动流式协议。

## 4. 历史记录

如果要把分析结果写入 `ai_chat_list`，`chat_type` 需要新增一个取值
（如 `student_analysis`），并同步前端 `utils/ai-chat-type.ts` 的类型与中文名；
本次前端改动未接入历史记录，属于可选增强。