145 lines
3.5 KiB
Markdown
145 lines
3.5 KiB
Markdown
# 临时文件上传功能设计
|
||
|
||
**日期**: 2026-05-25
|
||
**状态**: 已批准
|
||
|
||
## 概述
|
||
|
||
在现有 `/public/` 公开内容页面中增加临时文件上传功能，允许任何人上传文件并自动在指定时间后删除。
|
||
|
||
## 功能需求
|
||
|
||
1. 上传临时文件作为 PublicContent 类型发布
|
||
2. 上传者选择过期时间：1小时 / 1天 / 7天
|
||
3. 上传文件最大500MB
|
||
4. 过期文件自动从存储中删除
|
||
5. 上传表单对人类用户视觉隐藏（1px宽度），但agent可访问
|
||
6. 提供REST API方式上传文件
|
||
|
||
## 技术方案
|
||
|
||
### 1. 模型改动
|
||
|
||
**文件**: `core/models.py`
|
||
|
||
在 `PublicContent` 模型中增加字段：
|
||
|
||
```python
|
||
is_temp_file = models.BooleanField(default=False, verbose_name='临时文件')
|
||
expire_type = models.CharField(
|
||
max_length=10,
|
||
choices=[
|
||
('expire_1h', '1小时'),
|
||
('expire_1d', '1天'),
|
||
('expire_7d', '7天'),
|
||
],
|
||
blank=True, null=True,
|
||
verbose_name='过期类型'
|
||
)
|
||
expire_at = models.DateTimeField(blank=True, null=True, verbose_name='过期时间')
|
||
```
|
||
|
||
### 2. 表单改动
|
||
|
||
**文件**: `core/forms.py`
|
||
|
||
扩展 `PublicContentForm`，增加过期类型选择字段。
|
||
|
||
### 3. 上传表单HTML
|
||
|
||
**文件**: `core/templates/core/public_content.html`
|
||
|
||
在页面底部添加上传表单，设置 `style="width: 1px"` 使人类用户难以阅读，但agent可解析。
|
||
|
||
```html
|
||
<form method="post" enctype="multipart/form-data" style="width: 1px; position: absolute; left: -9999px;" action="{% url 'temp_upload' %}">
|
||
{% csrf_token %}
|
||
{{ temp_upload_form }}
|
||
<button type="submit">上传</button>
|
||
</form>
|
||
```
|
||
|
||
### 4. API端点
|
||
|
||
**文件**: `core/urls.py` 和 `core/views.py`
|
||
|
||
新增 API 端点 `POST /api/v1/temp-upload/`:
|
||
|
||
- 路径: `api/v1/temp-upload/`
|
||
- 方法: POST
|
||
- 参数:
|
||
- `file`: 文件 (必填, 最大500MB)
|
||
- `title`: 文件标题 (必填)
|
||
- `expire_type`: 过期类型 `expire_1h` | `expire_1d` | `expire_7d` (必填)
|
||
- 返回: JSON `{ "success": true, "file_url": "...", "expire_at": "..." }`
|
||
|
||
### 5. 定时清理任务
|
||
|
||
**文件**: `core/tasks.py`
|
||
|
||
新增 Celery 任务 `cleanup_expired_temp_files`:
|
||
|
||
```python
|
||
@shared_task
|
||
def cleanup_expired_temp_files():
|
||
expired_files = PublicContent.objects.filter(
|
||
is_temp_file=True,
|
||
expire_at__lte=timezone.now()
|
||
)
|
||
for file in expired_files:
|
||
# 删除物理文件
|
||
if file.file:
|
||
file.file.delete()
|
||
file.delete()
|
||
```
|
||
|
||
配置 Celery Beat 每小时执行。
|
||
|
||
### 6. API文档（写在公开内容页面）
|
||
|
||
```markdown
|
||
## 临时文件上传 API
|
||
|
||
### 上传文件
|
||
POST /api/v1/temp-upload/
|
||
|
||
**参数**:
|
||
- `file`: 文件 (multipart/form-data, 最大500MB)
|
||
- `title`: 文件标题 (string)
|
||
- `expire_type`: 过期时间 (`expire_1h` | `expire_1d` | `expire_7d`)
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"file_url": "/media/temp_files/xxx.pdf",
|
||
"expire_at": "2026-05-25T18:30:00Z",
|
||
"file_name": "document.pdf",
|
||
"file_size": 1048576
|
||
}
|
||
```
|
||
|
||
**示例**:
|
||
```bash
|
||
curl -X POST -F "file=@document.pdf" -F "title=测试文件" -F "expire_type=expire_1d" http://localhost:8000/api/v1/temp-upload/
|
||
```
|
||
|
||
## 数据库迁移
|
||
|
||
```bash
|
||
python manage.py makemigrations core --name add_temp_file_fields
|
||
python manage.py migrate
|
||
```
|
||
|
||
## Celery Beat 配置
|
||
|
||
在 `diary_family/celery.py` 中添加周期任务：
|
||
|
||
```python
|
||
CELERY_BEAT_SCHEDULE = {
|
||
'cleanup-expired-temp-files': {
|
||
'task': 'core.tasks.cleanup_expired_temp_files',
|
||
'schedule': crontab(minute=0), # 每小时整点执行
|
||
},
|
||
}
|
||
``` |