📚 泡芙云开发文档

完整的开发指南与使用说明书

版本：v1.0.0 | 更新日期：2026年5月

一、项目背景

1.1 开发初衷

泡芙云（PicForm）的诞生源于一个真实的教育场景需求。在日常教学中，收集和管理学生的作业图片是一件既繁琐又重要的事情。无论是让学生拍摄解题过程、记录实验结果，还是提交手工作品，传统的微信群文件、邮箱附件等方式总是显得力不从心——文件散落各处、难以整理统计、无法统一查看。

随着人工智能技术的飞速发展，我开始探索如何将大模型（如 ChatGPT、Claude）与教育教学深度融合。在实践中我发现，让 AI 生成交互式网页来收集学生反馈是一个绝佳的方案，但现有的图片托管服务要么过于复杂，要么无法满足教育场景的特殊需求。

1.2 项目定位

泡芙云是一款专为开发者和教育工作者设计的智能数据管理平台，提供两大核心功能：

图片存储API：上传并存储图片文件，自动生成访问链接，支持多种图片格式
数据存储API：存储JSON数据，类似QuickForm，返回标准API接口供查询

核心价值在于：

降低技术门槛：让不懂编程的用户也能轻松创建任务，只需一个task_code即可分享
拥抱AI时代：提供标准化的提示语和接口，让大模型生成的页面能够无缝对接
灵活资源管理：支持申请加额，超级会员享受无限额使用
开源共享精神：代码完全开源，欢迎更多开发者参与改进

1.3 目标用户

中小学教师：收集学生作业、作品、活动照片
培训讲师：收集学员作品、反馈数据
活动组织者：收集活动照片、报名材料
开发者：快速搭建图片或数据收集功能原型
AI应用开发者：为大模型生成的网页提供数据存储能力
小程序开发者：为小程序提供轻量级数据存储API服务

二、开发思路

2.1 设计理念

泡芙云的设计遵循"简单、开放、实用"三大原则：

🎯 简单至上

用户无需了解技术细节，只需三步即可开始使用：注册账号 → 创建任务 → 分享 task_code。整个流程设计得尽可能简洁，让非技术用户也能轻松上手。

🔓 开放兼容

提供标准 REST API，支持跨域访问，可以与任何前端框架、任何编程语言无缝对接。特别针对 AI 生成网页场景优化，提供完整的系统提示语模板。

💡 实用优先

每一个功能都来自真实的使用场景。任务数量限制、存储空间管理、图片批量操作等功能，都是根据实际教学需求精心设计的。

2.2 核心功能设计

功能模块	设计说明
任务管理	图片存储任务最多3个，数据存储任务最多3个，超级会员无限制
图片存储	支持PNG/JPG/GIF/WebP格式，单文件最大10MB，存储空间100MB/任务
数据存储	支持任意JSON格式数据，自动解析格式化，存储空间50MB/任务
API调用限制	图片API 200次/任务，数据API 10000次/任务，超级会员无限制
流量限制	图片流量200MB/任务，数据流量50MB/任务，超级会员无限制
数据查询	通过task_code查询所有上传的图片或数据，包含元数据
删除管理	支持单张/单条删除，任务创建者可管理自己任务下的所有数据
AI集成	自动生成系统提示语，让AI生成的网页直接具备数据存储能力
超级会员	后台可设置超级会员，享受无限额使用，无任何限制

2.3 技术选型

项目采用成熟稳定的技术栈，确保可靠性和可维护性：

后端框架：Flask - 轻量级 Python Web 框架，易于学习和扩展
数据库：SQLite - 零配置、单文件存储，适合中小规模应用
认证方案：JWT (JSON Web Token) - 无状态认证，支持分布式部署
前端技术：原生 HTML/CSS/JavaScript - 无框架依赖，兼容性好
API 设计：RESTful 风格 - 标准化接口，易于对接

三、系统架构

3.1 整体架构

