# Web 控制台使用指南

## 概述

Web 控制台是基于浏览器的现代化图形界面，提供完整的视频号视频管理功能。

### 主要功能

- **浏览记录管理** - 查看、搜索、导出浏览历史
- **下载记录管理** - 查看历史下载记录和统计
- **下载队列管理** - 管理下载任务，支持超长视频分片下载
- **批量下载** - 批量提交下载任务，自动解密加密视频
- **数据导出** - 支持 JSON/CSV 格式导出
- **系统设置** - 配置下载参数、自动清理等

## 快速开始

### 1. 启动程序

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

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

### 2. 访问控制台

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

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

### 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. 概览页面

**功能说明**：
- 显示系统运行状态
- 统计信息概览
- 快速访问常用功能

**统计卡片**：
- 浏览记录总数
- 下载记录总数
- 队列任务数
- 系统运行时间

### 2. 浏览记录页面

**功能说明**：
查看和管理所有浏览过的视频记录。

**主要功能**：
- 实时搜索 - 按标题、作者、描述搜索
- 时间筛选 - 按日期范围筛选记录
- 批量操作 - 全选、批量删除、批量下载
- 数据导出 - 导出为 JSON 或 CSV 格式
- 详细信息 - 查看视频完整信息

**操作说明**：
1. 使用搜索框快速查找视频
2. 点击时间筛选按钮选择日期范围
3. 勾选视频后可批量下载或删除
4. 点击"导出数据"按钮导出记录

**导出格式**：
- JSON - 包含完整视频信息，适合程序处理
- CSV - 表格格式，可用 Excel 打开

### 3. 下载记录页面

**功能说明**：
查看所有历史下载记录和统计信息。

**主要功能**：
- 下载历史 - 显示所有下载记录
- 状态筛选 - 按成功/失败状态筛选
- 搜索功能 - 按标题、作者搜索
- 重新下载 - 失败任务可重新下载
- 数据导出 - 导出下载记录

**统计信息**：
- 总下载数
- 成功数量
- 失败数量
- 总下载大小

### 4. 下载队列页面

**功能说明**：
管理当前下载队列，支持超长视频分片下载。

**主要功能**：
- 队列管理 - 查看所有下载任务
- 任务控制 - 开始、暂停、恢复、删除
- 进度监控 - 实时显示下载进度
- 批量操作 - 暂停全部、恢复全部、清空队列

**队列状态**：
- 等待中 (pending) - 等待开始下载
- 下载中 (downloading) - 正在下载
- 已暂停 (paused) - 已暂停
- 已完成 (completed) - 下载完成
- 失败 (failed) - 下载失败

**超长视频支持**：
- 自动分片下载
- 断点续传
- 进度实时更新
- 分片大小可在设置中配置

### 5. 批量下载页面

**功能说明**：
批量提交下载任务，支持多种数据格式。

**使用步骤**：
1. 粘贴视频列表 JSON
2. 选择是否强制重新下载
3. 点击"开始下载"
4. 查看实时进度和日志

**支持的数据格式**：
- 标准批量下载格式
- 账户导出格式（自动转换）
- 加密视频格式

详见下方"数据格式"章节。

### 6. 设置页面

**功能说明**：
配置系统参数和下载选项。

**服务地址设置**：
- API 地址 - 后端服务地址
- 测试连接 - 验证连接是否正常
- 保存地址 - 保存到本地存储

**下载设置**：
- 下载目录 - 视频保存路径
- 分片大小 - 超长视频分片大小 (1-100 MB)
- 并发下载数 - 同时下载任务数 (1-5)
- 文件名附带视频 ID - 控制默认命名是否追加 `video_id`
- 下载文件名模板 - 只读展示 `config.yaml` 中的 `download_filename_template`

**自动清理设置**：
- 启用自动清理 - 自动删除旧记录
- 清理天数阈值 - 超过指定天数的记录将被删除 (1-365)

