# py_datanest

**Repository Path**: hduzn/py_datanest

## Basic Information

- **Project Name**: py_datanest
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-08
- **Last Updated**: 2026-01-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Python 数据收集展示系统

基于 FastAPI + PostgreSQL + SQLAlchemy 构建的教育数据收集展示系统，适用于中小学教育场景中的答题数据收集、实时展示和智能分析。

## 一、功能特性

### 1.学生端功能

- 📝 **交互式答题**：多学科 HTML 答题页面，实时反馈答题结果
- 🎯 **进度跟踪**：关卡式学习进度显示，清晰的答题状态
- 👤 **用户验证**：自动验证学生身份，确保数据安全

### 2.管理员功能

- 👥 **用户管理**：
  - 添加单个用户
  - 批量导入用户（支持 CSV/Excel）
  - 搜索和分页查看
- 📊 **数据分析大屏**：
  - 实时数据可视化
  - 多维度统计分析
  - 题目难度分析
- 🏆 **排行榜系统**：
  - Top 10 快速排行
  - 完整排行榜（支持分页、搜索、筛选）
- 🤖 **AI 智能分析**：
  - 基于 DeepSeek API 的智能分析
  - 自动识别学习薄弱点
  - 生成个性化学习建议
- 💾 **数据导出**：支持答题数据的 CSV 格式导出
- 🎛️ **页面管理**：数据库驱动的动态页面配置管理

### 3.技术特性

- 🔐 权限管理：管理员登录验证机制
- 📱 响应式设计：适配各种屏幕尺寸
- ⚡ 高性能：支持多 worker 并发处理

## 二、技术栈

- **后端框架**：FastAPI
- **数据库**：PostgreSQL
- **ORM**：SQLAlchemy
- **前端**：HTML5 + JavaScript + Tailwind CSS
- **图表库**：Chart.js + ECharts
- **AI 服务**：DeepSeek API
- **Web 服务器**：Uvicorn（支持多进程）

## 三、支持的学习页面

系统当前支持以下学习页面：

| 页面              | 路径              | 题目数 | 描述                |
| ----------------- | ----------------- | ------ | ------------------- |
| Python 编程       | `/python`         | 15题   | Python 基础知识测试 |
| 科学 - 时间的测量 | `/kexue/kexue5_1` | 16题   | 五年级科学第一单元  |
| 科学 - 健康生活   | `/kexue/kexue5_2` | 40题   | 五年级科学第二单元  |
| 信息技术          | `/xinxi/xinxi3_1` | 12题   | 三年级信息技术上册  |

## 四、项目结构

```
py_datanest/
├── app.py                      # 应用入口文件（启动配置）
├── init_pages.py              # 页面配置初始化脚本
├── update_learning_pages.py   # 更新学习页面配置脚本
├── src/                       # 源代码目录
│   ├── main.py               # FastAPI 主应用（3900+ 行，包含所有路由）
│   ├── database.py           # 数据库模型和连接配置
│   ├── config.py             # 服务器配置（支持多服务器）
│   └── ai_analyzer.py        # AI 分析模块（DeepSeek API 集成）
├── templates/                 # HTML 模板目录
│   ├── python.html           # Python 编程答题页面（1300+ 行）
│   ├── kexue/                # 科学课程模板
│   │   ├── kexue5_1.html     # 五年级科学 - 时间的测量
│   │   └── kexue5_2.html     # 五年级科学 - 健康生活
│   ├── xinxi/                # 信息技术课程模板
│   │   └── xinxi3_1.html     # 三年级信息技术上册
│   ├── admin_login.html      # 管理员登录页面
│   ├── dashboard.html        # 管理员仪表板
│   ├── pages_manage.html     # 页面管理界面
│   ├── user_manage.html      # 用户管理界面
│   ├── python_dashboard.html # Python 数据大屏
│   ├── kexue_dashboard.html  # 科学数据大屏
│   ├── ai_analysis.html      # AI 分析报告页面
│   └── full_leaderboard.html # 完整排行榜页面
├── static/                    # 静态资源目录
│   ├── css/                   # 样式文件
│   ├── js/                    # JavaScript 文件
│   ├── favicon.ico            # 网站图标
│   └── *.csv                  # 导出的数据文件
└── README.md                  # 本说明文档
```

## 五、安装与配置

### 1. 环境要求

- Python 3.9+
- PostgreSQL 数据库
- 网络连接（用于 AI 分析功能）

### 2. 安装依赖

```bash
# 使用 uv 安装依赖（推荐）
uv add fastapi uvicorn sqlalchemy psycopg2-binary python-multipart jinja2 httpx openpyxl

# 或者使用 pip
pip install fastapi uvicorn sqlalchemy psycopg2-binary python-multipart jinja2 httpx openpyxl
```

