docs: complete API docs and configuration reference

2026-08-31 14:00:22 +08:00
parent 7481bfedd5
commit 1a935cae6e
1 changed files with 71 additions and 20 deletions
@@ -2,40 +2,91 @@

 智能项目交付检测平台(面向程序部作业/项目提交场景)。

-与传统 OJ 不同,本平台接收成员提交的**完整项目**,基于**作业要求**由 AI 解析出需要检测的维度,并对项目进行多维度检测,产出结构化报告。
+与传统 OJ 不同,本平台接收成员提交的**完整项目包**,基于**作业要求**由 AI 解析出需要检测的维度,并对项目执行多维度检测,产出结构化报告。

 ## 功能

- 上传作业要求,平台后台 AI 分析需要检测哪些维度:
-  - 稳定度(稳定性指标要求)
-  - 压力测试(并发/负载)
-  - 功能点完善度
-  - AI 检测(必备项)
-  - 其他由作业要求决定的自定义检查
- 提交项目后自动执行检测,生成报告
- 对外提供 API 接口
+- `POST /api/requirements/create/` 上传作业要求 → 后台 AI 分析需要检测哪些维度:
+  - **稳定度**(压力测试: 基准并发 → 加压两阶段, 错误率/崩溃率)
+  - **功能点完善度**(AI 逐项核查作业要求中的功能点)
+  - **AI 检测**(必备项: 代码审查、风险与达标分析)
+  - 性能、安全(可按作业要求启用)
+- `POST /api/requirements/{id}/submissions/` 提交项目包(tar/tar.gz/zip)
+- `GET /api/submissions/{id}/report/` 获取检测报告
+- 平台会自动识别项目语言(Python/Django/Node 等),启动服务并执行真实压测

 ## 技术栈

- Python + Django(REST API)
- uv 依赖管理
- AI 检测通过可配置的 LLM API(OpenAI 兼容接口),凭证置于 `.env`
+- Python 3.13 + Django + Django REST Framework
+- **uv** 依赖管理
+- AI 检测走可配置的 LLM API(OpenAI 兼容接口),凭证置于 `.env`
+- SQLite 存储(可换 Postgres)

 ## 快速开始

 ```bash
-uv sync
-cp .env.example .env  # 填入 LLM_API_KEY 等
+uv sync                          # 安装依赖
+cp .env.example .env             # 填入 LLM_BASE_URL / LLM_API_KEY / LLM_MODEL
 uv run python manage.py migrate
+uv run python manage.py createsuperuser   # admin 后台
 uv run python manage.py runserver
 ```

-## API(示例)
+## API 使用示例

- `POST /api/requirements/` 上传作业要求
- `POST /api/submissions/` 提交项目
- `GET /api/submissions/{id}/report/` 获取检测报告
+```bash
+# 1. 登录拿 token
+curl -X POST http://127.0.0.1:8000/api/auth/token/ \
+  -d "username=admin&password=xxx"
+# → {"token": "..."}

-## 状态
+# 2. 上传作业要求(后台 AI 分析检测维度)
+curl -X POST http://127.0.0.1:8000/api/requirements/create/ \
+  -H "Authorization: Token <token>" -H "Content-Type: application/json" \
+  -d '{"title":"作业1","content":"实现 web 服务, 稳定度要求 99%, 首页返回 ok"}'

-开发中。
+# 3. 提交项目包
+curl -X POST http://127.0.0.1:8000/api/requirements/1/submissions/ \
+  -H "Authorization: Token <token>" \
+  -F "name=张三" -F "file=@myproject.tar"
+
+# 4. 轮询报告
+curl http://127.0.0.1:8000/api/submissions/1/report/ \
+  -H "Authorization: Token <token>"
+```
+
+报告结构:
+
+```json
+{
+  "language": "python",
+  "stability": {"enabled": true, "pass": true, "base_error_rate": 0.0,
+                 "rampup_crash_rate": 0.0, "total_requests": 18704, "details": {}},
+  "performance": {"enabled": true, "requirements": "..."},
+  "security": {"enabled": false},
+  "functional": {"enabled": true, "points": ["首页可访问"]},
+  "ai_inspection": {"summary": "...", "issues": [{"point": "...", "status": "pass|fail|warn", "detail": "..."}]},
+  "overall": {"passed_checks": 2, "decided_checks": 2, "checks": [...]}
+}
+```
+
+## 测试
+
+```bash
+uv run python manage.py test --settings=test_settings   # 单元 + 端到端
+uv run python smoke_test.py /path/to/project.tar       # 真实压测冒烟
+```
+
+## 配置项(.env)
+
+| 变量 | 说明 | 默认 |
+|---|---|---|
+| `LLM_BASE_URL` | LLM 接口地址(OpenAI 兼容) | - |
+| `LLM_API_KEY` | LLM API Key | - |
+| `LLM_MODEL` | 模型名 | - |
+| `STABILITY_BASE_DURATION` | 基准压测时长(秒) | 30 |
+| `STABILITY_RAMPUP_DURATION` | 加压阶段时长(秒) | 60 |
+| `STABILITY_CONCURRENCY` | 基准并发数 | 20 |
+| `MAX_UPLOAD_SIZE_MB` | 上传上限 | 200 |
+
+未配置 LLM 时,AI 分析降级为默认检测计划(仍会执行稳定度压测)。