**配置持有项说明**：
- `download_filename_template` 需要在 `config.yaml` 中修改，控制台仅展示当前值和支持的占位符。
- `radar_enabled` 需要在 `config.yaml` 中修改并重启程序，控制台仅展示当前状态。

**主题设置**：
- 浅色模式 / 深色模式切换
- 自动保存到本地

## 核心功能

### 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 - 结构化数据，适合程序处理
- CSV - 表格格式，可用 Excel 打开

**导出内容**：
- 浏览记录 - 包含视频信息、浏览时间等
- 下载记录 - 包含下载状态、文件大小等

**导出步骤**：
1. 在浏览记录或下载记录页面
2. 点击"导出数据"按钮
3. 选择导出格式（JSON 或 CSV）
4. 确认导出
5. 文件自动下载到浏览器下载目录

**CSV 格式说明**：
- 包含标题行
- 使用逗号分隔
- 时间格式：YYYY-MM-DD HH:mm:ss
- 可直接用 Excel 打开

### 5. 批量操作

**浏览记录批量操作**：
- 全选 / 取消全选
- 批量下载 - 将选中视频加入下载队列
- 批量删除 - 删除选中的浏览记录

**下载队列批量操作**：
- 暂停全部 - 暂停所有下载任务
- 恢复全部 - 恢复所有暂停的任务
- 清空队列 - 删除所有队列任务

**操作提示**：
- 批量操作前会显示确认对话框
- 删除操作不可恢复，请谨慎操作
- 批量下载会自动去重

## 使用场景

