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 表新增字段

```sql
-- 以下字段已添加到 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