一、项目定位

一个面向 C 语言教学的全链路智能平台：学生提交代码 → AI 自动批改 → 多维度学情分析 → QQ 群实时通知 → RAG 知识库辅助教学决策。

一句话：把教师从重复批改中解放出来，把教学决策从”凭感觉”变成”看数据”。

二、核心业务流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
学生提交代码(QQ/Web)
      │
      ▼
  文件名解析 ─── 学号_姓名_班级_作业名.c
  (正则提取，无需登录)
      │
      ▼
  提交次数校验(最多3次) + 班级校验
      │
      ▼
  Redis Stream 异步队列
      │         │
      ▼         ▼
  AI 批改     定时提醒(QQ群+私聊)
  (OpenClaw   24h/1h截止预警
   Agent)     全员完成播报
      │
      ▼
  JSON 结构化结果
  ├── totalScore / overallComment
  ├── strengths / weaknesses
  ├── suggestions (优先级+建议)
  └── knowledgePoints (掌握度)
      │
      ▼
  写入 DB → Dashboard 聚合
      │         │
      ▼         ▼
  仪表盘分析    RAG 知识库
  ├── 核心指标    (每日凌晨2点
  ├── 成绩分布     自动上传)
  ├── 知识点掌握度
  ├── 高频错题 TOP10
  └── 学生成长曲线

三、技术架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
┌─────────────────────────────────────────────┐
│                前端 (Vue 3)                   │
├─────────────────────────────────────────────┤
│              Controller 层 (8 个)             │
│  Auth / Chat / Homework / Dashboard / Task  │
│  Document / FileUpload / OnebotRag          │
├─────────────────────────────────────────────┤
│               Service 层 (13 个)              │
│  ┌──────────┬───────────┬────────────────┐  │
│  │ 业务服务  │ 分析服务   │ 基础设施服务    │  │
│  │ Task     │ Dashboard │ OpenClaw(AI)   │  │
│  │ Homework │ RAG       │ OneBotHttp     │  │
│  │ Class    │ Document  │ TaskReminder   │  │
│  │ User     │           │ FileStorage    │  │
│  └──────────┴───────────┴────────────────┘  │
├─────────────────────────────────────────────┤
│              Mapper 层 (MyBatis-Plus)        │
├─────────────────────────────────────────────┤
│         PostgreSQL + pgvector + Redis        │
├─────────────────────────────────────────────┤
│           外部服务: OpenClaw Gateway          │
│        (AI Agent: jarvis / main)            │
└─────────────────────────────────────────────┘

技术栈：Spring Boot 4.0 + MyBatis-Plus + PostgreSQL + Redis(Stream/Redisson) + Spring Security(JWT) + Spring AI 2.0 + Bucket4j 限流 + Caffeine 缓存 + pgvector 向量检索

四、亮点

1. 异步批改架构 — Redis Stream 生产者/消费者模式

批改（AI 调用耗时 10-30s）不走同步 HTTP 阻塞，而是：

  • GradingStreamProducer 推入 Redis Stream
  • GradingStreamConsumer 单线程串行消费
  • 前端轮询 GET /api/homework/result/{id} 直到 COMPLETED

好处：AI 不会被打崩，高峰期提交不阻塞，消费者宕机后 Pending 消息可自动认领。

2. AI Agent 路由

通过 status 字段区分学生(1)和教师(2)，自动路由到不同 OpenClaw Agent（jarvis vs main），一条代码实现差异化回复质量。

3. 三层限流体系

层 技术 作用
网关层 Bucket4j-Redis 分布式令牌桶 全局限流，按 /api 路径差异化配置
接口层 Redis Lua 滑动窗口切面 支持 GLOBAL/IP/USER 三维限流
防穿透 Caffeine + 布隆过滤器 缓存穿透保护（如 classIdBloomFilter）

4. RAG 知识库

  • 每日凌晨 2 点自动将 Dashboard 数据上传到 pgvector 向量库
  • Chat 接口自动 RAG 增强（检索 Top-K 相关文档拼入 prompt）
  • OneBot 对外提供 RAG 查询接口供 QQ 机器人调用

5. QQ 全流程打通

  • 作业发布 → QQ 群通知
  • 截止前 24h/1h → 群提醒 + 私聊
  • 批改完成 → QQ 群发结果
  • 全员交完 → 祝贺消息
  • 借助 Napcat + OpenClaw OneBot 插件实现群聊 AI 问答

五、已完成的重构

项目 说明
Controller 越层问题 5 个 Controller 中全部 Mapper 直调改为 Service 层调用
Service 合并 16→13，合并了同域的 ClassService、HomeworkResultService
Controller 合并 10→8，StudentProgress + TeachingPlan 并入 Dashboard

六、待改进项

问题 方案
ChatController 19KB 上帝类 拆分为 ChatStream + HomeworkGrade，提取 ChatAssistant 工具类
GradingStreamConsumer 12 参数构造函数 Pipeline 化：Reader → Engine → Persister → Notifier
DashboardServiceImpl KP_CANONICAL 200 行硬编码 外部化到 YAML 配置或 DB 表
OpenClawService 8 个重载 统一为 ChatRequest DTO
Submission 表 30+ 字段 拆为 Submission + GradingResult
OneBot sendRequest fire-and-forget 关键通知应 .block() 确认送达
java.util.Timer 做定时提醒 生产应换 Quartz / xxl-job
包命名大写(Controller/Service) 改为小写(controller/service)
热力图 vs AI 回复数据不一致 批改后即时更新 RAG 向量库