Skip to content

yale-zhang/intelli-task-ai

BranchesTags

Repository files navigation

IntelliTask AI 系统

基于 Spring AI Alibaba 框架的 DDD 领域设计分层项目

项目架构

1. 业务逻辑

该系统构建了一个闭环的“采集-批改-反馈-提升”教育路径：

  • 账号与同步：多账号切换、云端持久化、本地缓存、国际化
  • 作业采集：IM群聊提取、手动录入、任务状态流转
  • AI 批改扫描：OCR 文字识别、逻辑评估与打分、强弱项分析、知识点掌握度建模
  • 自适应学习：深度学情剖析、按作业切换计划、阶梯式任务
  • 数据可视化：趋势分析、能力图谱、漏洞预警

2. 领域驱动设计 (DDD) 分层架构

2.1 领域模型层 (Domain Model)

核心实体：

  • UserProfile：用户资料聚合根
  • HomeworkTask：作业任务实体
  • LearningPlan：学习计划实体
  • AppSettings：应用设置实体

2.2 领域服务层 (Domain Service)

  • AIService：AI 智能服务，包括作业内容提取、智能批改扫描、自适应学习路径生成

2.3 应用服务层 (Application Service)

  • UserService：用户服务，处理用户资料和应用设置
  • HomeworkService：作业服务，处理作业任务的创建、提交、批改
  • LearningPlanService：学习计划服务，处理学习计划的生成和管理

2.4 基础设施层 (Infrastructure)

  • 仓储层：基于 Spring Data JPA 的数据持久化
  • 控制器层：RESTful API 接口实现
  • DTO 层：数据传输对象，用于 API 请求和响应

3. 技术栈

  • 框架：Spring Boot 3.2.0
  • AI 框架：Spring AI 0.8.0
  • 微服务：Spring Cloud Alibaba 2023.0.0.0
  • 数据库：PostgreSQL (支持 JSONB)
  • ORM：Spring Data JPA
  • AI 模型：支持 OpenAI、Ollama、HuggingFace

项目结构

├── src/main/java/com/intellitask/
│   ├── application/          # 应用服务层
│   │   ├── service/         # 服务接口
│   │   └── impl/            # 服务实现
│   ├── domain/              # 领域层
│   │   ├── model/           # 领域模型
│   │   └── service/         # 领域服务
│   └── infrastructure/      # 基础设施层
│       ├── controller/      # 控制器
│       ├── dto/             # 数据传输对象
│       └── repository/      # 仓储接口
├── src/main/resources/
│   └── application.yml      # 配置文件
└── pom.xml                  # Maven 依赖

API 接口

所有接口统一返回 ApiResponse<T>：

{
  "code": 0,
  "message": "操作成功",
  "data": {},
  "timestamp": 1710000000000
}

0. 认证 (Auth)

功能 接口路径 核心参数 返回类型
注册 POST /api/v1/auth/register username, password, email, nickname, grade ApiResponse
登录 POST /api/v1/auth/login username, password ApiResponse
刷新 POST /api/v1/auth/refresh refreshToken ApiResponse
登出 POST /api/v1/auth/logout - ApiResponse

1. 数据持久化层 (REST API)

功能模块 动作 接口路径 核心参数 返回类型
用户资料 Upsert POST /api/v1/user_profiles UserProfileDTO ApiResponse
作业列表 Get GET /api/v1/homework_tasks?user_id={uid} user_id ApiResponse<HomeworkTask[]>
保存作业 Upsert POST /api/v1/homework_tasks HomeworkTaskDTO ApiResponse
获取计划 Get GET /api/v1/learning_plans?source_task_id={taskId} source_task_id ApiResponse
云端设置 Get GET /api/v1/app_settings?id={uid} id ApiResponse

2. AI 智能服务层 (API)