┌─────────────────────────────────────────────────────────────┐
│                        前端层                                │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐       │
│  │  首页   │  │任务管理 │  │任务详情 │  │管理后台 │       │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘       │
│       │            │            │            │             │
│       └────────────┴────────────┴────────────┘             │
│                         │                                   │
│                    HTTP/HTTPS                               │
└─────────────────────────┼───────────────────────────────────┘
                          │
┌─────────────────────────┼───────────────────────────────────┐
│                         ▼                                   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                   Flask 应用                         │   │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌────────┐ │   │
│  │  │认证路由 │  │任务路由 │  │图片路由 │  │管理路由│ │   │
│  │  └────┬────┘  └────┬────┘  └────┬────┘  └───┬────┘ │   │
│  │       │            │            │            │       │   │
│  │       └────────────┴────────────┴────────────┘       │   │
│  │                         │                             │   │
│  │  ┌──────────────────────┴────────────────────────┐   │   │
│  │  │              业务逻辑层                        │   │   │
│  │  │  用户管理 │ 任务管理 │ 图片处理 │ 权限控制    │   │   │
│  │  └──────────────────────┬────────────────────────┘   │   │
│  └─────────────────────────┼─────────────────────────────┘   │
│                            │                                 │
│                        数据访问层                            │
└────────────────────────────┼────────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        ▼                    ▼                    ▼
  ┌──────────┐        ┌──────────┐        ┌──────────┐
  │ SQLite   │        │ 文件存储 │        │ 日志系统 │
  │ 数据库   │        │  uploads │        │          │
  └──────────┘        └──────────┘        └──────────┘

3.2 数据库设计

系统包含三个核心数据表：

用户表 (users)

字段	类型	说明
id	INTEGER	主键，自增
username	STRING(50)	用户名，唯一
email	STRING(100)	邮箱，唯一
password_hash	STRING(255)	密码哈希
nickname	STRING(50)	昵称
organization	STRING(100)	单位/组织
role	STRING(20)	角色：user/admin
is_vip	BOOLEAN	是否为超级会员
is_active	BOOLEAN	账号状态
created_at	DATETIME	创建时间

任务表 (tasks)

字段	类型	说明
id	INTEGER	主键，自增
user_id	INTEGER	所属用户ID，外键
task_code	STRING(12)	任务代码，唯一
task_name	STRING(100)	任务名称
task_type	STRING(10)	任务类型：image/data
description	TEXT	任务描述
prompt	TEXT	自定义AI提示语
api_calls	INTEGER	API调用次数
api_traffic	INTEGER	API流量（字节）
created_at	DATETIME	创建时间

图片表 (images)

字段	类型	说明
id	INTEGER	主键，自增
task_id	INTEGER	所属任务ID，外键
filename	STRING(255)	文件名
original_name	STRING(255)	原始文件名
file_path	STRING(500)	存储路径
file_size	INTEGER	文件大小（字节）
mime_type	STRING(50)	MIME类型
uploader_name	STRING(100)	上传者名称
uploader_info	TEXT	上传者附加信息
created_at	DATETIME	上传时间

3.3 目录结构

picpuff/
├── app/                    # 应用核心目录
│   ├── __init__.py        # 应用工厂
│   ├── config.py          # 配置文件
│   ├── models/            # 数据模型
│   │   ├── __init__.py
│   │   ├── user.py        # 用户模型
│   │   ├── task.py        # 任务模型
│   │   └── image.py       # 图片模型
│   ├── routes/            # 路由模块
│   │   ├── __init__.py
│   │   ├── auth.py        # 认证相关
│   │   ├── task.py        # 任务管理
│   │   ├── image.py       # 图片上传
│   │   └── admin.py       # 管理后台
│   └── utils/             # 工具函数
│       ├── __init__.py
│       ├── response.py    # 响应格式化
│       └── token.py       # Token处理
├── static/                # 静态资源
│   ├── css/              # 样式文件
│   ├── js/               # JavaScript
│   └── logo.png          # Logo图片
├── templates/             # 模板文件
│   ├── base.html         # 基础模板
│   ├── index.html        # 首页
│   ├── tasks.html        # 任务管理
│   ├── task_detail.html  # 任务详情
│   ├── settings.html     # 个人设置
│   ├── admin.html        # 管理后台
│   └── docs.html         # 开发文档
├── uploads/              # 上传文件存储
├── instance/             # 数据库文件
├── run.py                # 启动脚本
├── requirements.txt      # 依赖列表
└── README.md             # 项目说明

