# swipeflow

**Repository Path**: singlr/swipeflow

## Basic Information

- **Project Name**: swipeflow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-07
- **Last Updated**: 2026-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# 刷Flow (SwipeFlow)

**轻量级网页版短视频播放器 · 类抖音交互体验 · 多数据源聚合**

![.NET 8](https://img.shields.io/badge/.NET-8-blue)
![Furion](https://img.shields.io/badge/Furion-4.9+-green)
![SqlSugar](https://img.shields.io/badge/SqlSugar-5.1+-orange)
![Vben Admin](https://img.shields.io/badge/Vben%20Admin-5.0-purple)
![Element Plus](https://img.shields.io/badge/Element%20Plus-2.x-blue)
![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)
![License](https://img.shields.io/badge/License-MIT-green)
![Status](https://img.shields.io/badge/Status-Active-blue)

</div>

---

## 项目简介

**刷Flow** 是一个基于 Web 的短视频播放器应用，提供类似抖音的竖屏全屏、上下滑动切换的沉浸式浏览体验。支持对接多种数据源——包括通过账号授权自动同步今日头条收藏视频、后台手动录入、JSON 批量导入等，可灵活扩展内容来源。

### 核心特性

- **沉浸式播放** — 竖屏全屏、上下滑动切换、自动播放/暂停
- **移动端适配** — 手势操作、内联播放、触屏优化
- **多数据源** — 支持头条收藏同步（Cookie 授权 + 浏览器抓取）、后台手动录入、JSON 批量导入
- **边抓边入库** — 收藏同步每抓到一批就按稳定内容 ID 去重写库，中途中断也不丢已抓数据
- **点开即播** — 头条直链过期自动刷新（常驻无头浏览器复用 + 按「并发刷新数」并行，单条约 2 秒；服务启动即预热浏览器）+ 同源流代理，封面自动本地化，绕开跨域与防盗链；视频本地转存可选（默认关闭，播放走在线直链）
- **用户互动** — 前端用户登录后可点赞、收藏视频，未登录按设备标识记录浏览
- **流畅体验** — 视频预加载、播放结束自动切换下一条、滑动窗口自动释放解码器
- **后台管理** — 基于 Vben Admin 5 + Element Plus 的可视化内容管理系统（含定时任务管理）
- **高性能后端** — .NET 8 + Furion + SqlSugar，RESTful API 自动生成

## 技术架构

```
┌──────────────────────────────────────────────────┐
│         前端播放器 (SPA，8004)                      │
│   Vue 3 + Vite + 原生 video + 自定义手势           │
└──────────────────────┬───────────────────────────┘
                       │ RESTful API（开发态跨域，发布态 /api 反代）
┌──────────────────────▼───────────────────────────┐
│          后端服务层 (.NET 8，5002)                  │
│   ASP.NET Core + Furion 4.9+ (动态 WebAPI ·        │
│   JWT 鉴权 · 统一异常处理 · Swagger)               │
├──────────────────────────────────────────────────┤
│          ORM 层 (SqlSugar 5.1+)                   │
│   CodeFirst 自动建表 · 链式查询 · 分页 · SQLite     │
└──────────────────────┬───────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────┐
│          数据与抓取层                               │
│   SQLite (Data/database.db) · Playwright 浏览器抓取 │
│   （收藏同步 / 直链刷新 / 账号授权）· 转存与封面本地化 │
└──────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────┐
│         管理后台 (SPA，8003)                        │
│   Vben Admin 5.0 + Element Plus + TypeScript      │
│   Monorepo (pnpm + Turborepo)                     │
│   视频/数据源/系统配置/定时任务管理                  │
└──────────────────────────────────────────────────┘
```

### 技术栈详情

| 层级 | 技术选型 | 说明 |
|------|----------|------|
| **后端框架** | .NET 8 + ASP.NET Core + Furion 4.9+ | 动态 WebAPI、依赖注入、JWT 鉴权、Swagger、统一异常处理 |
| **ORM** | SqlSugar 5.1+ | 高性能 ORM，CodeFirst 自动建表、链式查询、分页、SQLite 适配 |
| **数据库** | SQLite | 轻量级嵌入式数据库，零配置部署，库文件在 `Data/database.db` |
| **浏览器自动化** | Microsoft.Playwright | 头条授权登录、收藏页抓取、播放直链刷新（优先复用本机 Edge/Chrome，不下载内核） |
| **定时任务** | Quartz 3.22 + AdoJobStore | 自研调度方案：调度信息持久化到 SQLite 的 `QRTZ_` 表，任务定义与执行记录落在业务表 `quartz_job_definition` / `job_execution_log`，后台原生页面管理 |
| **管理后台** | Vben Admin 5.0 + Element Plus | Monorepo 架构，动态路由、细粒度权限、多主题 |
| **前端播放器** | Vue 3 + Vite + 原生 `<video>` | 竖屏全屏、跟手滑切、双指缩放/长按倍速等自定义手势 |

## 快速开始

### 环境要求

| 工具 | 版本要求 | 说明 |
|------|----------|------|
| .NET SDK | >= 8.0 | 后端运行环境 |
| Node.js | >= 22.18（推荐 24 LTS） | 前端 & 管理后台构建环境，Vben Admin 5 对 `engines` 有版本要求 |
| pnpm | >= 9.x | Vben Admin 5 使用 pnpm 管理依赖（client 也可用 npm） |
| Git | 最新版 | 代码版本管理 |
| 浏览器 | Edge 或 Chrome | 头条授权/抓取走 Playwright，优先复用本机浏览器内核，无需下载 Chromium |

### 安装步骤

#### 1. 克隆项目

```bash
git clone https://gitee.com/singlr/swipeflow.git
cd swipeflow
```

#### 2. 后端启动（.NET 8 + Furion + SqlSugar）

```bash
cd server/SwipeFlow.Web.Entry

# 还原 NuGet 包
dotnet restore

# 启动项目（首次启动自动创建 SQLite 数据库及表结构）
dotnet run
```

后端默认运行在 `http://localhost:5002`，Swagger 文档地址：`http://localhost:5002/swagger`

> Furion 的 SqlSugar 集成支持 CodeFirst 模式，首次启动时会自动根据实体类创建 SQLite 数据库和表结构，无需手动建表。

#### 3. 管理后台启动（Vben Admin 5 + Element Plus）

```bash
cd admin

# 安装依赖（仅支持 pnpm）
pnpm install

# 启动 Element Plus 版本
pnpm dev:ele
```

管理后台默认运行在 `http://localhost:8003`

#### 4. 前端播放器启动

```bash
cd client

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev
```

前端播放器默认运行在 `http://localhost:8004`

### 一键启动与发布（推荐）

约定：**编译产物统一输出到仓库根目录的 `./publish`（server / admin / client 三个子目录），运行只跑 publish 下的产物**。

```powershell
# 一键启动：检查依赖 → 结束占用 5002/8003/8004 的旧进程 → 编译发布到 ./publish → 启动
powershell -ExecutionPolicy Bypass -File .\start.ps1

# 只编译发布（不启动）
powershell -ExecutionPolicy Bypass -File .\publish.ps1
```

> `publish.ps1` 的行为约定：
> - 发布前会**自动停止占用 5002 / 8003 / 8004 的本地服务**（后端占用 `publish/server/Data` 与产物 dll、预览服务占用 `publish/admin`、`publish/client`，不停会报 `Access denied` 中断发布），发布完成后**不会自动重启**，需自行启动后端与 `tools/serve-publish.mjs`；
> - 识别范围**不只看端口**：崩溃/卡住后已不再监听端口、但仍加载着产物 dll 的**残留后端**也会被结束（2026-09-30 踩到过：这类进程让发布停在 `Access to the path 'e_sqlite3.dll' is denied`，而端口检查完全看不到它）。识别依据是「端口 + 命令行 + 主模块路径 + 已加载模块落在 `publish` 下」四者取并集，并在阶段 0 用「独占打开产物」再兜底探测一次；
> - 发布前会**自动备份运行时数据库**：把 `publish/server/Data/database.db`（含 `-wal` / `-shm`）复制到 `publish/.db-backups/database-yyyyMMdd-HHmmss.db`，只保留最近 10 份。需要手工恢复时，停掉后端后把备份复制成 `publish/server/Data/database.db` 即可；
> - 运行时数据目录 `Data` 采用「挪到 `publish/.server-data-stash` → 重新发布 → 挪回」的方式保留。若上一次发布**在挪走之后、挪回之前被中断**（Ctrl+C、关窗口、进程被杀），数据会滞留在暂存目录，此时脚本**不会删除**该目录（会改名成 `.server-data-stash-interrupted-<时间戳>` 并提示），需要人工确认后再清理；
> - 出错时会打印完整原因并**等待按键**，避免双击运行时窗口一闪而过看不到错误；自动化调用可加 `-NoPause` 跳过等待；
> - 若服务进程由**更高权限**启动（例如管理员终端、IDE 的自动化终端），普通权限既停不掉它、也读不到它的命令行与模块列表：脚本会在阶段 0 用「独占打开产物」兜底探测，打印被占用的具体文件（例如 `publish/server/runtimes/win-x64/native/e_sqlite3.dll`）并中止，此时改用**管理员身份运行本脚本**，或先手动结束该进程（`taskkill /F /PID <pid>`）再重试；用普通权限终端自行启动服务可避免这个问题；
> - 脚本内含中文，**必须保存为 UTF-8 with BOM**：Windows PowerShell 5.1 对无 BOM 的 UTF-8 文件按 GBK 解码，会把中文字符串里的引号解析错，导致脚本语法报错（表现为"闪退"）。

| 端 | 目录 | 本地地址 |
|----|------|----------|
| 后端 API | `publish/server`（`dotnet SwipeFlow.Web.Entry.dll`） | http://localhost:5002（Swagger：`/swagger`） |
| 管理后台 | `publish/admin` | http://localhost:8003 |
| 播放器 | `publish/client` | http://localhost:8004 |
| 定时任务 | 后台原生菜单（接口 `/api/admin/quartz-job/*`） | http://localhost:8003/#/job/list（任务列表、作业分析、设置；执行记录在任务列表右栏） |

- 8003/8004 由 `tools/serve-publish.mjs` 托管，并把 `/api` 反向代理到 5002。
- 重复发布时 `publish/server/Data`（SQLite 库、转存视频与封面，定时任务定义与执行记录也在库中）会原样保留；生产部署前请备份生产环境的 `appsettings.json`。
- 发布产物运行时的数据在 `publish/server/Data/database.db`，源码方式运行时数据在 `server/SwipeFlow.Web.Entry/Data/database.db`，两者互相独立。

## 项目结构

```
swipeflow/
├── server/                              # 后端项目（.NET 8 + Furion + SqlSugar）
│   ├── SwipeFlow.Web.Entry/             # Web 入口层（启动项目，监听 5002）
│   │   ├── Controllers/                 # 显式控制器（视频/访问记录/互动/数据源/认证/系统管理/定时任务）
│   │   ├── Quartz/                      # 自研 Quartz 基础设施（作业目录、调度同步、执行记录、分析、设置）
│   │   ├── Jobs/                        # Quartz 定时任务
│   │   │   ├── PlatformSyncJob.cs               # 平台收藏同步
│   │   │   ├── RefreshExpiredLinksJob.cs        # 播放直链保鲜
│   │   │   ├── PreheatVideosJob.cs              # 播放列表预热
│   │   │   ├── DownloadVideosJob.cs             # 视频转存 + 封面本地化
│   │   │   ├── RefreshAuthTokenJob.cs           # 第三方登录态刷新
│   │   │   ├── PlaybackSessionSettleJob.cs      # 播放会话结算（超时会话补记播放时长）
│   │   │   └── HttpRequestJob.cs                # 通用 HTTP 请求
│   │   ├── Handlers/ApiExceptionHandler.cs      # 全局异常处理（统一 JSON 响应）
│   │   ├── Logging/                     # 统一控制台日志格式（格式化器 + 角色映射）
│   │   │   ├── SwipeFlowConsoleFormatter.cs     # 五段格式：时间 类型 [角色或操作者] 动作: 详情
│   │   │   └── LogRoleCatalog.cs                # 日志类别 -> 中文角色映射
│   │   ├── Program.cs                   # 应用入口（DI、Swagger、Quartz 调度）
│   │   └── appsettings.json             # 应用配置（数据库、监听地址）
│   │
│   ├── SwipeFlow.Application/           # 应用层（业务逻辑）
│   │   ├── Dtos/Dtos.cs                 # 请求/响应模型
│   │   ├── Security/PasswordHelper.cs   # 密码哈希
│   │   └── Services/
│   │       ├── VideoService.cs                    # 视频列表、访问记录与排序
│   │       ├── InteractionService.cs              # 点赞/收藏
│   │       ├── VisitRecordService.cs              # 访问记录明细/统计/行为日志、浏览记录删除与清空
│   │       ├── PlaybackSessionService.cs          # 播放会话（开始/结束、时长与进度结算、超时结算）
│   │       ├── UserActionLogService.cs            # 用户行为日志写入（点赞/收藏/浏览视频）
│   │       ├── BaseSyncService.cs                 # 同步基类（边抓边入库 + 去重）
│   │       ├── ToutiaoSyncService.cs              # 头条收藏同步（浏览器拦截）
│   │       ├── DouyinSyncService.cs               # 抖音收藏同步（收藏夹分页抓取）
│   │       ├── ToutiaoAuthService.cs              # 头条授权与登录态刷新
│   │       ├── DouyinAuthService.cs               # 抖音授权（账号密码自动登录，保存 cookies + localStorage）
│   │       ├── ToutiaoPlayResolverService.cs      # 可播直链统一入口（按来源分派）
│   │       ├── DouyinPlayResolverService.cs       # 抖音直链解析与过期刷新
│   │       ├── DataSourceService.cs               # 数据源管理与手动同步
│   │       ├── ThumbnailLocalStorage.cs           # 封面本地化
│   │       ├── VideoLocalStorage.cs               # 视频转存（含本地文件清空）
│   │       ├── LocalTransferSettings.cs           # 本地转存开关读取（download_videos_enabled）
│   │       ├── BackgroundTaskCoordinator.cs       # 后台长任务互斥（避免同时驱动浏览器）
│   │       └── AuthService / SysUserService / SysDeptService / SysRoleService
│   │           / SysMenuService / SysConfigService
│   │
│   ├── SwipeFlow.Core/                  # 核心层（实体与运行时路径）
│   │   ├── Entities/                    # SqlSugar CodeFirst 实体
│   │   │   ├── VideoInfo.cs / VideoCategory.cs / UserVisitRecord.cs / UserActionLog.cs
│   │   │   ├── VideoLike.cs / VideoFavorite.cs / ThirdPartyAuth.cs
│   │   │   ├── DataSource.cs / SysEntities.cs / EntityBase.cs
│   │   │   └── QuartzJobDefinition.cs / JobExecutionLog.cs
│   │   ├── Logging/LogOperator.cs       # 日志作用域里的「操作者」（第三段显示浏览者）
│   │   └── Storage/RuntimePaths.cs      # AppRoot、Data 目录解析
│   │
│   ├── SwipeFlow.Database/              # 数据库层
│   │   ├── SqlSugarSetup.cs             # SqlSugar 注册、旧库补列与清理
│   │   ├── DbContext.cs                 # 数据库上下文
│   │   ├── QuartzSchemaScript.cs        # Quartz 调度表建表脚本（QRTZ_ 前缀，启动缺表才建）
│   │   └── SeedData.cs                  # 种子数据（默认配置、默认数据源、管理员、默认任务）
│   │
│   └── SwipeFlow.sln                    # 解决方案文件
│
├── admin/                               # 管理后台（Vben Admin 5 + Element Plus）
│   └── apps/web-ele/                    # Element Plus 子应用（监听 8003）
│       └── src/
│           ├── api/
│           │   ├── swipeflow.ts         # 业务接口（视频/数据源/系统配置/同步）
│           │   ├── job.ts               # 定时任务接口
│           │   ├── request.ts           # 请求客户端（统一认证与超时）
│           │   └── core/                # 登录、菜单、用户等基础接口
│           ├── components/              # 页面共用组件
│           │   └── video-preview-player # 视频预览播放器弹窗（视频管理 / 数据概览共用，按视频真实比例自适应，竖屏按高度撑满）
│           ├── router/routes/modules/   # 菜单路由
│           │   ├── video.ts             # 视频管理
│           │   ├── visit.ts             # 用户访问记录
│           │   ├── datasource.ts        # 数据源管理
│           │   ├── config.ts            # 系统配置
│           │   ├── job.ts               # 定时任务（一级菜单：任务列表、作业分析、设置）
│           │   ├── system.ts            # 用户管理
│           │   └── dashboard.ts / profile.ts
│           └── views/
│               ├── dashboard/overview/  # 数据概览（统计卡片、最近入库视频、平台账号、关键配置；点封面看大图、点标题开预览播放器）
│               ├── video/               # 视频管理（列表、关键词与来源搜索、JSON 批量导入、预览播放，播放器按视频真实比例自适应，竖屏按高度撑满）
│               ├── visit/               # 用户访问记录（8 个统计卡片 + 访问记录明细 + 行为日志两个选项卡，分页与关键词搜索，点封面预览播放）
│               ├── datasource/          # 数据源管理与授权（平台名称为枚举下拉：今日头条 / 抖音）
│               ├── config/              # 系统配置（四个选项卡 + 固定配置表单 + 保存）
│               ├── job/                 # 定时任务（任务列表、作业分析、设置；执行记录并入任务列表右栏）
│               └── system-user/         # 用户管理
│
├── client/                              # 前端播放器（Vue 3 + Vite，监听 8004）
│   └── src/
│       ├── components/
│       │   ├── VideoPlayer.vue          # 竖屏播放器（手势切屏、倍速、纯净模式、横屏）
│       │   ├── VideoCard.vue            # 卡片（点赞/收藏乐观更新）
│       │   ├── VideoGrid.vue            # 通用网格列表（分页加载、可配置单条删除与清空）
│       │   └── AuthPanel/               # 登录弹窗
│       ├── views/
│       │   ├── Home.vue                 # 首页信息流（推荐/收藏/频道/浏览记录上下文，播放会话与进度上报、按进度续播）
│       │   ├── Profile.vue              # 我的（浏览记录/喜欢/收藏，浏览记录支持分页、删除单条与全部清空）
│       │   └── Favorites.vue            # 收藏网格
│       ├── api/                         # video.ts / auth.ts / interaction.ts
│       ├── utils/device.ts              # 未登录设备标识
│       └── stores/user.ts               # 当前用户状态
│
├── tools/serve-publish.mjs              # 发布产物预览服务器（托管 admin/client，反代 /api）
├── publish/                             # 发布产物（server/admin/client，不入库）
├── start.ps1                            # 一键：清理端口 → 编译到 publish → 启动
├── publish.ps1                          # 一键：编译三端到 publish（保留 Data）
├── docs/                                # 项目文档
├── LICENSE
└── README.md
```

## 后端配置说明

### SqlSugar 数据库配置（appsettings.json）

```json
{
  "ConnectionConfigs": [
    {
      "DbType": "Sqlite",
      "ConnectionString": "DataSource=./swipeflow.db",
      "EnableUnderLine": false,
      "EnableDiffLog": false,
      "IsAutoCloseConnection": true,
      "InitKeyType": "Attribute"
    }
  ]
}
```

### SqlSugar 服务注册（SqlSugarSetup.cs）

```csharp
// server/SwipeFlow.Database/SqlSugarSetup.cs
public static void AddSqlSugarSetup(this IServiceCollection services, IConfiguration configuration)
{
    var connStr = ResolveConnectionString(configuration.GetConnectionString("Default"));

    var config = new ConnectionConfig
    {
        DbType = DbType.Sqlite,
        ConnectionString = connStr,   // 库文件固定落在「数据根目录/Data/database.db」
        IsAutoCloseConnection = true,
        InitKeyType = InitKeyType.Attribute
    };

    // SQL 日志默认关闭（不注册 AOP）：原先每条 SQL 都会在控制台打一行，高频查询会刷屏
    // 需要排查 SQL 时临时加回 db.Aop.OnLogExecuting 即可
    var db = new SqlSugarScope(new List<ConnectionConfig> { config });

    services.AddSingleton<ISqlSugarClient>(db);

    // 启动即建库建表（CodeFirst）
    db.DbMaintenance.CreateDatabase();
    foreach (var table in tables) db.CodeFirst.InitTables(table);

    EnsureLegacyColumns(db);   // 旧库补列（如 video_info.source_id / expire_time、sys_config.is_enabled）
    DropLegacyTables(db);      // 清理已被 user_visit_record 取代的 video_watch
}
```

### 实体示例（CodeFirst 自动建表）

```csharp
[SugarTable("video_info", TableDescription = "视频信息表")]
public class VideoInfo : EntityBase
{
    [SugarColumn(ColumnName = "title", ColumnDescription = "视频标题", Length = 200)]
    public string Title { get; set; }

    [SugarColumn(ColumnName = "cover_url", ColumnDescription = "封面地址", Length = 500)]
    public string CoverUrl { get; set; }

    [SugarColumn(ColumnName = "video_url", ColumnDescription = "视频播放地址", Length = 2000)]
    public string VideoUrl { get; set; }

    [SugarColumn(ColumnName = "expire_time", ColumnDescription = "播放地址过期时间（取到直链时记录，直链不带过期时间则为空）", IsNullable = true)]
    public DateTime? ExpireTime { get; set; }

    [SugarColumn(ColumnName = "source_id", ColumnDescription = "平台内容ID（稳定去重键，如头条 group_id）", Length = 100, IsNullable = true)]
    public string? SourceId { get; set; }

    [SugarColumn(ColumnName = "author", ColumnDescription = "作者", Length = 100)]
    public string Author { get; set; }

    [SugarColumn(ColumnName = "source", ColumnDescription = "来源标识", Length = 50)]
    public string Source { get; set; }

    [SugarColumn(ColumnName = "duration", ColumnDescription = "时长(秒)")]
    public int Duration { get; set; }

    [SugarColumn(ColumnName = "channel_id", ColumnDescription = "所属频道ID")]
    public int? ChannelId { get; set; }

    [SugarColumn(ColumnName = "like_count", ColumnDescription = "点赞数")]
    public int LikeCount { get; set; } = 0;

    [SugarColumn(ColumnName = "favorite_count", ColumnDescription = "收藏数")]
    public int FavoriteCount { get; set; } = 0;

    [SugarColumn(ColumnName = "sort_order", ColumnDescription = "排序")]
    public int SortOrder { get; set; }

    [SugarColumn(ColumnName = "status", ColumnDescription = "状态: 0正常 1垃圾箱 2已删除")]
    public int Status { get; set; } = 0;

    [SugarColumn(ColumnName = "status_reason", ColumnDescription = "移入回收站的原因（仅自动判定失效时写入，手动移入/恢复会清空）", Length = 200, IsNullable = true)]
    public string? StatusReason { get; set; }
}
```

> 直链探测或播放代理发现上游返回 **404**（内容被平台删除/下架）时，服务端会把该视频自动移入回收站，
> 并把原因写入 `status_reason`；管理后台「回收站」Tab 的「移入原因」列可查看。为避免签名/CDN 抖动误判，
> 只有**强制刷新直链重试后仍为 404** 才判定失效；403（签名过期）、超时等可重试错误不会移入回收站。

### 用户互动实体示例

```csharp
[SugarTable("video_like", TableDescription = "用户点赞记录表")]
public class VideoLike
{
    [SugarColumn(IsPrimaryKey = true, ColumnName = "video_id", ColumnDescription = "视频ID")]
    public long VideoId { get; set; }

    [SugarColumn(IsPrimaryKey = true, ColumnName = "user_id", ColumnDescription = "用户ID")]
    public long UserId { get; set; }

    [SugarColumn(ColumnName = "create_time", ColumnDescription = "点赞时间")]
    public DateTime CreateTime { get; set; } = DateTime.Now;
}

[SugarTable("video_favorite", TableDescription = "用户收藏记录表")]
public class VideoFavorite
{
    [SugarColumn(IsPrimaryKey = true, ColumnName = "video_id", ColumnDescription = "视频ID")]
    public long VideoId { get; set; }

    [SugarColumn(IsPrimaryKey = true, ColumnName = "user_id", ColumnDescription = "用户ID")]
    public long UserId { get; set; }

    [SugarColumn(ColumnName = "create_time", ColumnDescription = "收藏时间")]
    public DateTime CreateTime { get; set; } = DateTime.Now;
}
```

### 系统管理实体示例

```csharp
[SugarTable("sys_dept", TableDescription = "部门表")]
public class SysDept : EntityBase
{
    [SugarColumn(ColumnName = "parent_id", ColumnDescription = "上级部门ID")]
    public long? ParentId { get; set; }

    [SugarColumn(ColumnName = "dept_name", ColumnDescription = "部门名称", Length = 100)]
    public string DeptName { get; set; }

    [SugarColumn(ColumnName = "order_num", ColumnDescription = "排序")]
    public int OrderNum { get; set; }

    [SugarColumn(ColumnName = "status", ColumnDescription = "状态: 0正常 1停用")]
    public int Status { get; set; } = 0;
}

[SugarTable("sys_role", TableDescription = "角色表")]
public class SysRole : EntityBase
{
    [SugarColumn(ColumnName = "role_name", ColumnDescription = "角色名称", Length = 100)]
    public string RoleName { get; set; }

    [SugarColumn(ColumnName = "role_key", ColumnDescription = "角色权限标识", Length = 100)]
    public string RoleKey { get; set; }

    [SugarColumn(ColumnName = "order_num", ColumnDescription = "排序")]
    public int OrderNum { get; set; }

    [SugarColumn(ColumnName = "status", ColumnDescription = "状态: 0正常 1停用")]
    public int Status { get; set; } = 0;
}

[SugarTable("sys_menu", TableDescription = "菜单表")]
public class SysMenu : EntityBase
{
    [SugarColumn(ColumnName = "parent_id", ColumnDescription = "上级菜单ID")]
    public long? ParentId { get; set; }

    [SugarColumn(ColumnName = "menu_name", ColumnDescription = "菜单名称", Length = 100)]
    public string MenuName { get; set; }

    [SugarColumn(ColumnName = "menu_type", ColumnDescription = "菜单类型: M目录 C菜单 F按钮")]
    public string MenuType { get; set; }

    [SugarColumn(ColumnName = "path", ColumnDescription = "路由地址", Length = 200)]
    public string Path { get; set; }

    [SugarColumn(ColumnName = "component", ColumnDescription = "组件路径", Length = 200)]
    public string Component { get; set; }

    [SugarColumn(ColumnName = "perms", ColumnDescription = "权限标识", Length = 200)]
    public string Perms { get; set; }

    [SugarColumn(ColumnName = "icon", ColumnDescription = "菜单图标", Length = 100)]
    public string Icon { get; set; }

    [SugarColumn(ColumnName = "order_num", ColumnDescription = "排序")]
    public int OrderNum { get; set; }

    [SugarColumn(ColumnName = "status", ColumnDescription = "状态: 0正常 1停用")]
    public int Status { get; set; } = 0;
}

[SugarTable("sys_config", TableDescription = "系统配置表")]
public class SysConfig : EntityBase
{
    [SugarColumn(ColumnName = "config_name", ColumnDescription = "配置名称", Length = 100)]
    public string ConfigName { get; set; }

    [SugarColumn(ColumnName = "config_key", ColumnDescription = "配置键", Length = 100)]
    public string ConfigKey { get; set; }

    [SugarColumn(ColumnName = "config_value", ColumnDescription = "配置值", Length = 500)]
    public string ConfigValue { get; set; }

    [SugarColumn(ColumnName = "config_type", ColumnDescription = "配置类型: 0系统 1自定义")]
    public int ConfigType { get; set; } = 1;

    [SugarColumn(ColumnName = "remark", ColumnDescription = "备注", Length = 500)]
    public string Remark { get; set; }
}

[SugarTable("sys_user_role", TableDescription = "用户角色关联表")]
public class SysUserRole
{
    [SugarColumn(IsPrimaryKey = true, ColumnName = "user_id", ColumnDescription = "用户ID")]
    public long UserId { get; set; }

    [SugarColumn(IsPrimaryKey = true, ColumnName = "role_id", ColumnDescription = "角色ID")]
    public long RoleId { get; set; }
}

[SugarTable("sys_role_menu", TableDescription = "角色菜单关联表")]
public class SysRoleMenu
{
    [SugarColumn(IsPrimaryKey = true, ColumnName = "role_id", ColumnDescription = "角色ID")]
    public long RoleId { get; set; }

    [SugarColumn(IsPrimaryKey = true, ColumnName = "menu_id", ColumnDescription = "菜单ID")]
    public long MenuId { get; set; }
}
```

### 第三方登录配置实体示例

```csharp
[SugarTable("third_party_auth", TableDescription = "第三方登录配置表")]
public class ThirdPartyAuth : EntityBase
{
    [SugarColumn(ColumnName = "site_name", ColumnDescription = "站点名称", Length = 100)]
    public string SiteName { get; set; }

    [SugarColumn(ColumnName = "username", ColumnDescription = "用户名", Length = 100)]
    public string Username { get; set; }

    [SugarColumn(ColumnName = "password", ColumnDescription = "密码", Length = 200)]
    public string Password { get; set; }

    [SugarColumn(ColumnName = "site_url", ColumnDescription = "站点网址", Length = 500)]
    public string SiteUrl { get; set; }

    [SugarColumn(ColumnName = "api_url", ColumnDescription = "接口地址", Length = 500)]
    public string ApiUrl { get; set; }

    [SugarColumn(ColumnName = "cookies", ColumnDescription = "登录Cookie", Length = -1)]
    public string Cookies { get; set; }

    [SugarColumn(ColumnName = "token", ColumnDescription = "访问令牌", Length = 500)]
    public string Token { get; set; }

    [SugarColumn(ColumnName = "login_time", ColumnDescription = "登录时间")]
    public DateTime? LoginTime { get; set; }

    [SugarColumn(ColumnName = "expire_time", ColumnDescription = "失效时间")]
    public DateTime? ExpireTime { get; set; }

    [SugarColumn(ColumnName = "is_valid", ColumnDescription = "是否有效: 0无效 1有效")]
    public int IsValid { get; set; } = 1;

    [SugarColumn(ColumnName = "remark", ColumnDescription = "备注", Length = 500)]
    public string Remark { get; set; }
}
```

### 控制台日志格式（统一约定）

服务端控制台日志由 `SwipeFlow.Web.Entry/Logging/SwipeFlowConsoleFormatter.cs` 统一格式化，单行五段（时间、类型不加方括号，角色加方括号）：

```
2026-09-26 19:50:25 信息 [收藏同步] 抓取进度: 已滚动 3 次 / 已解析 20 条
```

| 段 | 说明 |
|----|------|
| 时间 | 年月日时分秒，如 `2026-09-26 19:50:25` |
| 类型 | 信息 / 警告 / 错误 / 调试 / 跟踪 / 致命，按日志级别映射 |
| 角色 | 日志来源模块，由 `LogRoleCatalog` 按日志类别映射（收藏同步 / 直链解析 / 头条授权 / 定时任务 / 数据库 / 接口异常等），未登记的业务类退化为类名，可随时在映射表补一条；日志作用域里推入了操作者时改显操作者（见下） |
| 动作 | 日志正文里第一个竖线 `\|` 之前的内容，输出时后接半角冒号 `: ` |
| 详情 | 竖线 `\|` 之后的内容；未按约定书写的框架日志，动作显示为 `-` |

约定：**写日志时消息模板统一写成 `"动作 | 详情"`**，例如
`_logger.LogInformation("抓取进度 | 已滚动 {Scrolls} 次 / 已解析 {Items} 条", scrolls, items)`；
异常堆栈另起一行完整输出。两个 PowerShell 脚本的 `Write-Log` 用同一套五段格式，消息同样按「动作 | 详情」书写：
`start.ps1` 角色固定为 `启动脚本`，`publish.ps1` 角色固定为 `发布脚本`。

第三段除了模块角色，还可以显示「操作者」（谁做了这件事）：调用方用 `_logger.BeginScope(new LogOperator(名称))`
推入 `SwipeFlow.Core/Logging/LogOperator.cs` 后，格式化器优先把它当第三段输出（`Program.cs` 里
`ConsoleFormatterOptions.IncludeScopes` 打开后格式化器才能读到作用域）。目前用于「浏览视频」日志 ——
`/api/video/stream/{id}` 代理成功时打印（本地文件分支同样打印），登录用户显示用户名（为空退回真实姓名），未登录显示「访客」；
一次播放会发起多次 Range 请求，只对首个请求打印，避免刷屏。客户端在播放地址上带 `userId` 查询参数：

```
2026-09-27 00:00:28 信息 [admin] 浏览视频: id=3109 直连：成功，标题=甜酷辣妹穿搭指南，粉嫩与酷炫的完美结合！
2026-09-27 00:00:30 信息 [访客] 浏览视频: id=3110 本地文件：成功，标题=示例视频
```

非头条来源（手动录入等）由客户端直接播放原始地址、不经过服务端，因此不会产生该日志。

#### 预取请求不计入「浏览视频」

播放器会为「下一条」提前挂上地址做缓冲（`VideoPlayer.vue` 的 `preloadNext`）。这种提前拉流不是用户
真的在看，所以客户端给这类地址加上 `prefetch=1`，`VideoController.PlayStream` 读到该参数时只代理字节流、
不打印「浏览视频」（`onStreamStarted` 传 null），重试分支也会带上该参数。判断规则只有一条：
`preloadNext && !autoPlay`，不能再掺入 `loaded` 这类会随加载状态变化的条件 —— 地址一旦变化，浏览器会按
新地址重新请求一次，那次请求就失去 `prefetch=1`、被误记成浏览。另外，还没加载的卡片不能渲染 `src=""`：
浏览器会把空地址当成一次非法媒体加载并触发 `error`，`onPlayError` 于是真的去拉一次流，同样会被误记。
因此未加载时 `src` 绑成 `undefined`（不渲染该属性），且 `onPlayError` 只在 `shouldLoad` 为真时处理。

框架自带的英文日志（ASP.NET Core 主机生命周期、Quartz 调度器初始化等）由格式化器里的翻译表译成中文：

```
2026-09-26 20:43:30 信息 [服务端] 正在监听: http://localhost:5002
2026-09-26 20:43:30 信息 [服务端] 运行环境: 生产
2026-09-26 20:43:30 信息 [定时任务] 调度器已启动: SwipeFlowScheduler_$_NON_CLUSTERED
```

翻译表见 `SwipeFlowConsoleFormatter.FrameworkMessages`（正则匹配原文、替换为「动作 | 详情」；
替换文本以竖线开头表示这句话没有动作，输出为 `[角色] : 详情`），
只覆盖已知会输出到控制台的消息；框架升级后新增的英文消息会原样输出（动作显示为 `-`），
按同格式补一条规则即可。`SqlSugar` 的 SQL 日志已关闭（见 `SqlSugarSetup.cs`）。

`System.Net.Http` 的出站请求日志（`开始处理 HTTP 请求 GET …`）信息量低且刷屏，已在 `appsettings.json`
里把 `System.Net.Http.HttpClient` 降到 `Warning`；需要看「哪个平台做什么操作」时，改由 `VideoController`
自己打印带平台与状态的日志。

#### 拉流日志与场景作用域

`VideoController` 代理上游字节流时会打印「拉取视频流」，一条日志就能看出**哪个视频、哪个平台、上游什么状态**
（该行排在「浏览视频」之后，符合「先有人看，再去拉流」的顺序；上游拒绝时同样打印，只是不会记浏览）：

```
2026-09-29 12:57:10 信息 [访客] 浏览视频: id=4829 直连：成功，标题=@李家杠：恍惚半生烂如泥…
2026-09-29 12:57:10 信息 [视频代理] 拉取视频流: id=4829 · 抖音 · 上游状态 206
```

同一个 `VideoController` 也会被「播放列表预热」与「直链保鲜」两个定时任务调用，为了不让它们的日志混进用户
浏览，这两个任务在逐条处理时用 `BeginScope(new SwipeFlow.Core.Logging.LogOperator("预热"/"保鲜"))` 推入场景
作用域，于是第三段显示为 `[预热]` / `[保鲜]`：

```
2026-09-29 12:51:02 信息 [预热] 刷新直链: 已刷新 id=4639 长度=517
```

注意该类型在 `SwipeFlow.Core.Logging` 命名空间下，任务里得写全名，否则编译不过。

#### 上游连不上不抛异常

直链域名偶尔会解析失败（`SocketException 11001 不知道这样的主机`，实测同一个 CDN 主机本机解析正常，
属于瞬时故障），也可能连接被拒/被重置、等待响应超时。这类情况**必须在代理内部消化**：以前异常直接冒到
上层，一次播放失败就打出一整页 `500` 堆栈，把控制台淹没。

现在 `ProxyStreamAsync` 通过 `SendUpstreamAsync` 发起上游请求，命中
`IsUpstreamUnreachable`（`HttpRequestException` / `SocketException` / `IOException`，以及非客户端主动
断开引起的取消）时只记录一行日志并按拉流失败返回，响应未开始写出时状态码给 `502`：

```
2026-09-29 14:43:03 信息 [视频代理] 拉取视频流: id=4691 · 头条 · 上游不可达（域名解析失败：dead-host-swipeflow-test.invalid）
```

随后仍走原有的恢复链路：强制刷新一次直链（新直链通常换到别的 CDN 主机）→ 重试成功则客户端无感；
两次都连不上（如不可刷新的来源）就给客户端 `502`。原因由 `DescribeUpstreamFailure` 翻译成
`域名解析失败 / 连接被拒 / 连接被重置 / 连接超时 / 等待响应超时` 并附上主机名。
注意区分：客户端自己断开（用户划走、切歌）由取消令牌识别，静默结束、不触发无谓的直链刷新。

### 接口实现方式（Furion 动态 WebAPI + 显式控制器）

服务类实现 `IDynamicApiController`，Furion 会自动注册为 WebAPI；同时在 `server/SwipeFlow.Web.Entry/Controllers` 下提供显式控制器，给出稳定的 `api/xxx` 路径并直接调用服务层：

| 控制器 | 路由前缀 | 说明 |
|--------|----------|------|
| `AuthController` | `/api/auth` | 用户注册、登录 |
| `VideoController` | `/api/video` | 视频列表、增删改、批量导入、访问上报、播放直链与流代理、封面 |
| `InteractionController` | `/api/interaction` | 点赞、收藏与状态查询 |
| `DataSourceController` | `/api/datasource` | 数据源增删改、账号授权、手动同步 |
| `AdminQuartzJobController` | `/api/admin/quartz-job` | 定时任务：任务列表与增删改启停、立即执行、执行记录、作业分析、设置 |
| `SysUserController` / `SysDeptController` / `SysRoleController` / `SysMenuController` / `SysConfigController` | `/api/system/*` | 系统管理 |
| `UserController` | `/api/user` | 前台用户信息 |

```csharp
// 服务层：server/SwipeFlow.Application/Services/VideoService.cs
public class VideoService : IDynamicApiController
{
    /// <summary>获取视频列表 - 传 userId 或 deviceId 时按访问记录排序</summary>
    public async Task<PagedResult<VideoInfo>> GetList([FromQuery] VideoQueryDto query) { /* ... */ }
}

// 控制器层：server/SwipeFlow.Web.Entry/Controllers/VideoController.cs
[ApiController]
[Route("api/video")]
public class VideoController : ControllerBase
{
    private readonly VideoService _videoService;
    private readonly ToutiaoPlayResolverService _playResolver;

    /// <summary>获取可立即播放的视频地址 - 头条过期直链会自动刷新</summary>
    [HttpGet("play-url")]
    public async Task<ActionResult> GetPlayUrl([FromQuery] long id, [FromQuery] bool force = false)
        => Ok(await _playResolver.ResolveAsync(id, force));
}
```

> 接口文档：`http://localhost:5002/swagger`。注释遵循仓库约定（XML 注释中禁用斜杠、全角括号与逗号，否则会影响 Knife4j 的锚点跳转）。

## 数据源接入

> **重要说明**：今日头条、抖音等平台没有面向第三方开发者的开放平台 API。以下方案基于用户身份登录获取登录态（Cookie），通过调用平台内部接口获取个人收藏数据，仅限个人学习研究使用。

### 方式一：第三方收藏同步

#### 整体架构

支持接入多个第三方平台的收藏列表，每个平台有独立的同步服务（继承 `BaseSyncService`），统一由定时任务 `PlatformSyncJob` 触发，平台级开关与间隔读 `SysConfig`：

```
┌──────────────────────────────────────────────────┐
│        定时任务调度（任务：平台同步）                  │
│   每分钟触发，遍历平台 → 查开关 → 按间隔节流 → 同步    │
└──────┬───────────────────┬───────────────────────┘
       │                   │
┌──────▼───────┐   ┌───────▼──────┐
│ 头条同步服务   │   │ 抖音同步服务  │  ... 可扩展更多平台
│ 浏览器拦截收藏 │   │ （待实现）    │
└──────┬───────┘   └───────┬──────┘
       │  抓一批回调一批（去重后立即入库）
┌──────▼───────────────────▼───────┐
│  video_info（source_id 去重 + 直链刷新） │
└──────────────────────────────────┘
       │ 认证信息来自 third_party_auth 表
       │（登录态由 RefreshAuthTokenJob 定时刷新）
```

#### 同步开关配置

在 `SysConfig` 中按平台配置开关与间隔，可在管理后台「系统配置」页面查看与修改。该页布局仿照「定时任务 - 设置」：卡片内按业务域分「今日头条 / 抖音 / 播放与存储 / 登录态与其它」**四个选项卡**，选项卡内是 label 居左、控件居右的配置表单：

- 选项卡内**按功能分区域块**：一个区块 = 一个功能（区块标题 + 功能说明 + 分隔线），区块内**每项配置各占一行**（行标签在左、控件在右、该配置的说明文字跟在控件右侧）
- 例如「今日头条」下有「收藏同步 / 播放直链保鲜 / 播放列表预热」三块，其中"播放列表预热"块内逐行为：启用、可播条数、最大扫描条数、失败重试间隔、安全余量
- 控件按配置值形态渲染：`true`/`false` → 开关；纯整数 → 数字输入框（带单位）；其它（如 `sync_toutiao_biz_ids`）→ 文本框；某配置被停用（`is_enabled=false`）时行内出现「已停用，点击启用」标记
- 行标签可悬停查看该配置在库中的配置键（如 `preheat_toutiao_scan_max`）
- 表单 **label 列统一 200px**：未归入功能的配置直接拿库里的 `configName` 当行标签，最长的一条实测需要
  168px，而原来的 120px 只留得下 108px 可用宽度，会把标签挤成两行且断点难看（如「定时任务执行历｜史」
  「定时任务HTTP主｜机白名单」），故按最长名称留出余量取 200px
- 右上角统一为「放弃修改 / 重新读取 / 保存设置」，**跨选项卡一次性提交**所有修改；选项卡标签用红色数字标记该组未保存项数
- 未归入任何功能的配置会在所属选项卡末尾的「其它配置」区块逐项列出，避免新增配置在页面上「消失」

| 配置键 | 默认值 | 说明 |
|--------|--------|------|
| `sync_toutiao_enabled` | true | 是否开启今日头条收藏同步 |
| `sync_douyin_enabled` | false | 是否开启抖音收藏同步 |
| `sync_toutiao_interval` | 21600 | 头条同步间隔（秒）；一次全量同步耗时较长，不建议调小 |
| `sync_douyin_interval` | 3600 | 抖音同步间隔（秒） |
| `sync_toutiao_biz_ids` | `[]` | 头条同步的「内容类型」过滤（JSON 数组，空数组=全部类型），在后台「系统配置 → 今日头条 → 收藏同步 → 内容类型过滤」中填写 |
| `sync_toutiao_max_count` | 0 | 头条同步的数量上限：只保留最新收藏的 N 条（0=不限），设置后同步结束时会把视频库里多出来的旧头条视频移除（已点赞或已收藏的不清理，其余优先清理累计观看不足 5 秒的），在后台「系统配置 → 今日头条 → 收藏同步 → 数量上限」中设置 |
| `refresh_toutiao_enabled` | true | 是否定时刷新过期的头条播放直链 |
| `refresh_toutiao_interval` | 900 | 头条直链保鲜检查间隔（秒） |
| `refresh_toutiao_concurrency` | 3 | 同时刷新视频直链的条数（1-8）：并发越高，整批直链过期时恢复越快，占用内存也越多 |
| `preheat_toutiao_enabled` | true | 是否提前检测播放列表并刷新即将过期的直链 |
| `preheat_toutiao_count` | 25 | 每个访问者要凑够的可播视频条数；凑不够时会继续往后检测 |
| `preheat_toutiao_scan_max` | 50 | 每个访问者最多扫描的播放列表条数：前面可播条数不足时向后扩展检测的上限 |
| `preheat_toutiao_interval` | 300 | 同一条视频直链刷新失败后的重试间隔（秒），仅用于失败退避 |
| `preheat_toutiao_margin` | 900 | 预热安全余量（秒）：直链剩余有效期不足该值时提前刷新 |
| `download_videos_enabled` | false | 是否开启视频本地转存：开启后才把头条视频下载到 `Data/videos` 并用本地文件播放；关闭时不下载、清理已转存文件并释放磁盘，播放一律走在线直链（本地文件往往带有平台版权声明片头） |
| `auth_token_enabled` | true | 是否定时自动刷新第三方登录态（头条 Cookie） |
| `auth_token_interval` | 86400 | 登录态自动刷新间隔（秒），默认每天一次 |

> 间隔类配置被停用时回退代码内缺省值；开关类配置被停用时视为关闭。

#### 登录态定时刷新

登录态（头条登录 Cookie）由 `RefreshAuthTokenJob` 定时刷新：先用已保存的 Cookie 静默续期，
确认失效时再用 `third_party_auth` 中保存的账号密码无头自动登录兜底；仍失败则把该条记录标记为失效并提示人工重新授权。
刷新后的登录态由收藏同步与播放直链解析统一复用，各视频无需再单独处理登录态。

> 该任务与其它内置任务（平台同步 / 直链保鲜 / 播放列表预热 / 视频转存 / 本地文件清理 / 健康检查）都已注册为调度条目，各自按 Cron 触发、再由任务内部按配置与防重入判断是否真正执行；后台左侧「定时任务」菜单（任务列表 / 作业分析 / 设置，执行记录在任务列表右栏）即管理这些调度条目。

#### 通用同步接口（边抓边入库）

基类统一负责开关校验、登录态读取、去重与入库；子类只负责「抓」——每抓到一批就回调 `onBatch`，不等整个收藏夹抓完：

```csharp
// server/SwipeFlow.Application/Services/BaseSyncService.cs
public abstract class BaseSyncService
{
    /// <summary>
    /// 拉取指定平台收藏列表，每抓到一批就回调 onBatch，由基类立即去重入库；
    /// 实现方不应先把全部数据攒在内存里
    /// </summary>
    protected abstract Task FetchFavoritesAsync(ThirdPartyAuth auth, Func<IReadOnlyList<VideoInfo>, Task> onBatch);

    public async Task<SyncResult> SyncFavorites()
    {
        // 1. 检查同步开关：sync_{SourceTag}_enabled 且配置项未被停用
        // 2. 读取 third_party_auth 中该平台的有效登录态

        // 3. 载入去重基线（只读一次）：
        //    稳定内容 ID（source_id，如头条 group_id）-> 库中主键；以及存量视频网址
        var existingIdMap = /* source_id -> Id */;
        var knownSourceIds = new HashSet<string>(existingIdMap.Keys);
        var knownUrls = /* 存量 video_url */;

        // 4. 每批数据到达即落库：先去重，再分流到「新增」与「存量刷新」
        async Task OnBatchAsync(IReadOnlyList<VideoInfo> batch)
        {
            foreach (var video in batch)
            {
                if (existingIdMap.TryGetValue(video.SourceId, out var dbId))
                    refreshRows.Add(video);              // 已有：刷新直链/标题/封面，不动点赞数、收藏数、状态
                else if (knownSourceIds.Add(video.SourceId))
                    newVideos.Add(video);                // 新内容：入库并登记，防止后续批重复
                else if (knownUrls.Add(video.VideoUrl))
                    newVideos.Add(video);                // 无稳定 ID 的历史数据按网址去重
            }

            await _db.Insertable(newVideos).ExecuteCommandAsync();                     // 新增
            await _db.Updateable(refreshRows)
                .UpdateColumns(x => new { x.Title, x.CoverUrl, x.VideoUrl, x.Author, x.Duration, x.UpdateTime })
                .ExecuteCommandAsync();                                                // 存量批量刷新
        }

        // 5. 抓取：抓多少入库多少，中途异常时已入库的数据保留
        await FetchFavoritesAsync(auth, OnBatchAsync);

        // 6. 回写认证表的登录时间
    }
}
```

要点：

- **增量入库** —— 每批（每个分页响应）到达就写库，不再等全部抓完；一轮同步半小时，中途失败也不会白跑。
- **三层去重** —— 同批内、跨批、与库内已有数据都只入库一次（新增的键会即时登记到 `knownSourceIds` / `knownUrls`）。
- **存量只刷新可播放字段** —— 直链带签名会过期，每次同步刷新 `video_url` / 标题 / 封面 / 作者 / 时长，不覆盖点赞数、收藏数、状态。
- **写锁重试** —— 同步、转存、直链保鲜会同时写 SQLite，偶发 `database is locked` 时短暂退避重试，避免整轮同步中断。

#### 今日头条同步实现

头条收藏接口已加入 `msToken` / `a_bogus` 反爬签名，直接用 `HttpClient` 调用会被风控返回空数据。因此改为浏览器模式：
用已保存的 Cookie 启动无头浏览器（优先复用本机 Edge/Chrome）打开「我的收藏」页，由页面自身携带签名请求
`/api/pc/list/user/feed?category=my_favorites`，程序拦截该响应解析条目，并持续滚动到底。

```csharp
// server/SwipeFlow.Application/Services/ToutiaoSyncService.cs
protected override async Task FetchFavoritesAsync(ThirdPartyAuth auth, Func<IReadOnlyList<VideoInfo>, Task> onBatch)
{
    var filter = await GetBizTypeFilterAsync();   // 内容类型过滤（空 = 全部）

    await CollectFavoriteItemsAsync(auth, async chunk =>
    {
        var batch = chunk
            .Where(x => x.Video != null)                                  // 图文类收藏没有直链，跳过
            .Where(x => filter.Count == 0 || filter.Contains(x.BizId))    // 按 log_pb.stream_biz_id 过滤
            .Select(x => x.Video!)
            .ToList();

        if (batch.Count > 0) await onBatch(batch);   // 立即去重入库
    });
}
```

收藏条目字段解析：

| 字段 | 取值位置 |
|------|----------|
| 稳定内容 ID（去重键） | `group_id_str` |
| 播放直链 | `video_play_info.video_list[0].main_url`，回退 `video.download_addr.url_list[0]` |
| 标题 | `title`，回退 `share_info.share_title` |
| 封面 | `first_frame_image_list[0].url` |
| 作者 | `user.name`，回退 `media_name` |
| 时长 | `video.duration` |
| 内容类型 | `log_pb.stream_biz_id` |

> 授权方式：在后台「数据源管理」填写账号密码后点击「账号密码登录并自动获取授权」，会弹出可见浏览器完成登录，
> 遇到滑块/短信验证需人工在窗口内完成，成功后自动回填完整 Cookie。
>
> 「平台名称」是固定枚举下拉（今日头条 / 抖音），不提供自由输入：后端按名称关键字匹配登录态
> （`third_party_auth.site_name` 含「头条」即头条来源、含「抖音」即抖音来源），手写「今天头条」这类写法会取不到授权。

#### 抖音收藏同步实现（收藏夹模式）

抖音网页接口带强签名（`a_bogus` / `x-secsdk-web-signature` / `msToken`），直接复刻请求会被风控。因此实现方式是：
把授权时保存的**浏览器存储状态**（cookies + localStorage，用 Playwright 的 storage state）注入浏览器 →
打开抖音收藏页 → **在页面上下文里 `fetch` 接口**（站点脚本会自动给页面内请求补签名）→ 自己控分页：

| 步骤 | 接口 | 说明 |
|------|------|------|
| 找收藏夹 | `GET /aweme/v1/web/collects/list/` | 按 `collects_name` 匹配配置项 `sync_douyin_collection`（默认「美女」），取 `collects_id`；没匹配到时错误信息会列出账号下真实的收藏夹名 |
| 拉作品 | `GET /aweme/v1/web/collects/video/list/?collects_id=xxx&cursor=&count=50` | 每页 50 条，`cursor` 是**扫描窗口偏移**（按 count 递增），必须用**响应里的 cursor** 续翻，并以 `has_more` 为准（单页可能 0 条而 `has_more` 仍为 1） |

字段映射：`aweme_id` → `source_id`、`desc` → 标题、`video.cover.url_list[0]` → 封面、`video.play_addr.url_list[0]` → 播放地址、
`video.duration`（毫秒 → 秒）、`author.nickname` → 作者；图文类没有视频直链会跳过。

| 关键点 | 说明 |
|--------|------|
| 必须有 localStorage | 抖音前端把一部分登录态放在 localStorage，**只注入 Cookie 会返回 `status_code=8 用户未登录`**；授权成功后会把 storage state 存进 `third_party_auth.cookies` 供同步复用 |
| 不能用无头浏览器 | 实测无头下接口回 `status_code=8`；同步用「有头但移到屏幕外」（`--window-position=-32000,-32000`）的浏览器 |
| 收藏夹数量与入库数不一致 | 抖音显示的「共 N 作品」包含已失效/不可见的作品，接口只返回有效作品。实测某夹子显示 348 条，接口 7 页共只返回 **109 条**（且全部可播），属正常现象 |
| 播放 | 直链防盗链：后端代理按域名补 `Referer: https://www.douyin.com/`（与头条一致） |

配置项（系统配置 → 抖音 → 收藏同步）：`sync_douyin_enabled`（开关，默认 false）、`sync_douyin_interval`（同步间隔，默认 3600 秒）、
`sync_douyin_collection`（同步的收藏夹名，默认「美女」）、`sync_douyin_max_count`（数量上限，默认 0=不限）。
授权入口在「数据源管理 → 抖音 → 编辑 → 获取授权」：默认「账号密码登录并自动获取授权」（自动填写账密，滑块/短信验证由人工在弹出窗口完成），
另有「改用扫码登录」备用。

#### 同步调度器（自研 Quartz 调度 + 任务内部节流）

定时任务在管理后台「定时任务」菜单中管理（子页为任务列表、作业分析与设置；数据由后端 `/api/admin/quartz-job/*` 提供）。其中「任务列表」页为左右两栏：左栏是可点选的任务列表，右栏展示所点任务的执行记录（含分页；执行记录没有独立菜单，入口就在这里，点击任意一行弹出「执行详情」，含触发时间、耗时、任务参数、结果文本与异常信息），任务的增删改查、启停与立即执行都针对左栏当前选中的任务。当前注册 9 个系统内置调度条目（下表按作业类型归纳，其中保鲜类型下挂了「头条直链保鲜」与「抖音直链保鲜」两条任务），是否真正执行由任务内部按配置与防重入判断：

| 任务 | 作用 | 默认 Cron | 节流依据 |
|------|------|-----------|----------|
| `PlatformSyncJob` | 遍历平台执行收藏同步 | `0 0 0/6 * * ?` | `sync_{平台}_enabled` + `sync_{平台}_interval` |
| `RefreshExpiredLinksJob` | 提前刷新即将过期的播放直链（**覆盖所有数据源**：按视频来源分派到头条/抖音各自的解析实现；本地转存开启时已本地化的视频跳过）。同类型注册两条：全量的「头条直链保鲜」与只扫抖音的「抖音直链保鲜」（`Source=douyin`，百条量级、约 3 小时有效期，单开一条低频任务即可刷完，不会与预热抢刷新资源）；节流与防重入**按任务分别记录** | `0 0/30 * * * ?`（全量）+ `15 0/20 * * * ?`（抖音，与预热整分第 0 秒、健康检查第 30 秒都错开） | 任务参数 `Source`（all 或留空=全部 - toutiao 仅头条 - douyin 仅抖音）+ `refresh_toutiao_enabled` + `refresh_toutiao_interval`（开关与间隔对整个保鲜机制生效，不区分平台与任务） |
| `PreheatVideosJob` | 播放列表预热：为每个访问者凑够可播视频（默认 25 条，前面不足时最多各扫前 50 条），**覆盖所有数据源**，按 `refresh_toutiao_concurrency` 分批并发刷新 | `0 * * * * ?`（每分钟；服务启动后立即补跑一次） | `preheat_toutiao_enabled`（每轮触发都检测，失败条目按 `preheat_toutiao_interval` 退避） |
| `DownloadVideosJob` | 视频转存到本地、封面本地化；关闭（默认）时清理已转存文件、只本地化封面 | `0 0/15 * * * ?` | `download_videos_enabled`（默认 false）+ 每轮限量 |
| `RefreshAuthTokenJob` | 静默续期第三方登录态 | `0 0 3 * * ?` | `auth_token_enabled` + `auth_token_interval` |
| `health_check`（`http_request`） | 请求自身视频列表接口探活 | `30 0/5 * * * ?` | 固定 Cron |
| `cleanup_local_files` | 清理本地转存目录中的残留文件与临时文件 | `0 30 4 * * ?` | 固定 Cron |
| `playback_session_settle` | 结算超时未结束的播放会话，把本次播放时长补记到访问记录 | `0 * * * * ?` | `playback_session_expire_seconds`（缺省 60 秒） |

- 作业类型目录共登记 8 种，除上表任务用到的类型外，还提供 `http_request`（通用 HTTP 请求）供自定义任务使用；保鲜类型带一个 `Source` 参数（all - toutiao - douyin）用于按来源拆任务。
- 执行记录按条数上限自动裁剪（`JobExecutionListener` 的保留策略），高频任务不会把 `job_execution_log` 撑大。
- 每个任务都有防重入标记，上一轮未跑完时本次跳过；涉及浏览器的长任务通过 `BackgroundTaskCoordinator` 错开，避免同时驱动多个浏览器。
- 让路优先级：转存任务 > 预热任务 > 全量保鲜。全量保鲜一轮要刷完整库（头条千条量级 × 1 小时有效期，远超其间隔，实际刷不完一轮）会一直占着闸门，因此转存与预热都会置位待办标志，保鲜任务检测到后尽快结束当前轮让出资源。**让路检查每处理 5 条做一次**（不是每条都查），否则只扫百条量级的来源限定任务（抖音）会刚开跑就被打断，长期刷不动。
- 抢闸门一律用「限时等待」而非非阻塞抢占：多个任务会在同一时刻触发（5/15/30 分钟周期在整点重合），非阻塞抢占会让后到的任务每次都抢不过、永远被跳过（保鲜任务曾因此长期空转）。保鲜任务等 1 分钟，转存与预热各等 3 分钟。
- 本地转存开启时，保鲜任务只处理「尚未本地化」的视频：已转存到本地的视频播放走本地文件，直链过期与否都不影响播放，刷新纯属白开浏览器；转存关闭时本地文件不参与播放，所有视频照常刷新。
- 为什么抖音单独一条任务：抖音直链只有百条量级、有效期约 3 小时，一条 20 分钟周期的任务就能全量刷完；头条则是数千条 × 1 小时有效期，全量刷新在吞吐上不可能跟得上（每分钟需要刷约 50 条），因此头条侧实际靠「播放列表预热」只保每个访问者前 50 条，全量那条（`Source` 留空即全部来源）作为兜底，并在遇到预热待办时让路。
- 任务定义与执行记录都落在 SQLite 库的 `quartz_job_definition` / `job_execution_log` 表，调度信息由 Quartz AdoJobStore 写入同一库的 `QRTZ_` 表，重复发布产物时会保留。

#### 播放列表预热（为每个访问者凑够可播视频，避免刷到时提示「正在刷新」）

头条直链带签名、有效期约 1 小时（过期时间写在直链路径里），过期后需重新用无头浏览器解析（常驻浏览器复用后单条约 2-4 秒）。若用户刷到某条视频时直链刚好过期，就会现场等待甚至提示「正在刷新视频播放地址，请稍后重试」。因此播放路径与后台任务共用同一套刷新机制：**常驻无头浏览器复用（只新建 Context）+ 按视频去重（同一视频只刷一次）+ 受 `refresh_toutiao_concurrency` 约束的并发**；播放请求最多等 10 秒，前端遇到「正在刷新」还会自动重试（最多 5 次、每次间隔 2 秒）。

`PreheatVideosJob`（默认每分钟触发一次；服务启动后立即补跑一次，避免重启后用户马上刷视频时无池可用）为每个访问者维持一个「可播池」：

1. 排序与播放器 `/api/video/get-list` 完全一致（没看过优先 → 点赞过 → 收藏过 → 看过没互动的）—— 对**每个访问者**（`user_visit_record.visitor_key`）按序从播放列表第一条往后逐条检测；尚无任何访问记录时退化为默认列表顺序（`sort_order` 升序 + ID 倒序）
2. 逐条调用 `ToutiaoPlayResolverService.ResolveAsync`，并传入**安全余量** `preheat_toutiao_margin`（默认 900 秒）：剩余有效期够用的秒回不动并计入可播池，不足该余量的立即在后台刷新补齐（成功后同样计入）
3. 每个访问者凑够 `preheat_toutiao_count`（默认 25 条）可播即停止，因此前面有不可播的（刷新失败、正被其它任务刷新）时会**继续往后检测**，最多扫到 `preheat_toutiao_scan_max`（默认 50 条）为止 —— 即「目标 25 条、最多看 50 条」
4. 按 `refresh_toutiao_concurrency`（默认 3）**分批并发刷新**：批内并发、批间按顺序累计可播条数，凑满目标条数即停；整批直链同时过期时，一轮耗时约降到串行的 1/并发数
5. 检测失败的条目在 `preheat_toutiao_interval`（默认 300 秒）内不再重试，避免反复开浏览器；返回「正在刷新」（正被其它任务刷新）的条目不算失败，下一轮继续
6. 本地转存开启时，已转存到本地的视频直接跳过（本地文件永不过期）；非头条来源同样跳过
7. 解析服务内部优先读 `video_info.expire_time`（取到直链/同步/录入时就按直链自带的过期时间写入：头条直链路径里的 8 位十六进制过期秒、抖音等直链的 `x-expires`），该列为空时再现场解析直链 —— 头条直链有效期 1 小时且过期时间可解析，因此剩余不足安全余量时就能**提前**刷新，而不是等链接失效后才刷新；解析不出过期时间时才退回「探测缓存 → 刷新窗口（窗口 = 60 分钟 - 安全余量）→ 秒级 Range 探测」，都不满足才开无头浏览器

> 播放路径调用同一解析服务，但安全余量用默认 60 秒 —— 只关心「此刻能不能播」；预热任务用更大的余量，关心「再过一会儿会不会过期」。

#### 同步流程总结

1. Quartz 任务 `PlatformSyncJob` 按 Cron 触发（默认每 6 小时），先查平台开关，再按 `sync_{平台}_interval` 判断是否到间隔
2. 从 `third_party_auth` 读取该平台的有效登录态（缺失或失效则跳过并提示重新授权）
3. 载入去重基线：存量 `source_id`（如头条 `group_id`）与存量视频网址
4. 平台服务开始抓取，**每抓到一批就回调入库**：命中已有 `source_id` 只刷新直链、标题、封面等可播放字段；新内容插入；同批内与跨批重复都只入库一次
5. 配置了 `sync_{平台}_max_count`（如 `sync_toutiao_max_count = 1000`）时，只取最新收藏的前 N 条——收藏列表按收藏时间倒序，抓够 N 条即停止翻页，超出部分不入库
6. 抓取结束后按上限裁剪：把该平台视频库里不在「最新 N 条」中的记录移除（连同本地转存文件、封面与点赞收藏、访问记录），仅在本轮确实抓到数据时执行，避免登录态失效等异常把存量清空。裁剪时有两条规则：
   - **已点赞或已收藏的视频不清理**（点赞/收藏数是视频上的 `like_count` / `favorite_count`，并会核对 `video_like` / `video_favorite` 互动记录兜底），这些视频会保留下来，实际总量可能略高于配置的上限
   - 其余待清理视频**优先清理「已观看但所有访问者累计观看不足 5 秒」**的（`user_visit_record.watch_seconds` 按视频汇总，即刚刷到就划走的低价值视频）；没看过或认真看过 5 秒以上的排在后面
7. 未配置数量上限时，线上已移除的收藏在本地保留不动
8. 同步结束后回写认证表的登录时间
9. 也可在后台「数据源管理」手动触发某平台的同步（该接口耗时可达数十分钟，前端超时单独放宽到 60 分钟）
10. 中途中断时已入库的数据保留，下一轮同步会重新抓取并刷新存量记录

### 方式二：后台手动录入

通过 Vben Admin 5 管理后台直接添加视频信息，新增时按 `video_url` 检测是否已存在，防止重复录入：

| 字段 | 类型 | 说明 |
|------|------|------|
| `title` | string | 视频标题 |
| `coverUrl` | string | 封面图地址 |
| `videoUrl` | string | 视频播放地址（MP4/HLS） |
| `author` | string | 作者名称 |
| `source` | string | 来源标识 |
| `duration` | int | 视频时长（秒） |
| `sortOrder` | int | 排序权重 |

### 方式三：批量导入

管理后台「视频管理」页提供批量导入：把 JSON 数组粘贴到导入弹窗后提交 `POST /api/video/batch-import`，
按 `video_url` 去重，已存在的条目自动跳过；接口返回 `总条数 / 新增条数`，页面会给出导入结果提示。

#### 去重策略

| 导入方式 | 去重依据 | 重复处理 | 覆盖更新 |
|----------|----------|----------|----------|
| 平台同步（头条） | `source_id`（头条 `group_id`）优先，`video_url` 兜底 | 不新增，只刷新直链、标题、封面、作者、时长 | 仅上述可播放字段 |
| 后台手动录入 | `video_url` | 提示已存在，不允许提交 | 否 |
| 批量导入 | `video_url` | 自动跳过，返回结果中体现新增条数 | 否 |

> 平台同步按 `source_id` 去重是必要的：头条直链带签名、每次同步都会变化，若按 `video_url` 去重会把同一条视频反复插入。

## 播放链路

头条视频直链（`*.toutiaovod.com`）带签名且有效期约 1 小时（过期时间写在直链路径里，可从路径解析出来），过期后返回 403，且跨域直连播放常被拒绝。为此做了三层处理：

| 环节 | 接口 / 服务 | 说明 |
|------|-------------|------|
| 播放前取直链 | `GET /api/video/play-url?id=&force=`（[ToutiaoPlayResolverService.cs](server/SwipeFlow.Application/Services/ToutiaoPlayResolverService.cs)） | `video_info.expire_time` 未过期时直接返回；已过期（或无过期时间记录、解析不出且超出 60 分钟新鲜窗口、探测也失败）则用无头浏览器打开落地页拦截媒体请求拿到新直链，回写 `video_url` 与 `expire_time` |
| 减少无头刷新 | `expire_time` 列 + 秒级 Range 探测 + 内存缓存 | 优先用库里记录的过期时间判断（取到直链时解析写入），无需探测；无记录时才做一次 Range 探测，命中缓存（10 分钟）则跳过浏览器刷新，避免「有效链也开浏览器」的十几秒等待 |
| 实际播放 | `GET /api/video/stream/{id}` | 本地转存开启且视频已转存时直接返回本地文件（原生支持 `Range` 拖动）；其余情况走同源流式代理：服务端拉取直链并透传 `Range` / `Content-Range`，返回 `200/206 video/mp4`，绕开跨域与防盗链 |
| 封面显示 | `GET /api/video/thumbnail/{id}` | 封面本地化到 `Data/thumbnails/{id}.jpg`，本地已有直接返回（浏览器缓存 7 天），下载失败则 302 回退在线封面地址 |

- 管理后台预览与播放器对头条源一律使用 `/api/video/stream/{id}`，不使用原始直链。
- 直链路径里带 8 位十六进制过期秒（`/{32位内容标识}/{8位十六进制过期秒}/video/tos/...`），**头条（toutiaovod.com）与抖音（douyinvod.com）结构一致、都会解析**并写入 `video_info.expire_time`，因此两个平台都能被「直链保鲜 / 播放列表预热」按剩余有效期提前续期（抖音此前未解析，`expire_time` 恒为空，只能靠每次现场探测判断是否过期）。
- 播放时上游返回 404 时，只有**强制刷新拿到新直链后仍然是 404** 才判定内容失效并自动移入回收站；刷新失败或直链未变化时保持原状，避免单次 404（CDN 抖动、防盗链拒绝）误伤仍可播放的视频。真正「内容已被删除」由解析器内的落地页 404 判定负责。
- 管理后台预览的 `play-url` 接口单独放宽超时到 60 秒（抖音等来源需要开无头浏览器抓取新直链，冷启动可能超过默认 10 秒）。
- 配合「直链保鲜」定时任务（每 900 秒检查一次），开启后播放基本走缓存、点开即播；若停用该任务，直链超过新鲜窗口后首次播放仍需现场刷新一次。
- 头条封面地址同样带签名会过期，需保持同步任务开启以刷新 `cover_url`，否则封面本地化会因 403 而失败。

## 播放器核心能力

| 能力 | 实现方式 |
|------|----------|
| 竖屏全屏 | 手机壳布局（桌面 420px 圆角边框 + 刘海，≤500px 全屏），原生 `<video>` 铺满 |
| 滑动切换 | 上下跟手滑动（位移 >80px 切换、否则回弹）+ 滚轮/键盘切屏 |
| 手势 | 双指张开进「纯净模式」、再张开逐级放大（上限 16x）并支持单指平移；长按 2 倍速；单击播放/暂停、双击点赞 |
| 进度拖动 | 竖屏仅屏幕下半带触发 seek（上半带让位给滑切），横屏全屏可拖，拖动时显示时间预览 |
| 横屏 | 容器整体 `rotate(90deg)` 铺满视口，并拦截返回键退出横屏 |
| 自动播放/暂停 | `IntersectionObserver` 判定当前屏，播放到 95% 自动切下一条 |
| iOS 内联播放 | `playsinline` + `webkit-playsinline` |
| 声音 | 有声起播，被浏览器自动播放策略拦截时降级静音并同步 UI |
| 预加载与释放 | 当前屏 `auto`、下一屏 `preload`，滑动窗口只保留当前 ±3 个视频的媒体缓冲 |

## 用户互动功能

| 功能 | 说明 |
|------|------|
| 用户注册/登录 | 前端播放器独立账号，JWT 鉴权 |
| 点赞 | 点击爱心图标点赞/取消点赞，本地乐观更新 + 串行队列同步计数 |
| 收藏 | 点击收藏图标收藏视频，可在个人中心查看 |
| 操作状态同步 | 已点赞/已收藏的视频状态随页面刷新保持 |
| 未登录引导 | 未登录用户点击操作按钮时弹出登录面板；浏览记录按设备标识（`localStorage` 中的设备 ID）记录 |
| 访问记录 | 记录首次/最近访问时间、访问次数、累计观看时长，并参与首页排序（未看过 > 点赞过 > 收藏过 > 看过） |

## 用户访问记录与行为日志

访问者身份统一由 `UserVisitRecord.BuildVisitorKey` 生成：登录用户为 `u:用户ID`，未登录为 `d:设备ID`；两者都缺失时不记录。

### 数据表

| 表 / 字段 | 说明 |
|-----------|------|
| `user_visit_record` | 汇总式：每个「访问者 + 视频」一行（联合主键 `visitor_key` + `video_id`）。字段：首次/最近访问时间、访问次数、累计浏览时长、**最近一次播放时长 `last_played_seconds`**、**播放进度 `last_position_seconds`**、是否点赞/收藏及对应时间 |
| `user_action_log` | 用户行为日志：访问者标识、登录用户ID、操作类型（1点赞 2取消点赞 3收藏 4取消收藏 5发表评论 6删除评论 7浏览视频）、关联视频、详情、浏览时长、操作时间 |

### 上报接口

| 接口 | 说明 |
|------|------|
| `POST /api/video/visit` | 访问上报（切屏或离开页面时）：累加访问次数与累计浏览时长、刷新最近访问时间，并写入一条「浏览视频」行为日志。页面隐藏/关闭时用 `navigator.sendBeacon` 保证请求发得出去 |
| `POST /api/video/start-playback` | 开始播放：服务端在内存记录开始时间 |
| `POST /api/video/end-playback` | 结束播放：按服务端时间差结算本次播放时长（写入 `last_played_seconds`），并记录播放进度 `last_position_seconds`（只推进不回退）；仅更新已存在的访问记录，不新增行 |
| `GET /api/video/my-visits` | 播放器「我的 - 浏览记录」分页列表（按最近访问倒序），附带访问次数、累计时长与播放进度 |
| `POST /api/video/delete-visit` | 删除当前访问者对某个视频的浏览记录 |
| `POST /api/video/clear-visits` | 清空当前访问者的全部浏览记录 |

`get-list` 在传入访问者标识时同样回填上述访问汇总字段，客户端据 `last_position_seconds` 续播（从上次位置继续，接近片尾则不续播）。

### 超时会话兜底

用户直接关闭浏览器等场景下播放会话不会结束，由定时任务「播放会话结算」（`PlaybackSessionSettleJob`，默认每分钟）按系统配置 `playback_session_expire_seconds`（默认 60 秒）自动补记播放时长；异常结算无法得知播放位置，只补时长。

### 管理后台「用户访问记录」

菜单 `用户访问记录`（`/visit`）提供两个选项卡：

- **访问记录**：8 个统计卡片（用户数、访问者数、浏览总次数、访问记录数、累计浏览时长、点赞总数、收藏总数、行为日志）+ 分页明细表（预览封面、视频、来源、访问者、访问次数、最近时长、播放进度、累计时长、点赞、收藏、最近观看、首次观看）；支持按访问者（用户名/昵称/设备标识）搜索；点击封面复用后台预览播放器播放。
- **行为日志**：分页展示点赞、取消点赞、收藏、取消收藏、浏览视频等操作明细，支持按操作类型与访问者筛选。

对应接口：`GET /api/admin/visit/list`、`GET /api/admin/visit/stats`、`GET /api/admin/visit/action-logs`。

## 开发路线图

> 图例：`[x]` 已在仓库中实现，`[ ]` 待办。

### Phase 1 — 基础框架搭建

- [x] 后端 .NET 8 + SqlSugar + SQLite 项目初始化
- [x] 管理后台 Vben Admin 5 (Element Plus) 项目初始化
- [x] 前端播放器 Vue 3 + Vite 项目初始化
- [x] 视频实体 CodeFirst 自动建表
- [x] 视频 CRUD 接口（显式控制器 + 服务层）

### Phase 2 — 核心功能

- [x] 竖屏滑动播放器（跟手滑切、手势缩放、长按倍速、横屏）
- [x] 管理后台视频管理页面（列表、关键词与来源搜索、新增/编辑/删除、JSON 批量导入）
- [x] JWT 鉴权 + 管理后台登录对接
- [ ] 视频文件上传（本地/OSS）
- [x] 前端用户注册/登录及点赞收藏功能

### Phase 3 — 系统管理（RBAC）

- [ ] 部门管理：树形结构、增删改查（后端接口已就绪，前端页面待补）
- [ ] 角色管理：角色 CRUD、权限标识配置（同上）
- [ ] 菜单管理：树形菜单、目录/菜单/按钮三级类型（同上）
- [x] 用户管理：用户 CRUD、分配角色
- [ ] 角色菜单关联：按角色分配菜单权限
- [x] 配置管理：系统参数键值对维护（含启用开关）

### Phase 4 — 头条收藏同步

- [x] 数据源与授权管理页面（账号密码登录自动获取 Cookie）
- [x] 头条收藏抓取与解析（浏览器拦截，支持内容类型过滤）
- [x] 同步服务 + 增量入库（`source_id` 去重 + 存量直链刷新）
- [x] 定时任务自动同步（自研 Quartz 调度，可开关与调间隔）
- [x] 登录态失效检测与自动续期（静默续期 + 账密兜底 + 失效标记）

### Phase 5 — 体验优化

- [x] 视频预加载与滑动窗口释放策略
- [x] 点赞、收藏交互（乐观更新 + 串行队列）
- [x] 播放直链保鲜、同源流代理与封面本地化
- [ ] 骨架屏与加载动画
- [ ] 视频转码与自适应码率（HLS）

### Phase 6 — 部署与运维

- [x] 一键脚本：本地编译发布与启动（`start.ps1` / `publish.ps1`）
- [ ] Docker 一键部署（docker-compose）
- [ ] Nginx 反向代理配置（生产环境需把 `/api` 代理到后端）
- [ ] CI/CD 自动化部署
- [ ] PWA 离线支持

## 部署

### 本机发布产物部署（当前方式）

```powershell
# 1) 本机编译发布到 ./publish（server / admin / client）
powershell -ExecutionPolicy Bypass -File .\publish.ps1

# 2) 把 publish 下的产物上传到服务器，按需启动后端并配置静态站点
```

- 后端：`publish/server`，入口 `dotnet SwipeFlow.Web.Entry.dll`，默认监听 5002（`appsettings.json` 中的 `Urls`）。
- 管理后台 / 播放器：`publish/admin`、`publish/client` 为纯静态产物，交给 Nginx 托管；`admin` 的 `VITE_GLOB_API_URL` 默认 `/api`，需由 Nginx 反向代理到后端。
- 必须持久化的运行目录：`server/Data`（SQLite 库、转存视频、缩略图，定时任务定义与执行记录也在库中）。
- **部署前先备份生产环境的 `appsettings.json`**（数据库路径、监听地址等），发布产物会覆盖该文件。
- Nginx 需要把 `/api` 反代到后端。

### Docker 部署（待补充）

仓库暂未提供 Dockerfile，以下为目标编排（端口与目录按本地约定）：

```yaml
# docker-compose.yml（示例，需先补各端 Dockerfile）
version: '3.8'
services:
  server:
    build:
      context: ./server
      dockerfile: Dockerfile
    ports:
      - "5002:8080"
    volumes:
      - ./data:/app/Data                  # SQLite 数据库、转存视频、缩略图
    environment:
      - ASPNETCORE_ENVIRONMENT=Production

  web:
    build:
      context: .                          # 构建并托管 admin(8003) 与 client(8004) 静态产物
      dockerfile: Dockerfile
    ports:
      - "8003:80"
      - "8004:80"
    depends_on:
      - server
```

## 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改（提交信息使用中文动作词开头，例如 `新增：播放结束自动切到下一个视频`，详见 `.trae/rules/git-commit-message.md`）
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 开源协议

本项目基于 MIT License 开源。

- 后端框架 Furion — MIT/Apache-2.0 双重协议
- ORM 框架 SqlSugar — MIT 协议
- 管理后台 Vben Admin — MIT 协议

> **合规提醒**：通过账号登录态（Cookie）获取的今日头条收藏数据仅限个人学习研究使用，不得用于商业用途。请遵守今日头条的服务条款，尊重内容创作者的版权。账号与 Cookie 信息请妥善保管，避免泄露。

---

**如果这个项目对你有帮助，欢迎在 [Gitee](https://gitee.com/singlr/swipeflow) 上 Star 支持一下！**