# Web 控制台使用指南

## 概述

Web 控制台是基于浏览器的图形界面，用于批量下载和管理视频号视频。

### 主要功能

- 批量下载视频
- 自动解密加密视频（WASM 集成）
- 实时进度监控和日志显示
- 取消下载和失败任务管理
- 支持多种数据格式自动转换

## 快速开始

### 1. 启动程序

```bash
# 启动下载助手
wx_channel.exe
```

程序默认在 `http://127.0.0.1:2025` 启动。

### 2. 访问控制台

在浏览器中打开：
```
http://127.0.0.1:2025/console
```

推荐使用 HTTP 访问，避免 CORS 跨域问题。

### 3. 提交下载任务

1. 粘贴视频列表 JSON
2. 点击"开始下载"
3. 查看实时进度和日志

## 数据格式

### 批量下载格式（标准）

```json
[
  {
    "id": "video_001",
    "url": "https://example.com/video.mp4",
    "title": "视频标题",
    "authorName": "作者名称"
  }
]
```

### 账户导出格式（自动转换）

```json
{
  "videos": [
    {
      "id": "video_001",
      "url": "https://example.com/video.mp4",
      "title": "视频标题",
      "author": "作者名称",
      "key": "123765583"
    }
  ]
}
```

**自动转换**：
- `author` → `authorName`
- `key` → `decryptorPrefix`（通过 WASM 处理）

### 加密视频格式

```json
[
  {
    "id": "video_001",
    "url": "https://example.com/encrypted.mp4",
    "title": "加密视频",
    "authorName": "作者名",
    "decryptorPrefix": "AQIDBAUG...",
    "prefixLen": 1024
  }
]
```

### 字段说明

| 字段 | 必填 | 说明 |
|------|------|------|
| id | 是 | 视频唯一标识，用于去重 |
| url | 是 | 视频下载地址 |
| title | 是 | 视频标题，用作文件名 |
| authorName | 是 | 作者名称，用于创建文件夹 |
| author | 否 | 账户导出格式的作者字段，自动转换为 authorName |
| key | 否 | 加密密钥（数字），自动通过 WASM 转换为 decryptorPrefix |
| decryptorPrefix | 否 | Base64 编码的解密密钥 |
| prefixLen | 否 | 解密长度，默认使用全部 |

## 核心功能

### 1. WASM 自动解密

**功能说明**：
- 自动加载微信 WASM 解密库
- 自动处理 `key` 字段
- 生成正确的解密密钥
- 无需手动转换

**使用方法**：
直接粘贴包含 `key` 字段的账户导出数据，系统会自动：
1. 加载 WASM 库（首次约 1-2 秒）
2. 处理每个视频的 key
3. 生成 decryptorPrefix
4. 提交到后端下载

**技术细节**：
- 库地址：`https://res.wx.qq.com/t/wx_fed/cdn_libs/res/decrypt-video-core/1.3.0/wasm_video_decode.js`
- 工作流程：`key (数字) → WASM 处理 → 解密数组 → Base64 → decryptorPrefix`
- 性能：首次加载 1-2 秒，每个密钥处理 100-200ms

### 2. 实时进度显示

**统计信息**：
- 总任务数：提交的视频总数
- 已完成：成功下载的数量
- 失败：下载失败的数量
- 进行中：正在下载的数量

**当前任务**：
- 视频标题
- 下载进度条（百分比）
- 已下载 / 总大小

**进度条**：
- 总体完成百分比
- 微信绿色渐变
- 每 2 秒自动更新

### 3. 实时日志

**日志类型**：
- 信息（青色）：解析过程、格式转换
- 成功（绿色）：提交成功、下载完成
- 警告（橙色）：重试、跳过
- 错误（红色）：下载失败、解析错误

**日志内容**：
- 解析过程和格式转换
- 提交状态和下载进度
- 完成统计和错误信息