依赖说明：

- `fastapi` - Web 框架
- `uvicorn` - ASGI 服务器
- `sqlalchemy` - ORM 框架
- `psycopg2-binary` - PostgreSQL 数据库驱动
- `python-multipart` - 表单数据支持
- `jinja2` - 模板引擎
- `httpx` - HTTP 客户端（AI API 调用）
- `openpyxl` - Excel 文件支持（用户导入）

### 3. 数据库配置

修改 `src/config.py` 中的数据库连接配置：

```python
# 修改为你的 PostgreSQL 数据库连接信息
DATABASE_URL = "postgresql://username:password@localhost:5432/dbname"

# 配置 DeepSeek API（用于 AI 分析功能）
DEEPSEEK_API_KEY = "your_deepseek_api_key"
DEEPSEEK_API_BASE = "https://api.deepseek.com/v1"
```

系统支持多服务器配置，可根据部署环境选择不同的数据库连接。

### 4. 初始化数据库

首次运行前，需要创建数据库并初始化页面配置：

```bash
# 1. 创建 PostgreSQL 数据库
createdb py_datanest

# 2. 初始化页面配置（创建表并插入默认数据）
python init_pages.py

# 3. （可选）如需更新现有页面配置
python update_learning_pages.py
```

### 5. 运行系统

```bash
# 方式 1：直接运行（使用配置的 worker 数量）
python app.py

# 方式 2：使用 uvicorn（单 worker 开发模式）
uvicorn app:app --reload --host 0.0.0.0 --port 8024

# 方式 3：使用 uvicorn（多 worker 生产模式）
uvicorn app:app --host 0.0.0.0 --port 8024 --workers 4
```

系统启动后访问：

- 学生答题入口：http://localhost:8024
- 管理后台登录：http://localhost:8024/admin

默认管理员密码：`admin123`

### 6. 配置 favicon

系统已内置 favicon.ico 文件，访问 `/favicon.ico` 即可显示网站图标。

### 7. 页面管理

访问 **页面管理** 后台：http://localhost:8024/admin/pages

在这里可以：

- 查看所有学习页面配置
- 添加新的学习页面
- 编辑页面配置（名称、图标、颜色等）
- 启用/禁用页面
- 删除页面

## 六、使用说明

### 学生答题流程

1. **访问答题页面**
   - 首页：http://localhost:8024
   - 选择对应的学习页面（Python、科学、信息技术等）

2. **输入身份信息**
   - 输入姓名和班级
   - 系统自动验证是否为已注册用户
   - 未注册用户无法继续答题

3. **开始答题**
   - 关卡式答题界面
   - 实时显示答题进度
   - 完成后自动提交数据

4. **查看结果**
   - 答题完成后显示得分和正确率
   - 可查看详细答题记录

### 管理员功能

#### 1. 登录管理后台

- 访问：http://localhost:8024/admin
- 输入管理员密码（默认：`admin123`）

#### 2. 页面管理

- 查看所有学习页面配置
- 添加/编辑/删除页面
- 启用/禁用页面
- 调整页面显示顺序

#### 3. 用户管理

- 添加单个用户
- 批量导入用户（支持 CSV/Excel）
- 搜索和筛选用户
- 查看用户答题记录

#### 4. 数据分析

- **仪表板统计**：整体数据概览
- **实时数据大屏**：动态数据可视化
- **排行榜**：
  - Top 10 快速排行
  - 完整排行榜（支持分页、搜索、班级筛选）
- **题目统计**：分析每道题的正确率，找出难点
- **下载答题数据**：导出 CSV 格式

#### 5. AI 智能分析

- 基于所有答题数据生成分析报告
- 自动识别学习薄弱点
- 生成个性化学习建议
- 支持多学科独立分析

## 七、添加新学习页面

系统采用数据库驱动的页面管理方式，添加新的学习页面非常简单。以添加"数学闯关学习"页面为例：

### 步骤 1：创建答题记录表模型

在 `src/database.py` 中添加新的数据模型：

```python
class MathRecord(Base):
    __tablename__ = 'math_records'

    id = Column(Integer, primary_key=True, index=True)
    user_id = Column(Integer, ForeignKey('users.id'), nullable=False)
    user_name = Column(String(100), nullable=False)

    # 答题数据
    total_score = Column(Integer, comment='总分')
    correct_count = Column(Integer, comment='答对题目数')
    total_questions = Column(Integer, comment='总题目数')
    accuracy_rate = Column(Float, comment='正确率')

    # 详细答题记录（JSON格式存储）
    answers = Column(Text, comment='答题记录JSON')

    # 完成时间
    completed_at = Column(DateTime, default=datetime.now)

    def get_answers_data(self):
        """获取答题记录的字典格式"""
        if self.answers:
            return json.loads(self.answers)
        return None

    def set_answers_data(self, data):
        """设置答题记录"""
        self.answers = json.dumps(data, ensure_ascii=False)
```