功能 接口路径 核心参数 返回类型
作业内容提取 POST /api/v1/ai/extract-homework message, lang ApiResponse<String(JSON)>
图片作业提取 POST /api/v1/ai/extract-homework-image imageBuffer, lang ApiResponse<String(JSON)>
智能批改扫描 POST /api/v1/ai/grade-submission imageBuffer, prompt, lang ApiResponse<String(JSON)>
自适应学习路径生成 POST /api/v1/ai/generate-plan weaknesses, lang ApiResponse<String(JSON)>
备考建议生成 POST /api/v1/ai/milestone-advice eventTitle, eventType, tasksSummary, lang ApiResponse

快速开始

1. 环境要求

  • JDK 17+
  • Maven 3.6+
  • PostgreSQL 13+

2. 配置修改

编辑 src/main/resources/application.yml 文件，配置数据库连接、AI 服务与 CORS：

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/intelli_task?useSSL=false&serverTimezone=UTC
    username: postgres
    password: 123456
  
  ai:
    openai:
      api-key: ${OPENAI_API_KEY:}
      chat:
        options:
          model: ${OPENAI_MODEL:gpt-4o-mini}
    ollama:
      base-url: http://localhost:11434
      default-model: llama3

app:
  cors:
    allowed-origins: ${CORS_ALLOWED_ORIGINS:http://localhost:5173,http://localhost:4173}

> 可选：使用 `SERVER_CONTEXT_PATH` 设置全局 API 前缀（默认不设置）。

3. 启动项目

mvn spring-boot:run

核心功能

1. 作业采集与提取

  • 从 IM 群聊消息中智能提取作业信息
  • 支持手动录入作业，AI 辅助生成
  • 作业状态自动流转：Pending → Submitted → Graded

2. AI 智能批改

  • 支持 OCR 文字识别
  • 逻辑评估与自动打分
  • 分析强弱项和知识点掌握度

3. 自适应学习计划

  • 基于作业批改结果生成个性化学习计划
  • 深度学情剖析，提供专家视角建议
  • 阶梯式任务设计：基础/进阶/挑战

4. 数据可视化

  • 学习趋势分析
  • 能力雷达图
  • 核心知识漏洞预警

技术亮点

  1. DDD 领域设计：清晰的分层架构，领域模型驱动
  2. Spring AI 集成：支持多 AI 模型提供商
  3. 微服务架构：基于 Spring Cloud Alibaba，支持服务发现和分布式事务
  4. JSONB 支持：灵活存储 AI 分析结果和复杂数据结构
  5. RESTful API：遵循 REST 设计规范，易于集成

开发指南

代码风格

  • 遵循 Spring Boot 编码规范
  • 使用 Lombok 简化代码
  • 采用构造函数注入
  • 事务管理使用 @Transactional 注解

测试

mvn test

构建

mvn clean package -DskipTests

系统优化

高优先级优化

1. 统一异常处理

系统实现了完整的异常处理机制，包括自定义异常类、错误码枚举和全局异常处理器。

核心组件：

  • ErrorCode - 错误码枚举

    • 定义了系统所有错误码和错误信息
    • 支持国际化错误信息

  • BusinessException - 业务异常类

    • 继承自 RuntimeException
    • 支持错误码和动态错误消息

  • GlobalExceptionHandler - 全局异常处理器

    • 使用 @RestControllerAdvice 注解
    • 统一处理所有异常类型
    • 返回统一的错误响应格式

使用示例：

throw new BusinessException(ErrorCode.USER_NOT_FOUND, userId);
throw new BusinessException(ErrorCode.HOMEWORK_SUBMISSION_FAILED, taskId);

2. 统一响应格式

所有 API 接口使用统一的响应格式 ApiResponse。

响应结构：

{
  "code": 200,
  "message": "success",
  "data": {},
  "timestamp": 1234567890
}

使用方式：

return ApiResponse.success(data);
return ApiResponse.error(ErrorCode.VALIDATION_ERROR);

3. 参数验证

所有 DTO 类添加了 Jakarta Bean Validation 注解，确保请求数据的合法性。

常用验证注解：

  • @NotNull - 不能为 null
  • @NotBlank - 字符串不能为空
  • @Size(min, max) - 字符串/集合长度限制
  • @Email - 邮箱格式验证
  • @Pattern - 正则表达式验证

示例：

public class UserProfileDTO {
    @NotBlank(message = "用户名不能为空")
    @Size(min = 2, max = 50, message = "用户名长度必须在 2-50 之间")
    private String username;
    
    @Email(message = "邮箱格式不正确")
    private String email;
}

4. 环境配置分离

将配置文件按环境分离，避免硬编码敏感信息。

配置文件结构：

  • application.yml - 基础配置
  • application-dev.yml - 开发环境配置
  • application-prod.yml - 生产环境配置

环境变量配置：

spring:
  profiles:
    active: ${SPRING_PROFILES_ACTIVE:dev}
  
  datasource:
    url: ${DB_URL}
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}

