Add video download failure reporting feature

- Introduced a new API endpoint `POST /api/v1/video/remove_watermark/report_failure` for reporting download failures.
- Added a new database table `video_download_failures` to store details about failed downloads, including domain, URL, error message, and reporting metadata.
- Updated the video handler to process failure reports and save them to the database.
- Enhanced documentation to include details about the new reporting feature and its usage.

docs/remove_watermark/API.md

@@ -99,3 +99,25 @@ curl -X POST 'http://127.0.0.1:8080/api/v1/video/remove_watermark/unlock' \
 - 每次解析调用都会写入 `video_parse_logs`，其中包含 `request_content`、`parsed_url`、第三方响应、调用耗时等字段，便于审计和配额统计。
 - 第三方返回的 JSON 直接保存在 `video_parse_logs.third_party_payload` 字段，可通过 SQL 查询和脱敏。
 - SQL DDL 位于 `docs/sql/remove_watermark.sql`，部署数据库时执行即可。
+
+## 5. 下载失败上报
+
+`POST /api/v1/video/remove_watermark/report_failure`
+
+| 项目 | 说明 |
+| --- | --- |
+| Header | 可为空（供内部服务调用），也可附加 `Content-Type: application/json` |
+| 请求体 | `{ "domain": "example.com", "failedUrl": "https://example.com/video.mp4", "errorMessage": "403 from CDN", "timestamp": 1728034710000, "userAgent": "miniprogram" }` |
+| 响应 | `{"code":200,"message":"success","data":{"reported":true}}` |
+
+字段说明：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `domain` | string，可选 | 失败 URL 所属域名，若缺失会自动从 `failedUrl` 解析 |
+| `failedUrl` | string，必填 | 下载失败的完整地址 |
+| `errorMessage` | string，可选 | 失败原因描述，建议包含第三方响应 |
+| `timestamp` | number，可选 | 失败发生时间，毫秒级 Unix 时间戳。默认使用服务端接收时间。 |
+| `userAgent` | string，可选 | 报告端的 UA，默认取 HTTP 头 |
+
+服务端会额外记录请求来源 IP（`client_ip`），并存入 `video_download_failures` 表，便于后续排查白名单或 CDN 问题。

docs/remove_watermark/README.md

@@ -97,6 +97,7 @@ Authorization: Bearer <token>
 
 - 项目已将 `SHORT_VIDEO_API_KEY`、`SHORT_VIDEO_FREE_QUOTA`、`SHORT_VIDEO_TIMEOUT_SECONDS` 等变量加入配置，可通过 `.env` 控制。
 - 新增 `video_parse_logs` / `video_parse_unlocks` 表（DDL 见 `docs/sql/remove_watermark.sql`）：分别记录每次解析详情和“观看广告解锁”状态。
+- 新增 `video_download_failures` 表，用于记录第三方下载失败的域名、URL、错误原因、上报端 UA/IP、失败时间，方便排查白名单问题。
 - 用户在登录后可使用登录接口返回的 `session_key` 作为 `Authorization: Bearer <session_key>` 调用受保护的接口。
 - 成功解析后会将第三方原始响应以 JSON 形式直接写入 `video_parse_logs.third_party_payload` 字段，方便统一检索。
-- API 列表和请求/响应示例详见 `docs/remove_watermark/API.md`。
+- API 列表和请求/响应示例详见 `docs/remove_watermark/API.md`，其中包含新的 `POST /api/v1/video/remove_watermark/report_failure` 上报接口。

docs/sql/remove_watermark.sql

@@ -31,3 +31,19 @@ CREATE TABLE IF NOT EXISTS `video_parse_unlocks` (
   PRIMARY KEY (`id`),
   UNIQUE KEY `uniq_video_unlock_date` (`mini_program_id`,`user_id`,`unlock_date`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- 下载失败上报
+CREATE TABLE IF NOT EXISTS `video_download_failures` (
+  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
+  `created_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `updated_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  `deleted_at` datetime DEFAULT NULL,
+  `domain` varchar(255) DEFAULT NULL,
+  `failed_url` varchar(1000) NOT NULL,
+  `error_message` text,
+  `reported_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `user_agent` varchar(255) DEFAULT NULL,
+  `client_ip` varchar(64) DEFAULT NULL,
+  PRIMARY KEY (`id`),
+  KEY `idx_video_download_domain` (`domain`,`reported_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;