164 lines
8.3 KiB
Markdown
164 lines
8.3 KiB
Markdown
# 05-功能流程文档
|
||
|
||
> 本文按"角色 → 端到端流程"梳理当前项目的全部业务功能（截至 2026-10-18，App v1.3.7）。
|
||
> 技术实现细节见《02-技术文档》，接口字段见《03-接口文档》，数值参数以 `server/config.yaml` 与后台「系统配置」为准。
|
||
|
||
## 1. 角色与端
|
||
|
||
| 角色 | 使用端 | 能力 |
|
||
|---|---|---|
|
||
| 游客 | App | 每日免费观看 10 部、浏览/搜索（部分接口需登录） |
|
||
| 注册用户 | App | 观看计费、点赞/收藏/评论、充值/会员、邀请、上传（若开放）、提现 |
|
||
| 会员 | App | 有效期内观看不扣积分 |
|
||
| 管理员 | 后台 vm.256kb.top | super=全部；operator=仪表盘/套餐/赠送；reviewer=视频审核 |
|
||
|
||
## 2. 账号体系流程
|
||
|
||
### 2.1 注册
|
||
|
||
```
|
||
App 注册页（手机号/邮箱 Tab 切换）
|
||
├─ 手机号注册 → /auth/sms/send（短信宝）→ 填验证码+密码(+邀请码) → 注册
|
||
└─ 邮箱注册 → /auth/email/send（SMTP）→ 填验证码+密码(+邀请码) → 注册
|
||
│
|
||
├─ 验证码写 Redis（5 分钟有效，防刷频控）
|
||
├─ 填邀请码 → 建立 referral 绑定（风控：同人单日绑定≤10、同 IP 单日注册≤5）
|
||
└─ 可选「注册送试用会员」：后台开关 register_gift_trial.enabled / .days
|
||
```
|
||
|
||
### 2.2 登录与登录态
|
||
|
||
- 登录账号支持**手机号或邮箱**（不支持昵称）；密码 bcrypt 校验
|
||
- 令牌体系：`access_token`（短效）+ `refresh_token`（长效，Redis 白名单）
|
||
- App 收到 401 → 自动用 refresh 换新 access；**refresh 也失效/缺失 → 清登录态回游客**（防僵尸登录态）
|
||
- 全端下线机制：改密/后台改密后 `auth:epoch:{uid}` 递增并删除 refresh，旧 token 全部立即失效
|
||
- 后台管理员独立 `admin_token`（含角色， super 放行一切）
|
||
|
||
## 3. 观看与计费流程（核心）
|
||
|
||
```
|
||
打开 App → Splash（版本检查/app/version → 必要时弹更新）
|
||
→ Feed（推荐/最新/热度/口碑/热播 五 Tab，各自保活、独立翻页）
|
||
→ 进入某视频：
|
||
1. 播放器池加载（当前播放 + 下一个预缓冲；ts 走 App 内嵌缓存代理，命中免下载）
|
||
2. 计费判定（仅登录用户）：
|
||
├─ 会员有效期内 → 免费
|
||
├─ 今日免费额度未用完（10 部/日）→ 免费，额度-1
|
||
├─ 该视频今日已付过费（去重） → 免费
|
||
└─ 否则扣 1 积分/部；积分不足 → 弹充值引导
|
||
3. 观看上报 → watch_records（完播判定：进度≥95%）
|
||
```
|
||
|
||
- 数值：`points.daily_free_count=10`、`points.watch_cost=1`、`asset.complete_progress=0.95`
|
||
- 热度公式：`(播放×1 + 点赞×5 + 评论×10) ÷ (1 + 发布天数)`；口碑=按点赞量、热播=按播放量
|
||
- 评论奖励：每评论 10 个不同视频奖 1 积分（≥5 字，日限 5 次）
|
||
|
||
## 4. 充值与会员流程
|
||
|
||
### 4.1 积分充值
|
||
|
||
```
|
||
App「钱包/充值」→ 选套餐（后台可配 recharge_packages，1 元=10 积分，支持自定义金额）
|
||
→ 下单（recharge_orders，30 分钟超时自动关单）
|
||
→ 支付渠道：支付宝 / 微信 / USDT-TRC20（rate 7.2，19 确认）
|
||
（未配置真实密钥时服务端返回 dev_mock，App 走轮询查单兜底）
|
||
→ 回调/查单到账 → 积分入账（point_transactions）
|
||
→ 若该用户有邀请人 → 充值额的 5% 以资产返利给邀请人
|
||
```
|
||
|
||
### 4.2 会员
|
||
|
||
- 档位：试用 1 天 5 积分 / 月 30 天 300 / 年 365 天 3650 / 永久 10000（均可后台开关）
|
||
- 用**积分**兑换 → 写 user_membership + membership_orders；有效期内观看不扣积分
|
||
- 管理员可在后台「赠送管理」直接赠送会员/积分（operator 权限）
|
||
|
||
## 5. 邀请裂变流程（referral）
|
||
|
||
```
|
||
用户 A 分享邀请链接（h5.256kb.top/r/{code}）→ 用户 B 打开落地页下载 App
|
||
→ B 注册时带邀请码 → 绑定 referral
|
||
→ A 立即得 10 积分（register_reward_points，不限量）
|
||
→ B 在 72h 内观看≥3 个视频 → referral「激活」（周期任务结算）
|
||
→ B 每次充值 → A 得充值积分 5% 的资产返利
|
||
风控：A 单日新绑定>10 → 冻结审核；同 IP 单日注册>5 → 标记风险；后台「推荐风控」可人工处理
|
||
```
|
||
|
||
## 6. 创作激励与提现流程
|
||
|
||
```
|
||
作者发布视频（见 §8）→ 视频产生数据
|
||
→ 激励结算（周期任务）：
|
||
每 1000 次完整观看 = 1 资产；每 100 次点赞 = 1 资产（video_earnings → asset_wallets）
|
||
→ 资产价值：10 资产 = 1 元
|
||
→ 提现：满 100 资产（=10 元）可提，渠道 支付宝/微信/USDT，当前手续费 0
|
||
→ withdrawals 提交 → 后台「提现审核」人工通过/驳回 → 打款登记（asset_transactions 全程流水）
|
||
```
|
||
|
||
## 7. 互动功能流程
|
||
|
||
- **点赞/收藏**：即时生效，计入视频计数与热度分；收藏还用于推荐策略的标签偏好（收藏+5 > 点赞+3 > 观看+1）
|
||
- **评论**：发布前过**敏感词过滤**（后台可配词库与开关 `sensitive.filter.enabled`）；后台可删评
|
||
- **举报**：用户举报视频/评论 → reports → 后台「举报处理」（待处理/已处理/已驳回）
|
||
- **通知**：审核结果、结算、系统公告 → notifications → App 消息中心（未读数）
|
||
|
||
## 8. 内容供给流程（三条路）
|
||
|
||
### 8.1 用户/管理员上传
|
||
|
||
```
|
||
上传 mp4/mov/mkv/avi（≤500MB，时长 5~600s）
|
||
→ transcode_tasks 转码 HLS 720p（4s 分片）
|
||
→ videos.status=1 待审核 → 后台「视频审核」(reviewer) 通过/拒绝（拒绝填原因回显作者）
|
||
→ 通过：status=2 上架、通知作者、进入各 Feed 池
|
||
```
|
||
|
||
### 8.2 采集源同步（当前内容主力，约 1.8 万部）
|
||
|
||
```
|
||
后台「采集源管理」配置源站（URL 模板等）→ 手动「同步单源/全部同步」
|
||
→ collection_service 按模板拉取 → collection_records 记录明细（成功/失败/关联 video_id）
|
||
→ 入库存量视频直接上架（status=2）
|
||
```
|
||
|
||
### 8.3 标题关键词标签（离线脚本）
|
||
|
||
```
|
||
server/scripts/build_tags_from_titles.py（幂等，可重复跑）
|
||
→ jieba TF-IDF topK=6 + 番号/书名号/括号提取 - 噪音词过滤
|
||
→ 写 tags / video_tags，回算 tags.video_count
|
||
→ App 搜索热词/标签视频页、后台「标签管理」均消费此数据
|
||
```
|
||
|
||
## 9. 视频与后台管理状态机
|
||
|
||
**视频 status**：0 草稿 / 1 待审核 / 2 已上架 / 3 审核拒绝 / 4 已下架（后台可编辑标题/封面/分类/系列/剧集、上下架、删除——删除会级联清理标签/点赞/收藏/评论/观看/收益/举报）
|
||
|
||
**系列 series**：视频可绑定 series_id + episode_no 组成剧集；App 播放页提供选集；`total_episodes` 自动维护
|
||
|
||
**用户管理**：列表/详情（观看、充值、推荐关系）→ 可 封禁/解封（status 1/2/3）、调整积分（正负流水+原因）、**修改密码**（全端立即下线，记 admin_logs）
|
||
|
||
**其余后台能力**：仪表盘（今日 DAU/新增/充值/积分/播放+待审数）、积分流水、充值订单、套餐 CRUD、分类管理、提现审核、推荐风控、举报处理、敏感词、系统配置（白名单热改）、操作日志（admin_logs 全量留痕）
|
||
|
||
## 10. App 版本更新流程
|
||
|
||
```
|
||
deploy.sh 发版 → APK 覆盖 h5.256kb.top/downloads/video-app.apk
|
||
+ DB app.version.android 更新（latest/min/update_url/notice）
|
||
App 每次启动 → /app/version 比对本地真实 versionCode（package_info_plus）
|
||
├─ local < min_version_code → 强制更新弹窗（不可跳过）
|
||
├─ local < latest → 提示更新（可跳过），装新版后自动消失
|
||
└─ notice 非空 → 弹窗附带公告文案
|
||
```
|
||
|
||
## 11. 本地缓存与下载流程（App 端体验层）
|
||
|
||
```
|
||
播放：网络 m3u8 → 改写走 127.0.0.1 本地代理
|
||
├─ m3u8 每次回源（签名时效）→ ts 地址改写指向本地
|
||
├─ ts 按「去签名路径」磁盘缓存，命中直接返回（回看/重开 App 免下载）
|
||
└─ LRU 上限 1GB（超限按访问时间清到 900MB）
|
||
|
||
下载：Feed/播放页长按 →「下载」→ 拉 m3u8 → 4 并发下 ts+密钥 → 生成本地 index.m3u8
|
||
→「我的 → 已下载」列表（封面/时长/大小）→ 点击经本地代理离线播放（支持拖动）→ 可删除
|
||
```
|