# AIClair **Repository Path**: Mr-low/aiclair ## Basic Information - **Project Name**: AIClair - **Description**: 智课明镜 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-12-14 - **Last Updated**: 2026-03-03 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

# 🎓 AIClair 智课明镜 # AI Teaching Insights Engine ### 🚀 基于多模态数据与实时计算的课堂质量分析系统 [![Python](https://img.shields.io/badge/python-3.11+-yellow.svg)](https://www.python.org/) [![Vue](https://img.shields.io/badge/vue-3.4+-brightgreen.svg)](https://vuejs.org/) [![FastAPI](https://img.shields.io/badge/fastapi-latest-teal.svg)](https://fastapi.tiangolo.com/) [![TypeScript](https://img.shields.io/badge/typescript-5.3+-blue.svg)](https://www.typescriptlang.org/) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Coverage](https://img.shields.io/badge/coverage-85%25-brightgreen.svg)]() --- **一个融合计算机视觉 🎥、实时流处理 📊、AI大模型 🤖 的智能教学分析平台** 通过"感知-分析-决策-辅助"的闭环架构，实现从数据采集到智能决策的全流程自动化 [功能特性](#-核心特性) • [快速开始](#-快速开始) • [系统架构](#-系统架构) • [文档](#-相关文档) • [贡献指南](#-贡献)

--- ## 💡 项目名称寓意 **AIClair 智课明镜** - **"AI"** - 点明技术核心，人工智能驱动 - **"Clair"** - 源于法语"清晰、明亮"（如 Clairvoyant"有洞察力的"），直接对应"洞察引擎"的产品定位 - **"明镜"** - 寓意系统像一面明镜，清晰照见课堂全貌与教学本质，为教师提供客观、准确的教学反馈 --- ## 📋 目录 - [✨ 核心特性](#-核心特性) - [🏗️ 系统架构](#-系统架构) - [🎨 技术栈](#-技术栈) - [🚀 快速开始](#-快速开始) - [💻 开发指南](#-开发指南) - [📊 服务监控](#-服务监控) - [🧪 测试](#-测试) - [📁 项目结构](#-项目结构) - [🎯 项目进度](#-项目进度) - [📖 相关文档](#-相关文档) - [🤝 贡献](#-贡献) - [📄 许可证](#-许可证) - [🆘 故障排除](#-故障排除) --- ## ✨ 核心特性 ### 🎯 多模态行为检测

- 🎭 **MediaPipe集成** - 468个面部关键点检测、头部姿态估计、7种表情识别 - 🏃 **YOLOv8行为识别** - 举手、趴桌、玩手机、看书、写字等11种课堂行为 - 🧠 **专注度量化** - 综合头部姿态、眼部状态、身体动作的多维评分算法 - 😴 **疲劳检测** - 打哈欠、揉眼睛、趴桌等疲劳状态识别 ### 📊 实时数据分析

- ⚡ **Flink流处理** - 毫秒级实时学生状态计算和异常检测 - 📈 **Spark批处理** - 大规模历史数据分析和模式挖掘 - 🔄 **Kafka消息队列** - 可靠的数据传输和异步处理 - 📉 **时序数据存储** - ClickHouse优化的时间序列数据管理 ### 🤖 AI智能助教

- 💡 **教学改进建议** - 基于课堂分析的个性化教学方案 - 🗺️ **学习路径规划** - 根据学生表现动态调整学习路径 - 🕸️ **知识图谱生成** - 可视化知识结构和薄弱点识别 - 📚 **个性化推荐** - 智能推荐学习资源和练习题 ### 👥 角色权限管理

| 角色 | 权限范围 | 主要功能 | |:---:|:---|:---| | 👨‍💼 **管理员** | 全局数据访问 | 系统管理、用户管理、全局数据查看 | | 👩‍🏫 **教师** | 仅限自己课程 | 课程管理、视频分析、教学改进建议 | | 👨‍🎓 **学生** | 个人学习数据 | 学习路径、知识图谱、个人分析 | ### 📱 响应式界面

