# 教务管理

**Repository Path**: coder-yzx/educational-administration

## Basic Information

- **Project Name**: 教务管理
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-21
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 少儿编程教务管理平台

面向少儿编程教育机构的 SaaS 教务管理平台，覆盖学员管理、课程购课、排课签到、课堂教学、考试系统、作品评审、星币商城、学习档案等完整教务生命周期。支持 AI 多模型（Claude/OpenAI/Doubao/Qwen）自动生成编程题目。

## 功能特性

- 🏫 **教务管理** — 学员生命周期、教师管理、课程与班级、订单购课缴费、智能排课、考勤签到、课时核销
- 🎓 **课堂教学** — 授课工作台（课件/模板/资料/点名/作品）、考试系统、成绩管理、课堂演示
- 🤖 **AI 题目生成** — 多模型网关，5 级难度体系，知识点自动标签化
- 📚 **内容管理** — 知识点库、题目库、项目管理、代码模板、Scratch 编辑器、资料包
- ⭐ **星币商城** — 学员激励体系，星币账户与交易流水
- 📊 **学习档案** — 知识点掌握追踪、配套练习、错题本、学习快照
- 🔐 **RBAC 权限** — 7 种角色、60+ 权限码、三级数据隔离
- 📱 **三端分离** — PC 管理后台 + 教师端 + 学员小程序端

## 快速开始

### 1. 环境要求

- Python >= 3.11
- Node.js >= 18（前端开发）
- uv（Python 包管理器）

### 2. 安装 uv

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### 3. 安装依赖

```bash
uv sync
```

### 4. 配置环境变量

```bash
cp .env.example .env
```

必填项：`AI_ENCRYPTION_KEY`（加密数据库中 AI API 密钥，设置后不可更改）

### 5. 初始化数据库并启动

```bash
# 方式一：一键启动（含种子数据）
make setup
make dev

# 方式二：手动步骤
uv run python -c "from src.database import init_db; init_db()"
uv run python seed_data.py
uv run python run.py
```

### 6. 访问系统

- **API 文档**: http://localhost:8000/docs
- **前端开发**: `make frontend-dev` → http://localhost:3000
- **默认管理员**: admin / admin123（种子数据创建）

### 7. Docker 部署

```bash
make docker-build    # 构建镜像（含前端）
make docker-up       # 启动 SQLite 版
# 或 PostgreSQL 版
docker compose --profile postgres up -d
```

## 项目结构

```
├── src/                          # 后端源代码 (86+ Python 文件)
│   ├── api/                      # API 路由层（6 业务域：educational/teaching/ai/content/system/legacy）
│   ├── models/                   # 数据模型层（54 个 SQLAlchemy ORM 模型）
│   ├── services/                 # 业务逻辑层（52 个服务文件）
│   ├── schemas/                  # Pydantic 请求/响应验证（24 个 schema）
│   ├── core/                     # 核心基础设施（中间件、权限、日志、导出）
│   ├── seed_data/                # 种子数据脚本（27 个文件）
│   ├── config.py                 # pydantic-settings 配置管理
│   ├── database.py               # 数据库连接与迁移
│   ├── exceptions.py             # 统一异常体系
│   └── main.py                   # FastAPI 应用工厂
├── frontend/                     # 前端源代码 (310+ 文件)
│   └── src/
│       ├── api/                  # Axios API 模块
│       ├── stores/               # Pinia 状态管理
│       ├── views/                # 页面（admin/teacher/student）
│       ├── layouts/              # 布局组件
│       ├── router/               # 路由与守卫
│       └── types/                # TypeScript 类型定义
├── docx/                         # 项目文档中心（详见 docx/README.md）
├── tests/                        # 后端测试 (24 文件)
├── docker-compose.yml            # Docker 编排
├── Dockerfile                    # Docker 镜像
├── Makefile                      # 开发命令快捷入口
└── pyproject.toml                # Python 项目配置
```

## 技术栈

| 层级 | 技术 | 版本 |
|------|------|------|
| 后端框架 | FastAPI | latest |
| ORM | SQLAlchemy | 2.0+ |
| 数据库 | SQLite (开发) / PostgreSQL (生产) | — |
| AI 网关 | Claude + OpenAI + Doubao + Qwen | 多模型 |
| 前端框架 | Vue 3 + Composition API | 3.5 |
| UI 库 | Element Plus | 2.14 |
| 状态管理 | Pinia | 3.0 |
| 构建工具 | Vite | 8.0 |
| 代码编辑器 | Monaco Editor | 0.50 |
| Scratch | scratch-vm + scratch-gui | 5.0 |
| 测试 | pytest + vitest + Hypothesis | — |
| 包管理 | uv (Python) + npm (前端) | — |

## 文档导航

- **开发指南**: [CLAUDE.md](./CLAUDE.md) — AI 助手开发参考
- **文档中心**: [docx/README.md](./docx/README.md) — 完整文档索引
- **AI Agent 规范**: [src/agent.md](./src/agent.md) — 研发作业流程规范

## 开发原则

本项目遵循 MVP 最小原则开发：
- 只实现必需功能，延迟高级特性
- 最简实现优先于最优雅实现
- 最少外部依赖，优先标准库
- 重构阈值：代码重复 3 次、函数超 50 行、文件超 300 行