简介

本设计文档围绕 DouPHP 的“分享推广”能力，聚焦数据层表结构设计，覆盖分享记录、推广链接、分享统计、邀请关系等核心实体，并给出渠道管理、链接生成、点击追踪、转化统计等业务的数据模型建议。文档同时提供表关系图与性能优化策略，便于市场推广人员理解业务指标口径，以及开发者进行扩展与二次开发。

项目结构

当前仓库中与分享推广相关的数据定义主要位于模块存储备份 SQL 中：

• 分享模块：分享申请/审核记录表
• 分销模块：分销申请、等级、等级日志、邀请关系表

此外，后台视图页面展示了分享列表入口，用于运营侧查看与管理分享申请。

graph TB
subgraph "分享模块"
S["dou_share<br/>分享申请/审核记录"]
end
subgraph "分销模块"
D["dou_distribution<br/>分销申请/状态"]
L["dou_distribution_level<br/>分销等级配置"]
LL["dou_distribution_level_log<br/>等级变更日志"]
R["dou_distribution_relation<br/>邀请关系"]
end
V["后台分享视图<br/>share.htm"]
U["用户/会员"]
O["订单/支付"]
U --> S
U --> D
D --> L
D --> R
S --> V
R --> O

核心组件

• 分享申请与审核记录（分享记录表）
  • 用途：记录用户发起的分享申请、处理轨迹与状态流转，支撑分享活动准入与审计。
  • 关键字段：自增ID、分享单号、会员ID、处理记录、处理时间、状态、创建时间。
• 分销申请与等级（分销申请表、等级表）
  • 用途：管理分销员申请、等级权益（直推/间推奖励比例）、升级条件等。
  • 关键字段：会员ID、姓名、备注、等级ID、处理记录、处理时间、状态、创建时间；等级名称、直推/间推奖励百分比、升级金额阈值、排序、创建时间。
• 等级变更日志（等级日志表）
  • 用途：记录用户等级升降级原因与触发事件（如订单），便于对账与溯源。
  • 关键字段：用户ID、旧等级ID、新等级ID、条件值、关联订单号、创建时间。
• 邀请关系（邀请关系表）
  • 用途：维护上下级邀请关系，支撑多级分佣计算与归属判定。
  • 关键字段：用户ID、上级用户ID、层级、创建时间；唯一约束保证一对一父子关系。

架构总览

分享推广在数据层的整体关系如下：

• 用户通过分享申请进入分享体系（分享记录表）。
• 用户可申请成为分销员（分销申请表），获得等级（等级表）后参与推广。
• 分销员邀请新用户形成邀请关系（邀请关系表），后续订单可据此计算奖励。
• 等级变更由系统根据规则触发，写入等级日志（等级日志表）。

