# interactive-learning

**Repository Path**: com-xiaoxu/interactive-learning

## Basic Information

- **Project Name**: interactive-learning
- **Description**: 面向专业知识学习场景的 AI 交互式知识解释器。用户可以输入概念或上传资料，系统将内容转换为分层解释、可视化过程、示例和测验，并根据学习结果提供针对性反馈。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-11
- **Last Updated**: 2026-07-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Interactive Learning

面向专业知识学习场景的 AI 交互式知识解释器。用户可以输入概念或上传资料，系统将内容转换为分层解释、可视化过程、示例和测验，并根据学习结果提供针对性反馈。

## 当前阶段

当前版本为 `0.3.0`，已完成“输入概念 → 生成结构化课程 → 写入数据库 → 查询课程 → 完成即时测验”的业务链路。课程生成目前使用可替换的本地模板实现，资料解析、AI 模型接入和用户认证将在后续纵向切片中实现。

## 计划技术栈

- Web：Next.js、React、TypeScript
- API：FastAPI、Python
- 业务数据库：MySQL 8.4 LTS
- 向量检索：Qdrant
- 缓存与异步任务：Redis
- 文件存储：兼容 S3 的对象存储
- 可视化：React Flow、Apache ECharts、KaTeX
- 本地环境：Docker Compose

## 项目文档

- [项目级开发约束](./AGENTS.md)
- [开发指南](./docs/DEVELOPMENT.md)
- [系统架构](./docs/ARCHITECTURE.md)
- [API 接口](./docs/API.md)
- [数据库设计](./docs/DATABASE.md)
- [UI 设计规范](./docs/UI_GUIDELINES.md)

## MVP 目标

第一阶段实现一条完整学习链路：

1. 用户输入一个专业概念。
2. AI 生成经过结构校验的课程内容。
3. 前端渲染解释、类比、流程图、代码示例和测验。
4. 系统保存学习记录与测验结果。
5. AI 根据错误知识点生成补充解释。

## 本地启动

### Web

```powershell
npm install
npm run dev:web
```

访问 `http://localhost:3000`。

### API

```powershell
cd apps/api
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload --port 8000
```

健康检查地址为 `http://localhost:8000/api/v1/health`。

课程生成接口为 `POST http://localhost:8000/api/v1/courses/generate`。

课程详情接口为 `GET http://localhost:8000/api/v1/courses/{course_id}`。

### 基础设施

本机安装 Docker 后，在项目根目录执行：

```powershell
docker compose -f infrastructure/docker-compose.yml up -d
```

当前开发环境没有 Docker，因此本轮仅验证了 API 和 Web，不会自动启动这些依赖服务。

已有本地 MySQL 时，也可以直接导入：

```powershell
mysql --default-character-set=utf8mb4 -h 127.0.0.1 -P 3306 -u root -p < infrastructure/mysql/001_init.sql
```

命令会交互式询问密码，仓库不会保存数据库账号密码。