中优先级优化

1. 日志记录

使用 SLF4J + Logback 实现完整的日志记录系统。

日志级别：

  • ERROR - 错误日志
  • WARN - 警告日志
  • INFO - 信息日志
  • DEBUG - 调试日志

使用示例：

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class UserServiceImpl implements UserService {
    private static final Logger logger = LoggerFactory.getLogger(UserServiceImpl.class);
    
    @Override
    public UserProfile createUser(UserProfileDTO dto) {
        logger.info("创建用户: {}", dto.getUsername());
        try {
            UserProfile user = new UserProfile();
            // ...
            logger.info("用户创建成功: {}", user.getId());
            return user;
        } catch (Exception e) {
            logger.error("用户创建失败: {}", dto.getUsername(), e);
            throw new BusinessException(ErrorCode.USER_CREATION_FAILED, dto.getUsername());
        }
    }
}

2. 异步处理

使用 Spring 的 @Async 注解实现异步处理，提高系统响应速度。

异步配置： AsyncConfig

@Configuration
@EnableAsync
public class AsyncConfig {
    
    @Bean(name = "taskExecutor")
    public Executor taskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(5);
        executor.setMaxPoolSize(10);
        executor.setQueueCapacity(100);
        executor.setThreadNamePrefix("async-");
        executor.initialize();
        return executor;
    }
}

异步服务： AsyncAIService

@Async("taskExecutor")
public CompletableFuture<GradingResult> gradeSubmissionAsync(byte[] imageBuffer, String prompt, String lang) {
    // 异步执行批改任务
}

使用方式：

asyncAIService.gradeSubmissionAsync(imageBuffer, prompt, lang)
    .thenAccept(result -> {
        logger.info("批改完成: {}", result.getScore());
    })
    .exceptionally(ex -> {
        logger.error("批改失败", ex);
        return null;
    });

3. 缓存机制

使用 Redis 实现缓存机制，提高数据访问速度。

缓存配置：

spring:
  cache:
    type: redis
    redis:
      time-to-live: 600000
  data:
    redis:
      host: ${REDIS_HOST:localhost}
      port: ${REDIS_PORT:6379}

缓存注解：

  • @Cacheable - 缓存方法结果
  • @CachePut - 更新缓存
  • @CacheEvict - 清除缓存

使用示例：

@Cacheable(value = "userProfiles", key = "#userId")
public UserProfile getUserProfile(String userId) {
    return userRepository.findById(userId)
        .orElseThrow(() -> new BusinessException(ErrorCode.USER_NOT_FOUND, userId));
}

@CachePut(value = "userProfiles", key = "#userId")
public UserProfile updateUserProfile(String userId, UserProfileDTO dto) {
    // 更新用户信息
}

@CacheEvict(value = "userProfiles", key = "#userId")
public void deleteUserProfile(String userId) {
    userRepository.deleteById(userId);
}

4. 限流保护

使用 Resilience4j 实现限流保护，防止系统过载。

限流配置：

