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