erDiagram
DOU_USER ||--o{ DOU_SHARE : "发起分享申请"
DOU_USER ||--o{ DOU_DISTRIBUTION : "申请分销"
DOU_DISTRIBUTION }o--|| DOU_DISTRIBUTION_LEVEL : "所属等级"
DOU_DISTRIBUTION ||--o{ DOU_DISTRIBUTION_LEVEL_LOG : "等级变更日志"
DOU_USER ||--o{ DOU_DISTRIBUTION_RELATION : "作为被邀请人"
DOU_USER ||--o{ DOU_DISTRIBUTION_RELATION : "作为邀请人"

详细组件分析

分享记录表（dou_share）

• 字段说明
  • id：主键自增
  • share_sn：分享单号（唯一标识一次分享申请）
  • user_id：会员ID
  • handle_record：处理记录（审批意见、操作留痕）
  • handled_at：处理时间
  • status：状态（-1待审核、0已驳回、1已通过）
  • created_at：创建时间
• 索引与查询
  • 以id为主键；可按user_id、status、created_at组合查询筛选。
• 业务含义
  • 用于分享活动报名、审核流程与审计；可与后续推广行为解耦，避免强耦合影响高并发场景。

分销申请表（dou_distribution）

• 字段说明
  • id：主键自增
  • user_id：会员ID
  • name：申请人姓名
  • remark：申请备注
  • level_id：等级ID（关联等级表）
  • handle_record：处理记录
  • handled_at：处理时间
  • status：状态（如pending/已通过/已拒绝等）
  • created_at：创建时间
• 索引与查询
  • 已建索引：user_id、status；支持按用户与状态快速检索。
• 业务含义
  • 管理分销员准入与状态流转；level_id决定奖励比例与升级条件。

分销等级表（dou_distribution_level）

• 字段说明
  • id：主键自增
  • name：等级名称
  • direct_reward_percent：直推奖励百分比
  • indirect_reward_percent：间推奖励百分比
  • upgrade_condition_amount：升级条件金额阈值
  • sort：排序权重
  • created_at：创建时间
• 业务含义
  • 定义不同等级的收益与升级门槛，驱动分佣计算与等级晋升。

等级变更日志表（dou_distribution_level_log）

• 字段说明
  • id：主键自增
  • user_id：用户ID
  • old_level_id：原等级ID
  • new_level_id：新等级ID
  • condition_value：触发升级的条件值（如累计金额）
  • order_sn：关联订单号（可选，用于归因）
  • created_at：创建时间
• 索引与查询
  • 已建索引：user_id、order_sn；便于按用户或订单追溯等级变化。
• 业务含义
  • 记录等级变动原因与上下文，支持对账、申诉与数据分析。

邀请关系表（dou_distribution_relation）

• 字段说明
  • id：主键自增
  • user_id：被邀请用户ID
  • parent_user_id：邀请人用户ID
  • level：层级（1为直接邀请，2为间接邀请等）
  • created_at：创建时间
• 索引与查询
  • 唯一约束：(user_id, parent_user_id) 防止重复绑定；
  • 索引：parent_user_id 便于统计下线规模。
• 业务含义
  • 构建邀请树，支撑多级分佣、团队业绩统计与排行榜。

后台分享视图（share.htm）

• 作用
  • 提供分享申请列表页入口，支持按用户名等条件过滤，便于运营审核与管理。
• 与数据的关系
  • 列表数据通常来源于分享记录表（dou_share），结合状态与时间维度进行展示。

依赖关系分析

• 表间依赖
  • dou_distribution.level_id → dou_distribution_level.id
  • dou_distribution.user_id → 用户表（外部）
  • dou_distribution_relation.user_id / parent_user_id → 用户表（外部）
  • dou_distribution_level_log.order_sn → 订单表（外部，用于归因）
• 运行期依赖
  • 分销等级变更可能由订单结算触发，需与订单/资金模块协作。
  • 分享申请审核通过后，方可授予推广权限或发放推广码。

graph LR
A["dou_distribution"] --> B["dou_distribution_level"]
C["dou_distribution_relation"] --> |user_id| U["用户表"]
C --> |parent_user_id| U
D["dou_distribution_level_log"] --> |order_sn| E["订单表"]

性能考虑

• 索引策略
  • 已有索引：distribution.user_id、distribution.status、relation.parent_user_id、level_log.user_id、level_log.order_sn。
  • 建议补充：share.user_id、share.status、share.created_at 的复合索引，提升列表与统计查询效率。
• 读写分离与归档
  • 分享申请与等级日志属于写多读少，建议定期归档历史数据至冷存储，保持热表轻量。
• 事务与一致性
  • 邀请关系建立与等级变更应置于事务中，确保原子性；失败时回滚并记录错误日志。
• 缓存与预聚合
  • 排行榜、团队规模等高频读取指标可采用缓存或定时物化视图/汇总表，降低实时聚合压力。
• 扩容与分区
  • 当数据量增长到千万级，可对日志类表按时间分区；对关系表可按用户ID哈希分片。

故障排查指南

• 常见问题定位
  • 邀请关系重复：检查唯一约束 (user_id, parent_user_id)，确认是否存在并发插入未加锁。
  • 等级变更异常：核对 level_log 的 old/new level 与触发条件（如订单金额）是否一致。
  • 分享申请卡住：检查 status 与 handled_at 是否为空，确认审核流程是否完成。
• 诊断方法
  • 通过 user_id、order_sn、status 等索引字段快速定位记录。
  • 结合后台分享列表页（share.htm）进行人工核验。
• 修复建议
  • 对并发场景增加行级锁或分布式锁；对幂等接口增加去重键。
  • 对长事务拆分，减少锁持有时间。

结论

当前数据层已具备分享申请与分销体系的基础表结构，涵盖申请、等级、日志与邀请关系等关键要素。为满足更完整的“分享推广”闭环，建议在现有基础上补充分享渠道、推广链接、点击追踪与转化统计等表结构，并结合索引、缓存与归档策略保障性能与可维护性。

附录

推荐新增表结构（概念设计）

以下为面向市场推广与开发的参考设计，便于实现“渠道管理、链接生成、点击追踪、转化统计”等能力。该部分为概念设计，非仓库现有代码。

• 分享渠道表（share_channel）
  • 字段：id、渠道编码、渠道名称、类型（社交/短信/邮件/其他）、参数模板、启用状态、创建时间
  • 用途：统一管理分享渠道及其投放参数
• 推广链接表（share_link）
  • 字段：id、share_sn、channel_id、user_id、目标URL、短链、二维码、有效期、点击次数、转化次数、创建时间
  • 用途：记录每次分享的推广链接及基础计数
• 点击追踪表（share_click）
  • 字段：id、link_id、user_agent、ip、referer、设备信息、地理位置、访问IP、访问时间
  • 用途：精细化追踪访客来源与设备环境
• 转化统计表（share_conversion）
  • 字段：id、link_id、user_id、event_type（注册/下单/付费）、target_id（如订单号）、金额、佣金、状态、创建时间
  • 用途：将推广行为与业务转化关联，支撑ROI与分佣计算
• 分享效果报表（share_report_daily）
  • 字段：date、channel_id、user_id、clicks、registrations、orders、amount、commission、conversion_rate
  • 用途：按日聚合渠道与个人维度的推广效果，供运营看板使用

erDiagram
SHARE_CHANNEL ||--o{ SHARE_LINK : "生成推广链接"
SHARE_LINK ||--o{ SHARE_CLICK : "记录点击"
SHARE_LINK ||--o{ SHARE_CONVERSION : "记录转化"
SHARE_CONVERSION }o--|| ORDER : "关联订单"
SHARE_REPORT_DAILY }o--|| SHARE_CHANNEL : "按渠道汇总"
SHARE_REPORT_DAILY }o--|| SHARE_LINK : "按链接汇总"

[此图为概念设计，不对应仓库现有代码文件]

业务流程示意（概念）

sequenceDiagram
participant U as "用户"
participant F as "前端"
participant S as "分享服务"
participant DB as "数据库"
participant O as "订单服务"
U->>F : 打开分享落地页
F->>S : 请求生成推广链接
S->>DB : 写入分享渠道/链接
S-->>F : 返回短链/二维码
U->>F : 点击推广链接
F->>S : 记录点击
S->>DB : 写入点击追踪
U->>O : 完成下单/注册
O->>S : 回调转化事件
S->>DB : 写入转化记录并更新统计

[此图为概念流程，不对应仓库现有代码文件]