dysync/docs/下载配置功能说明.md

下载配置功能说明

📋 功能概述

为了避免自动下载占用过多存储空间，系统现在支持可配置的下载策略。默认情况下，系统不会自动下载视频，只会同步视频信息到数据库。

🎯 功能特点

1. 默认不下载：未配置的用户不会自动下载视频，避免占用存储空间
2. 按时间范围配置：可以设置只下载指定天数内的视频（例如：只下载最近30天）
3. 按作者配置：支持作者白名单和黑名单
4. 按类型配置：可以分别控制是否下载"喜欢的视频"和"收藏的视频"

⚙️ 配置选项

1. 启用自动下载

• 开关：启用/禁用自动下载功能
• 默认值：关闭（false）
• 说明：关闭后，系统只同步视频信息到数据库，不会下载视频文件

2. 下载时间范围

• 类型：数字（天数）
• 默认值：0（不限制）
• 说明：
  • 0：不限制时间，下载所有符合条件的视频
  • 30：只下载最近30天的视频
  • 90：只下载最近90天的视频
  • 最大支持 3650 天（10年）

3. 下载类型

• 下载喜欢的视频：是否下载"喜欢的视频"（ViedoType = "1"）
• 下载收藏的视频：是否下载"收藏的视频"（ViedoType = "2"）
• 默认值：都关闭（false）

4. 作者白名单

• 类型：多行文本（每行一个作者）
• 格式：每行一个作者名称或作者ID
• 说明：
  • 配置后，只有白名单中的作者视频才会被下载
  • 留空则不限制
  • 支持作者名称或作者ID（AuthorId）
  • 示例：

    作者1
    作者2
    MS4wLjABAAAA...
    

5. 作者黑名单

• 类型：多行文本（每行一个作者）
• 格式：每行一个作者名称或作者ID
• 说明：
  • 配置后，黑名单中的作者视频不会被下载
  • 留空则不限制
  • 支持作者名称或作者ID（AuthorId）
  • 示例：

    作者1
    作者2
    MS4wLjABAAAA...
    

🔍 判断逻辑

系统按照以下顺序判断是否应该下载视频：

1. 检查是否启用自动下载

   • 如果未启用，直接跳过下载

2. 检查视频类型

   • 如果视频类型为"喜欢"（ViedoType = "1"），检查 DownloadFavorite 是否为 true
   • 如果视频类型为"收藏"（ViedoType = "2"），检查 DownloadCollect 是否为 true
   • 如果对应类型未启用，跳过下载

3. 检查时间范围

   • 如果配置了 DownloadDaysRange > 0，检查视频创建时间是否在范围内
   • 超出时间范围的视频跳过下载

4. 检查作者白名单

   • 如果配置了白名单，检查作者是否在白名单中
   • 不在白名单中的视频跳过下载

5. 检查作者黑名单

   • 如果配置了黑名单，检查作者是否在黑名单中
   • 在黑名单中的视频跳过下载

6. 所有检查通过，开始下载

📝 配置示例

示例 1：只下载最近30天的喜欢视频

启用自动下载：✅ 开启
下载时间范围：30 天
下载喜欢的视频：✅ 开启
下载收藏的视频：❌ 关闭
作者白名单：（留空）
作者黑名单：（留空）

示例 2：只下载指定作者的视频

启用自动下载：✅ 开启
下载时间范围：0（不限制）
下载喜欢的视频：✅ 开启
下载收藏的视频：✅ 开启
作者白名单：
  作者1
  作者2
  MS4wLjABAAAA...
作者黑名单：（留空）

示例 3：排除某些作者，下载其他所有视频

启用自动下载：✅ 开启
下载时间范围：0（不限制）
下载喜欢的视频：✅ 开启
下载收藏的视频：✅ 开启
作者白名单：（留空）
作者黑名单：
  不想下载的作者1
  不想下载的作者2

示例 4：不自动下载（默认）

启用自动下载：❌ 关闭
（其他选项无效）

🚀 使用方法

1. 登录系统，进入"设置"页面
2. **点击"修改配置"**按钮
3. 配置下载选项：
   • 开启"启用自动下载"
   • 根据需要设置时间范围、类型、作者白名单/黑名单
4. **点击"确认"**保存配置
5. 系统会在下次同步时应用新配置

📊 数据库变更

AppConfig 表新增字段

-- 以下字段已添加到 dy_app_config 表
EnableAutoDownload BOOLEAN DEFAULT 0  -- 是否启用自动下载
DownloadDaysRange INTEGER DEFAULT 0   -- 下载时间范围（天数）
AuthorWhitelist TEXT                   -- 作者白名单（JSON数组）
AuthorBlacklist TEXT                   -- 作者黑名单（JSON数组）
DownloadFavorite BOOLEAN DEFAULT 0    -- 是否下载喜欢的视频
DownloadCollect BOOLEAN DEFAULT 0     -- 是否下载收藏的视频

🔧 技术实现

后端变更

1. 模型扩展：AppConfig 模型新增下载配置字段
2. 服务新增：DownloadConfigService 服务实现下载判断逻辑
3. Job 修改：
   • DouYinFavoritSyncJob：在下载前检查配置
   • DouYinCollectSyncJob：在下载前检查配置
4. 服务更新：CommonService 支持保存和读取下载配置

前端变更

1. 配置页面：AppSet.vue 新增下载配置界面
2. 表单字段：添加下载相关的表单字段
3. 数据处理：处理作者白名单/黑名单的 JSON 转换

⚠️ 注意事项

1. 默认行为：未配置的用户默认不会下载视频，只会同步视频信息
2. 配置优先级：白名单和黑名单同时配置时，黑名单优先级更高
3. 时间计算：时间范围基于视频的创建时间（CreateTime），不是同步时间
4. 作者匹配：支持按作者名称或作者ID匹配，不区分大小写
5. 配置生效：配置修改后，会在下次同步任务执行时生效

🐛 故障排查

问题：配置了但视频仍然不下载

检查项：

1. 确认"启用自动下载"已开启
2. 确认对应的视频类型（喜欢/收藏）已开启
3. 检查时间范围是否合理（视频是否在范围内）
4. 检查作者是否在白名单中（如果配置了白名单）
5. 检查作者是否在黑名单中（如果配置了黑名单）

问题：配置了白名单但所有视频都不下载

可能原因：

• 作者名称或ID不匹配
• 白名单格式错误（应该是每行一个）

解决方法：

• 检查作者名称是否完全匹配（包括空格、特殊字符）
• 尝试使用作者ID而不是名称
• 查看日志中的"不符合下载配置"提示

问题：配置了时间范围但旧视频仍然下载

可能原因：

• 时间范围配置未生效
• 视频创建时间解析错误

解决方法：

• 确认配置已保存
• 检查日志中的时间判断逻辑
• 重启服务后重试

📚 相关文件

• 后端模型：model/AppConfig.cs
• 下载服务：service/DownloadConfigService.cs
• 配置服务：service/CommonService.cs
• 喜欢视频Job：job/DouYinFavoritSyncJob.cs
• 收藏视频Job：job/DouYinCollectSyncJob.cs
• 前端配置页：app/src/pages/set/AppSet.vue
• API控制器：Controllers/ConfigController.cs

---

最后更新：2024-11-24