nepiedg
49b709df9f
- 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.
104 lines
5.0 KiB
Markdown
104 lines
5.0 KiB
Markdown
# 去水印小程序需求说明
|
||
|
||
## 背景
|
||
|
||
小程序需要提供“短视频去水印”功能。用户提交的文本中包含短视频分享链接，后台需调用第三方接口 `https://api.23bt.cn/api/d1w/index?key=<你的key>&url=<分享链接>` 获取解析结果并返回。该接口仅向已登录用户开放。
|
||
|
||
公共登录与认证说明见：`docs/common/auth.md`。
|
||
|
||
## 功能需求
|
||
|
||
1. **访问控制**
|
||
- 用户必须先调用 `POST /api/v1/auth/login` 完成登录，接口需要校验 token / 会话。
|
||
2. **请求参数**
|
||
- 前端提交 JSON：`{"content":"帮我解析 https://v.douyin.com/xxx/"}`。
|
||
- 后端从 `content` 中提取第一个合法 http/https 链接；未找到时返回 400。
|
||
3. **第三方请求**
|
||
- 构造 `GET https://api.23bt.cn/api/d1w/index?key=<KEY>&url=<LINK>`。
|
||
- `key` 存放在配置或环境变量（如 `SHORT_VIDEO_API_KEY`）。
|
||
- 设置合理超时（建议 ≤5s），捕获网络/业务错误。
|
||
4. **返回结果**
|
||
- 成功：将第三方返回体（可直接透传或转换为 `provider/raw` 结构）返回客户端。
|
||
- 失败：输出统一错误结构，例如 `{"code":502,"message":"third-party api error: ..."}`
|
||
5. **日志与监控**
|
||
- 记录 mini_program_id、user_id、目标链接、第三方响应码、耗时。
|
||
- 按用户建立调用记录表，统计每日次数并保存第三方返回内容概要（参考「计费与记录设计」）。
|
||
|
||
## 推荐接口设计
|
||
|
||
```
|
||
POST /api/v1/video/remove_watermark
|
||
Authorization: Bearer <token>
|
||
|
||
{
|
||
"content": "帮我解析这个 https://v.douyin.com/xxx/ 谢谢"
|
||
}
|
||
```
|
||
|
||
**成功响应**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"provider": "23bt",
|
||
"raw": { "...第三方响应..." }
|
||
}
|
||
}
|
||
```
|
||
|
||
**常见错误**
|
||
- `400`：缺少 `content`、未能解析链接。
|
||
- `401/403`：未登录或 token 失效。
|
||
- `502`：第三方解析失败。
|
||
|
||
## 处理流程
|
||
|
||
1. 校验登录状态 → 解析 JSON → 提取链接。
|
||
2. 生成第三方接口 URL（带 key、url），发起 HTTP 请求。
|
||
3. 根据第三方响应判定成功/失败，封装结果并返回。
|
||
4. 记录日志，可在失败时重试一次或提示用户稍后重试。
|
||
|
||
## 计费与记录设计
|
||
|
||
### 表结构建议：`video_parse_logs`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `id` | bigint unsigned | 主键 |
|
||
| `mini_program_id` | bigint unsigned | 关联 `mini_programs.id` |
|
||
| `user_id` | bigint unsigned | 关联 `users.id` |
|
||
| `request_content` | text | 用户提交的原始文本 |
|
||
| `parsed_url` | varchar(500) | 提取的短视频链接 |
|
||
| `third_party_status` | int | 第三方 HTTP 状态或业务码 |
|
||
| `third_party_payload` | json | 第三方响应原文（可截断/脱敏） |
|
||
| `free_quota_used` | tinyint | 本次调用是否计入免费次数 |
|
||
| `created_at` | datetime | 记录生成时间 |
|
||
|
||
按 `user_id + date(created_at)` 建索引，方便统计当日次数。
|
||
|
||
### 免费次数与广告策略
|
||
|
||
1. **每日额度**：默认每天 20 次免费解析。统计逻辑基于 `video_parse_logs` 中 `free_quota_used=1` 的数量（按用户和当天日期）。
|
||
2. **广告解锁**：
|
||
- 当用户当天已使用 ≥20 次免费额度时，接口返回提示“需观看广告以继续使用”。
|
||
- 用户观看广告后，后台记录一条标记（例如 `video_parse_unlocks` 表，包含 `user_id`、`date`、`ad_watched_at`）。
|
||
- 当天一旦观看成功，`free_quota_used` 设为 `0`，并允许无限制解析。
|
||
3. **流程概述**：
|
||
- 登录 → 检查 `video_parse_unlocks` 是否在当天存在记录。
|
||
- 若不存在，统计 `video_parse_logs` 免费调用次数；未超 20 次→继续，超限→返回广告提示。
|
||
- 用户观看广告后调用“广告完成”接口，服务端写入解锁记录。
|
||
- 解锁后所有解析均记录日志但不再限制次数（直到次日零点自动失效）。
|
||
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`）：分别记录每次解析详情和“观看广告解锁”状态。
|
||
- 新增 `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`，其中包含新的 `POST /api/v1/video/remove_watermark/report_failure` 上报接口。
|