重构 AI

docs/API接口对比分析.md

@@ -1,5 +1,19 @@
 # API接口对比分析
 
+## 更新日志
+
+### 最近更新（2025-10）
+- ✨ **AI分析功能增强**：完善了AI智能分析模块的文档说明
+  - 详细说明了4个AI相关接口的功能和参数
+  - 新增等级系统说明（S/A/B/C），包含特殊规则
+  - 补充了时间范围选择功能
+  - 说明了流式响应的实现方式
+  - 前端组件从 `WeeklyChart.vue` 升级为 `DurationChart.vue`（混合图表）
+- 🔧 **数据缓存优化**：后端AI接口增加了缓存机制，提升性能
+- 🐛 **修正等级系统说明**：更正了等级阈值（A级：前35%，B级：前75%），并补充了小规模参与惩罚规则
+
+---
+
 ## 一、前端已使用的API接口
 
 ### 1. 用户认证相关（shared/api.ts）
@@ -65,10 +79,23 @@
 - `GET /api/tutorials` - 获取教程列表
 
 #### 2.11 AI分析相关
-- `GET /api/ai/detail` - 获取AI详细数据
-- `GET /api/ai/weekly` - 获取AI周数据
-- `GET /api/ai/heatmap` - 获取AI热力图数据
-- `POST /api/ai/analysis` - AI分析生成（使用fetch直接调用，流式响应）
+- `GET /api/ai/detail` - 获取用户详细数据
+  - **参数**: start, end（时间范围）
+  - **返回**: 用户等级(S/A/B/C)、已解决题目列表、标签统计、难度统计、参赛次数等
+  - **特点**: 包含班级排名对比，计算每道题的解题排名和等级
+- `GET /api/ai/duration` - 获取时段数据
+  - **参数**: end（结束时间）, duration（时间单位，如 "months:6", "weeks:1"）
+  - **返回**: 每周/每月的综合情况（题目数、提交数、等级）
+  - **用途**: 用于绘制时间趋势图，展示学习进度变化
+- `GET /api/ai/heatmap` - 获取热力图数据
+  - **返回**: 用户的提交热力图数据（按日期统计提交数）
+  - **用途**: 可视化用户活跃度分布
+- `POST /api/ai/analysis` - AI智能分析生成
+  - **请求体**: details（详细数据）, duration（时段数据）
+  - **响应方式**: 流式响应（Server-Sent Events）
+  - **AI提供商**: DeepSeek
+  - **功能**: 根据用户学习数据生成个性化学习建议和鼓励
+  - **实现**: 使用fetch直接调用，在 `oj/store/ai.ts` 中处理流式输出
 
 ### 3. 管理员API（admin/api.ts）
 #### 3.1 仪表板
@@ -278,8 +305,40 @@
 
 ### 特殊说明
 
-#### 1. 流式接口
-`POST /api/ai/analysis` 接口使用了**流式响应（Server-Sent Events）**，因此没有在 `oj/api.ts` 中定义封装函数，而是在 `oj/store/ai.ts` 中直接使用 `fetch` API 调用，用于实时流式输出AI生成的分析内容。
+#### 1. AI智能分析功能 ✨
+
+**功能概述**: 基于用户的学习数据，使用DeepSeek AI生成个性化的学习分析报告和建议。
+
+**涉及接口**:
+- `GET /api/ai/detail` - 获取详细学习数据
+- `GET /api/ai/duration` - 获取时段趋势数据
+- `GET /api/ai/heatmap` - 获取活跃度热力图
+- `POST /api/ai/analysis` - 生成AI分析（流式响应）
+
+**前端实现**:
+- **页面**: `src/oj/ai/analysis.vue`
+- **Store**: `src/oj/store/ai.ts`
+- **组件**: 
+  - `DurationChart.vue` - 混合图表（柱状图+折线图），展示题目数、提交数、等级变化
+  - `Heatmap.vue` - 提交热力图
+  - `Details.vue` - 详细数据展示
+  - `AI.vue` - AI分析结果展示（Markdown格式）
+
+**时间范围选择**:
+支持多种时间范围：一节课(1小时)、两节课(2小时)、一天、一周、一个月、两个月、半年、一年
+
+**等级系统**:
+- **S级**: 排名前10%（卓越水平，约10%的人）
+- **A级**: 排名前35%（优秀水平，约25%的人）
+- **B级**: 排名前75%（良好水平，约40%的人）
+- **C级**: 75%之后（及格水平，约25%的人）
+- **特殊规则**: 参与人数少于10人时，S级降为A级，A级降为B级（避免因人少而评级虚高）
+
+**流式接口实现**:
+`POST /api/ai/analysis` 使用了**流式响应（Server-Sent Events）**，在 `oj/store/ai.ts` 中直接使用 `fetch` API调用，配合 `consumeJSONEventStream` 工具函数处理流式数据，实现AI内容的实时流式输出。
+
+**数据缓存**:
+为提升性能，后端对 `ai/detail` 和 `ai/duration` 接口的返回数据进行了缓存，相同参数的请求会直接返回缓存结果。
 
 #### 2. ACM 比赛辅助检查功能 ✨