# quickform

**Repository Path**: yldj-it/quickform

## Basic Information

- **Project Name**: quickform
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-03
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QuickForm 教师版 2.0（社区优化版）

## 软件说明

QuickForm 是温州科技高级中学 AI 科创中心联合温州大学开发的智能表单管理服务，是一个为 AI 赋能教学而生的开源教学辅助系统。教师借助 AI 大模型生成交互网页后，可以借助 QuickForm 提供的 API 接口回收数据。教师通过对学习数据的智能分析，走向基于数据的精准教学。

本项目基于 [QuickForm 教师版 2.0（wstlab/quickform）](https://gitee.com/wstlab/quickform) 进行了针对性优化，聚焦 **并发安全**、**异步分析** 和 **生产环境稳定性**。

> **关于 PR**：原项目经过多个版本迭代后合并，提交历史较复杂，无法直接发起有意义的 PR。因此以独立仓库形式维护优化版本，定期同步上游更新。

## 本次优化内容

### 一、并发与性能优化

| 项目 | 改动 |
|------|------|
| SQLite WAL 模式 | 启用 `journal_mode=WAL`，支持并发读写，避免锁表 |
| 连接池 | 添加 `pool_size=10, max_overflow=20`，避免并发请求时连接耗尽 |
| Web 服务器 | `app.run()` → Gunicorn 4 Worker，支持真实并发 |
| 分页查询 | GET `/api/<task_id>` 新增 `page` / `per_page` 参数，默认 50 条/页，上限 200 |
| 启动脚本 | `run.sh` 增加端口释放等待逻辑，避免重启时端口冲突 |

### 二、安全与稳定性修复

| 项目 | 改动 |
|------|------|
| SECRET_KEY | 随机生成（`secrets.token_hex(32)`），不再硬编码 |
| 开放重定向 | 登录 `next` 参数校验，防止 `url_for` 注入 |
| system_init 二次确认 | 必须传入 `confirm=RESET_ALL_DATA` + 当前密码验证 |
| traceback import | 修复 AI 模型失败时未导入 traceback 的 crash |
| 重复 import 清理 | 清理 15 处重复的 `import json/math/traceback` |

### 三、异步分析 + 进度条（新功能）

原来的"开始分析"是同步阻塞的——用户点了按钮要等到 AI 返回才能看到结果，长时间无响应容易超时。

**改动：**

```
点击"开始分析" → 立即返回（显示进度条）→ 后台线程执行 AI 分析 → 前端轮询进度 → 完成后展示报告
```

**涉及文件：**

| 文件 | 改动 |
|------|------|
| `app.py` - Task 模型 | 新增 `analysis_status`、`analysis_progress`、`analysis_message` 三个字段 |
| `app.py` - DB 迁移 | 启动时自动 `ALTER TABLE` 添加新列 |
| `app.py` - `/start_analysis/<task_id>` | POST 接口，启动后台线程，立即返回 JSON |
| `app.py` - `/analysis_status/<task_id>` | GET 接口，返回 `{status, progress, message}` |
| `templates/smart_analyze.html` | 前端轮询 + 进度条 UI |

### 四、AI 模型调用架构重构

原代码中 `call_ai_model`（~240 行）和 `_call_ai_model_for_html`（~70 行）存在大量重复逻辑，且 `_call_ai_model_for_html` 仅支持 3 个模型（DeepSeek、豆包、通义千问），使用其他模型生成大屏时会报错。

**重构方案：**

| 组件 | 说明 |
|------|------|
| `MODEL_REGISTRY` | 模型配置映射表，集中管理 7 个模型的 API URL、默认模型名、超时时间 |
| `_get_model_config()` | 从数据库配置中获取指定模型的 API Key / URL |
| `_build_api_request()` | 统一构建 API 请求（URL、headers、body、timeout） |
| `_parse_ai_response()` | 统一解析 AI 响应，兼容 OpenAI 格式和通义千问格式 |
| `call_ai_model()` | 简化为 ~20 行，支持 `max_tokens`、`temperature`、`system_prompt` 参数 |
| `_call_ai_model_for_html()` | 简化为 ~8 行，复用 `call_ai_model`，自动支持全部 7 个模型 |

**优化效果：**

- 代码量：从 ~310 行 → ~80 行（减少约 75%）
- 模型支持：`_call_ai_model_for_html` 从仅支持 3 个模型 → 全部 7 个模型
- 维护成本：新增模型只需在 `MODEL_REGISTRY` 添加一条记录

### 五、前端资源本地化

将大屏生成页面中引用的第三方 CDN（`cdn.jsdelivr.net`）替换为本地资源，解决国内访问慢或不可用的问题。

| 资源 | 原地址 | 现地址 |
|------|--------|--------|
| Bootstrap CSS | `cdn.jsdelivr.net/npm/bootstrap@5.3.3/...` | `/static/vendor/bootstrap/css/bootstrap.min.css` |
| ECharts JS | `cdn.jsdelivr.net/npm/echarts@5.5.0/...` | `/static/vendor/echarts/echarts.min.js` |

涉及位置：AI 大屏提示词（`_build_ai_dashboard_prompt`）和静态大屏模板（`_render_stable_dashboard_html`）。

## 环境要求

- Python 3.11+
- pip（或 venv）
- 内存建议 2GB+（Gunicorn 4 Worker 各约 60MB）

## 快速启动

### Linux / macOS

```bash
# 1. 克隆仓库
git clone https://gitee.com/yldj-it/quickform.git
cd quickform

# 2. 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 3. 安装依赖
pip install -r requirements.txt

# 4. 启动
chmod +x run.sh
./run.sh
```

服务默认监听 `0.0.0.0:5001`。修改端口请编辑 `run.sh`。

### Windows 免安装分发（无需 Python）

适用于未安装 Python 的 Windows 用户。开发者在 Windows 上运行打包脚本，生成一个**解压即用**的分发包。

**开发者操作（生成分发包）：**

```bat
# 在 Windows 上克隆仓库后，双击运行
build_windows.bat
```

脚本会自动完成：
1. 从**华为云镜像**下载嵌入式 Python 3.12（~10MB）
2. 配置 pip 使用**清华 TUNA 镜像源**
3. 安装所有依赖（自动跳过 Linux 专用的 gunicorn）
4. 复制项目文件，生成用户端启动脚本
5. 打包成 `QuickForm-Windows-x64.zip`

**终端用户操作：**

```
收到 zip → 解压 → 双击 start.bat → 浏览器自动打开
```

全程无需安装 Python、无需配置环境。首次运行会自动安装依赖。

**分发包目录结构：**

```
QuickForm-Windows-x64/
├── python/              # 嵌入式 Python（用户无需关心）
│   ├── python.exe
│   └── pip/pip.ini      # 已配置国内镜像源
├── app.py               # 主应用
├── requirements.txt     # 依赖列表
├── start.bat            # 一键启动（双击即可）
├── templates/           # 页面模板
├── static/              # 静态资源
│   ├── uploads/         # 上传目录
│   └── reports/         # 报告目录
└── data/                # 数据目录
```

> **国内镜像源配置：**
> - Python 下载：`mirrors.huaweicloud.com`（华为云）
> - pip 包安装：`pypi.tuna.tsinghua.edu.cn`（清华 TUNA）

## 内置管理信息

| 项目 | 值 |
|------|----|
| 用户名 | `admin` |
| 密码 | `quickform` |

> 首次启动后请在「个人设置」中修改密码。

## 密码重置

如果忘记密码，可使用以下脚本重置：

### Windows

```bat
reset_password.bat
```

双击运行，按提示确认即可重置 `admin` 用户密码为 `quickform`。

### Linux / macOS

```bash
bash reset_password.sh
```

### 自定义参数

```bash
# 重置指定用户的密码
python reset_password.py 用户名 新密码
```

## API 接口文档

### 1. 回收数据（学生提交）

**POST** `/api/<task_id>`

学生提交表单数据，支持 JSON 和 Form 格式。

```bash
# JSON 格式
curl -X POST http://localhost:5001/api/abc123 \
  -H "Content-Type: application/json" \
  -d '{"姓名": "张三", "答案": "床前明月光"}'

# Form 格式
curl -X POST http://localhost:5001/api/abc123 \
  -d "姓名=张三&答案=床前明月光"
```

**响应：**
```json
{"message": "提交成功"}
```

### 2. 查询已有数据

**GET** `/api/<task_id>?page=1&per_page=50`

```bash
curl http://localhost:5001/api/abc123

# 分页查询
curl "http://localhost:5001/api/abc123?page=2&per_page=20"
```

**响应：**
```json
{
  "task_id": "abc123",
  "task_title": "古诗词名句填空",
  "total_submissions": 157,
  "page": 1,
  "per_page": 50,
  "total_pages": 4,
  "submissions": [
    {
      "id": 1,
      "data": {"姓名": "张三", "答案": "床前明月光"},
      "submitted_at": "2026-05-03 14:30:00"
    }
  ]
}
```

### 3. 导出数据

| 格式 | 接口 |
|------|------|
| CSV | `GET /export/<task_id>`（需登录） |
| JSON | `GET /export_json/<task_id>`（需登录） |

### 4. 系统初始化（重置）

**POST** `/api/system/init`

```bash
curl -X POST http://localhost:5001/api/system/init \
  -H "Content-Type: application/json" \
  -d '{"confirm": "RESET_ALL_DATA", "password": "quickform"}'
```

> ⚠️ 需要登录态 + 二次确认 + 密码验证。会清空所有数据和配置。

### 5. AI 密钥测试

**POST** `/test_api_key`（需登录）

```bash
curl -X POST http://localhost:5001/test_api_key \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek", "api_key": "sk-xxx"}'
```

## 接入大模型的方法

QuickForm 的核心价值是 **让 AI 大模型生成的交互网页有地方回收和分析数据**。以下是接入方式：

### 场景一：AI 生成表单网页 → 自动对接 QuickForm

教师在 AI 对话中描述需求（如"帮我出一份古诗词填空练习"），AI 生成一个包含 `<form>` 的 HTML 文件。教师将该 HTML 上传到 QuickForm，系统会自动将表单的 `action` 地址替换为 QuickForm 的回收接口。

**上传方式：**
1. 登录 QuickForm → 创建任务
2. 上传 AI 生成的 HTML/ZIP 文件
3. 系统自动替换 API 地址
4. 分享生成的链接或二维码给学生

### 场景二：手动在 AI 提示词中嵌入 API 地址

在跟 AI 对话时，可以把 QuickForm 的 API 地址告诉它，让它生成的 HTML 自带正确的提交地址。

**提示词模板：**

```
请生成一个交互式练习网页，要求：
1. 表单包含：姓名（text）、答案（textarea）
2. 提交方式：POST
3. 提交地址：http://你的服务器IP:5001/api/你的task_id
4. 提交格式：JSON，Content-Type: application/json
5. 提交成功后显示"提交成功"提示
```

### 场景三：在第三方大模型中调用 QuickForm API（使用建议）

> ⚠️ 以下为使用建议，QuickForm 本身不内置 Function Calling 集成。需用户自行在第三方大模型平台配置。

对于支持 Function Calling 的大模型（如 ChatGPT、Claude），可以将 QuickForm 的 HTTP API 注册为工具函数，让 AI 自动读取和分析学生数据。

**工具函数定义示例（ChatGPT Function Calling）：**

```json
{
  "name": "get_student_submissions",
  "description": "获取学生的表单提交数据",
  "parameters": {
    "type": "object",
    "properties": {
      "task_id": {
        "type": "string",
        "description": "任务ID，如 abc123"
      },
      "page": {
        "type": "integer",
        "description": "页码，从1开始"
      }
    },
    "required": ["task_id"]
  }
}
```

对应的实际调用：

```bash
GET http://localhost:5001/api/{task_id}?page={page}
```

### 场景四：结合 AI 智能分析

QuickForm 内置了 AI 分析功能。配置好 AI 模型后（支持 DeepSeek、豆包、通义千问、智谱、Ollama 等），点击「智能分析」：

1. 系统将学生的提交数据整理为结构化文本
2. 调用配置的 AI 模型进行分析
3. 生成分析报告（支持 Markdown 格式）
4. 可自定义分析提示词

**支持的 AI 模型：**

| 模型 | api_url | 备注 |
|------|---------|------|
| DeepSeek | https://api.deepseek.com | 需要 API Key |
| 豆包（Doubao） | https://ark.cn-beijing.volces.com | 需要 API Key |
| 通义千问（Qwen） | https://dashscope.aliyuncs.com | 需要 API Key |
| 智谱（GLM） | https://open.bigmodel.cn | 需要 API Key |
| SiliconFlow | https://api.siliconflow.cn | 需要 API Key，模型名可自定义 |
| Ollama（本地） | http://localhost:11434 | 无需 Key，需本地运行 Ollama |
| 自定义模型 | 用户配置 | 兼容 OpenAI API 格式的任意模型 |

## 目录结构

```
quickform/
├── app.py                  # 主应用（Flask + SQLAlchemy）
├── run.sh                  # 启动脚本（Gunicorn 4 Worker）
├── build_windows.bat       # Windows 一键打包脚本（嵌入式 Python + 国内镜像）
├── start.bat               # Windows 启动脚本（已有的系统 Python 版）
├── requirements.txt        # Python 依赖
├── quickform.db            # SQLite 数据库（自动创建）
├── templates/              # Jinja2 模板
│   ├── smart_analyze.html  # 智能分析页面（含异步进度条）
│   ├── task_data.html      # 数据查看页面
│   └── ...
├── static/
│   └── vendor/             # 第三方前端资源（本地化）
│       ├── bootstrap/      # Bootstrap 5 CSS/JS
│       └── echarts/        # ECharts 图表库
├── uploads/                # 用户上传的文件
└── gunicorn.log            # 运行日志
```

## 本次修改的 Git 提交记录

| Commit | 说明 |
|--------|------|
| `f5e78aa` | Git 初始化 + .gitignore |
| `a8d3c27` | feat: 并发优化（WAL + Gunicorn + 分页） |
| `115db54` | fix: 安全与稳定性修复（SECRET_KEY + 重定向 + traceback） |
| `6a7e45c` | fix: 清理重复 import |
| `2ac15fd` | merge: 合并到 main |
| `523f378` | feat: 异步分析 + 进度条 |
| `e478720` | fix: run.sh 端口释放等待 |
| `latest` | refactor: AI 模型调用架构重构（MODEL_REGISTRY + 统一请求/响应处理） |
| `latest` | fix: 前端资源本地化（Bootstrap/ECharts 改用本地 vendor） |
| `546b6b8` | feat: 新增 Windows 一键打包脚本（嵌入式 Python + 国内镜像源） |

## 上游项目

- 原始仓库：https://gitee.com/wstlab/quickform
- 本优化版：https://gitee.com/yldj-it/quickform
- 分支策略：`main`（稳定版）+ `feat/*`（功能分支）

## License

遵循上游项目的开源协议。