四、快速开始

4.1 环境要求

Python 3.8 或更高版本
pip 包管理器
（可选）虚拟环境工具

4.2 安装步骤

克隆项目

git clone https://github.com/your-repo/picform.git
cd picform

创建虚拟环境（推荐）

python -m venv venv

# Windows
venv\Scripts\activate

# Linux/Mac
source venv/bin/activate

安装依赖

pip install -r requirements.txt

初始化管理员账号

python init_admin.py

默认管理员账号：admin / admin123

启动服务

python run.py

访问 http://localhost:5000 开始使用

4.3 基本使用流程

注册账号：点击首页右上角"免费使用"按钮，填写注册信息
创建任务：登录后点击"新建任务"，填写任务名称和描述
获取 Task Code：创建成功后，系统自动生成唯一的 task_code
分享使用：将 task_code 分享给学生或嵌入到网页中
查看数据：在任务详情中查看所有上传的图片

五、API 文档

5.1 基础信息

Base URL：http://your-domain.com/api

认证方式：Bearer Token (JWT)

内容类型：application/json

5.2 认证接口

POST /api/auth/register

说明：用户注册

请求参数：

{
    "username": "用户名（至少3个字符）",
    "email": "邮箱地址",
    "password": "密码（至少6个字符）"
}

响应示例：

{
    "success": true,
    "message": "注册成功",
    "data": {
        "user_id": 1,
        "username": "testuser"
    }
}

POST /api/auth/login

说明：用户登录

请求参数：

{
    "username": "用户名",
    "password": "密码"
}

响应示例：

{
    "success": true,
    "message": "登录成功",
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIs...",
        "user": {
            "user_id": 1,
            "username": "testuser",
            "role": "user"
        }
    }
}

5.3 任务接口

POST /api/tasks

说明：创建新任务（需要认证）

请求头：

Authorization: Bearer {token}

请求参数：

{
    "task_name": "任务名称",
    "task_type": "image或data（默认image）",
    "description": "任务描述（可选）",
    "prompt": "自定义AI提示语（可选）"
}

任务类型说明：

image：图片存储任务，支持上传图片文件
data：数据存储任务，支持提交JSON数据

GET /api/tasks

说明：获取当前用户的所有任务（需要认证）

GET /api/tasks/{task_id}

说明：获取任务详情（需要认证）

DELETE /api/tasks/{task_id}

说明：删除任务（需要认证，仅限任务所有者）

5.4 图片接口

POST /api/upload/{task_code}

说明：上传图片到指定任务（无需认证）

请求类型：multipart/form-data

请求参数：

file: 图片文件
uploader_name: 上传者名称（可选）
uploader_info: 上传者附加信息（可选，JSON格式）

响应示例：

{
    "success": true,
    "message": "上传成功",
    "data": {
        "image_id": 1,
        "url": "/uploads/xxx/image.png",
        "thumbnail_url": "/uploads/xxx/thumb_image.png"
    }
}

GET /api/task/{task_code}/images

说明：获取任务下的所有图片（无需认证）

响应示例：

{
    "success": true,
    "data": {
        "task": {
            "task_name": "数学作业",
            "task_code": "abc123"
        },
        "images": [
            {
                "image_id": 1,
                "url": "http://...",
                "uploader_name": "张三",
                "created_at": "2026-05-01 10:00:00"
            }
        ],
        "total": 1
    }
}

DELETE /api/images/{image_id}

说明：删除图片（无需认证）

5.5 数据接口

POST /api/data/{task_code}

说明：提交JSON数据到指定任务（无需认证，仅限数据类型任务）

请求类型：application/json

请求示例：

{
    "name": "张三",
    "score": 95,
    "comment": "完成得很好"
}

响应示例：

{
    "message": "数据提交成功",
    "record_id": 1,
    "data_size": 64,
    "query_url": "/api/task/abc123/data"
}