### 场景 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)
- 背景：浅灰 (#f5f5f5)
- 卡片：白色
- 文字：深灰 (#333333)
- 边框：浅灰 (#e0e0e0)

**设计特点**：
- 侧边栏导航 - 清晰的功能分组
- 卡片式布局 - 内容模块化
- 圆角设计 - 柔和的视觉效果
- 微交互 - 悬停效果和过渡动画

### 主题支持

**浅色模式**（默认）：
- 白色背景
- 深色文字
- 适合白天使用

**深色模式**：
- 深色背景
- 浅色文字
- 适合夜间使用
- 减少眼睛疲劳

**切换方式**：
- 点击侧边栏底部的主题切换按钮
- 设置自动保存到本地

### 响应式布局

**桌面端**：
- 侧边栏固定在左侧
- 主内容区域自适应宽度
- 统计卡片 4 列布局

**移动端**：
- 侧边栏可折叠
- 汉堡菜单按钮
- 统计卡片 2 列布局
- 触摸友好的按钮大小

## 高级功能

### 1. 搜索和筛选

**实时搜索**：
- 在浏览记录和下载记录页面
- 输入关键词即时筛选
- 支持标题、作者、描述搜索
- 不区分大小写

**时间筛选**：
- 今天 - 显示今天的记录
- 最近 7 天 - 显示最近一周的记录
- 最近 30 天 - 显示最近一个月的记录
- 自定义范围 - 选择任意日期范围

**状态筛选**：
- 在下载记录页面
- 按成功/失败状态筛选
- 快速定位问题任务

### 2. 自定义 API 地址

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

在设置页面的"服务地址"中修改。

### 3. 下载参数配置

**分片大小**：
- 用于超长视频下载
- 范围：1-100 MB
- 默认：10 MB
- 较大的分片可提高速度，但占用更多内存

**并发下载数**：
- 同时下载的任务数
- 范围：1-5
- 默认：3
- 根据网络带宽和系统性能调整

### 4. 自动清理

**功能说明**：
- 自动删除超过指定天数的浏览记录
- 避免数据库过大
- 保持系统性能

**配置步骤**：
1. 进入设置页面
2. 启用"自动清理"开关
3. 设置清理天数阈值（1-365 天）
4. 保存设置

**注意事项**：
- 清理操作不可恢复
- 建议定期导出重要数据
- 下载记录不受影响

### 5. 强制重新下载

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

**使用场景**：
- 文件损坏需要重新下载
- 更新已下载的视频
- 测试下载功能

## 界面布局说明

### 侧边栏

**功能分组**：
- 主要功能 - 概览、浏览记录、下载记录、下载队列
- 工具 - 批量下载
- 系统 - 设置、帮助、主题切换

**导航特点**：
- 当前页面高亮显示
- 图标 + 文字标签
- 移动端可折叠

### 主内容区域

**页面头部**：
- 页面标题和描述
- 操作按钮（搜索、筛选、导出等）

**内容区域**：
- 卡片式布局
- 统计信息
- 数据列表
- 操作按钮

**底部区域**：
- 分页控件（如适用）
- 批量操作按钮

### 移动端适配

**汉堡菜单**：
- 点击展开/收起侧边栏
- 遮罩层防止误操作

**触摸优化**：
- 按钮大小适合触摸
- 滑动操作支持
- 响应式表格布局

## 故障排除

### 问题 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. 使用"加载示例"查看正确格式

### 问题 7：数据导出失败

**症状**：点击导出按钮无反应或提示错误

**原因**：
- 浏览器阻止下载
- 数据量过大
- 权限问题

**解决方案**：
1. 检查浏览器下载设置
2. 允许弹出窗口和下载
3. 尝试分批导出
4. 检查磁盘空间

### 问题 8：队列任务卡住

**症状**：下载队列中的任务长时间处于"下载中"状态

**解决方案**：
1. 查看下载记录页面的详细信息
2. 检查后端日志
3. 尝试暂停后重新开始
4. 如果持续失败，删除任务后重新添加

### 问题 9：搜索功能不工作

**症状**：输入搜索关键词后没有筛选结果

**解决方案**：
1. 确认输入的关键词正确
2. 尝试使用部分关键词
3. 检查是否有时间筛选冲突
4. 刷新页面重试

## 浏览器兼容性

### 推荐浏览器
- ✅ Chrome 90+ （推荐）
- ✅ Edge 90+
- ✅ Firefox 88+
- ✅ Safari 14+

### 功能支持
- ✅ 现代 ES6+ 语法
- ✅ Fetch API
- ✅ LocalStorage
- ✅ CSS Grid 和 Flexbox
- ✅ WebAssembly（用于解密）

### 不支持
- ❌ IE 11 及更早版本
- ❌ 旧版移动浏览器

## 安全注意事项

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

**原因**：
- 无身份验证机制
- 直接访问本地文件系统
- 可能暴露敏感信息

### 数据隐私
- 所有数据存储在本地数据库
- 浏览器 LocalStorage 保存设置
- 不会上传到任何服务器
- 导出的文件保存在本地

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

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

### 数据备份
建议定期导出重要数据：
- 浏览记录
- 下载记录
- 配置设置

导出的 JSON 文件可用于数据恢复。

## 键盘操作

### 支持的按键
- `Escape` - 关闭对话框、播放器或灯箱
- 视频播放器内支持空格键暂停/播放

### 移动端操作
- 点击汉堡菜单展开/收起侧边栏
- 滑动操作支持
- 触摸友好的按钮设计

## 使用技巧

### 1. 快速导航
- 使用侧边栏快速切换页面
- 移动端使用汉堡菜单
- 键盘快捷键提高效率

### 2. 批量操作
- 使用搜索和筛选缩小范围
- 全选后批量处理
- 导出前先筛选需要的数据

### 3. 数据管理
- 定期导出重要数据
- 启用自动清理避免数据过多
- 使用 CSV 格式便于 Excel 分析

### 4. 下载优化
- 根据网络情况调整并发数
- 超长视频适当增加分片大小
- 失败任务可在下载记录中重试

### 5. 主题选择
- 白天使用浅色模式
- 夜间使用深色模式
- 设置自动保存无需重复切换

## 相关文档

- [批量下载使用指南](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-12-07