resilience4j:
  ratelimiter:
    instances:
      aiService:
        limit-for-period: 10
        limit-refresh-period: 1s
        timeout-duration: 3s

使用示例：

@RateLimiter(name = "aiService", fallbackMethod = "rateLimitFallback")
public GradingResult gradeSubmission(byte[] imageBuffer, String prompt, String lang) {
    // AI 批改逻辑
}

public GradingResult rateLimitFallback(byte[] imageBuffer, String prompt, String lang, Exception ex) {
    logger.warn("触发限流，返回默认结果");
    return GradingResult.defaultResult();
}

部署

Docker 部署

项目提供了完整的 Docker 部署方案，包括 Docker Compose 配置，可以一键启动所有依赖服务。

1. 环境准备

确保已安装 Docker 和 Docker Compose：

docker --version
docker-compose --version

2. 配置环境变量

创建 .env 文件（可选），配置 AI 服务密钥：

# OpenAI 配置
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

# Ollama 配置
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_DEFAULT_MODEL=llama3

# HuggingFace 配置
HUGGINGFACE_API_KEY=your_huggingface_api_key_here

3. 使用 Docker Compose 部署

启动所有服务（包括数据库、Redis、Nacos、Seata）：

docker-compose up -d

查看服务状态：

docker-compose ps

查看日志：

# 查看所有服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f app
docker-compose logs -f postgres
docker-compose logs -f redis

停止所有服务：

docker-compose down

停止并删除数据卷：

docker-compose down -v

4. 服务说明

Docker Compose 包含以下服务：

服务名 端口 说明 是否必需
postgres 5432 PostgreSQL 数据库 必需
redis 6379 Redis 缓存 必需
nacos 8848, 9848 服务注册中心 可选
mysql 3306 Nacos 数据库 可选
seata 8091, 7091 分布式事务 可选
app 8080 应用服务 必需

5. 仅启动核心服务

如果不需要 Nacos 和 Seata，可以创建 docker-compose.core.yml：

docker-compose -f docker-compose.core.yml up -d

6. 单独构建和运行应用镜像

构建镜像：

docker build -t intelli-task-ai:latest .

运行容器：

docker run -d \
  --name intelli-task-app \
  -p 8080:8080 \
  -e SPRING_PROFILES_ACTIVE=prod \
  -e DB_URL=jdbc:postgresql://host.docker.internal:5432/intelli_task \
  -e DB_USERNAME=admin \
  -e DB_PASSWORD=admin \
  -e REDIS_HOST=host.docker.internal \
  -e REDIS_PORT=6379 \
  -e OPENAI_API_KEY=your_api_key \
  intelli-task-ai:latest

7. 健康检查

服务启动后，可以通过以下方式检查健康状态：

# 检查应用健康状态
curl http://localhost:8080/actuator/health

# 检查 PostgreSQL
docker exec intelli-task-postgres pg_isready -U admin -d intelli_task

# 检查 Redis
docker exec intelli-task-redis redis-cli ping

8. 数据持久化

Docker Compose 使用命名卷来持久化数据：

  • postgres_data：PostgreSQL 数据
  • redis_data：Redis 数据
  • mysql_data：MySQL 数据（Nacos）

数据在容器删除后仍然保留，除非使用 docker-compose down -v 删除卷。

9. 故障排查

查看容器日志：

docker logs intelli-task-app
docker logs intelli-task-postgres
docker logs intelli-task-redis

进入容器调试：

# 进入应用容器
docker exec -it intelli-task-app bash

# 进入 PostgreSQL 容器
docker exec -it intelli-task-postgres psql -U admin -d intelli_task

# 进入 Redis 容器
docker exec -it intelli-task-redis redis-cli

重启服务：

docker-compose restart app

Kubernetes 部署

参考 k8s 目录下的部署配置文件。

许可证

Apache License 2.0

About

IntelliTask AI 是一个闭环的智能教育辅助系统,基于 Spring AI Alibaba 框架的 DDD 领域设计分层项目服务端。

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages