feat(volunteer): 新增志愿服务证明材料识别及年度证明功能

- 新增志愿证明材料识别功能，支持自动识别材料并回填关键信息
- 在志愿时长编辑页面添加材料识别按钮及识别结果展示
- 新增志愿服务证明模块，支持查询、生成及下载年度志愿服务证明PDF
- 志愿时长列表及审核详情中新增“服务地点”字段显示
- 志愿时长导入功能支持“服务地点”字段，完善导入表头与数据映射
- 志愿时长详情、审核流程等界面优化，增加识别材料公章状态及流程节点提示
- 志愿时长待审核项支持用户撤回操作，撤回后记录被删除需重新录入
- 社团年度报告相关接口新增，实现社团年度报告生成及分页查询
- 调整相关样式与界面布局，提升用户体验与信息展示完整性

docs/ai-qmgc-student-analysis-contract.md

@@ -0,0 +1,68 @@
+# 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` 的类型与中文名；
+本次前端改动未接入历史记录，属于可选增强。

docs/phase2-P0-delivery.md

@@ -137,7 +137,9 @@ src/views/system/{messageTemplate,messageLog}/
 
 | 项 | 说明 |
 | --- | --- |
-| 志愿证明 PDF | 当前只做数据汇总与提示，模板渲染与电子章在 P1 接入（需学校提供模板与印章图） |
+| 志愿证明 PDF | **已实现**：按年度汇总已通过审核的志愿时长，生成含志愿者姓名、学院、专业、班级、学号、活动名称、活动时间、活动地点、时长、数据来源、总时长的 PDF，自动加水印，不设电子章（正文留公章位）。接口 `/api/gxmu/volunteer/certificate/*` |
+| 社团年度数据报告 | **已实现**：按年度汇总活动、成员、场地数据，生成含核心指标、类别分布、月度趋势、成员构成图表与文字小结的 PDF。入口「社团与志愿 → 年度数据报告」(`/club/report`)，接口 `/api/gxmu/club/report/*`。文字小结可按需编辑后再生成 |
+| 志愿记录服务地点 | 新增 `gxmu_volunteer_record.service_place`，录入表单与导入模板均支持；证明材料「活动地点」列取此值 |
 | OCR 公章识别 | 字段已预留（`ocr_status` / `ocr_org` / `ocr_raw`），未接 OCR 服务；活动审批暂由人工核验材料 |
 | 审核流并行 | **已实现**，见下方「补充交付」 |
 | 学分自动获取 | 第二课堂/桂志愿暂无 API，先走 Excel 导入，`source` + `external_id` 已为后续对接预留 |

docs/phase2-implementation-plan.md

@@ -84,6 +84,10 @@
 
 AI 学员学习情况分析、AI 定制培养建议、OCR 公章识别、AI 数字人、移动端接口整理。
 
+> AI 学员学习情况分析的前端入口已落在青马学员档案（列表操作列「AI 分析」+ 档案抽屉按钮），
+> 复用 `utils/ai-stream.ts` 流式链路，接口契约见 `docs/ai-qmgc-student-analysis-contract.md`。
+> 归入 AI 能力域、入口留在业务域，不作为独立 AI 菜单页。
+
 ## 四、数据模型
 
 统一规范：`id BIGINT AUTO_INCREMENT`、`tenant_id`、`user_id`、`deleted`、`create_time`、`update_time`。