# 知了数学题库系统

一个基于 Flask 开发的数学题库管理系统，支持题目的增删改查、审核、知识点管理、PDF导出等功能。

## 项目概述

本系统是一个完整的数学题库管理平台，提供了题目管理、知识点层级管理、题目审核、AI辅助优化、PDF导出等核心功能。系统采用 Flask 作为后端框架，使用 MySQL 数据库存储数据，前端使用 Tailwind CSS 构建现代化界面。

## 功能特性

### 1. 题目管理
- **题目列表展示**：按知识点分类展示题目，支持统计信息（总数、合格数、不合格数、待审核数）
- **题目详情查看**：查看题目的完整信息，包括题干、选项、答案、解析等
- **题目编辑**：支持编辑题目的所有字段
- **题目添加**：通过表单添加新题目，支持单个录入和批量导入
- **题目删除**：支持删除题目（需确认）
- **题目搜索**：支持按题目ID搜索
- **年级选项**：其他题目（未关联知识点）支持选择年级（小学/初中/高中）

### 2. 知识点管理
- **层级结构**：支持章（Chapter）、节（Section）、小节（Subsection）三级知识点结构
- **知识点目录**：左侧导航栏展示知识点层级树
- **知识点统计**：每个知识点显示题目数量、合格率等统计信息
- **知识点编辑**：支持编辑知识点名称
- **知识点添加**：支持添加新的节或小节
- **学段筛选**：目前只显示初中知识点（小学和高中已注释）

### 3. 题目审核
- **审核模式**：专门的审核页面，显示所有未审核的题目
- **审核操作**：支持标记题目为"合格"或"不合格"，并填写审核原因
- **审核统计**：按知识点统计未审核题目数量
- **同步机制**：审核通过（"合格"）的题目会自动同步到正式的 `questions` 表

### 4. AI辅助功能
- **难度评分**：使用AI对题目进行难度评分，输出维度分数和难度等级（筑基/提分/培优）
- **查重检测**：支持题目查重功能，检测重复题目

### 5. PDF导出
- **远程导出**：调用远程API接口生成PDF
- **批量导出**：支持批量导出多个题目

### 6. 教材管理
- **教材节点**：支持按教材目录节点管理题目
- **节点统计**：显示每个教材节点的题目统计信息

## 技术架构

### 后端技术
- **框架**：Flask 3.x
- **数据库**：MySQL（使用 mysql-connector-python）
- **Web服务器**：Waitress（生产环境）

### 前端技术
- **CSS框架**：Tailwind CSS（CDN）
- **数学公式渲染**：KaTeX
- **图标库**：Remix Icon
- **模板引擎**：Jinja2

### AI集成
- **AI接口**：支持 OpenAI 兼容接口
- **查重接口**：`http://47.77.199.85:8888`

## 安装与配置

### 1. 环境要求
- Python 3.7+
- MySQL 数据库

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 配置文件

复制 `config.env.example` 为 `config.env`，并修改配置：

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

编辑 `config.env` 文件，配置以下内容：

```env
# 数据库配置
DB_HOST=your_db_host
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password

# Web服务配置
WEB_HOST=127.0.0.1
WEB_PORT=5000

# AI配置（可选）
AI_API_KEY=your_api_key
AI_BASE_URL=https://api.openai.com/v1
AI_MODEL_NAME=gpt-5.2

# PDF导出配置
PDF_API_URL=https://teaching-content.chunsunqiuzhu.com/api/questions/pdf
PDF_STUDENT_ID=44

# 查重接口配置
DUPLICATE_CHECK_API_URL=http://47.77.199.85:8888
```

### 4. 数据库结构

系统使用以下主要数据表：
- `questions_tem`：题目表（临时表，用于审核）
- `questions`：题目表（正式表，只包含审核通过的题目）
- `knowledge_points_copy1`：知识点表
- `textbook_catalog_nodes`：教材目录节点表

## 使用方法

### 1. 启动服务

