网页本地媒体上传、本人历史与停止分享

docs/features/local-upload.md

@@ -0,0 +1,83 @@
+# 本地音视频文件上传与历史管理 (Local Media Upload)
+
+## 功能概述
+
+本地音视频文件上传功能允许用户直接在网页端上传本地音视频文件进行 ASR 转录与 AI 处理，并在个人历史页面查看任务进度、保留期与管理公开分享状态。
+
+---
+
+## 页面操作流程
+
+### 1. 提交上传 (`/add_task_by_web`)
+
+1. **模式切换**：在首页表单顶部切换“音视频链接”与“本地文件上传”标签页。
+2. **鉴权与可用性探测**：
+   - 上传功能需要 Bearer 访问令牌认证；在高级设置中填写访问令牌。
+   - 填写令牌后，页面会自动请求 `GET /api/uploads/capabilities` 探测服务端能力开关与配置限制。
+   - 上传功能启用的必要前提为：服务端配置开关开启、具备正有限数值的配额限制（如 `max_file_mib > 0`）且后台 worker 就绪。若三者中任一不满足（或未授权/网络异常），前端必须明确可见禁用提示并禁用提交按钮，不承诺可上传。
+3. **选择文件**：
+   - 点击文件选择区域或将音视频文件拖拽至虚线框内。仅支持单文件选择，不支持批量上传。
+   - 若文件体积超过服务端配置的 `max_file_mib`，页面将进行提示并拦截提交。
+4. **元数据配置**：
+   - **自定义标题**：可选，最多不超过 200 个字符。若未填写则传 `null`。
+   - **来源网址**：可选，仅作溯源展示，不超过 2048 字节。必须为 `http://` 或 `https://` 协议，不得包含用户名/密码（userinfo）。
+   - **保留期限**：提供“保留 30 天”（默认）与“永久保留”。每次重新选择文件或变更意图时，保留期均重置为默认 30 天。
+   - **处理选项**：包括 AI 文本校对（calibrate）、内容总结（summarize）、提取章节（chapters）、说话人识别（infer_speaker_names）等开关。
+5. **提交与传输**：
+   - 点击“提交上传”按钮。
+   - 前端生成单次意图唯一的 `Idempotency-Key`（格式：`<epoch_ms>-<UUID>`）与 `X-Upload-Metadata` 头（base64url UTF-8 编码 JSON，恰包含 6 个字段：`filename`, `byte_size`, `title`, `source_url`, `retention`, `processing_options`）。
+   - 以 `application/octet-stream` 流式发送原始文件字节。
+   - 具备双击防重保护；若因网络异常导致结果未知，保持原 `Idempotency-Key`，通过 `GET /api/uploads/by-idempotency-key/{key}` 进行回执查询，不重复发送文件字节。
+
+---
+
+## 任务生命周期与阶段状态
+
+| 阶段 | 状态码 / 标识 | 说明 |
+|------|-------------|------|
+| 传输接收 | `receiving` | 服务端正在流式接收上传文件字节 |
+| 任务受理 | `accepted` | 文件完整写入临时存储，已生成回执（包含 `upload_id`, `state`, `task_id`, `view_token` 等），后台转录任务已入队 |
+| 后台排队与处理 | `pending` / `processing` | 后台 worker 正在执行 ASR 识别、校对与总结处理 |
+| 处理完成 | `success` | 任务处理成功，可通过 `view_token` 打开公开阅读页面查看转录正文；临时媒体输入文件在转录完成后及时清理 |
+| 处理失败 | `failed` | 任务处理失败，可查看失败原因 |
+
+---
+
+## 数据保留期 (Retention) 与生命周期策略
+
+- **临时媒体清理**：上传的原始音视频媒体仅作为临时转录输入，转录任务处理完成后即时进行清理释放空间。
+- **计算起点**：保留期从根任务首次到达终态（`success` 或 `failed`）起算，派生或重处理任务不延长生命周期。
+- **30 天保留 (`30d`)**：默认选项，转录正文在 30 天内映射受保护阅读，到期后由既有系统的 cleanup 规则统一回收。
+- **永久保留 (`never`)**：需用户在提交前显式选择，转录正文长期保持映射受保护阅读。
+- **停止公开分享说明**：用户在历史记录中停止分享将立即撤销公开阅读访问权限（公开链接访问返回 404），但不等同于立即从磁盘物理擦除转录正文；系统不提供任意“手动删除”功能。
+
+---
+
+## 本人历史与停止公开分享 (`/static/history.html`)
+
+1. **历史查询与过滤**：
+   - 输入访问令牌后查询个人历史记录。
+   - 顶部过滤栏提供“来源”下拉菜单（支持“音视频链接”与“本地上传”两种模式切换），过滤条件同步至 URL 参数。
+2. **上传任务状态展示**：
+   - 列表展示任务标题、请求时间、保留期标识（如“30天保留”或“永久保留”）。
+   - 展示公开分享状态徽章（“分享中”或“已停止分享”）。
+   - 任务完成后，通过 `upload_view_token` 点击条目可打开公开阅读页。
+3. **停止公开分享 (Owner 操作)**：
+   - 拥有者在历史条目中点击“停止分享”按钮。
+   - 弹出确认对话框提示：“确认关闭公开分享？关闭后将停止后续阅读、导出与重新处理，但不立即擦除正文，也不取消在途处理与通知。”
+   - 确认后前端发送 `DELETE /api/uploads/{upload_id}/share` 请求。
+   - 停止分享后，公开阅读链接即刻失效（访问返回 404），历史记录中状态就地更新为“已停止分享”。
+   - 阅读页面展示正文及现有重处理能力，不包含停止分享按钮。
+
+---
+
+## 限制与系统配置
+
+| 配置项 / 约束 | 默认值 / 限制 | 说明 |
+|--------------|--------------|------|
+| 服务开关 | 默认禁用 (`false`) | 由服务端配置或环境变量 `VTA_UPLOADS_ENABLED="true"` 控制；同时需正有限配额 limits 与 worker 就绪 |
+| 单文件体积限制 | 由服务端 `limits.max_file_mib` 决定 | 超过限制的文件将在前端被拦截 |
+| 文件名长度 | 最多 255 字节 | UTF-8 编码 |
+| 标题长度 | 最多 200 字符 | 可选 |
+| 来源网址长度 | 最多 2048 字节 | 可选，必须为 http(s) 且无 userinfo |
+| 传输格式 | 单文件 raw binary | `application/octet-stream`，不使用 multipart 格式 |