### 步骤 2：注册数据模型

在 `src/main.py` 的 `get_record_model()` 函数中注册：

```python
def get_record_model(table_name: str):
    """根据记录表名返回对应的ORM模型"""
    models = {
        'python_records': PythonRecord,
        'kexue_records': KexueRecord,
        'math_records': MathRecord,  # 新增
    }
    return models.get(table_name)
```

### 步骤 3：创建前端答题页面

在 `templates/` 目录创建 `math.html`（参考 `templates/python.html`）

### 步骤 4：添加后端路由

在 `src/main.py` 中添加以下路由：

```python
# ==================== 数学闯关学习相关路由 ====================

# 答题页面路由
@app.get("/math", response_class=HTMLResponse)
async def math_page(request: Request):
    return templates.TemplateResponse("math.html", {"request": request})

# 提交答题数据
@app.post("/api/submit-math-answers")
async def submit_math_answers(request: Request, db: Session = Depends(get_db)):
    # 参考 submit_python_answers 的实现
    pass

# 数据大屏
@app.get("/admin/dashboard/math", response_class=HTMLResponse)
async def math_dashboard(request: Request, db: Session = Depends(get_db)):
    await verify_admin_cookie(request)
    # 参考 python_dashboard 的实现
    return templates.TemplateResponse("math_dashboard.html", {...})

# AI 分析
@app.get("/admin/ai-analysis/math", response_class=HTMLResponse)
async def ai_analysis_math_page(request: Request, db: Session = Depends(get_db)):
    await verify_admin_cookie(request)
    return templates.TemplateResponse("ai_analysis.html", {
        "request": request,
        "page_type": "math",
        "page_title": "数学闯关学习 - AI分析报告"
    })

@app.post("/api/ai-analyze/math")
async def ai_analyze_math(request: Request, db: Session = Depends(get_db)):
    await verify_admin_cookie(request)
    # 参考 ai_analyze_python 的实现
    pass
```

### 步骤 5：在后台添加页面配置

1. 访问页面管理：http://localhost:8024/admin/pages

2. 点击"添加页面"按钮

3. 填写以下信息：

   | 字段       | 值                 | 说明              |
   | ---------- | ------------------ | ----------------- |
   | 页面ID     | `math`             | 唯一标识          |
   | 页面名称   | `数学闯关学习`     | 显示名称          |
   | 页面描述   | `小学数学答题页面` | 可选              |
   | HTML文件名 | `math.html`        | 模板文件          |
   | URL路径    | `/math`            | 访问路径          |
   | 路由前缀   | `math`             | 用于生成其他路由  |
   | 记录表名   | `math_records`     | 数据表            |
   | 图标       | `fa-calculator`    | Font Awesome 图标 |
   | 颜色       | `blue`             | Tailwind 颜色     |
   | 总题目数   | `20`               | 题目数量          |

4. 点击"添加"完成

### 完成！

新页面会自动出现在：

- 仪表板页面列表
- 所有功能按钮（数据大屏、排行榜、下载、AI分析）
- 学生可以访问 /math 开始答题

所有 URL 自动生成：

- 答题页面：`/math`
- 数据大屏：`/admin/dashboard/math`
- 排行榜：`/admin/leaderboard/all/math`
- 下载数据：`/admin/download/records?table=math_records`
- AI 分析：`/admin/ai-analysis/math`

## 常见问题

### 1. 数据库连接失败

- 确保 PostgreSQL 服务正在运行
- 检查 `src/config.py` 中的数据库连接字符串
- 确认数据库已创建：`createdb py_datanest`

### 2. AI 分析功能不可用

- 检查网络连接
- 确认 `src/config.py` 中已配置 DeepSeek API Key
- 验证 API 配额是否充足

### 3. 页面无法访问

- 确认页面已在后台启用
- 检查模板文件是否存在于 `templates/` 目录
- 查看浏览器控制台是否有错误

### 4. 数据导出失败

- 确认数据库表中有数据
- 检查文件写入权限

## 开发路线图

- [ ] 支持更多文件格式导入（JSON、TXT）
- [ ] 增加数据备份和恢复功能
- [ ] 支持自定义 AI 分析提示词模板
- [ ] 添加学生端个人成绩查询
- [ ] 支持多管理员权限分级
- [ ] 增加答题历史版本管理
- [ ] 支持移动端原生应用

## 许可证

MIT License

---

**项目维护者**: py_datanest 开发团队
**最后更新**: 2026-01-08