# submit-api-server

**Repository Path**: ClassAgent/submit-api-server

## Basic Information

- **Project Name**: submit-api-server
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-28
- **Last Updated**: 2026-06-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ClassAgent 表单提交服务

开源的 HTML 表单数据收集 API：学生通过 `formId` 匿名提交，教师通过 Web 管理后台登录、创建任务、查看数据并导出 CSV。

## 功能概览

| 角色 | 能力 |
|------|------|
| 学生 | 本地 HTML 调用 `POST /api/v1/submit`（仅需 `formId`） |
| 教师 | 访问 `/admin` 登录，创建任务、查看提交、导出 CSV |
| 运维 | Docker Compose 一键部署，MySQL 默认持久化 |

## 快速开始（Docker Compose，默认 MySQL）

```bash
git clone <repo-url>
cd ClassAgent-submit-api-server
cp .env.example .env
# 编辑 .env，至少修改 JWT_SECRET

docker compose up -d --build
docker compose run --rm api node dist/scripts/seed.js

# 管理后台：http://localhost:8080/admin
# 默认 seed 账号见 .env.example（SEED_EMAIL / SEED_PASSWORD）
```

健康检查：`GET /health`

## 可选：PostgreSQL 模式

```bash
cp .env.example .env
# 设置 DB_DIALECT=postgres 及相关变量

docker compose -f docker-compose.yml -f docker-compose.postgres.yml up -d --build
docker compose run --rm api node dist/scripts/seed.js
```

## 信创 / 外置数据库

使用 OceanBase、TiDB（MySQL 协议）或 Kingbase、瀚高（PostgreSQL 协议）等外置库时，在 `.env` 中配置 `DATABASE_URL` 与 `DB_DIALECT`，仅启动 API：

```bash
docker compose -f docker-compose.yml -f docker-compose.xinchuang.yml up -d api
```

## HTML 表单接入

1. 登录管理后台，创建任务，复制 **formId**（UUID）
2. 参考 [`examples/AI-HTML-PROMPT.md`](examples/AI-HTML-PROMPT.md) 复制提示词给 AI，自动生成带 ClassAgent 集成的 HTML；或直接使用 [`examples/submit-form.html`](examples/submit-form.html)
3. 支持 `application/json` 与 `application/x-www-form-urlencoded`

```javascript
fetch('http://your-server:8080/api/v1/submit', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ formId: 'YOUR-UUID', name: '张三', score: 95 }),
});
```

## 数据持久化与备份

| 方式 | 说明 |
|------|------|
| Docker 命名卷（默认） | 卷名 `classagent_mysql_data`，`docker compose down` **不会**删除数据 |
| 绑定目录（可选） | `.env` 中设置 `MYSQL_DATA_PATH=./data/mysql` |

**停止服务（保留数据）：**

```bash
docker compose down
```

**⚠️ 警告：** `docker compose down -v` 会删除命名卷，**生产环境禁止使用**，仅开发重置时使用。

**MySQL 逻辑备份示例：**

```bash
docker compose exec mysql mysqldump -u classagent -pclassagent classagent > backup.sql
```

**恢复示例：**

```bash
docker compose exec -T mysql mysql -u classagent -pclassagent classagent < backup.sql
```

升级镜像不丢数据：

```bash
docker compose pull
docker compose up -d --build
```

## 本地开发

```bash
npm install

# 需本地 MySQL 或 PostgreSQL，配置根目录 .env
npm run migrate
npm run seed

npm run dev:api      # API :8080
npm run dev:admin    # Admin dev server（/admin/）
```

## 项目结构

`apps/` 存放本仓库内两个可独立构建运行的应用（API 与 Admin 后台）：

```
├── docker-compose.yml           # 默认 api + mysql
├── docker-compose.postgres.yml  # 可选 PostgreSQL
├── docker-compose.xinchuang.yml # 信创：仅 api
├── apps/api/                    # Fastify API
├── apps/admin/                  # React 管理后台
└── examples/submit-form.html    # HTML 提交示例
```

## 环境变量

见 [`.env.example`](.env.example)。关键项：

- `DB_DIALECT`：`mysql`（默认）或 `postgres`
- `DATABASE_URL`：数据库连接串
- `JWT_SECRET`：管理 API 签名密钥（生产必改）
- `CORS_ORIGINS`：生产建议显式配置

## API 摘要

| 路径 | 鉴权 | 说明 |
|------|------|------|
| `POST /api/v1/submit` | 无 | 公开提交 |
| `POST /api/v1/auth/login` | 无 | 教师登录 |
| `/api/v1/datasets/*` | JWT / API Key | 任务管理 |
| `/api/v1/datasets/:id/submissions` | JWT / API Key | 查看提交 |
| `/api/v1/datasets/:id/submissions/export` | JWT / API Key | CSV 导出 |

## 许可证

MIT