# edu-agent-backend

**Repository Path**: Guqier/edu-agent-backend

## Basic Information

- **Project Name**: edu-agent-backend
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-28
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AAServer - 教育管理平台后端服务

## 项目简介

AAServer 是一个基于 Django 和 Django REST Framework 构建的现代化教育管理平台后端服务系统。该系统专为教育机构设计，提供完整的用户管理、权限控制、资源管理和教育业务流程支持。采用微服务架构思想，通过模块化设计实现高内聚、低耦合的系统架构。

## 核心功能

### 🔐 用户认证与权限管理
- **多类型用户支持** - 管理员、教师、学生三种用户角色
- **基于Redis的Token认证** - 高性能的分布式认证机制
- **RBAC权限控制** - 基于角色的访问控制，支持细粒度权限管理
- **安全机制** - 密码加密存储、逻辑删除、账号过期控制

### 👥 教育用户管理
- **教师信息管理** - 支持教师档案、职业信息、学科专业等完整信息
- **学生信息管理** - 学籍管理、个人档案、学习状态跟踪
- **高校信息管理** - 学校基础信息、办学层次、主管部门等

### 🗄️ 资源与文件管理
- **MinIO对象存储** - 集成MinIO实现分布式文件存储
- **多媒体资源支持** - 图片、PDF等多种文件类型管理
- **资源分组管理** - 支持文件分组和层级管理

### 📊 系统管理功能
- **码表管理** - 统一的数据字典和编码管理
- **角色权限管理** - 灵活的角色定义和权限分配
- **通知系统** - 消息通知和系统公告功能
- **代理管理** - 支持代理用户和权限委托

## 技术架构

### 核心技术栈
- **后端框架**: Django 5.2.4
- **API框架**: Django REST Framework 3.16.0
- **数据库**: MySQL 8.0+
- **缓存系统**: Redis 6.0+
- **文件存储**: MinIO 对象存储
- **异步任务**: Celery + Redis
- **Python版本**: 3.13+

### 系统特性
- **高性能缓存** - Redis缓存提升系统响应速度
- **异步任务处理** - Celery支持后台任务和定时任务
- **跨域支持** - 内置CORS中间件支持前后端分离
- **自定义分页** - 优化的分页组件提升用户体验
- **统一异常处理** - 全局异常处理机制
- **自定义渲染器** - 支持数字类型自动转换

## 项目架构

```
AAServer/
├── AAServer/                    # Django项目核心配置
│   ├── common/                  # 公共组件模块
│   │   ├── authentication.py   # 自定义认证组件
│   │   ├── cache.py            # 缓存工具
│   │   ├── decorators.py       # 装饰器
│   │   ├── exceptions.py       # 自定义异常
│   │   ├── middleware.py       # 中间件
│   │   ├── models.py           # 基础模型
│   │   ├── pagination.py       # 分页组件
│   │   ├── permissions.py      # 权限控制
│   │   ├── renderers.py        # 渲染器
│   │   └── validator.py        # 数据验证
│   ├── utils/                  # 工具类
│   │   ├── RedisUtils.py       # Redis工具
│   │   └── SessionUtils.py     # 会话工具
│   ├── settings.py             # 项目配置
│   ├── urls.py                 # 主路由配置
│   └── celery.py               # Celery配置
├── apps/                       # 业务应用模块
│   ├── auth/                   # 用户认证模块
│   ├── user/                   # 用户管理模块
│   ├── teacher/                # 教师管理模块
│   ├── student/                # 学生管理模块
│   ├── university/             # 高校管理模块
│   ├── role/                   # 角色管理模块
│   ├── permission/             # 权限管理模块
│   ├── rbac/                   # RBAC权限控制
│   ├── resource/               # 资源管理模块
│   ├── code_dict/              # 码表管理模块
│   ├── agent/                  # 智能体模块
│   └── notification/           # 通知管理模块
├── Dockerfile.dev              # 开发环境Docker配置
├── Dockerfile.prod             # 生产环境Docker配置
└── requirements.txt            # 项目依赖
```

## 本地启动与 Celery

### 环境与依赖

1. 建议使用 Python 3.13+，创建虚拟环境并安装依赖：

