up
This commit is contained in:
lz_db
+108
-18
@@ -56,14 +56,13 @@ video/ # 项目根目录（当前目录）
|
||||
- 游客不可点赞、收藏、评论、上传
|
||||
|
||||
#### 2.1.2 注册
|
||||
- **优先手机号注册**：手机号 + 短信验证码 + 密码
|
||||
- 备选邮箱注册：邮箱 + 邮箱验证码 + 密码
|
||||
- 注册页**手机号 / 邮箱 Tab 切换**：手机号 + 短信验证码 + 密码，或 邮箱 + 邮箱验证码 + 密码
|
||||
- 邮箱验证码由服务端**真实 SMTP 发送**（`POST /auth/email/send`），验证码写 Redis（`email:code:{email}`，600s），与短信验证码同一套校验机制
|
||||
- 注册即登录，返回 Token
|
||||
- 约束：手机号/邮箱全局唯一；密码 ≥ 8 位，含字母和数字
|
||||
|
||||
#### 2.1.3 登录
|
||||
- 手机号 + 密码，或 手机号 + 短信验证码
|
||||
- 邮箱 + 密码
|
||||
- 支持**手机号或邮箱**作为账号：手机号 + 密码 / 手机号 + 短信验证码 / 邮箱 + 密码
|
||||
- 登录成功后，游客时期的设备 ID 与账号可关联（观看记录合并，可选）
|
||||
|
||||
#### 2.1.4 资料管理
|
||||
@@ -189,7 +188,10 @@ App 调用「观看上报」接口
|
||||
|
||||
#### 2.5.4 视频播放
|
||||
- m3u8（HLS）流媒体播放，App 竖屏全屏沉浸式播放
|
||||
- 上滑/下滑切换视频，预加载下一个视频
|
||||
- 上滑/下滑切换视频；**3 槽播放器池**预加载：当前页播放 + 下一页预缓冲，划走即 stop（断音 + 中断缓存下载）
|
||||
- 切到"我的"等页面时播放器池**挂起（suspend）静音断流**，回到 Feed 且首页 Tab 可见才恢复（resume），修复"切页仍出声"问题
|
||||
- 网络 m3u8 播放地址改写为 **App 内嵌本地媒体代理**（127.0.0.1 HTTP 服务）：m3u8 每次回源保证签名时效，ts 分片落盘缓存（1GB LRU），支持拖动进度条（Range/206）；ts 流量直连源站 CDN，不经过业务服务器
|
||||
- 进度条拖动时显示**时间气泡**（x时xx分xx秒），标题后带**时长角标**
|
||||
- 记录播放量（进入播放即 +1，Redis 计数异步落库）
|
||||
|
||||
#### 2.5.5 视频标签（Tag）
|
||||
@@ -197,15 +199,20 @@ App 调用「观看上报」接口
|
||||
- 播放页在**标题后展示标签**（#标签 样式）
|
||||
- 点击标签进入"标签视频列表页"：展示该标签下全部已发布视频（支持 热度/最新 排序）
|
||||
- 标签是推荐策略中个性化加权的主要特征
|
||||
- 存量视频标签由**离线脚本批量生成**（server/scripts/build_tags_from_titles.py：jieba TF-IDF topK=6 + 番号/书名号提取 + 噪音过滤，幂等可重跑；已生成 2.2 万+ 标签、9.9 万+ 关联），后台提供"标签管理"页维护
|
||||
|
||||
#### 2.5.6 视频推荐策略
|
||||
Feed 支持三种策略，客户端通过接口参数切换：
|
||||
Feed 支持五种策略，客户端通过接口参数切换（App 顶部 Tab：推荐 / 最新 / 热度 / 口碑 / 热播，各策略独立保活分页状态）：
|
||||
|
||||
| 策略 | 说明 |
|
||||
|---|---|
|
||||
| recommend（默认） | 个性化推荐 |
|
||||
| latest | 最新发布倒序 |
|
||||
| hot | 热度倒序（播放/点赞/评论加权） |
|
||||
| hot | 热度倒序：热度分 = (播放×1 + 点赞×5 + 评论×10) / (1 + 发布天数) |
|
||||
| liked（口碑） | 按点赞量倒序 |
|
||||
| viewed（热播） | 按播放量倒序 |
|
||||
|
||||
> liked / viewed 为纯数值排序，游标采用（值, id）双键避免同值翻页丢失。
|
||||
|
||||
**个性化推荐（recommend）规则：**
|
||||
1. 候选池：全部"已发布"视频
|
||||
@@ -224,6 +231,13 @@ Feed 支持三种策略，客户端通过接口参数切换：
|
||||
- 搜索历史：App 端本地存储最近 10 条，不上报服务端
|
||||
- 搜索词先过敏感词过滤，命中直接返回空结果
|
||||
|
||||
#### 2.5.9 视频下载（离线缓存）
|
||||
- **入口**：Feed 页 / 播放页长按弹出菜单 →「下载」（已下载/下载中置灰）
|
||||
- HLS 视频：4 并发下载 ts 分片与 AES-128 密钥，改写为本地 index.m3u8；mp4 整文件直接下载
|
||||
- 下载过程展示进度，支持取消；失败自动清理半成品文件
|
||||
- 下载列表在「我的 → 已下载」；离线播放走本地媒体代理，支持拖动进度条
|
||||
- 已下载视频离线观看**不重复扣积分**（线上播放时已按正常规则计费）
|
||||
|
||||
### 2.6 互动模块
|
||||
|
||||
| 功能 | 规则 |
|
||||
@@ -330,7 +344,7 @@ Feed 支持三种策略，客户端通过接口参数切换：
|
||||
|---|---|
|
||||
| 仪表盘 | 今日/累计：DAU、新增注册、充值金额、积分发放与消耗、播放量、待审核数 |
|
||||
| 视频审核（人工） | 待审核列表（在线预览 m3u8）、通过、拒绝（必填原因）、已发布视频下架 |
|
||||
| 用户管理 | 搜索（ID/手机号/邮箱）、用户详情（钱包/会员/作品/流水）、封禁与解封 |
|
||||
| 用户管理 | 搜索（ID/手机号/邮箱）、用户详情（钱包/会员/作品/流水）、封禁与解封、**修改密码**（重置后 `auth:epoch` 递增，该用户全端 Token 立即失效） |
|
||||
| 积分管理 | 用户积分流水查询、手动加/减积分（原因必填 + 二次确认，写流水 biz_type=6） |
|
||||
| 订单管理 | 充值订单查询（状态/渠道/时间筛选）、异常订单人工补单（核实已收款后手动入账） |
|
||||
| 提现审核 | 提现申请列表、审核通过（线下打款后确认）/ 拒绝（自动退回资产） |
|
||||
@@ -338,6 +352,8 @@ Feed 支持三种策略，客户端通过接口参数切换：
|
||||
| 平台配置 | 注册赠送体验会员开关与天数等运营参数（system_configs 键值对，实时生效） |
|
||||
| 充值套餐管理 | 档位与赠送积分增删改、上下架、排序，实时生效 |
|
||||
| 活动运营 | 赠送体验会员/积分（支持单个或批量用户） |
|
||||
| 标签管理 | 标签列表查询（关联视频数）、重命名、删除（联动清理 video_tags） |
|
||||
| 采集源管理 | 采集源 CRUD（分类名 + 列表 URL 模板）、批量添加、单源/全部同步（后台异步采集外部单视频入库） |
|
||||
| 管理员管理 | 管理员账号增删、角色分配（超级管理员/审核员/运营）、操作日志查询 |
|
||||
|
||||
角色权限：超级管理员（全部）、审核员（仅视频审核）、运营（套餐/活动/看板）。
|
||||
@@ -369,6 +385,8 @@ Feed 支持三种策略，客户端通过接口参数切换：
|
||||
|
||||
### 3.1 表清单
|
||||
|
||||
现共 **30 张业务表**。Alembic 迁移链：`init_27_tables` → `add_collection_records` → `add_collection_sources`；线上数据量约 1.8 万视频。
|
||||
|
||||
| 表 | 说明 |
|
||||
|---|---|
|
||||
| users | 用户表 |
|
||||
@@ -397,6 +415,9 @@ Feed 支持三种策略，客户端通过接口参数切换：
|
||||
| notifications | 消息通知表 |
|
||||
| reports | 举报表 |
|
||||
| sensitive_words | 敏感词表 |
|
||||
| series | 系列（合集）表：多条视频组织成集数列表 |
|
||||
| collection_sources | 采集源配置表（分类名 + 列表 URL 模板） |
|
||||
| collection_records | 采集记录表（外部内容源 → 本站系列/视频映射，幂等导入） |
|
||||
|
||||
### 3.2 用户域
|
||||
|
||||
@@ -792,6 +813,47 @@ Feed 支持三种策略，客户端通过接口参数切换：
|
||||
| word | VARCHAR(50) | 敏感词，**唯一索引** |
|
||||
| created_at | DATETIME | |
|
||||
|
||||
### 3.10 采集域
|
||||
|
||||
#### series 系列（合集）表
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| id | BIGINT PK AUTO_INCREMENT | |
|
||||
| title | VARCHAR(100) | 系列标题 |
|
||||
| cover_url | VARCHAR(500) | 封面 |
|
||||
| description | VARCHAR(500) | 简介 |
|
||||
| author_id | BIGINT NULL | 作者 |
|
||||
| category_id | INT | 分类 |
|
||||
| total_episodes | INT DEFAULT 0 | 总集数 |
|
||||
| view_count | BIGINT DEFAULT 0 | 播放量 |
|
||||
| status | SMALLINT DEFAULT 1 | 1正常 0隐藏 |
|
||||
| created_at / updated_at | DATETIME | |
|
||||
|
||||
索引：`idx_series_cat_status(category_id, status)`、`idx_series_status_created(status, created_at)`；videos 表以 `series_id` 关联所属系列
|
||||
|
||||
#### collection_sources 采集源配置表
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| id | BIGINT PK AUTO_INCREMENT | |
|
||||
| name | VARCHAR(50) | 分类名（添加时自动建/找本站分类） |
|
||||
| list_url | VARCHAR(500) | 列表 URL 模板，`{{page}}` 为页码占位 |
|
||||
| category_id | INT UNSIGNED | 本站分类 id |
|
||||
| status | SMALLINT DEFAULT 1 | 1启用 0停用 |
|
||||
| last_sync_at | DATETIME NULL | 最近同步时间 |
|
||||
| created_at / updated_at | DATETIME | |
|
||||
|
||||
#### collection_records 采集记录表
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| id | BIGINT PK AUTO_INCREMENT | |
|
||||
| source_key | VARCHAR(50) | 内容源标识 |
|
||||
| source_id | BIGINT | 源站内容 id |
|
||||
| series_id | BIGINT NULL | 本站系列 id |
|
||||
| video_id | BIGINT NULL | 本站视频 id（单视频类） |
|
||||
| created_at | DATETIME | |
|
||||
|
||||
约束：唯一索引 `uk_source(source_key, source_id)` 保证幂等导入（重复同步不产生重复视频）；索引 `idx_record_series(series_id)`、`idx_record_video(video_id)`
|
||||
|
||||
---
|
||||
|
||||
## 4. 接口设计（概览）
|
||||
@@ -842,16 +904,19 @@ Feed 支持三种策略，客户端通过接口参数切换：
|
||||
| /mine/history | 观看历史 | |
|
||||
| /upload | 上传视频 | 选片→剪辑信息→发布 |
|
||||
| /search | 搜索 | |
|
||||
| /category | 分类页 | 按分类浏览视频 |
|
||||
| /tags/:name | 标签视频页 | 某标签下的视频列表 |
|
||||
| /mine/downloads | 已下载 | 离线视频列表（进度/删除/播放） |
|
||||
| /notifications | 消息通知 | 通知列表、未读标记 |
|
||||
| /settings | 设置 | 退出登录等 |
|
||||
|
||||
### 5.2 核心页面布局
|
||||
|
||||
#### 5.2.1 首页（视频 Feed）
|
||||
- 全屏竖向 PageView，每个页面一个视频播放器
|
||||
- 顶部：Feed 策略 Tab（推荐 / 最新 / 热度）+ 搜索图标
|
||||
- 全屏竖向 PageView，每个页面一个视频播放器（3 槽播放器池：当前页播放 + 下一页预缓冲，划走即停）
|
||||
- 顶部：Feed 策略 Tab（推荐 / 最新 / 热度 / 口碑 / 热播）+ 搜索图标；各策略分页状态独立保活，切 Tab 不丢进度
|
||||
- 右侧互动栏（自上而下）：作者头像（+关注预留）、点赞（红心+计数）、评论（气泡+计数）、收藏（星标+计数）、分享
|
||||
- 左下：作者昵称、标题（标题后展示 #标签，点击跳转标签视频页）、描述（展开/收起）
|
||||
- 左下：作者昵称、标题（标题后展示 #标签，点击跳转标签视频页；并带时长角标）、描述（展开/收起）
|
||||
- 底部（游客/非会员场景）：今日免费剩余次数提示条（剩余 ≤ 3 次时显示）
|
||||
|
||||
#### 5.2.2 评论页（底部弹层）
|
||||
@@ -885,6 +950,8 @@ Feed 支持三种策略，客户端通过接口参数切换：
|
||||
| 切换视频 | 垂直滑动，松手吸附；滑出即暂停，滑入自动播放并**上报观看计费** |
|
||||
| 单击屏幕 | 暂停 / 继续播放（暂停时显示播放图标） |
|
||||
| 双击屏幕 | 点赞动画（大爱心飘出） |
|
||||
| 长按屏幕 | 弹出操作菜单：下载视频 / 倍速 / 分享（已下载或下载中置灰） |
|
||||
| 拖动进度条 | 跟随 thumb 显示时间气泡（x时xx分xx秒，两端自动夹在屏内） |
|
||||
| 游客超限 | 播放第 11 个视频时弹出登录引导弹窗（"注册解锁更多视频，今日已看 10/10"） |
|
||||
| 用户积分不足 | 弹窗"积分不足"：去充值 / 开通会员 两个按钮 |
|
||||
| 扣费提示 | 每次扣积分播放时顶部 Toast"本次消耗 1 积分" |
|
||||
@@ -895,7 +962,7 @@ Feed 支持三种策略，客户端通过接口参数切换：
|
||||
|
||||
| 项 | 规范 |
|
||||
|---|---|
|
||||
| 主题 | 深色为主（#121212 背景），保证视频沉浸感；浅色可选（二期） |
|
||||
| 主题 | 深色为主（#121212 背景），保证视频沉浸感；浅色可选（二期）；**弹窗/底部菜单统一白底亮色**（局部包 `ThemeData.light()`，避免深色背景下文字看不清） |
|
||||
| 主色 | #FE2C55（红），辅助色 #25F4EE（青） |
|
||||
| 会员色 | 金色渐变 #F7D794 → #D4A017 |
|
||||
| 文字 | 主 #FFFFFF，次 #B0B0B0，弱 #6E6E6E |
|
||||
@@ -924,6 +991,25 @@ App 不内置固定 API 域名，启动时按以下流程动态获取：
|
||||
- App 启动及回到前台时调用 `GET /app/version`：返回最新版本号、是否强制更新、下载地址、维护公告
|
||||
- 强制更新：弹窗阻断使用并跳转商店/下载页；非强制：可跳过的提示弹窗；维护公告：全 App 只读提示
|
||||
|
||||
### 5.8 工程结构（与当前代码对齐）
|
||||
|
||||
```
|
||||
app/lib/
|
||||
├── screens/ # 页面：splash / home(HomeShell+IndexedStack) / feed / search / category
|
||||
│ # / player / membership / payment / wallet / assets / upload
|
||||
│ # / profile / auth / settings / notification / downloads
|
||||
├── providers/ # Riverpod 状态（12 个）：auth / feed / comment / wallet / member
|
||||
│ # / payment / profile / search / upload / asset / notification
|
||||
│ # / tag_videos
|
||||
└── core/ # 子系统：config（环境配置）/ media（local_media_server 本地代理、
|
||||
# download_manager 下载）/ network（api_client、域名发现）/
|
||||
# player（feed_player_pool 播放器池）/ storage（token、本地存储）/
|
||||
# theme / utils
|
||||
```
|
||||
|
||||
- Feed 策略状态按策略保活：`feedProviderFamily(strategy)` 每个策略一个独立 FeedNotifier；`activeFeedStrategyProvider` + `feedTabVisibleProvider` 配合 HomeShell（IndexedStack）在切页/回前台时挂起与恢复正确的播放器池
|
||||
- 401 兜底：无 refresh token 或刷新被拒时清登录态并跳登录页，防止"僵尸登录态"
|
||||
|
||||
## 6. 后端设计
|
||||
|
||||
### 6.1 框架推荐：**FastAPI**
|
||||
@@ -945,17 +1031,21 @@ App 不内置固定 API 域名，启动时按以下流程动态获取：
|
||||
```
|
||||
server/
|
||||
├── app/
|
||||
│ ├── main.py # 应用入口、中间件、路由注册
|
||||
│ ├── main.py # 应用入口、中间件、路由注册、lifespan（settle 周期任务启动）
|
||||
│ ├── core/ # 配置、日志、异常、安全(JWT/密码)
|
||||
│ ├── api/v1/ # App 路由层：auth/users/videos/interact/vip/pay
|
||||
│ ├── api/admin/ # 管理后台路由（独立管理员鉴权）
|
||||
│ ├── api/v1/ # 路由层（11 个文件）：admin / auth / common / incentives
|
||||
│ │ # / interactions / invite / media / membership / payments
|
||||
│ │ # / users / videos（管理后台同文件 /admin 前缀、独立管理员鉴权）
|
||||
│ ├── schemas/ # Pydantic 请求/响应模型
|
||||
│ ├── models/ # SQLAlchemy ORM 模型
|
||||
│ ├── services/ # 业务逻辑：计费、积分、会员、视频、互动
|
||||
│ ├── models/ # SQLAlchemy ORM 模型（30 张表）
|
||||
│ ├── services/ # 业务逻辑（17 个）：user/auth/wallet/video/interaction/membership
|
||||
│ │ # /payment/incentive/invite/admin/common/config/sensitive
|
||||
│ │ # /storage/transcode/settle/collection
|
||||
│ ├── payment/ # 支付适配层：alipay / wechat / usdt
|
||||
│ ├── tasks/ # Celery 任务：转码、播放量落库、订单关单
|
||||
│ └── utils/ # 短信、邮件、OSS、设备指纹
|
||||
├── alembic/ # 数据库迁移
|
||||
├── scripts/ # 离线脚本：build_tags_from_titles.py（标签生成）、采集脚本
|
||||
├── alembic/ # 数据库迁移（init_27_tables → collection_records → collection_sources）
|
||||
├── config.yaml # 业务参数配置（积分/会员/支付/上传限制）
|
||||
├── .env # 密钥类配置（不入库）
|
||||
└── docker-compose.yml
|
||||
|
||||
Reference in New Issue
Block a user