**日志管理**：
- 最多保存 500 条
- 自动滚动到底部
- 一键清空

### 4. 操作按钮

**开始下载**：
- 提交下载任务
- 开始进度监控

**取消下载**：
- 停止当前任务
- 清空下载队列
- 重置统计信息

**导出失败清单**：
- 导出失败任务 JSON
- 保存到 `downloads/batch_failed_*.json`
- 包含失败原因和视频信息

**清空日志**：
- 清空日志显示
- 方便开始新任务

**加载示例**：
- 快速加载测试数据
- 学习数据格式

## 使用场景

## 设置页说明

- 下载目录、分片大小、并发下载数、自动清理等参数可通过控制台保存。
- `download_filename_template` 为只读展示项，需在 `config.yaml` 中修改。
- `radar_enabled` 为只读展示项，需在 `config.yaml` 中修改并重启程序。
- 当前支持的文件名模板占位符为 `{date} {datetime} {author} {title} {duration} {video_id} {size}`。

### 场景 1：批量下载普通视频

```json
[
  {
    "id": "video_001",
    "url": "https://example.com/video1.mp4",
    "title": "视频1",
    "authorName": "作者A"
  },
  {
    "id": "video_002",
    "url": "https://example.com/video2.mp4",
    "title": "视频2",
    "authorName": "作者B"
  }
]
```

### 场景 2：下载加密视频（使用 key）

```json
{
  "videos": [
    {
      "id": "video_001",
      "url": "https://example.com/encrypted.mp4",
      "title": "加密视频",
      "author": "作者名",
      "key": "123765583"
    }
  ]
}
```

系统会自动处理 key 并解密。

### 场景 3：混合下载

```json
{
  "videos": [
    {
      "id": "video_001",
      "url": "https://example.com/encrypted.mp4",
      "title": "加密视频",
      "author": "作者A",
      "key": "123765583"
    },
    {
      "id": "video_002",
      "url": "https://example.com/normal.mp4",
      "title": "普通视频",
      "author": "作者B"
    }
  ]
}
```

### 场景 4：强制重新下载

1. 勾选"强制重新下载"选项
2. 提交任务
3. 即使文件已存在也会重新下载

## 界面设计

### 微信风格