GET /api/task/{task_code}/data

说明：获取任务下的所有数据记录（无需认证，仅限数据类型任务）

查询参数：

page: 页码（默认1）
per_page: 每页数量（默认20，最大100）

响应示例：

{
    "task_name": "学生成绩收集",
    "task_code": "abc123",
    "total_records": 50,
    "page": 1,
    "per_page": 20,
    "total_pages": 3,
    "records": [
        {
            "id": 1,
            "data_content": "{\"name\":\"张三\",\"score\":95}",
            "data_size": 64,
            "created_at": "2026-05-01 10:00:00"
        }
    ]
}

GET /api/data/{task_code}/{record_id}

说明：获取单条数据记录（无需认证）

DELETE /api/data/{task_code}/{record_id}

说明：删除数据记录（需要认证，仅限任务所有者）

5.6 资源限制说明

限制项	图片任务	数据任务	超级会员
任务数量	3个	3个	无限制
存储空间	100MB/任务	50MB/任务	无限制
API调用次数	200次/任务	10000次/任务	无限制
API流量	200MB/任务	50MB/任务	无限制

提示：普通用户可以通过申请加额来获得更多资源，管理员可以在后台设置用户为超级会员。

六、前端集成

6.1 原生 JavaScript 示例

// 上传图片
async function uploadImage(taskCode, file) {
    const formData = new FormData();
    formData.append('file', file);
    formData.append('uploader_name', '学生姓名');
    
    const response = await fetch(
        `http://your-server.com/api/upload/${taskCode}`,
        {
            method: 'POST',
            body: formData
        }
    );
    return response.json();
}

// 提交数据
async function submitData(taskCode, data) {
    const response = await fetch(
        `http://your-server.com/api/data/${taskCode}`,
        {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(data)
        }
    );
    return response.json();
}

// 获取图片列表
async function getImages(taskCode) {
    const response = await fetch(
        `http://your-server.com/api/task/${taskCode}/images`
    );
    return response.json();
}

// 获取数据列表
async function getDataList(taskCode, page = 1) {
    const response = await fetch(
        `http://your-server.com/api/task/${taskCode}/data?page=${page}`
    );
    return response.json();
}
    );
    return response.json();
}

6.2 HTML 表单上传示例

<form id="uploadForm">
    <input type="file" name="file" accept="image/*" required>
    <input type="text" name="uploader_name" placeholder="您的姓名">
    <button type="submit">上传</button>
</form>

<script>
document.getElementById('uploadForm').addEventListener('submit', async (e) => {
    e.preventDefault();
    const formData = new FormData(e.target);
    
    const response = await fetch(
        'http://your-server.com/api/upload/YOUR_TASK_CODE',
        { method: 'POST', body: formData }
    );
    
    const result = await response.json();
    if (result.success) {
        alert('上传成功！');
    }
});
</script>

七、AI 集成指南

7.1 系统提示语模板

将以下提示语提供给 ChatGPT、Claude 等大模型，即可生成支持图片上传的交互页面：

你是一个专业的网页开发者。请帮我创建一个图片上传网页，要求如下：

## 功能需求
1. 页面标题和说明文字
2. 图片上传表单（支持拖拽上传）
3. 上传者姓名输入框
4. 上传进度显示
5. 上传成功/失败提示

## API 接口信息
- 上传接口：POST http://your-server.com/api/upload/{task_code}
- 查询接口：GET http://your-server.com/api/task/{task_code}/images
- 删除接口：DELETE http://your-server.com/api/images/{image_id}

## 上传参数
- file: 图片文件（必需）
- uploader_name: 上传者姓名（可选）

## 技术要求
- 使用原生 HTML/CSS/JavaScript
- 响应式设计，支持移动端
- 美观的 UI 设计
- 完善的错误处理

请生成完整的单页 HTML 代码。

7.2 使用场景示例

场景一：学生作业提交

让 AI 生成一个作业提交页面，学生可以上传解题过程照片，并填写姓名、学号等信息。

场景二：活动照片墙

