Add short video configuration and related API endpoints

- Updated .env.example to include SHORT_VIDEO_API_KEY, SHORT_VIDEO_FREE_QUOTA, and SHORT_VIDEO_TIMEOUT_SECONDS. - Enhanced main.go to auto-migrate new VideoParseLog and VideoParseUnlock models. - Introduced VideoService and VideoHandler for handling video-related operations. - Added protected API routes for removing watermarks and unlocking video features. - Updated config.go to support short video configuration settings. - Expanded documentation to reflect new features and configuration options.
2025-12-30 00:31:41 +00:00
parent a1eaaab39f
commit 97cadb033e
10 changed files with 590 additions and 4 deletions
@@ -0,0 +1,83 @@
+# 去水印服务 API 说明
+
+所有接口均位于 `/api/v1`，除登录外都需要在 Header 中携带 `Authorization: Bearer <session_key>`，其中 `<session_key>` 来自登录接口的响应。
+
+## 1. 登录（复用已有接口）
+
+`POST /api/v1/auth/login`
+
+## 接口
+
+### `POST /api/v1/auth/login`
+
+- **说明**：接收小程序端 `wx.login` 返回的 `code`，向微信 `jscode2session` 请求 `openid` / `session_key`。若 `open_id` 不存在则创建用户，存在则更新资料并返回用户信息。
+- **请求体**
+
+```json
+{
+  "mini_program_id": 1,
+  "code": "wx.login返回的code",
+  "nickname": "可选",
+  "avatar_url": "可选",
+  "gender": 1,
+  "phone": "110"
+}
+```
+
+## 2. 解析短视频去水印
+
+`POST /api/v1/video/remove_watermark`
+
+| 项目 | 说明 |
+| --- | --- |
+| Header | `Authorization: Bearer <session_key>` |
+| 请求体 | `{"content":"帮我解析 https://v.douyin.com/xxxx/"}` |
+| 必填校验 | `content` 必须包含一个合法的 http/https 链接 |
+| 响应 | `provider` 固定为 `23bt`，`raw` 为第三方原始 JSON，`free_quota_used` 表示是否占用免费额度 |
+
+**成功示例**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "provider": "23bt",
+    "raw": {
+      "code": 200,
+      "msg": "解析成功",
+      "data": { "...第三方原始字段..." }
+    },
+    "free_quota_used": true
+  }
+}
+```
+
+**错误返回**
+
+| HTTP 码 | code | message | 说明 |
+| --- | --- | --- | --- |
+| 400 | 400 | `content must contain a valid url` | 未找到链接 |
+| 401 | 401 | `unauthorized` | Token 缺失/失效 |
+| 403 | 403 | `daily free quota exceeded, please watch an ad to continue` | 超过每日免费额度，需要走广告解锁 |
+| 502 | 502 | `third-party api error: ...` | 第三方返回异常 |
+| 503 | 503 | `short video api key missing` | 未配置 `SHORT_VIDEO_API_KEY` |
+| 500 | 500 | `remove watermark failed` | 其他内部错误 |
+
+## 3. 完成广告解锁
+
+`POST /api/v1/video/remove_watermark/unlock`
+
+| 项目 | 说明 |
+| --- | --- |
+| Header | `Authorization: Bearer <session_key>` |
+| 请求体 | 空 |
+| 响应 | `{"code":200,"message":"success","data":{"unlocked":true}}` |
+
+说明：调用该接口表示用户当天已经观看完广告，服务端会写入 `video_parse_unlocks`，当天余下时间不再校验免费额度。
+
+## 4. 数据落地
+
+- 每次解析调用都会写入 `video_parse_logs`，其中包含 `request_content`、`parsed_url`、第三方响应、调用耗时等字段，便于审计和配额统计。
+- 第三方返回的 JSON 直接保存在 `video_parse_logs.third_party_payload` 字段，可通过 SQL 查询和脱敏。
+- SQL DDL 位于 `docs/sql/remove_watermark.sql`，部署数据库时执行即可。
@@ -90,3 +90,11 @@ Authorization: Bearer <token>
 4. **其他注意事项**：
   - 可在日志中存储第三方返回摘要（如视频标题、作者），便于后续分析。
   - 可配置单独的付费/会员策略，覆盖默认 20 次逻辑。
+
+## 实现概览
+
+- 项目已将 `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`）：分别记录每次解析详情和“观看广告解锁”状态。
+- 用户在登录后可使用登录接口返回的 `session_key` 作为 `Authorization: Bearer <session_key>` 调用受保护的接口。
+- 成功解析后会将第三方原始响应以 JSON 形式直接写入 `video_parse_logs.third_party_payload` 字段，方便统一检索。
+- API 列表和请求/响应示例详见 `docs/remove_watermark/API.md`。
@@ -0,0 +1,33 @@
+-- 短视频去水印调用日志
+CREATE TABLE IF NOT EXISTS `video_parse_logs` (
+  `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,
+  `mini_program_id` bigint unsigned NOT NULL,
+  `user_id` bigint unsigned NOT NULL,
+  `request_content` text,
+  `parsed_url` varchar(500) DEFAULT NULL,
+  `third_party_status` int DEFAULT NULL,
+  `third_party_payload` json DEFAULT NULL,
+  `free_quota_used` tinyint(1) NOT NULL DEFAULT '1',
+  `duration_ms` int DEFAULT NULL,
+  `error_message` varchar(500) DEFAULT NULL,
+  PRIMARY KEY (`id`),
+  KEY `idx_video_parse_user_date` (`mini_program_id`,`user_id`,`created_at`),
+  KEY `idx_video_parse_free` (`mini_program_id`,`user_id`,`free_quota_used`,`created_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- 每日广告解锁记录
+CREATE TABLE IF NOT EXISTS `video_parse_unlocks` (
+  `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,
+  `mini_program_id` bigint unsigned NOT NULL,
+  `user_id` bigint unsigned NOT NULL,
+  `unlock_date` date NOT NULL,
+  `ad_watched_at` datetime NOT NULL,
+  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;