**配色方案**：
- 主色：微信绿 (#07c160)
- 背景：浅灰 (#ededed)
- 卡片：白色
- 文字：深灰 (#191919)

**设计特点**：
- 简洁清爽
- 小圆角（4-8px）
- 轻微阴影
- 无多余装饰

### 响应式布局

- 桌面端：4 列统计卡片
- 移动端：2 列统计卡片
- 自适应按钮布局

## 高级功能

### 自定义 API 地址

如果程序运行在其他端口或服务器：
```
http://192.168.1.100:8080
```

在控制台页面的"API 地址"输入框中修改。

### 使用授权令牌

如果配置了 `WX_CHANNEL_TOKEN`：
1. 在"授权令牌"输入框中填写令牌
2. 所有 API 请求会自动携带令牌

### 强制重新下载

勾选"强制重新下载"选项，覆盖已存在的文件。

### 批量导入

可以从其他来源获取视频列表，转换为 JSON 格式后粘贴到控制台。

**示例：从 CSV 转换**

```javascript
// CSV 格式
const csv = `
id,url,title,author
video_001,https://example.com/1.mp4,视频1,作者A
video_002,https://example.com/2.mp4,视频2,作者B
`;

// 转换为 JSON
const lines = csv.trim().split('\n');
const headers = lines[0].split(',');
const videos = lines.slice(1).map(line => {
  const values = line.split(',');
  return {
    id: values[0],
    url: values[1],
    title: values[2],
    authorName: values[3]
  };
});

console.log(JSON.stringify(videos, null, 2));
```

## 界面说明

### 头部区域

- 显示控制台标题和说明
- 微信绿色渐变背景

### 下载表单

- **API 地址**：后端服务地址，默认 `http://127.0.0.1:2025`
- **授权令牌**：可选的安全令牌
- **视频列表**：JSON 格式的视频信息
- **强制重新下载**：覆盖已存在的文件

### 进度卡片

- **统计信息**：四个统计卡片显示实时数据
- **当前任务**：显示正在下载的视频和进度
- **进度条**：可视化显示完成百分比
- **操作按钮**：开始、取消、导出、清空日志

### 日志区域

- **实时日志**：显示操作过程和状态
- **颜色区分**：信息、成功、警告、错误
- **自动滚动**：新日志自动滚动到底部
- **日志管理**：最多 500 条，可一键清空

## 故障排除

### 问题 1：无法连接到 API（CORS 错误）

**症状**：提示"请求失败: Failed to fetch" 或 "ERR_CONNECTION_REFUSED"

**原因**：
- 程序未运行
- API 地址不正确
- 使用 `file://` 协议打开控制台

**解决方案**：
1. 确认程序正在运行
2. 通过 HTTP 访问控制台：`http://127.0.0.1:2025/console`
3. 检查 API 地址是否正确
4. 检查端口是否被占用

### 问题 2：WASM 加载失败

**症状**：提示"解密库加载失败"

**原因**：
- 网络问题
- 无法访问微信 CDN
- 浏览器不支持 WASM

**解决方案**：
1. 检查网络连接
2. 使用现代浏览器（Chrome 90+、Firefox 88+）
3. 使用 Profile 页面作为备选

### 问题 3：下载卡住

**症状**：进度长时间不更新

**原因**：
- 文件很大，正在下载
- 网络问题
- 服务器限速

**解决方案**：
1. 查看实时日志
2. 等待超时自动重试
3. 检查后端日志

### 问题 4：视频无法播放

**症状**：下载成功但无法播放

**原因**：
- 解密失败
- 密钥不正确
- 视频文件损坏

**解决方案**：
1. 检查 key 或 decryptorPrefix 是否正确
2. 重新下载
3. 使用 Profile 页面下载

### 问题 5：授权失败

**症状**：提示"unauthorized"

**解决方案**：
1. 检查是否配置了 `WX_CHANNEL_TOKEN`
2. 确认令牌输入正确
3. 检查令牌是否包含特殊字符

### 问题 6：JSON 格式错误

**症状**：提示"JSON 格式错误"

**解决方案**：
1. 使用 JSON 验证工具检查格式
2. 确保所有字符串使用双引号
3. 检查是否有多余的逗号
4. 使用"加载示例"查看正确格式

## 浏览器兼容性

### 支持
- ✅ Chrome 90+
- ✅ Firefox 88+
- ✅ Edge 90+
- ✅ Safari 14+

### 不支持
- ❌ IE 11 及更早版本

## 安全注意事项

### 本地使用
控制台设计为本地使用，不建议部署到公网。

### 授权令牌
如果使用授权令牌：
- 不要分享给他人
- 定期更换令牌
- 不在公共场所使用

### CORS 限制
推荐通过 HTTP 访问：`http://127.0.0.1:2025/console`

避免使用 `file://` 协议，会遇到跨域错误。

## 相关文档

- [批量下载使用指南](BATCH_DOWNLOAD_GUIDE.md) - 批量下载完整功能说明
- [API 文档](API.md) - 完整 API 接口说明
- [配置概览](CONFIGURATION.md) - 配置选项
- [故障排除](TROUBLESHOOTING.md) - 常见问题解决方案

### 详细文档（开发者参考）

- [批量下载索引](fix/BATCH_DOWNLOAD_INDEX.md) - 完整文档导航
- [批量下载加密说明](fix/BATCH_DOWNLOAD_ENCRYPTION.md) - 加密详解
- [批量下载 API](fix/BATCH_DOWNLOAD_API.md) - API 详细文档

---

最后更新：2025-11-23