**开发模式**：
```bash
python app.py
```

**生产模式**（使用 Waitress）：
```bash
python run_web.py
```

### 2. 访问系统

在浏览器中访问：`http://localhost:5000`

### 3. 主要功能使用

#### 查看题目列表
- 访问首页 `/`，查看按知识点分类的题目卡片
- 点击知识点卡片，查看该知识点下的所有题目

#### 审核题目
- 访问 `/audit_questions`，查看所有未审核的题目
- 点击题目，进入详情页进行审核
- 填写审核原因，标记为"合格"或"不合格"
- **注意**：只有审核通过（"合格"）的题目才会同步到正式的 `questions` 表

#### 添加题目
- 访问 `/question_management`，点击"录入题目"按钮
- 填写题目信息（题干、选项、答案等）
- 选择知识点或教材节点
- 如果是"其他题目"（未关联知识点），必须选择年级
- 提交保存

#### 编辑题目
- 在题目列表或详情页点击"编辑"按钮
- 修改题目信息
- 保存更改

#### 搜索题目
- 访问 `/search`，按题目ID搜索
- 或访问 `/search_id`，直接输入题目ID

#### 导出PDF
- 在题目详情页点击"导出PDF"按钮
- 选择本地导出或远程导出
- 下载生成的PDF文件

#### 管理知识点
- 访问 `/kp_management`，管理知识点
- 点击"增加"按钮添加知识点
- 点击知识点旁的编辑图标，修改知识点名称

## API接口

### 题目相关
- `POST /audit`：审核题目（审核通过会自动同步到 questions 表）
- `POST /create_question`：创建题目（保存到 questions_tem 表）
- `POST /update_question`：更新题目
- `POST /api/delete_question/<question_code>`：删除题目

### AI相关
- `POST /api/score`：难度评分
- `POST /api/check_duplicate`：查重检测（代理接口）

### 知识点相关
- `POST /add_kp_node`：添加知识点节点
- `POST /update_kp_node`：更新知识点节点

### PDF导出
- `GET /export_pdf_remote/<question_code>`：远程导出PDF

## 数据同步机制

### questions_tem → questions 同步规则

1. **未审核题目**（`audit_reason` 为 NULL 或空）：
   - 只存在于 `questions_tem` 表
   - **不会**同步到 `questions` 表

2. **审核通过**（`audit_reason = "合格"`）：
   - 更新 `questions_tem` 表的审核状态
   - **自动同步**到 `questions` 表（INSERT 或 UPDATE）

3. **审核不通过**（`audit_reason = "不合格"`）：
   - 更新 `questions_tem` 表的审核状态
   - **不会**同步到 `questions` 表

**总结**：只有审核通过（"合格"）的题目才会同步到正式的 `questions` 表。

## 项目结构

```
知了数学题库/
├── app.py                 # 主应用文件
├── run_web.py            # Web服务器启动文件
├── requirements.txt      # Python依赖
├── config.env            # 配置文件（需自行创建，不提交到Git）
├── config.env.example    # 配置示例文件
├── README.md             # 项目说明文档
├── .gitignore            # Git忽略文件
├── templates/            # HTML模板目录
│   ├── layout.html       # 基础布局模板
│   ├── index.html        # 首页模板
│   ├── questions.html    # 题目列表模板
│   ├── detail.html       # 题目详情模板
│   ├── edit.html         # 题目编辑模板
│   ├── question_management.html # 题目管理模板
│   ├── kp_management.html # 知识点管理模板
│   └── ...
├── static/               # 静态文件目录
└── 知了数学题库/         # 数据文件目录
    └── tree_new.json     # 知识点树结构数据
```

## 常见问题

### 1. 数据库连接失败
- 检查 `config.env` 中的数据库配置是否正确
- 确认数据库服务是否运行
- 检查网络连接和防火墙设置

### 2. PDF导出失败
- 检查 `PDF_API_URL` 配置是否正确，网络是否可达