```bash
python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

2. 配置数据库、Redis、MinIO 等（见 `AAServer/settings.py` 或本地 `.env`）。本地开发至少需要 **MySQL** 与可连通的 **Redis**（若要让作业/考试生命周期按时自动开始、到期）。

### 启动 Django

```bash
python manage.py migrate
python manage.py runserver
```

### Celery 队列说明

| 队列名 | 用途 |
|--------|------|
| `celery` | 默认队列（通知、Beat 下发的补偿任务等） |

`assignment_exam_v2` 生命周期不再使用 Celery ETA 队列，而是使用 Redis ZSET + 常驻 worker（见下节）。

### 环境变量

- **`CELERY_BROKER_URL`**：Celery 消息 Broker（通常为 Redis），例如 `redis://127.0.0.1:6379/0`。未设置时 `lifecycle_delay_queue_available()` 会认为不可投递。
- **`CELERY_REDBEAT_REDIS_URL`**：若启动 **Celery Beat**（项目使用 RedBeat），需单独配置，用于存储 Beat 调度元数据。
- **`ASSIGNMENT_EXAM_V2_LIFECYCLE_ZSET_KEY`**：生命周期调度 ZSET key（默认 `ae:v2:lifecycle:zset`）。
- **`ASSIGNMENT_EXAM_V2_LIFECYCLE_BATCH_SIZE`**：worker 单轮拉取上限（默认 200）。

### 启动 Worker（必做：若要跑 assignment_exam_v2 生命周期）

在**项目根目录**（`manage.py` 同级）执行。

`assignment_exam_v2` 生命周期 worker（Redis 调度）：

```bash
python manage.py run_assignment_exam_lifecycle_worker --interval 2 --batch-size 200
celery -A AAServer worker --loglevel=info --pool=solo -Q celery
```

在 **Windows** 上建议使用 `--pool=solo` 避免多进程/fork 问题；Linux 可对 `celery` 队列使用 `prefork` 提高并发。

### 启动 Beat（可选）

当需要 **CELERY_BEAT_SCHEDULE** 中的周期任务时再启动，例如：`recover-llm-zombie-tasks`（每 5 分钟）、**`assignment-exam-v2-lifecycle-sweep`**（每 2 分钟，扫描并补救未翻转的到点状态；该任务在 **`celery`** 队列）。**assignment_exam_v2** 到点主路径是 **Redis ZSET 生命周期 worker（`run_assignment_exam_lifecycle_worker`）**。

```bash
celery -A AAServer beat --loglevel=info
```

需保证 `CELERY_REDBEAT_REDIS_URL` 可用。

### 检查调度是否可用

1. **Redis**：`redis-cli -u <你的 REDIS_URL 或 CELERY_BROKER_URL> ping` 应返回 `PONG`。
2. **发布前就绪检查**：

```bash
python manage.py check_release_readiness
```

检查通过会输出 `release readiness OK`；若 migration 漂移或 Redis 不可用，会直接失败并给出原因。

### 活动到期与学生通知（assignment_exam_v2）

- **状态翻转**：依赖 `run_assignment_exam_lifecycle_worker` 消费 Redis 生命周期事件，以及可选 **Beat** `run_activity_deadline_once`（`celery` 队列）兜底；**GET 详情/列表不修改** `status`。
- **学生端「通知」**：到期并写入「已结束」时，服务在 `process_activity_deadline` 内调用 `_notify_activity_ended`，向 **`CurriculumNewStudent`** 选课下的学生用户（及发布教师）在 **`Notification`** 表中批量插入记录（`notification_type=3`）；客户端通过项目里**通知/消息中心**既有接口拉取未读列表即可，**不是**单独 websocket 推送到作业模块。
- 到期通知已在服务端改为 **`batch_add_notification.apply`（同步落库）**，避免「到点任务已跑完，但通知仍排在 `celery` 队列后面」的延迟。

### 常见问题

- **生命周期 worker 未启动**：Redis 到期事件无人消费，库内 `status` 不变。
- **Redis 不可用**：无法注册/拉取生命周期事件，发布检查会失败。
- **模型有变更未出 migration**：`check_release_readiness` 会直接阻断。

## 系统特点

### 🏗️ 模块化设计
- 采用Django应用模块化架构，每个业务模块独立开发
- 公共组件统一管理，提高代码复用性
- 清晰的模块边界，便于团队协作开发

### 🔒 安全可靠
- 基于Redis的分布式Token认证
- 完善的权限控制体系
- 数据加密存储和传输
- 支持逻辑删除，保证数据安全

### ⚡ 高性能
- Redis缓存加速数据访问
- 数据库连接池优化
- 异步任务处理提升用户体验
- MinIO分布式存储支持大文件处理

### 🌐 现代化架构
- RESTful API设计规范
- 支持前后端分离开发
- Docker容器化部署
- 微服务架构思想