让 AI 生成一个实时照片墙页面，参与者上传照片后自动显示在页面上。

场景三：作品征集

让 AI 生成一个作品提交页面，支持填写作品名称、创作说明等信息。

八、部署指南

8.1 宝塔面板部署

在宝塔面板中创建 Python 项目
上传项目文件到服务器
安装 Python 依赖：pip install -r requirements.txt
配置 Gunicorn 或 uWSGI
配置 Nginx 反向代理
设置 SSL 证书（推荐）

8.2 Nginx 配置示例

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    location /uploads/ {
        alias /path/to/picform/uploads/;
    }
}

8.3 Gunicorn 启动命令

gunicorn -w 4 -b 127.0.0.1:5000 run:app

九、常见问题

Q: 忘记密码怎么办？

A: 目前需要联系管理员重置密码。后续版本将添加密码找回功能。

Q: 图片上传失败怎么办？

A: 请检查：1) 图片格式是否支持；2) 文件大小是否超过10MB；3) 任务存储空间是否已满。

Q: 如何增加任务数量限制？

A: 每个用户默认最多3个任务。如需更多，可以修改 app/models/user.py 中的 MAX_TASKS 常量。

Q: 数据存储在哪里？

A: 数据库文件位于 instance/picform.db，上传的图片位于 uploads/ 目录。

Q: 如何备份数据？

A: 备份 instance/ 和 uploads/ 两个目录即可。

十、更新计划

v1.1.0（计划中）

✨ 图片批量下载功能
✨ 任务分享链接生成
✨ 图片水印功能
🐛 修复已知问题

v1.2.0（计划中）

✨ 邮箱验证功能
✨ 密码找回功能
✨ 任务模板功能
✨ 数据导出功能

v2.0.0（远期规划）

✨ 支持多语言
✨ 移动端 APP
✨ 图片智能分类
✨ 协作管理功能

十一、技术支持

泡芙云 PicForm

由 Cit 独立开发维护

编程爱好者 · 教育创新者

🌟 特别鸣谢

本项目获得小麻花平台技术支持

小麻花是一个免费的教育智能体发布平台，为教育工作者提供便捷的 AI 工具服务。

访问小麻花平台 →

联系方式

如有问题或建议，欢迎通过以下方式联系：

GitHub Issues：提交 Bug 报告或功能建议
邮箱：support@picform.com

开源协议

本项目采用 MIT 协议开源，欢迎学习和二次开发。

📚 泡芙云开发文档

一、项目背景

1.1 开发初衷

1.2 项目定位

1.3 目标用户

二、开发思路

2.1 设计理念

🎯 简单至上

🔓 开放兼容

💡 实用优先

2.2 核心功能设计

2.3 技术选型

三、系统架构

3.1 整体架构

3.2 数据库设计

用户表 (users)

任务表 (tasks)

图片表 (images)

3.3 目录结构

四、快速开始

4.1 环境要求

4.2 安装步骤

克隆项目

创建虚拟环境（推荐）

安装依赖

初始化管理员账号

启动服务

4.3 基本使用流程

五、API 文档

5.1 基础信息

5.2 认证接口

5.3 任务接口

5.4 图片接口

5.5 数据接口

5.6 资源限制说明

六、前端集成

6.1 原生 JavaScript 示例

6.2 HTML 表单上传示例

七、AI 集成指南

7.1 系统提示语模板

7.2 使用场景示例

场景一：学生作业提交

场景二：活动照片墙

场景三：作品征集

八、部署指南

8.1 宝塔面板部署

8.2 Nginx 配置示例

8.3 Gunicorn 启动命令

九、常见问题

Q: 忘记密码怎么办？

Q: 图片上传失败怎么办？

Q: 如何增加任务数量限制？

Q: 数据存储在哪里？

Q: 如何备份数据？

十、更新计划

v1.1.0（计划中）

v1.2.0（计划中）

v2.0.0（远期规划）

十一、技术支持

泡芙云 PicForm

🌟 特别鸣谢

联系方式

开源协议

欢迎回来

创建账号

创建新任务