1. 用户生命周期业务逻辑
1.1 用户类型体系
系统支持三种用户类型,每种有不同的状态机:
| 类型 | userType | 创建入口 | 状态流转 |
| 普通用户 | NORMAL | 手机登录 / 微信登录 | 正常(1) → 冻结(-1) → 封禁(-2) |
| CP 供应商 | CP | 注册时选择 CP 类型 / 管理员创建 | 正常(1) + PENDING → APPROVED/REJECTED |
| 管理员 | ADMIN | 管理员创建 | 正常(1) |
1.2 注册/登录流程
POST /api/user/login (phone + code) POST /api/user/wechat-login (wxCode)
│ │
▼ ▼
查询 t_user WHERE phone=? OAuth: code → openid/unionid
│ │
├─ 存在 ────────────────────────────── 查询 t_user WHERE openid=?
│ (跳过) ├─ 存在: 更新昵称
│ └─ 不存在: INSERT t_user
▼
┌─ 新用户 ─────────────────────────────────┐
│ 1. INSERT t_user │
│ 2. initProfileAndWallet(userId): │
│ INSERT t_user_profile │
│ INSERT t_user_wallet (balance=0) │
│ 3. profileClient.initProfile(userId) │
│ 4. 异步 registerToIM(user): │
│ 4a. OpenIM 注册 drama_user_{id} │
│ 4b. 确保 ai_assistant 已注册 │
│ 4c. 双向添加好友 │
│ 4d. ai_assistant 发送欢迎消息 │
│ 5. 若 type=CP: │
│ 5a. 异步 spreeClient.createVendor() │
│ 5b. 回写 edd_wp_user_id 到 t_user │
└──────────────────────────────────────────┘
│
▼
┌─ 风控检查 ──────────────────────────────────┐
│ riskClient.check(deviceId, userId, "LOGIN") │
│ ├─ BLOCK → 403 "设备环境异常" │
│ └─ PASS/WARN → 继续 │
└────────────────────────────────────────────┘
│
▼
记录 lastLoginTime
记录登录日志 (t_login_log)
JWT 签发: sub=userId, phone, exp=7天
→ {token, user}
1.3 微信登录降级策略
当微信 OAuth API 不可达时,自动降级为测试模式:openid = "wx_" + abs(code.hashCode()),保证用户体验不中断。
1.4 用户行为追踪
LocalProfileService 同时维护内存统计(ConcurrentHashMap)与 MySQL 持久化:
- 行为类型: watch_start / watch_half / watch_complete / like / favorite / share / comment
- 内存实时追踪: behaviorStats(userId → {likeCount, favCount, watchCount, watchMinutes, genres})
- SQL 持久化: INSERT INTO t_user_behavior_log (异步)
- 画像更新: 每次行为上报后更新 t_user_profile.prefCategories, lastActiveTime
1.5 IM 社交体系
- 用户登录后自动注册到 OpenIM,ID 格式为
drama_user_{userId}
- 每个用户自动与 "ai_assistant" 建立双向好友关系
- 支持 P2P 文字/图片/语音消息发送
- 支持好友申请/通过/拒绝流程
- 未读消息通知通过 ConcurrentHashMap 维护,按 receiverImId 隔离
2. 内容生命周期业务逻辑
2.1 短剧数据模型
t_drama 是系统最复杂的实体,拥有约60+字段,涵盖:基础信息、分级审核、版权合规、广电总局要求的全字段。
合规字段(广电总局): copyrightType, copyrightProofUrl, authorizationChainUrl, broadcastPermitNumber, icpLicenseNumber, culturalOpsPermit, filingTier, filingNumber, isAiGenerated, 6个AI相关URL, 5个备案相关URL, legalRepresentative, organizationProfile 等。
2.2 三级审核状态机
checkStatus 状态码:
┌─────────────────────────────────────────────────┐
│ 1 草稿 │
│ 10 已提交 (CP → 平台) │
│ 20 一审中 / 21 一审通过 / 22 一审驳回 │
│ 30 二审中 / 31 二审通过 / 32 二审驳回 │
│ 40 三审中 / 41 终审通过 / 42 终审驳回 │
│ 50 已发备案号 (ISSUE_LICENSE) │
│ 60 已入库 (ARCHIVE) │
│ 70 已上架 (PUBLISH) │
└─────────────────────────────────────────────────┘
reviewLevel 当前审核级别: 1→一审 / 2→二审 / 3→三审
CP操作:
SUBMIT → checkStatus=10, reviewLevel=1, auditStatus=PENDING
管理员操作:
REVIEW → checkStatus=rLevel==1?20:30:40 (开始审核)
APPROVE → 按级别升级: 21→2 / 31→3 / 41→上架
REJECT → 22 / 32 / 42, 记录原因
ISSUE_LICENSE → 50, 填写备案号
ARCHIVE → 60
PUBLISH → 70, status=1 (上架)
UNPUBLISH → 60, status=0 (下架)
2.3 内容上传流程
CP 上传短剧:
1. 创建 Drama: POST /api/content/dramas
└─ 自动同步到推荐系统: recSyncClient.uploadContent()
2. 上传封面: POST /api/content/dramas/{id}/cover
3. 创建分集: POST /api/content/episodes 或 /episodes/with-video
└─ 视频上传到 OSS, videoUrl 回写
4. 导入弹幕: POST /api/content/bullets/import
└─ 支持 JSON 和 CSV 格式
└─ 通过 epNum → episodeId 自动映射
5. 关联商品: POST /api/content/dramas/{id}/products
6. 提交审核: POST /api/content/drama/{id}/audit (action=SUBMIT)
2.4 外部内容同步
速能自有剧同步 (POST /api/content/dramas/sync-sunaying):
- 数据源:
外部API (os.zgddj.com)
- 同步字段: name→title, img→cover(下载到本地), sum→totalEpisodes, story→description, icp_name→icpRecordNumber, views→clickRate
- 去重: 按 externalSource="sunaying" + externalId 判断新增/更新
- 图片: 代理下载到本地 ./uploads/sunaying_{id}.jpg
2.5 OSS 存储
使用阿里云 OSS,通过 GET /api/content/oss/sts 获取临时 STS Token(1小时有效),前端直传。
2.6 UGC 内容管理
支持用户生成内容(UserContent): 创建 → pending → admin审核(approve/reject) → 展示。含用户权限校验(仅本人可修改/删除)。
3. 变现体系业务逻辑
3.1 金币经济模型
| 操作 | 金币变动 | 类型 | bizType | 风控 |
| 每日签到 | +10 | EARN | SIGN_IN | 无 |
| 激励视频 | +50 | EARN | WATCH_AD | ✅ adId |
| 充值 | +amount×100 | RECHARGE | RECHARGE | ✅ amount |
| 消费(打赏等) | -coinAmount | SPEND | 自定义 | ✅ amount+bizType |
汇率: 1元 = 100金币。所有操作均使用 @Transactional 保证原子性,余额不足时拒绝消费。
3.2 广告激励闭环
广告激励完整流程:
┌─ APP ─────────────────────────────────────────────┐
│ 1. 请求广告位 → POST /api/ad/placements/{dramaId} │
│ 2. 创建广告记录 → POST /api/ad/record/create │
│ └─ 返回 adSign (UUID, 无连字符) │
│ 3. 展示广告 (GROMORE SDK) │
│ 4. 广告回调 → POST /api/ad/ecpm/save (eCPM上报) │
│ 5. 激励验证 → POST /api/ad/reward/verify │
│ └─ 幂等检查: transId 唯一 │
│ └─ 更新 adSign 状态为 COMPLETED │
│ └─ 返回 rewardCoin │
│ 6. 发放金币 → POST /api/coin/ad-reward/{userId} │
│ └─ 风控检查 adId │
│ └─ 余额 + rewardCoin │
│ └─ 记录交易流水 t_coin_transaction │
└─────────────────────────────────────────────────────┘
广告位类型:
- pre-roll (片头, 5s, +10币)
- mid-roll (片中, 15s, +20币)
- reward (激励视频, 30s, +50币)
- banner (横幅)
用户侧广告控制:
POST /api/ad/control → 返回禁看编码列表 + 每日上限 + 冷却时间
3.3 支付流程
POST /api/payment/create (userId, amount, channel)
│
▼
generateOrderNo: "PAY" + yyyyMMddHHmmss + UUID前10位
INSERT t_payment_order (status=PENDING)
│
▼
返回 {orderNo, amount, payUrl}
│
▼ (用户跳转支付)
POST /api/payment/callback/{channel}
│
├─ 签名验证 (placeholder: 全通过)
├─ 重复回调幂等: status=PAID → 直接 success
├─ trade_status=SUCCESS → update status=PAID
└─ 否则 → update status=FAILED
3.4 虚拟打赏
5 级礼物体系: 🌹鲜花(100金币/个), 🎁礼盒, 👑皇冠, 🚀火箭, 💎钻石
打赏后记录到 t_virtual_gift,前端通过 WebSocket 弹幕广播打赏动画。
3.5 Spree 商城购买回调
POST /wp-json/drama/v1/place-order (172.16.0.62)
│
▼ (支付完成)
POST /api/content/spree/purchase-callback
│
├─ 根据 email 查找 t_user
└─ INSERT t_user_prop (发放道具到用户账户)
4. 推荐系统业务逻辑
4.1 双模推荐架构
| 模式 | 开关 | 数据源 | 工作原理 |
| 外部推荐 | external.recommend.enabled=true | 172.16.0.63:8000 | HTTP REST 直调,透传返回给客户端 |
| 本地推荐 | external.recommend.enabled=false (默认) | Redis | 基于用户偏好分类的 Redis Set 取交集 |
4.2 本地推荐算法
localRecommend(userId, size):
1. 获取用户已看集合: SMEMBERS rec:user:{userId}:seen
2. 获取用户最佳偏好分类: getBestGenre(userId)
└─ HGETALL rec:user:{userId}:genres
└─ 取 count 最大的 genre
3. 获取该分类内容: SMEMBERS rec:genre:{bestGenre}
4. 排除已看 + 排除元数据 key(:genre)
5. 返回前 size 个 → RecController → Mock fallback
4.3 冷启动策略
- 无偏好用户: 返回热度排行榜 → Mock fallback 12 部短剧随机排序
- 游客模式: /api/rec/feed 无 userId → 返回 hotRank
- 新剧精选: /api/rec/new → Mock fallback 随机排列
4.4 行为反馈闭环
报告用户交互:
POST /api/rec/interaction
│
├─ 本地模式: Redis SADD rec:user:{id}:seen; HINCRBY genre
└─ 外部模式: POST /interaction → 172.16.0.63:8000
正向反馈:
POST /api/rec/feedback/positive → 外部模式透传
4.5 推荐降级策略
- 外部推荐服务不可达 → 自动回退到本地 Redis 推荐
- Redis 无数据 → 返回空列表 → RecController 调用 Mock fallback
- Mock fallback 含 12 部内置短剧(古装/都市/悬疑/科幻四类),通过确定性随机(hashCode + page)保证翻页不重复
5. AI 弹幕与 IM 对话业务逻辑
5.1 弹幕系统架构
┌─ 客户端 ──┐ ┌─ HTTP ──┐ ┌─ WebSocket (STOMP) ──┐
│ 发送弹幕 │──→│ POST /api│──→│ 保存 DB │
│ │ │/ai/bullet│ │ 广播 /topic/bullet/{id} │
│ │ │ /push │ │ │
└────────────┘ └──────────┘ └────────────────────────┘
↓
┌─ 客户端 ──┐ ┌─ HTTP ──┐ 所有已订阅该 topic 的客户端
│ 接收弹幕 │←────│ WS订阅 │ 实时接收 JSON payload
└────────────┘ └──────────┘
STOMP 配置:
- 端点: /ws/bullet (SockJS, 全来源跨域)
- 订阅: /topic/bullet/{dramaId}
- 发送: /app/bullet
5.2 AI 弹幕生成
GET /api/ai/bullets?episodeId={id}&timePoint={mm:ss}
- 优先从 DB 查已有弹幕(按时间点前缀匹配),无则返回 Mock AI 弹幕
- Mock 示例: "剧情高能预警!🔥" / "这段演技炸裂💯"
5.3 IM 对话架构
两种对话通路:
┌─ 通路A: SSE 流式 (APP 内) ───────────────────────┐
│ POST /api/user/im/chat/stream │
│ → deepSeekClient.chatStream(message, history) │
│ → 逐 token 推送到 SseEmitter │
│ → 完成后通过 OpenIM 发送完整回复 │
└─────────────────────────────────────────────────┘
┌─ 通路B: OpenIM WebHook (IM 内) ──────────────────┐
│ 用户发消息 → OpenIM │
│ → WebHook POST /api/ai/webhook/im-callback │
│ → ImWebhookController 处理 │
│ → 过滤: 仅 AI_USER_ID 为收件人、文本型、非自己 │
│ → callDeepSeek(sendId, userMessage) │
│ → sendImMessage(ai_assistant → user, reply) │
└─────────────────────────────────────────────────┘
5.4 对话历史管理
- 隔离: ConcurrentHashMap<sendId, List<role+content>>,每个用户独立
- 长度: 最多保留 20 条消息(10 轮对话),超量自动删除旧记录
- System Prompt: 固定角色设定 "你是融合短剧平台的AI追剧助手,名字叫小柠"
- API: DeepSeek v1/chat/completions, model=deepseek-chat, max_tokens=500
- 降级: DeepSeek API 失败时返回友好兜底回复
5.5 OpenIM 回调处理
- 接收命令: callbackBeforeSendSingleMsgCommand, callbackBeforeGroupSendMsgCommand
- 好友申请通知: callbackBeforeAddFriendCommand → 自动向被申请人发送通知
- 防止死循环: 过滤 AI 自己发出的消息(sendID != "ai_assistant")
- 仅文本响应: contentType=101 才触发 AI 回复
6. 风控引擎业务逻辑
6.1 设备指纹采集维度
| 类别 | 字段 | 权重 | 说明 |
| 设备信息 | manufacturer, brand, model, sysVersion, securityPatch, batteryLevel | - | 基线数据 |
| 唯一标识 | deviceId, oaid, imei, imsi, mac (均加密) | - | 设备去重 |
| 关键风险 | isEmulator | 40 | 模拟器检测 |
| 关键风险 | isRoot | 30 | Root 检测 |
| 关键风险 | isHook | 35 | Xposed/Frida Hook 检测 |
| 高风险 | isVpn, isProxy | 15/15 | 网络代理检测 |
| 中风险 | isDebug, isMultiOpen | 10/20 | 调试/多开检测 |
| 低风险 | isAccessibility, simState | 15/10 | 无障碍/无SIM卡 |
| 网络 | networkType, dnsServers | - | 网络环境 |
| 应用 | appVersion, appSignMd5, installedApps | - | 完整性校验 |
| 位置 | lng, lat | - | 地理位置 |
6.2 风险评分算法
RiskScorer.calculate():
score = 0
if isEmulator → score += 40
if isRoot → score += 30
if isHook → score += 35
if isVpn → score += 15
if isProxy → score += 15
if isDebug → score += 10
if isMultiOpen→ score += 20
if isAccessibility → score += 15
if noSIM → score += 10
if battery<5% && networkType=WIFI → score += 15 (可能是服务器机房)
return min(score, 100)
6.3 决策流水线
reportDevice(req):
1. 黑名单检查: isBlacklisted() → BLOCK (终止)
2. 设备指纹: 新建或更新 t_device_fingerprint
3. 风险评分: RiskScorer.calculate()
4. 自动拉黑: score≥80 → INSERT t_blacklist
5. 规则引擎: 逐一匹配所有 enabled 规则
├─ 先匹配黑设备规则 (BlackDeviceRule)
└─ 再匹配通用规则 (RuleEngine)
6. 记录事件: t_risk_event
checkRisk(req):
1. 屏蔽检查: shieldingConfig → BLOCK (终止)
2. 黑名单检查: blacklist → BLOCK (终止)
3. 无指纹: 新设备 → PASS (score=30)
4. 有指纹: ruleEngine.decide(score, actionType)
├─ score≥80 → BLOCK
├─ score≥50 → WARN
└─ score<50 → PASS
6.4 覆盖场景
| 场景 | actionType | 调用时机 | 降级策略 |
| 登录 | LOGIN | UserController.login() 签发JWT前 | 服务不可达→PASS |
| 下单 | ORDER | TradeController.createOrder() | 服务不可达→PASS |
| 充值 | RECHARGE | CoinController.recharge() | 服务不可达→PASS |
| 消费 | SPEND | CoinController.spend() | 服务不可达→PASS |
| 提现 | WITHDRAW | WalletController | 服务不可达→PASS |
| 广告奖励 | AD_WATCH | CoinController.adReward() | 服务不可达→PASS |
| CP审核 | CP_REVIEW | UserController.reviewCp() | 服务不可达→PASS |
6.5 风控管理层
- 规则热加载: POST /api/risk/rules/reload → 从 DB 重新加载全部规则
- 客户端规则下发: GET /api/risk/rules/config → APP 获取检测规则配置
- 管理面板: /api/risk/blackcube/* → 黑设备/无障碍/定位/应用/Ping 异常管理
- 手动操作: /api/user/admin/users/{id}/risk-action → 封禁/解封/标记风险/加入黑名单
7. CP 管理与收益结算业务逻辑
7.1 CP 注册与审核
CP 注册流程:
用户选择 CP 类型注册
→ INSERT t_user (userType=CP, verifyStatus=PENDING)
→ 异步: spreeClient.createVendor(dramaUserId, username, displayName)
└─ POST /wp-json/drama/v1/sync-vendor (action=create) → 172.16.0.62
└─ 成功 → 回写 edd_wp_user_id 到 t_user
管理员审核:
→ GET /api/user/admin/cp-review (status=PENDING)
→ POST /api/user/admin/cp-review/{id}?action=approve
├─ 风控检查: riskClient.check(deviceId, userId, "CP_REVIEW")
├─ BLOCK → 403 拒绝
├─ 异步: spreeClient.approveVendor(dramaUserId)
│ └─ 激活 shop_vendor 角色
└─ update verifyStatus=APPROVED
7.2 道具资产管理
道具添加流程:
POST /api/content/props (Authorization, productId)
│
├─ 去重检查: 调用 8089 查询是否已存在该道具
├─ 提交分销申请: productSyncClient.applyDistribution(productId)
├─ 签约: POST /api/sync/props/sign → 8089
├─ 本地存储: INSERT t_prop_asset
└─ 异步同步到 Spree: syncToSpree()
├─ 查询 CP 的 edd_wp_user_id
└─ spreeClient.syncProduct(productId, wpUserId, ...)
7.3 收益模型
| 收益来源 | 数据来源 | Mock 参考值 |
| 广告分成 | t_ad_watch_log 聚合 | 12,500 |
| 商品佣金 | t_order 按 productId 聚合 | 3,800 |
| 打赏收入 | t_virtual_gift 聚合 | 2,100 |
| 总计 | CP 收益看板 | 18,400 |
7.4 商品关联体系
- 短剧 ↔ 商品: t_drama_product_rel (支持精确到分集+时间点)
- 商品来源: 选品中台 (drama-product-sync:8089) + Spree 商城 (172.16.0.62)
- 道具资产: t_prop_asset (CP 自有道具) → 可关联到短剧
- 分销申请: 调 8089 完成签约 → 同步到 Spree 商城
7.5 选品中台同步服务
drama-product-sync (8089) 是一个独立 Spring Boot 应用,提供:
- 商品管理后台 (Thymeleaf + Bootstrap 5.3)
- 全量/增量同步 API
- 道具签约接口
- CP 管理界面
- 不注册 Nacos,Gateway 直连
8. 业务风险与边界条件分析
8.1 已知风险点
| 风险域 | 问题 | 影响 | 当前措施 |
| 支付 | 签名验证为 placeholder(全通过) | 可被伪造回调 | 标记 TODO,开发环境接受 |
| IM | 对话历史纯内存(ConcurrentHashMap) | 重启丢失 | 影响有限(仅 20 条历史) |
| 推荐 | 外部推荐默认关闭,本地推荐依赖 Redis | Redis 故障回归 Mock | 三层降级保护 |
| 金币 | 无分布式锁,单机 @Transactional | 并发充值可能超扣 | 当前单机部署 |
| 风控 | 服务不可用时默认 PASS | 绕过风控 | 业务可用性优先 |
| 数据库 | 多处直接 JDBC 硬编码连接 | 连接泄漏风险 | 应在 DataSource 统一管理 |
| 异步操作 | new Thread() 裸线程 | 线程不受控 | 应使用线程池 |
| JWT | 7 天超长有效期,无 refresh mechanism | Token 泄漏风险 | RS256 非对称签名不可伪造 |
8.2 边界条件
- 游客模式: /api/rec/feed 无 userId 时自动返回热度榜,不要求登录
- 广告回调: transId 唯一性保证幂等,防止重复发放金币
- 支付回调: status=PAID 的订单直接返回 success,防止重复处理
- CP 重复注册: createVendor 已是幂等操作,WP bridge 处理重复请求
- 微信 OAuth 降级: 网络不可达时自动降级为测试模式
- 内容同步去重: externalSource + externalId 联合唯一判断
- 画像初始化: UserController.initProfileAndWallet 先查后插,幂等
8.3 数据一致性
- 金币操作全部 @Transactional,余额不足时拒绝并返回提示
- 设备和用户状态变更记录操作日志(t_risk_event, t_login_log)
- Spree 同步失败不影响主流程(独立的异步线程)
- 内容审核记录审计日志(t_content_audit_log)
- 行为追踪双写(内存 + SQL),内存优先读取,SQL 用于持久化和恢复