- 🎨 **现代化UI** - Vue3 + TypeScript + Arco Design - 🔴 **实时同步** - WebSocket支持的实时数据推送 - 📱 **响应式设计** - 完美支持桌面、平板、手机 - 🌙 **深色主题** - 统一的紫色渐变深色主题 ### ⚡ 性能优化 (v2.0)

- 🚀 **FastAPI异步架构** - 高性能异步框架，支持大规模并发 - 🔄 **独立Worker进程** - CV分析在独立进程处理，不阻塞API服务 - 💾 **内存缓存优化** - 上传后视频缓存内存，避免MinIO重复下载 - 🎯 **模型预加载** - 应用启动时预加载CV模型，首次分析无延迟 - 📨 **Kafka优化** - 正确的JSON序列化，大视频分析支持 --- ## 🏗️ 系统架构 ### 📐 整体分层架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ 🎨 前端展示层 (Vue3 + Arco Design + TypeScript) │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 👨‍💼 管理员 │ │ 👩‍🏫 教师 │ │ 👨‍🎓 学生 │ │ │ │ +数据面板 │ │ +数据面板 │ │ +学习路径 │ │ │ │ +视频播放 │ │ +视频播放 │ │ +知识图谱 │ │ │ │ +系统管理 │ │ +AI助教 │ │ +个人分析 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────┘ ⬇️ ┌─────────────────────────────────────────────────────────────┐ │ 🔌 API网关层 (FastAPI + Socket.IO + JWT) │ │ 异步处理 • 认证授权 • 路由分发 • WebSocket通信 │ └─────────────────────────────────────────────────────────────┘ ⬇️ ┌─────────────────────────────────────────────────────────────┐ │ 💼 业务服务层 │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 🎥 视频分析 │ │ 👤 用户管理 │ │ 🤖 AI助教 │ │ │ │ 📊 学生分析 │ │ 📚 课程管理 │ │ ⚠️ 监控服务 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────┘ ⬇️ ┌─────────────────────────────────────────────────────────────┐ │ 🔬 数据处理层 │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 🧠 CV模型 │ │ 📨 Kafka │ │ ⚡ Flink │ │ │ │MediaPipe+YOLO│ │ 消息队列 │ │ 实时流处理 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ ┌─────────────┐ │ │ │ 🔥 Spark │ │ │ │ 批处理 │ │ │ └─────────────┘ │ └─────────────────────────────────────────────────────────────┘ ⬇️ ┌─────────────────────────────────────────────────────────────┐ │ 💾 数据存储层 │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 🐘 PostgreSQL│ │ 🔴 Redis │ │ 🗄️ MinIO │ │ │ │ 元数据 │ │ 缓存+时序 │ │ 视频存储 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ ┌─────────────┐ │ │ │ 📊 ClickHouse│ │ │ │ 时序数据 │ │ │ └─────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ### 🔄 数据流处理架构 ``` 📹 视频上传 ⬇️ 🎬 CV模型检测 (MediaPipe + YOLOv8) ⬇️ 📨 Kafka消息队列 (异步解耦) ⬇️ ├─→ ⚡ Flink实时处理 → 🔄 实时状态推送 → 📱 WebSocket客户端 │ ⬇️ │ 📊 数据面板展示 │ └─→ 🔥 Spark批处理 → 🗄️ PostgreSQL元数据 ⬇️ 🔴 Redis缓存 ``` > 📌 **详细架构图**: 查看 [ARCHITECTURE.md](./ARCHITECTURE.md) 获取完整的系统架构图和模块设计 --- ## 🎨 技术栈 ### 前端技术 | 技术 | 版本 | 用途 | 文档 | |:---:|:---:|:---|:---| | **Vue** | 3.4+ | 渐进式框架 | [vuejs.org](https://vuejs.org/) | | **TypeScript** | 5.3+ | 类型系统 | [typescriptlang.org](https://www.typescriptlang.org/) | | **Arco Design** | Latest | UI组件库 | [arco.design](https://arco.design/) | | **Vite** | 5.0+ | 构建工具 | [vitejs.dev](https://vitejs.dev/) | | **Pinia** | Latest | 状态管理 | [pinia.vuejs.org](https://pinia.vuejs.org/) | | **Socket.IO** | Latest | WebSocket | [socket.io](https://socket.io/) | | **ECharts** | Latest | 数据可视化 | [echarts.apache.org](https://echarts.apache.org/) | ### 后端技术 | 技术 | 版本 | 用途 | 文档 | |:---:|:---:|:---|:---| | **Python** | 3.11+ | 编程语言 | [python.org](https://www.python.org/) | | **FastAPI** | Latest | 异步Web框架 | [fastapi.tiangolo.com](https://fastapi.tiangolo.com/) | | **Socket.IO** | Latest | WebSocket | [python-socketio](https://python-socketio.readthedocs.io/) | | **SQLModel** | Latest | ORM | [sqlmodel.tiangolo.com](https://sqlmodel.tiangolo.com/) | | **JWT** | Latest | 身份认证 | [jwt.io](https://jwt.io/) | | **Uvicorn** | Latest | ASGI服务器 | [uvicorn.readthedocs.io](https://uvicorn.readthedocs.io/) | ### 计算机视觉 | 技术 | 版本 | 用途 | 文档 | |:---:|:---:|:---|:---| | **MediaPipe** | 0.10+ | 面部检测 | [mediapipe.dev](https://mediapipe.dev/) | | **YOLOv8** | 8.0+ | 行为识别 | [ultralytics.com](https://ultralytics.com/) | | **OpenCV** | 4.8+ | 视频处理 | [opencv.org](https://opencv.org/) | ### 数据处理 | 技术 | 版本 | 用途 | 端口 | 文档 | |:---:|:---:|:---|:---:|:---| | **Kafka** | 7.9+ | 消息队列 | 9092 | [kafka.apache.org](https://kafka.apache.org/) | | **Flink** | 1.20+ | 实时流处理 | 8081 | [flink.apache.org](https://flink.apache.org/) | | **Spark** | 3.5+ | 批处理 | 8080 | [spark.apache.org](https://spark.apache.org/) | ### 数据存储 | 技术 | 版本 | 用途 | 端口 | 文档 | |:---:|:---:|:---|:---:|:---| | **PostgreSQL** | 15+ | 元数据存储 | 5432 | [postgresql.org](https://www.postgresql.org/) | | **Redis** | 7+ | 缓存/时序 | 6379 | [redis.io](https://redis.io/) | | **MinIO** | Latest | 对象存储 | 9000 | [min.io](https://min.io/) | | **ClickHouse** | 23+ | 时序数据 | 8123 | [clickhouse.com](https://clickhouse.com/) | ### 测试工具 | 技术 | 用途 | 文档 | |:---:|:---|:---| | **Pytest** | 后端单元测试 | [pytest.org](https://pytest.org/) | | **Hypothesis** | 属性测试 | [hypothesis.works](https://hypothesis.works/) | | **Vitest** | 前端单元测试 | [vitest.dev](https://vitest.dev/) | | **Playwright** | E2E测试 | [playwright.dev](https://playwright.dev/) | --- ## 🚀 快速开始 ### 📦 前置要求 - [x] **Docker** & **Docker Compose** - 容器化部署 - [x] **Node.js** 18+ - 前端开发 - [x] **Python** 3.11+ - 后端开发 - [x] **Make** - 命令行工具 (推荐) ### 🎬 一键启动开发环境 ```bash # 🚀 启动所有数据层服务（PostgreSQL、Redis、Kafka、Flink、Spark、MinIO、ClickHouse） cd /Users/ember/Desktop/人工智能/ATIE/backend make docker-start ``` 这将自动启动以下服务： | 服务 | 端口 | 用途 | 状态 | |:---:|:---:|:---|:---:| | 🐘 PostgreSQL | 5432 | 元数据存储 | ✅ | | 🔴 Redis | 6379 | 缓存/时序 | ✅ | | 📨 Kafka | 9092 | 消息队列 | ✅ | | 🎨 MinIO API | 9000 | 对象存储 | ✅ | | 🖥️ MinIO Console | 9001 | 存储管理界面 | ✅ | | ⚡ Flink Dashboard | 8081 | 流处理监控 | ✅ | | 🔥 Spark Master | 8080 | 批处理监控 | ✅ | | 📊 Kafka UI | 8083 | Kafka调试 | ✅ | | 📈 ClickHouse | 8123 | 时序数据 | ✅ | ### 💻 使用Makefile管理服务 ```bash cd /Users/ember/Desktop/人工智能/ATIE/backend # 查看所有可用命令 make help # 启动所有服务 (FastAPI + CV Worker) make start # 开发模式 (后台运行，日志保存到 logs/) make dev # 查看服务状态 make status # 查看日志 make logs # 停止服务 make stop # 重启服务 make restart ``` ### 🎨 前端开发 ```bash # 📦 安装依赖 cd /Users/ember/Desktop/人工智能/ATIE/frontend npm install # 🚀 启动开发服务器 (http://localhost:3000) npm run dev # 🔍 TypeScript类型检查 npm run type-check # 🏗️ 生产构建 npm run build # 🧪 运行测试 npm run test ``` ### ⚙️ 后端开发 ```bash # 📦 安装依赖 cd /Users/ember/Desktop/人工智能/ATIE/backend pip install -e . # 🚀 启动FastAPI服务器 (http://localhost:5001) make start-api # 🔄 启动CV Worker make start-worker # 🚀 启动所有服务 make dev # 👨‍💼 默认管理员账户 (admin/admin123) # 首次启动会自动创建 ``` ### 🎯 验证安装 ```bash # 1️⃣ 检查所有Docker服务状态 make docker-ps # 2️⃣ 测试后端健康检查 curl http://localhost:5001/health # 3️⃣ 测试数据库连接 docker exec ai-teaching-postgres-dev pg_isready -U postgres # 4️⃣ 测试Redis连接 docker exec ai-teaching-redis-dev redis-cli ping # 5️⃣ 检查Kafka主题 docker exec ai-teaching-kafka-dev kafka-topics --bootstrap-server localhost:9092 --list # 6️⃣ 验证优化配置 ./verify_optimizations.sh ``` --- ## 💻 开发指南 ### 🎨 UI组件开发项目提供了统一的深色主题和可复用组件： #### 使用 AdminTable 组件 ```vue ``` #### 统一的深色主题所有表格和组件使用统一的紫色渐变深色主题： - 🎨 主色调：`#667eea` → `#764ba2` - 🌙 深色背景，无白色 - ✨ 平滑过渡动画 - 💫 Hover渐变高亮 ### 🔧 VS Code 调试配置项目已配置完整的VS Code调试环境： 1. **🎯 全栈开发环境** - 同时启动前端和后端调试 2. **🔬 大数据调试环境** - 调试CV检测、Flink、Spark服务 3. **🔧 单独服务调试** - 可单独调试各个组件 **使用方法：** - 按 `F5` 选择调试配置 - 或 `Ctrl+Shift+P` → "Tasks: Run Task" ### 📝 常用命令 ```bash # 📊 查看服务状态 make status # 📋 查看服务日志 make logs # 所有日志 make logs-api # FastAPI日志 make logs-worker # CV Worker日志 # 🔄 重启服务 make restart # 🛑 停止所有服务 make stop # 🧹 清理临时文件 make clean # 🔍 运行验证脚本 make verify # 🧪 运行测试 make test ``` --- ## 📊 服务监控 ### 🖥️ 访问地址 | 服务 | URL | 凭据 | 说明 | |:---|:---|:---|:---| | **⚡ Flink Dashboard** | http://localhost:8081 | - | 实时流处理监控 | | **🔥 Spark Master UI** | http://localhost:8080 | - | 批处理任务监控 | | **🗄️ MinIO Console** | http://localhost:9001 | minioadmin / minioadmin123 | 对象存储管理 | | **📨 Kafka UI** | http://localhost:8083 | - | Kafka消息管理 | | **🐘 PostgreSQL** | localhost:5432 | postgres / password | 数据库连接 | | **🔴 Redis** | localhost:6379 | - | 缓存连接 | | **📈 ClickHouse** | http://localhost:8123 | - | 时序数据查询 | | **📡 FastAPI Docs** | http://localhost:5001/docs | - | API文档 | ### 🏥 健康检查 ```bash # 🔍 检查所有服务状态 make status # 🐘 检查数据库连接 docker exec ai-teaching-postgres-dev pg_isready -U postgres # 🔴 检查Redis连接 docker exec ai-teaching-redis-dev redis-cli ping # 📨 检查Kafka主题 docker exec ai-teaching-kafka-dev kafka-topics --bootstrap-server localhost:9092 --list # 📈 检查ClickHouse docker exec ai-teaching-clickhouse-dev clickhouse-client --query "SELECT 1" ``` --- ## 🧪 测试 ### 🔬 后端测试 ```bash cd backend # ✅ 运行所有测试 pytest -v # 🎯 运行特定测试文件 pytest tests/test_cv_detection.py -v # 🔬 属性测试 (Hypothesis) pytest tests/test_*_properties.py -v # 📊 生成覆盖率报告 pytest --cov=src/atie --cov-report=html ``` ### 🎨 前端测试 ```bash cd frontend # ✅ 运行单元测试 npm run test # 🔄 监听模式 npm run test:watch # 📊 覆盖率报告 npm run test:coverage # 🎭 E2E测试 npm run test:e2e ``` ### 🎯 测试覆盖率要求 - 后端：**85%+** - 前端：**80%+** - 关键路径：**100%** --- ## 📁 项目结构 ``` ai-teaching-insights/ ├── 📂 frontend/ # Vue3前端应用 │ ├── 📂 src/ │ │ ├── 📂 components/ # 可复用组件 │ │ │ ├── 📂 admin/ # 管理员组件 │ │ │ ├── 📂 shared/ # 共享组件 (AdminTable等) │ │ │ └── 📂 common/ # 通用组件 │ │ ├── 📂 views/ # 页面组件 │ │ │ ├── 📂 admin/ # 管理员页面 │ │ │ ├── 📂 teacher/ # 教师页面 │ │ │ ├── 📂 student/ # 学生页面 │ │ │ └── 📂 auth/ # 认证页面 │ │ ├── 📂 features/ # 功能模块 │ │ │ └── 📂 video/ # 视频相关功能 │ │ ├── 📂 stores/ # Pinia状态管理 │ │ ├── 📂 services/ # API服务 │ │ ├── 📂 types/ # TypeScript类型 │ │ ├── 📂 styles/ # 全局样式 │ │ └── 📂 router/ # 路由配置 │ ├── 📄 package.json │ └── 📄 vite.config.ts ├── 📂 backend/ # FastAPI后端应用 │ ├── 📂 src/atie/ # 源代码 │ │ ├── 📂 api/v1/ # API路由 │ │ │ ├── auth.py # 认证API │ │ │ ├── video.py # 视频管理API │ │ │ ├── course.py # 课程管理API │ │ │ ├── analysis.py # 分析服务API │ │ │ └── ... │ │ ├── 📂 core/ # 核心工具 │ │ │ └── security.py # JWT认证 │ │ ├── 📂 models/ # SQLModel ORM模型 │ │ │ └── core_models.py # 核心数据模型 │ │ ├── 📂 schemas/ # Pydantic模式 │ │ ├── 📂 repositories/ # 数据访问层 │ │ ├── 📂 services/ # 业务服务 │ │ │ ├── 📂 cv_detection/ # CV检测服务 │ │ │ │ ├── cv_service.py │ │ │ │ ├── yolo_detector.py │ │ │ │ ├── mediapipe_detector.py │ │ │ │ └── student_tracker.py │ │ │ ├── 📂 video/ # 视频服务 │ │ │ ├── 📂 kafka/ # Kafka服务 │ │ │ └── 📂 websocket/ # WebSocket服务 │ │ ├── 📂 infrastructure/ # 基础设施 │ │ │ ├── database.py # 数据库连接 │ │ │ ├── redis.py # Redis连接 │ │ │ ├── minio.py # MinIO客户端 │ │ │ ├── kafka.py # Kafka客户端 │ │ │ └── socketio.py # Socket.IO服务器 │ │ ├── 📂 workers/ # 后台Worker │ │ │ └── cv_worker.py # CV分析Worker │ │ └── main.py # FastAPI应用入口 │ ├── 📂 tests/ # 测试文件 │ ├── 📄 Makefile # 命令管理 │ ├── 📄 pyproject.toml # Python项目配置 │ ├── 📄 start-cv-worker.sh # Worker启动脚本 │ ├── 📄 start_fastapi.sh # FastAPI启动脚本 │ └── 📄 verify_optimizations.sh # 验证脚本 ├── 📄 docker-compose.dev.yml # 开发环境配置 ├── 📂 scripts/ # 开发脚本 ├── 📂 .vscode/ # VS Code配置 ├── 📄 ARCHITECTURE.md # 系统架构文档 ├── 📄 CLAUDE.md # Claude开发指南 ├── 📄 MAKEFILE_GUIDE.md # Makefile使用指南 └── 📄 README.md # 本文档 ``` --- ## 🎯 项目进度 ### ✅ 已完成 (Phase 0-7) ### 🚧 Phase 0-1: 基础架构 & 核心功能 ✅ - [x] **项目基础架构搭建** - Python/TypeScript项目结构 - [x] **Docker开发环境** - 完整的数据层服务部署 - [x] **数据库初始化** - RBAC权限系统和完整表结构 - [x] **用户认证系统** - JWT身份验证 + 角色权限控制 - [x] **视频上传功能** - MinIO对象存储集成 ### 🎨 Phase 2: CV检测引擎 ✅ - [x] **MediaPipe集成** - 468点面部关键点、头部姿态、表情识别 - [x] **YOLOv8行为检测** - 11种课堂行为识别 - [x] **YOLO模型训练系统** - 完整的训练和评估工具 - [x] **CV检测属性测试** - 确保检测准确性 ### ⚡ Phase 3: 数据处理管道 ✅ - [x] **Kafka消息队列** - CV检测数据传输 - [x] **Flink实时流处理** - 实时状态计算 - [x] **Spark批处理引擎** - 大规模数据分析 ### 📊 Phase 4: 学生状态分析 ✅ - [x] **多维状态评估** - 专注度和参与度计算 - [x] **时序分析系统** - 个体轨迹追踪 ### 🤖 Phase 5: AI智能功能 ✅ - [x] **QWEN AI助教** - 教学改进建议生成 - [x] **学习路径规划** - 个性化学习方案 ### 🎨 Phase 6: 前端界面开发 ✅ - [x] **管理员端界面** - 系统管理功能 - [x] **教师端界面** - 教学分析功能 - [x] **学生端界面** - 个人学习中心 - [x] **实时同步系统** - WebSocket通信 - [x] **统一深色主题** - 紫色渐变主题系统 ### 🚀 Phase 7: 架构迁移与性能优化 ✅ - [x] **FastAPI异步架构** - SQLModel + Pydantic v2 + async/await - [x] **独立CV Worker** - 后台进程处理，不阻塞API - [x] **内存缓存优化** - 视频数据缓存，避免重复下载 - [x] **模型预加载** - 启动时预加载，首次分析无延迟 - [x] **Kafka消息优化** - 正确JSON序列化 - [x] **进度显示修复** - 前端实时进度更新 - [x] **Makefile集成** - 统一命令管理 ### 🧪 Phase 8: 测试和质量保证 (85%) - [x] **单元测试** - 20+测试文件覆盖 - [x] **集成测试** - 端到端流程验证 - [x] **属性测试** - Hypothesis属性测试 - [ ] **性能测试** - 负载和压力测试 (待完善) - [ ] **前端E2E测试** - Playwright自动化 (待补充) ### 🚀 Phase 9: 生产部署 (20%) - [ ] **Kubernetes部署** - 云原生架构 - [ ] **CI/CD流水线** - 自动化部署 - [ ] **监控告警** - 完整的可观测性方案 - [ ] **安全加固** - 生产环境安全 ### 📊 完成度统计 | Phase | 进度 | 状态 | |:---:|:---:|:---:| | Phase 0 | 100% | ✅ | | Phase 1 | 100% | ✅ | | Phase 2 | 100% | ✅ | | Phase 3 | 100% | ✅ | | Phase 4 | 95% | ✅ | | Phase 5 | 100% | ✅ | | Phase 6 | 100% | ✅ | | Phase 7 | 100% | ✅ | | Phase 8 | 85% | 🚧 | | Phase 9 | 20% | 🚧 | ### 🎉 总体完成度: **~90%** ### 🎯 下一步重点 1. **📊 性能测试和优化** - 大规模视频处理性能基准 2. **🎭 前端E2E测试** - 端到端自动化测试 3. **🚀 Kubernetes生产部署** - 容器化和集群部署 4. **🔄 CI/CD流水线** - 自动化测试和部署 5. **📈 监控告警完善** - 完整的可观测性方案 **项目已接近生产就绪状态！** 🎉 --- ## 📖 相关文档 ### 📚 核心文档 - [📐 系统架构](./ARCHITECTURE.md) - 完整的系统架构图和设计说明 - [👨‍💻 开发指南](./CLAUDE.md) - Claude Code开发指南和项目规范 - [📋 Makefile指南](./backend/MAKEFILE_GUIDE.md) - Makefile命令参考 - [🔧 优化说明](./backend/verify_optimizations.sh) - 性能优化验证 ### 📖 API文档 - **后端API**: http://localhost:5001/docs (FastAPI自动生成) - **前端组件**: [组件文档](./frontend/src/components/README.md) (开发中) ### 🔧 配置说明 - **环境变量**: 参见 [配置说明](#-环境变量) - **Docker服务**: 参见 [docker-compose.dev.yml](./docker-compose.dev.yml) - **前端配置**: 参见 [vite.config.ts](./frontend/vite.config.ts) - **Makefile命令**: 运行 `make help` --- ## 🤝 贡献我们欢迎所有形式的贡献！🙌 ### 💡 如何参与 1. **🌿 创建分支** - `git checkout -b feature/your-feature-name` 2. **💻 编写代码** - 遵循项目代码规范 3. **✍️ 编写测试** - 确保新功能有相应的测试 4. **📤 提交PR** - 创建Pull Request并等待代码审查 ### 📝 代码规范 - **Python**: 遵循PEP 8，使用Black格式化 - **JavaScript/TypeScript**: 遵循ESLint规则，使用Prettier格式化 - **提交信息**: 使用[约定式提交](https://www.conventionalcommits.org/)格式 ```bash # 提交格式 feat: 添加视频上传功能 fix: 修复用户认证bug docs: 更新API文档 test: 添加单元测试 style: 统一表格深色主题样式 refactor: 重构CV检测服务 perf: 优化Flink流处理性能 chore: 更新依赖版本 ``` ### 🎨 UI组件开发规范 - ✅ 使用统一的 `AdminTable` 组件 - ✅ 遵循深色主题配色方案 - ✅ 所有表格无白色背景 - ✅ 使用紫色渐变主色调 - ✅ 统一的过渡动画效果 --- ## 🔧 配置说明 ### 🌍 环境变量 #### 后端配置 (.env) ```bash # 🗄️ 数据库配置 POSTGRES_HOST=localhost POSTGRES_PORT=5432 POSTGRES_DB=ai_teaching_insights POSTGRES_USER=postgres POSTGRES_PASSWORD=password # 🔴 Redis配置 REDIS_HOST=localhost REDIS_PORT=6379 # 📨 Kafka配置 KAFKA_BOOTSTRAP_SERVERS=localhost:9092 # 🗄️ MinIO配置 MINIO_ENDPOINT=localhost:9000 MINIO_ACCESS_KEY=minioadmin MINIO_SECRET_KEY=minioadmin123 # 🤖 AI服务配置 QWEN_API_KEY=your_qwen_api_key # ⚡ Flink配置 FLINK_HOST=localhost FLINK_PORT=8081 # 🔥 Spark配置 SPARK_MASTER=spark://localhost:7077 # 🔐 JWT密钥 SECRET_KEY=your-secret-key-here ``` #### 前端配置 (.env) ```bash # 🔌 API配置 VITE_API_BASE_URL=http://localhost:5001/api VITE_WS_URL=ws://localhost:5001 # 📊 其他配置 VITE_APP_TITLE=AI教学洞察引擎 VITE_UPLOAD_MAX_SIZE=500MB ``` --- ## 🚀 部署 ### 🐳 生产环境部署完整的部署方案请参考项目文档和架构说明。 ### 🏗️ Docker生产镜像 ```bash # 🎨 构建前端镜像 docker build -f frontend/Dockerfile -t ai-teaching-frontend . # ⚙️ 构建后端镜像 docker build -f backend/Dockerfile -t ai-teaching-backend . # 🎬 构建CV服务镜像 docker build -f backend/Dockerfile.cv -t ai-teaching-cv . ``` ### ☸️ Kubernetes部署 ```bash # 🚀 部署到Kubernetes kubectl apply -f k8s/ # 📊 查看部署状态 kubectl get pods -n ai-teaching # 📋 查看服务 kubectl get svc -n ai-teaching ``` --- ## 📄 许可证本项目采用 **MIT** 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。 --- ## 🆘 故障排除 ### ❓ 常见问题 #### 1. 🐳 Docker服务启动失败 **症状**: `docker-compose up` 失败 ```bash # 🔍 检查端口占用 lsof -i :5432 # 🗑️ 清理Docker资源 docker system prune -af # 🔄 重启Docker服务 sudo systemctl restart docker ``` #### 2. 📨 Kafka连接失败 **症状**: 无法连接到Kafka ```bash # 🔄 重启Kafka服务 make docker-restart # 📋 检查Kafka日志 make docker-logs # 🧪 测试Kafka连接 docker exec ai-teaching-kafka-dev kafka-topics --bootstrap-server localhost:9092 --list ``` #### 3. 🎨 前端代理失败 **症状**: API请求失败 ```bash # ✅ 检查后端服务是否启动 make status # 🔄 重启前端开发服务器 cd frontend && npm run dev # 🧹 清除缓存 rm -rf node_modules dist && npm install ``` #### 4. 🎬 CV Worker启动失败 **症状**: Worker无法处理视频 ```bash # 📋 查看Worker日志 make logs-worker # 🔍 验证Kafka主题 docker exec ai-teaching-kafka-dev kafka-topics --bootstrap-server localhost:9092 --list | grep cv_analysis # 🔄 重启Worker make stop-worker && make start-worker ``` #### 5. ⚡ Flink作业提交失败 **症状**: Flink作业无法启动 ```bash # 📋 检查Flink日志 docker-compose -f docker-compose.dev.yml logs flink # 🔄 重启Flink服务 docker-compose -f docker-compose.dev.yml restart flink # 🧪 测试Flink连接 curl http://localhost:8081 ``` ### 🆘 获取帮助 - 📖 阅读详细的[开发指南](./CLAUDE.md) - 📖 查看[Makefile指南](./backend/MAKEFILE_GUIDE.md) - 👨‍💻 联系项目维护者 --- ## 🙏 致谢感谢以下开源项目：

特别感谢： - 🎨 **Arco Design** - 优秀的Vue3组件库 - 🐘 **PostgreSQL** - 可靠的关系型数据库 - 🔴 **Redis** - 高性能缓存数据库 - 🗄️ **MinIO** - 优秀的对象存储方案 - 📊 **ClickHouse** - 强大的时序数据库 --- ## 📞 联系我们 - 📧 Email: [support@example.com](mailto:support@example.com) - 💬 Discord: [加入我们的Discord](https://discord.gg/your-server) - 📖 文档: [在线文档](https://docs.example.com) ---

**🎉 感谢使用 AI教学洞察引擎！** **Happy Coding! 💻✨** ---

_{Built with ❤️ by the AI Teaching Team}

_{⭐ 如果这个项目对你有帮助，请给我们一个星标！}