# 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 YOLOv8 OpenCV

- 🎭 **MediaPipe集成** - 468䞪面郚关键点检测、倎郚姿态䌰计、7种衚情识别 - 🏃 **YOLOv8行䞺识别** - 䞟手、趎桌、玩手机、看乊、写字等11种诟堂行䞺 - 🧠 **䞓泚床量化** - 绌合倎郚姿态、県郚状态、身䜓劚䜜的倚绎评分算法 - 😎 **疲劳检测** - 打哈欠、揉県睛、趎桌等疲劳状态识别 ### 📊 实时数据分析

Kafka Flink Spark

- ⚡ **Flink流倄理** - 毫秒级实时孊生状态计算和匂垞检测 - 📈 **Spark批倄理** - 倧规暡历史数据分析和暡匏挖掘 - 🔄 **Kafka消息队列** - 可靠的数据䌠蟓和匂步倄理 - 📉 **时序数据存傚** - ClickHouse䌘化的时闎序列数据管理 ### 🀖 AI智胜助教

QWEN

- 💡 **教孊改进建议** - 基于诟堂分析的䞪性化教孊方案 - 🗺 **孊习路埄规划** - 根据孊生衚现劚态调敎孊习路埄 - 🕞 **知识囟谱生成** - 可视化知识结构和薄匱点识别 - 📚 **䞪性化掚荐** - 智胜掚荐孊习资源和练习题 ### 👥 角色权限管理

JWT RBAC

| 角色 | 权限范囎 | 䞻芁功胜 | |:---:|:---|:---| | 👚‍💌 **管理员** | 党局数据访问 | 系统管理、甚户管理、党局数据查看 | | 👩‍🏫 **教垈** | 仅限自己诟皋 | 诟皋管理、视频分析、教孊改进建议 | | 👚‍🎓 **孊生** | 䞪人孊习数据 | 孊习路埄、知识囟谱、䞪人分析 | ### 📱 响应匏界面

Vue TypeScript Arco Design

- 🎚 **现代化UI** - Vue3 + TypeScript + Arco Design - 🔎 **实时同步** - WebSocket支持的实时数据掚送 - 📱 **响应匏讟计** - 完矎支持桌面、平板、手机 - 🌙 **深色䞻题** - 统䞀的玫色析变深色䞻题 ### ⚡ 性胜䌘化 (v2.0)

FastAPI Worker Cache

- 🚀 **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) - 👚‍💻 联系项目绎技者 --- ## 🙏 臎谢 感谢以䞋匀源项目

Vue.js FastAPI MediaPipe YOLOv8 Kafka Flink

特别感谢 - 🎚 **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
⭐ 劂果这䞪项目对䜠有垮助请给我们䞀䞪星标