# 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
  →「我的 → 已下载」列表（封面/时长/大小）→ 点击经本地代理离线播放（支持拖动）→ 可删除
```