docs: 业务逻辑矛盾深度分析报告

docs/业务逻辑矛盾分析报告.md

@@ -0,0 +1,277 @@
+# 糖心Fans v2.0 — 业务逻辑矛盾分析报告
+
+> 分析日期：2026-03-31
+> 分析范围：全部项目文档交叉比对（PRD确认清单、模块开发顺序、用户端API产品视角、运营后台API产品视角、数据库设计文档、用户端API技术视角）
+
+---
+
+## 一、🔴 重大矛盾（阻塞开发，必须立即解决）
+
+### 矛盾1：首充赠送规则——固定金额 vs 百分比
+
+- **矛盾描述**：PRD 明确首充赠送为"固定币数"，但技术视角 API 的全局配置接口返回的却是"百分比"字段。
+- **涉及文档**：
+  - `PRD_v1.2_需求确认清单.md` → 五、充值系统 第2条：「运营后台配置**固定赠送币数**（如50币），与档位bonus独立」
+  - `API-接口设计文档-技术视角.md` → CONFIG-01 获取全局配置 → 响应字段：`firstRecharge.bonusPercent`（number，首充赠送比例%）
+- **具体冲突**：PRD说"固定50币" vs 技术API说"bonusPercent百分比"。前端按百分比计算还是固定值？后端存哪个？
+- **影响范围**：充值系统（COIN-02/04）、全局配置（CONFIG-01）、platform_config 表
+- **建议解决方案**：统一为 PRD 确认的"固定币数"方案。将 `firstRecharge.bonusPercent` 改为 `firstRecharge.bonusAmount`（number，固定赠送糖心币数）。platform_config 中 config_key 改为 `first_recharge_bonus_amount`。
+
+---
+
+### 矛盾2：代聊员鉴权体系完全缺失
+
+- **矛盾描述**：多个接口标注"创作者/代聊员"有权限调用，但整套文档中无代聊员的数据模型、登录方式、鉴权机制。
+- **涉及文档**：
+  - `API_接口文档_产品视角.md` → 权限矩阵（2.6节/7.1节）：代聊员可调用 MSG-03、PPV-03/04
+  - `API-接口设计文档-技术视角.md` → PPV-02/03/04 权限要求均标注"创作者/代聊员"
+  - `数据库表设计文档.md` → **无 chat_agent 或 delegated_agent 相关 Collection**
+  - `PRD_v1.2_需求确认清单.md` → 十六、跨文档依赖 ❓1：《糖心代聊系统PRD》是否已出？
+- **具体冲突**：API 文档声明代聊员可发PPV、发消息，但数据库没有代聊员表，没有代聊员与创作者的绑定关系，没有代聊员登录/授权接口，ppv_message.sender_id 存的是谁的 user_id？
+- **影响范围**：PPV系统（PPV-02/03/04）、消息系统（MSG-03）、分润计算（有代聊15/80/5 vs 无代聊20/80的判断依据）
+- **建议解决方案**：
+  1. 新增 `chat_agent` Collection（字段：user_id、creator_id、status、permissions、persona等）
+  2. 新增代聊员登录/授权 API（创作者邀请代聊员、代聊员接受、代聊员以创作者身份发消息）
+  3. ppv_message 和 message 表增加 `is_delegated` 和 `agent_id` 字段，用于分润判断
+  4. 或者：M2 先不做代聊，统一走创作者本人，P1 再补代聊体系
+
+---
+
+### 矛盾3：PPV消息"永久可看" vs 数据库有"已过期"状态
+
+- **矛盾描述**：PRD 明确 PPV 解锁后永久可看，但数据库 ppv_message 有"已过期"状态值。
+- **涉及文档**：
+  - `PRD_v1.2_需求确认清单.md` → 七、PPV私信系统 第4条：「永久可看，解锁一次终身有效」
+  - `数据库表设计文档.md` → 8.2 ppv_message → status 字段：「1待解锁 2已解锁 **3已过期**」
+- **具体冲突**：如果 PPV 永久可看，"已过期"状态何时触发？会不会被定时任务误标记为过期导致用户无法查看已购内容？
+- **影响范围**：PPV系统（PPV-05/06）、ppv_message Collection
+- **建议解决方案**：删除 ppv_message.status=3（已过期）。PPV 消息只有两个状态：1待解锁、2已解锁。如果未来需要过期机制（如限时PPV），应作为新字段 `expire_at` 单独控制，而非复用 status。
+
+---
+
+### 矛盾4：密码规则不一致——≥8位 vs ≥6位
+
+- **矛盾描述**：PRD 确认密码≥8位，但前端发现 API 文档中有≥6位的描述。
+- **涉及文档**：
+  - `PRD_v1.2_需求确认清单.md` → 一、登录注册 第4条：「密码规则：≥8位，需含字母+数字」
+  - `模块开发顺序及需求待确认清单.md` → NEW-20：「密码规则不一致（PRD≥8位 vs API≥6位）」状态 ❓待确认
+  - `API-接口设计文档-技术视角.md` → AUTH-01：「密码，≥8位，需含字母+数字」（技术视角已修正为8位）
+- **具体冲突**：NEW-20 指出 API 曾有≥6位描述。虽然最新技术视角 API 已写≥8位，但若早期版本 API 被前端参考，可能产生不一致实现。
+- **影响范围**：注册/登录/改密（AUTH-01/02、USER-03）
+- **建议解决方案**：全文档统一为"≥8位，需含字母+数字"。在技术 API 的 AUTH-01 参数校验说明中增加正则表达式 `/^(?=.*[a-zA-Z])(?=.*\d).{8,}$/`，消除歧义。NEW-20 标记为已解决。
+
+---
+
+### 矛盾5：举报功能 MVP 取舍矛盾——M2 不做 vs M2 必须做
+
+- **矛盾描述**：同一份文档中，举报功能的 MVP 优先级自相矛盾。
+- **涉及文档**：
+  - `模块开发顺序及需求待确认清单.md` → "MVP（M2）功能取舍待确认"表格：举报功能建议"M2不做" ❓
+  - `PRD_v1.2_需求确认清单.md` → 十五、安全合规 第2条：「举报/投诉功能：**M2必须包含**」（苹果审核要求，阿汤3-31确认）
+  - `PRD_v1.2_需求确认清单.md` → 十四、交付计划 第4条：举报功能旁注 "→ **M2必须做**（苹果审核要求）"
+- **具体冲突**：模块开发顺序文档的取舍表仍建议"M2不做"，但 PRD 确认清单已明确"M2必须做"。如果开发团队参考了模块开发顺序文档，可能漏掉举报功能。
+- **影响范围**：M2 交付范围、举报系统（REPORT-01/02）、苹果审核通过性
+- **建议解决方案**：更新模块开发顺序文档，将举报功能的建议从"M2不做"改为"✅ M2必须做（苹果审核要求）"。同步更新 M2 开发计划，将举报系统从 P1 提前到 M2。
+
+---
+
+### 矛盾6：高档位是否包含低档位内容权限——已确认 vs 未实现
+
+- **矛盾描述**：产品视角 API 文档标注"已确认：高档位包含低档位权限"，但数据库和技术 API 均未实现此逻辑。
+- **涉及文档**：
+  - `API_接口文档_产品视角.md` → 八、8.4 待确认问题 第8条：「高档位是否自动包含低档权限？**已确认：是**」
+  - `数据库表设计文档.md` → post.visibility 字段：「可见性/所需订阅档位：0免费 1基础 2核心 3至尊」（**单值**，不是"≥某档位"）
+  - `API-接口设计文档-技术视角.md` → CONTENT-03 响应 `visibility` 字段说明："free/basic/core/supreme"，`isUnlocked` 基于 user_subscription 判断，但**未说明判断逻辑是"等于"还是"大于等于"**
+  - `模块开发顺序及需求待确认清单.md` → NEW-8：「高层级是否包含低层级权限」状态 ❓待确认
+- **具体冲突**：产品视角说"已确认包含"，但 NEW-8 仍标记为待确认；数据库 post.visibility 是单值，技术 API 未说明是 `tier_level == visibility` 还是 `tier_level >= visibility`。如果后端按"等于"实现，至尊用户看不到基础内容。
+- **影响范围**：内容权限判断（CONTENT-03）、订阅系统全链路、用户体验
+- **建议解决方案**：
+  1. 在技术 API 的 CONTENT-03 业务说明中明确：`isUnlocked = (user_subscription.tier_level >= post.visibility) OR (post.visibility == 0)`
+  2. 将 NEW-8 标记为"✅ 已确认：高档位包含低档位所有内容权限"
+  3. 在数据库文档 post.visibility 说明中补充："0免费=所有人可见，1基础=基础及以上，2核心=核心及以上，3至尊=仅至尊"
+
+---
+
+### 矛盾7：订阅价格单位全链路不清——糖心币 vs 人民币 vs USD
+
+- **矛盾描述**：订阅价格在不同文档中暗示不同币种，且数据库字段类型与业务逻辑不匹配。
+- **涉及文档**：
+  - `模块开发顺序及需求待确认清单.md` → BIZ-1：「币种体系混乱（订阅USD vs 充值糖心币 vs 提现¥）」❓待确认
+  - `模块开发顺序及需求待确认清单.md` → NEW-1：「订阅价格单位歧义」❓待确认
+  - `数据库表设计文档.md` → subscription_tier.price：「NumberInt，月订阅价格（糖心币）」
+  - `数据库表设计文档.md` → recharge_tier.price：「Decimal128，档位价格（人民币）」
+  - `数据库表设计文档.md` → wallet.balance：「NumberInt，可用余额（糖心币）」
+  - `PRD_v1.2_需求确认清单.md` → 十三、代币经济 第1条：「固定1元=1糖心币（1:1）」
+- **具体冲突**：
+  - subscription_tier.price 单位是"糖心币"（NumberInt），wallet.balance 也是"糖心币"（NumberInt），1:1 比例下可正常扣减 ✅
+  - 但 BIZ-1/NEW-1 指出原始 PRD 中有"USD定价"描述，且苹果 IAP 定价必须用美元
+  - withdrawal_order.amount（糖心币NumberInt）→ amount_cny（人民币Decimal128），这个换算在1:1下等价，但苹果IAP 30%抽成后的分润如何计算？
+- **影响范围**：订阅购买（SUB-02）、提现换算（WD-03）、苹果 IAP 定价（IAP-01/02）、分润计算
+- **建议解决方案**：
+  1. 明确所有内部交易统一使用"糖心币"，1糖心币=1人民币
+  2. 苹果 IAP 端定价用美元/当地货币，到账仍按糖心币（苹果扣30%后的到账金额需要运营配置对应关系）
+  3. 在 recharge_tier 表中为每个苹果 IAP 商品单独配置 `iap_coin_amount`（苹果端到账的糖心币数，已扣除苹果抽成）
+  4. 将 BIZ-1、NEW-1 的解决方案写入文档并标记已解决
+
+---
+
+## 二、🟡 中等矛盾（影响实现，需要确认）
+
+### 矛盾8：自动续费——"不做"但代码预留了
+
+- **涉及文档**：
+  - `PRD_v1.2_需求确认清单.md` → 六、订阅流程 第4条：「已变更：第一期不做自动续费」（JACK 3-31）
+  - `模块开发顺序及需求待确认清单.md` → 第5层订阅系统基础功能列表中仍包含"5. 自动续费"
+  - `数据库表设计文档.md` → user_subscription.auto_renew：「是否自动续费：0否 1是（第一期不做自动续费）」
+- **冲突**：模块开发顺序仍列自动续费为"基础功能"，可能误导开发。DB 有字段但备注了不做。
+- **建议**：模块开发顺序文档中将"自动续费"标注为"~~自动续费~~ → 第一期不做，手动续费"。DB auto_renew 字段保留但默认值 0，后端暂不实现自动扣费逻辑。
+
+### 矛盾9：提现冻结期完全未定义
+
+- **涉及文档**：
+  - `模块开发顺序及需求待确认清单.md` → BIZ-6：「提现与退款冲突（需提现冻结期）」❓待确认
+  - `API_接口文档_产品视角.md` → WD-03 备注：「[待确认] 是否需要T+7提现冻结期？」
+  - `API_运营后台接口文档_产品视角.md` → 待确认第4条：「提现是否需要T+7冻结期？」
+  - `数据库表设计文档.md` → withdrawal_order：**无 freeze_until 或 frozen_period 字段**
+- **冲突**：三份文档均标注待确认，DB 无冻结期字段。若不做冻结期，用户退款时创作者已提现的金额无法追回。
+- **建议**：建议实施 T+7 冻结期。在 wallet 表增加 `settlement_balance`（已结算可提现余额）字段，收入 7 天后才转入可提现余额。或在 withdrawal_order 增加 `earliest_withdraw_at` 字段。
+
+### 矛盾10：宽限期续费——新周期起算时间未确认
+
+- **涉及文档**：
+  - `API_接口文档_产品视角.md` → SUB-05 备注：「[待确认] 宽限期内续费，新周期从原到期日还是扣款日开始？」
+  - `API-接口设计文档-技术视角.md` → SUB-05 备注：同上
+- **冲突**：如果从原到期日算，用户在宽限期第3天续费相当于少了3天；如果从扣款日算，用户可故意拖到宽限期最后一天白嫖3天。
+- **建议**：从原到期日算起（业界惯例），宽限期是"给用户充值时间"，不是"免费延期"。
+
+### 矛盾11：创作者改价后续费规则未确认
+
+- **涉及文档**：
+  - `API_接口文档_产品视角.md` → SUB-07 备注：「[待确认] 创作者改价后，老用户续费按新价还是老价？」
+  - `模块开发顺序及需求待确认清单.md` → BIZ-8：「创作者改价后续费规则」❓待确认
+- **建议**：建议老用户按新价续费（简化实现）。在 user_subscription 表中无需存储历史价格。如果需要"老价格锁定"，则需增加 `locked_price` 字段，实现复杂度大增。
+
+### 矛盾12：群发PPV的技术实现——1万粉丝=1万条记录？
+
+- **涉及文档**：
+  - `模块开发顺序及需求待确认清单.md` → BIZ-7：「群发PPV不限次数已确认，但1万粉丝=1万条记录？回复算开启私聊？」❓待确认
+  - `API-接口设计文档-技术视角.md` → PPV-04 后置结果：「批量创建 ppv_message 记录 + 对应 message 记录。每条共享相同 batch_id」
+- **冲突**：技术 API 确认了"每个接收者创建一条记录"，但 BIZ-7 仍标记为待确认。1万条记录的性能和存储成本需评估。
+- **建议**：确认按"每人一条 ppv_message + 一条 message"实现。使用异步队列批量创建，避免同步阻塞。BIZ-7 可标记为"已在技术 API 中解决，使用 batch_id 关联"。
+
+### 矛盾13：创作者申请资料完全未定义
+
+- **涉及文档**：
+  - `API_接口文档_产品视角.md` → CREATOR-01 备注：「[待确认] 创作者申请需要哪些资料？是否需要实名认证？」
+  - `API-接口设计文档-技术视角.md` → CREATOR-01 请求参数：`applicationInfo`（object，申请资料，**字段结构待确认**）
+  - `数据库表设计文档.md` → creator_application.application_info：「Object，申请资料（字段待确认）」
+  - `模块开发顺序及需求待确认清单.md` → BIZ-18：「创作者申请流程过简」❓待确认
+  - `模块开发顺序及需求待确认清单.md` → NEW-18：「身份证数据无合规设计」❓待确认
+- **冲突**：3份文档均标注"待确认"，但创作者申请是 M2 必经流程，没有申请资料定义就无法开发。
+- **建议**：尽快确认最小申请资料集（建议：昵称、简介、至少1个订阅档位价格）。实名认证作为 P1 补充（或结合提现时要求）。
+
+---
+
+## 三、🟢 轻微矛盾（不阻塞但需统一）
+
+### 矛盾14：API 字段命名——nickname vs displayName
+
+- `API-接口设计文档-技术视角.md` → 2.7节说明：「API 统一用 nickname，DB 为 display_name」
+- 但 AUTH-01 注册响应**没有返回 nickname**，只返回 username。AUTH-02 登录响应有 nickname。
+- **建议**：AUTH-01 注册成功响应也应返回 nickname（注册时可为空，值为 null）。
+
+### 矛盾15：content_boost 注水上限规则——DB 无"真实数据3倍"约束
+
+- `PRD_v1.2_需求确认清单.md`：「boost上限=真实数据3倍」
+- `数据库表设计文档.md` → content_boost 表只有 boost_view_count 等固定数值字段，**无上限约束字段**
+- **建议**：上限规则在业务层实现即可，无需DB字段。但建议在 content_boost 表增加 `max_multiplier` 字段（默认3），方便运营后台调整。
+
+### 矛盾16：通知保留期限——90天清理无对应定时任务说明
+
+- `PRD_v1.2_需求确认清单.md`：「90天自动清理」
+- `API-接口设计文档-技术视角.md` → NOTI-01：「90天自动清理（后端定时任务）」
+- `数据库表设计文档.md` → notification 表无 TTL 索引或清理标记字段
+- **建议**：MongoDB 支持 TTL 索引，可在 notification.created_at 字段上设置 `expireAfterSeconds: 7776000`（90天），自动清理过期通知。
+
+### 矛盾17：user.profile 嵌套 vs AUTH-02 涉及表列 user_profile
+
+- `数据库表设计文档.md`：user_profile **已嵌入** user.profile 子文档
+- `API-接口设计文档-技术视角.md` → AUTH-02 涉及表：「user, **user_profile**, user_device」——但 user_profile 已不是独立 Collection
+- **建议**：技术 API 中"涉及表"统一为"user（含嵌套 profile）"而非"user_profile"。批量修正所有接口的涉及表描述。
+
+---
+
+## 四、已解决的历史问题
+
+### BIZ 系列
+
+| 编号 | 问题 | 状态 | 解决位置 |
+|------|------|------|---------|
+| BIZ-4 | 订阅过期后内容可见性 | ✅ 已解决 | PRD确认清单 六-7：降级已看过的不回收，推断过期同理 |
+| BIZ-5 | 退款机制缺失 | ✅ 已解决 | PRD确认清单 五-6：联系客服人工退款，扣10%手续费 |
+| BIZ-14 | 创作者封禁/注销连锁 | ✅ 部分解决 | PRD确认清单 十一-6：创作者注销流程已明确。但**封禁场景仍未覆盖** |
+| BIZ-16 | 评论缺审核机制 | ✅ 已解决 | PRD确认清单 四-2：敏感词+AI审核+Shadow Ban |
+
+### NEW 系列
+
+| 编号 | 问题 | 状态 | 解决位置 |
+|------|------|------|---------|
+| NEW-2 | 首充计算歧义 | ✅ 已解决 | PRD确认清单 五-2：固定赠送币数，不按百分比（但技术API仍写百分比，见矛盾1） |
+| NEW-3 | 至尊赠币经济模型风险 | ✅ 已解决 | PRD确认清单 十三-6：平台补贴，运营可调金额 |
+| NEW-6 | 升级补差价公式 | ✅ 已解决 | PRD确认清单 六-6：(高档日单价-低档日单价)×剩余天数，向上取整 |
+| NEW-13 | PPV解锁后签名URL过期无刷新接口 | ✅ 已解决 | 技术API PPV-06：获取已解锁PPV签名URL 接口已定义 |
+
+### 仍然悬而未决的关键项
+
+| 编号 | 问题 | 紧急程度 |
+|------|------|---------|
+| BIZ-1 | 币种体系混乱 | 🔴 见矛盾7 |
+| BIZ-2 | 关注 vs 免费订阅关系不清 | 🟡 建议：关注是关注，订阅是订阅，无"免费订阅"概念 |
+| BIZ-3 | 层级与内容权限映射 | 🔴 见矛盾6 |
+| BIZ-6 | 提现冻结期 | 🟡 见矛盾9 |
+| BIZ-7 | 群发PPV技术实现 | 🟡 见矛盾12 |
+| BIZ-8 | 创作者改价续费规则 | 🟡 见矛盾11 |
+| BIZ-18 | 创作者申请流程 | 🟡 见矛盾13 |
+| NEW-1 | 订阅价格单位 | 🔴 见矛盾7 |
+| NEW-4 | 缺取消订阅API | 🟡 PRD未提及"取消订阅"，只有降级和到期不续 |
+| NEW-5 | 宽限期扣费时机 | 🟡 见矛盾10 |
+| NEW-7 | requiredTier与tierId不匹配 | 🔴 见矛盾6 |
+| NEW-8 | 高层级包含低层级权限 | 🔴 见矛盾6 |
+| NEW-9 | isFree+accessTiers+unlockPrice组合规则 | 🟡 建议：统一用 post.visibility 单字段，0=免费，1/2/3=对应档位 |
+| NEW-18 | 身份证数据合规 | 🟡 见矛盾13 |
+| NEW-20 | 密码规则不一致 | 🔴 见矛盾4（技术API已修正，需确认全部统一） |
+
+---
+
+## 五、结论与建议
+
+### 5.1 核心发现
+
+1. **7个重大矛盾**直接阻塞开发，其中"代聊员鉴权缺失"和"高档位权限逻辑"影响最广
+2. **6个中等矛盾**需要产品决策确认，其中"提现冻结期"和"创作者申请资料"最紧急
+3. 历史待确认项（BIZ+NEW共38项），约12项已在后续文档中解决，**仍有约26项悬而未决**
+
+### 5.2 优先处理建议
+
+| 优先级 | 矛盾 | 建议负责人 | 预计影响 |
+|--------|------|-----------|---------|
+| 🔴 立即 | 矛盾1（首充固定/百分比） | 后端修正 API | 1处代码修改 |
+| 🔴 立即 | 矛盾3（PPV过期状态） | 后端删除状态值 | 1处DB修改 |
+| 🔴 立即 | 矛盾4（密码规则统一） | 全文档统一 | 文档修正 |
+| 🔴 立即 | 矛盾5（举报M2必做） | 更新模块开发顺序 | M2排期调整 |
+| 🔴 立即 | 矛盾6（高档位>=逻辑） | 后端+文档明确 | 权限判断核心逻辑 |
+| 🔴 本周 | 矛盾7（币种统一） | 产品确认 | 全链路影响 |
+| 🔴 本周 | 矛盾2（代聊员体系） | 产品+后端 | 新增DB表+API |
+| 🟡 M2前 | 矛盾9（提现冻结期） | 产品确认 | 资金安全 |
+| 🟡 M2前 | 矛盾13（创作者申请资料） | 产品确认 | 创作者入驻流程 |
+
+### 5.3 文档治理建议
+
+1. **建立单一事实来源**：所有业务规则以 `PRD_v1.2_需求确认清单.md` 为准，其他文档引用而非重复定义
+2. **待确认项跟踪**：将 BIZ-1~18 和 NEW-1~22 汇总到一个 Issue Tracker，每项有明确负责人和截止日期
+3. **文档版本同步**：每次产品确认后，同步更新所有相关文档（PRD→API产品视角→API技术视角→DB设计），避免文档间漂移
+
+---
+
+> 📋 本报告共识别 **7个重大矛盾 + 6个中等矛盾 + 4个轻微矛盾**，覆盖全部6份项目文档的交叉比对。
+> 建议在 Week 1 开发启动前解决全部重大矛盾，M2 上线前解决全部中等矛盾。