### 3. AI功能不可用
- 检查 `AI_API_KEY` 是否配置
- 确认 API 接口地址和模型名称正确
- 检查网络连接

### 4. 知识点不显示
- 确认数据库中有知识点数据
- 检查知识点表的 `grade` 字段（目前只显示"初中"）

### 5. Git推送失败
- 确认已安装 Git
- 检查 Git 凭据配置
- 确认远程仓库地址正确

## 开发说明

### 代码规范
- 使用 Python 类型提示
- 函数和类添加文档字符串
- 错误处理使用 try-except 块
- 数据库连接使用连接池管理

### 扩展功能
- 添加新的路由：在 `app.py` 中使用 `@app.route()` 装饰器
- 添加新的模板：在 `templates/` 目录下创建HTML文件
- 修改样式：编辑模板文件中的 Tailwind CSS 类

## 更新日志

### 2024-12-XX（最新）
- **知识点管理页面优化**：
  - 在知识点管理页面中，将小学和高中部分注释掉
  - 知识点管理页面现在只展示初中（grade='初中'）的知识点
  - 修改了知识点查询、下拉选择列表和题目统计查询，都添加了 `WHERE grade = '初中'` 条件
  - 注意：数据库中的 grade 字段存储的是中文（"小学"、"初中"、"高中"），不是数字
- **更新查重接口地址**：
  - 将查重检测接口地址从 `http://192.168.124.42:8888` 更新为 `http://47.77.199.85:8888`
  - 更新了 `/api/check_duplicate` 和 `/api/confirm_repeat` 两个接口的代理地址
- **添加选项预览功能**：
  - 在"题目管理"的所有录入页面（单个录入和批量导入）中添加了选项预览框（JSON格式）
  - 选项预览框支持双向同步：修改各个选项输入框会自动更新JSON预览，修改JSON预览会自动同步到各个选项输入框
  - 选项预览框支持直接编辑JSON格式，方便批量修改选项内容
  - 选项预览框仅在选择题时显示
- **添加年级选项功能（必填项）**：
  - 在"题目管理-其他题目"的两个录入页面（单个录入和批量导入）中添加了年级选择字段
  - 年级选项为枚举值：小学（传1）、初中（传2）、高中（传3）
  - 年级字段仅在"其他题目"（未关联知识点）时显示，且为必填项
  - 前端添加了必填验证：提交时会检查年级是否已选择
  - 后端接口 `/create_question` 已支持接收和处理 `grade` 参数，并验证年级值的有效性（1、2、3）
  - 后端添加了业务规则验证：如果是"其他题目"（没有kp_code），则grade字段必须存在
- **优化题干显示逻辑**：
  - 改进了题干容器的样式，添加了背景色和边框，使题干更易读
  - 优化了数学公式的自动渲染逻辑，确保题干中的数学公式能够正确显示
  - 改进了页面加载时的数学公式渲染处理，避免重复渲染
- **删除优化题目功能**：
  - 移除了"优化题目"按钮及其相关弹窗
  - 删除了题干优化相关的JavaScript代码（openOptimizeModal、closeOptimizeModal、replaceStem等函数）
  - 简化了题目详情页面的操作按钮，提升了用户体验

## Git 操作说明

### 首次提交到远程仓库

```bash
# 1. 初始化 Git 仓库（如果还没有）
git init

# 2. 添加远程仓库
git remote add origin https://git.yunzhixue.cn/wlh/wlh.git

# 3. 添加所有文件
git add .

# 4. 提交代码
git commit -m "初始提交：知了数学题库系统"

# 5. 设置主分支
git branch -M main

# 6. 推送到远程仓库
git push -u origin main
```

### 后续更新

```bash
# 1. 添加修改的文件
git add .

# 2. 提交更改
git commit -m "更新说明"

# 3. 推送到远程仓库
git push
```

## 许可证

本项目为内部使用项目，未经授权不得外传。

## 联系方式

如有问题或建议，请联系项目维护者。
