分销商系统

更新时间：2026-06-23

分销商（Reseller，亦称「经销商」）是 Dujiao-Next 内置的白标多租户分销体系。分销商拥有自己的独立站点（独立域名 + 自定义品牌），在主站商品的基础上自主加价销售，分销价与基准价之间的差价即为分销商利润。买家在分销商站点下单、支付，由主站统一履约发货；分销利润经过确认期后结算到分销商账户，分销商可申请提现。

与「分销推广」的区别

本系统与分销推广（Affiliate）是两套独立功能，请勿混淆：

维度	分销推广 Affiliate	分销商 Reseller（本文）
模式	推广链接 + 佣金返利	白标独立站点 + 自主定价差价
站点	共用主站	独立域名、独立品牌
买家感知	仍在主站购物	在分销商品牌站购物
收益来源	订单金额 × 佣金比例	分销价 − 基准价（差价利润）
适合人群	个人推广引流	渠道代理 / 二级商家

1. 功能概览

模块	说明
申请与审核	用户申请成为分销商，管理员审核并设置加价上限
域名绑定	系统二级域名（管理员分配）或自定义域名（管理员审核）
白标站点	自定义站名、Logo、Favicon、公告、SEO、导航、页脚、主题
商品与定价	商品上下架，4 种定价模式自主加价
订单履约	买家在分销站下单，主站统一发货
利润结算	利润入账 → 确认期 → 可提现，按币种独立记账
提现	分销商申请提现，管理员审核后线下打款
风控	自买 / 关联账号利润拦截，定价红线防止平台亏本

2. 启用分销商模式

分销商模式默认关闭，需在后端 config.yml 的 reseller 段开启：

yaml

reseller:
  enabled: false
  # 主站域名列表。启用分销模式后，请把正式主站域名写入这里。
  # 命中 main_hosts 的请求按主站上下文处理；未命中则尝试解析分销商域名。
  main_hosts:
    - localhost
    - 127.0.0.1
    - "::1"
  # 只有反向代理可信并正确传递 Host 时才开启。
  # false 时使用原始 Host；true 时优先使用 X-Forwarded-Host。
  trusted_forwarded_host: false
  # 管理员为分销商分配系统二级域名时使用的基础域名，例如 hello.{subdomain_base}。
  # 生产启用前请配置为已经做好 wildcard DNS/TLS 的域名，例如 shop.example.com。
  subdomain_base: ""
  # 是否允许普通用户在个人中心自助提交分销商申请。
  self_apply_enabled: true
  # 分销利润入账后转为「可提现」的确认天数（0 表示即时到账，最大 3650）。
  settlement_confirm_days: 7

配置项	说明
`enabled`	分销商模式总开关
`main_hosts`	主站域名列表，命中则按主站上下文处理
`trusted_forwarded_host`	反向代理可信时，优先用 `X-Forwarded-Host` 识别域名
`subdomain_base`	系统二级域名的基础域名（需提前配置 wildcard DNS/TLS）
`self_apply_enabled`	是否允许用户在个人中心自助申请
`settlement_confirm_days`	利润确认天数，`0` 为即时到账，最大 `3650`

生产部署前置条件

启用前请将真实主站域名写入 main_hosts，否则主站请求可能被误判为分销站。
若要使用系统二级域名，subdomain_base 必须指向一个已配置 wildcard DNS（*.shop.example.com）与 wildcard TLS 证书 的域名。
反向代理（Nginx 等）需把真实 Host/X-Forwarded-Host 透传给后端，分销域名解析依赖该请求头。

3. 整体流程

用户申请  →  管理员审核（设定加价上限）  →  分配/绑定域名
   →  分销商配置站点 + 商品定价  →  上线销售
   →  买家在分销站下单支付  →  利润入账（确认期）
   →  到期转可提现  →  分销商申请提现  →  管理员审核打款

4. 成为分销商（用户端）

4.1 提交申请

用户在前台个人中心进入「分销中心」
在「分销商申请」填写申请理由并提交
申请进入「待审核」状态，等待管理员处理

需管理员在 config.yml 中开启 enabled 且 self_apply_enabled: true 后，用户才能自助申请。

4.2 申请状态

状态	标识	说明
待审核	`pending_review`	已提交，等待管理员审核
已通过	`active`	审核通过，分销商身份生效
已拒绝	`rejected`	被拒绝，可修改理由后重新申请
已禁用	`disabled`	被管理员禁用，分销站立即下线，不能重新申请

被拒绝（rejected）的用户可再次提交申请；被禁用（disabled）则不能自助重申，需联系管理员恢复。

5. 管理员审核（后台）

后台「分销商管理 → 分销商审核」中处理分销商生命周期。

5.1 审核操作

操作	说明
通过	设置「默认加价比例」与「最大加价上限」，分销商身份生效
拒绝	填写拒绝原因，用户可重新申请
禁用	立即下线该分销商所有域名（分销站访问返回不可用）
恢复	将已禁用的分销商恢复为生效状态

5.2 经营参数

审核通过或后续编辑时，可调整以下分销商级参数：

参数	说明
默认加价比例	商品/SKU 未单独配置定价时套用的统一加价百分比
最大加价上限	单品隐含加价幅度的硬上限，超过则下单/展示校验失败（`0` 表示不限制）
结算状态	`normal` 正常 / `frozen` 冻结；冻结后禁止该分销商提现

5.3 状态机

              ┌──────────────┐
申请提交 ───▶ │ pending_review│
              └──────┬───────┘
            通过 │        │ 拒绝
                 ▼        ▼
            ┌────────┐ ┌──────────┐  重新申请
            │ active │ │ rejected │ ─────────▶ pending_review
            └───┬────┘ └────┬─────┘
          禁用 │           │ 禁用
                ▼           ▼
            ┌──────────────────┐
            │     disabled     │ ──恢复──▶ active
            └──────────────────┘

6. 域名绑定

分销站通过域名识别租户上下文，支持两类域名。

6.1 系统二级域名

由管理员在后台为分销商分配，基于 config.yml 的 subdomain_base：

例如 subdomain_base: shop.example.com，分配子域 hello 后即得 hello.shop.example.com
系统二级域名分配后自动标记为已验证、已生效，无需额外审核
子域标签只允许小写字母、数字与连字符，长度 ≤ 63

6.2 自定义域名

分销商在前台「域名管理」提交自有域名（如 shop.mybrand.com）：

分销商把域名 DNS 解析（CNAME/A 记录）指向平台
在前台提交该域名，进入「待审核」状态
管理员在后台「分销商管理」审核通过后域名生效

当前版本自定义域名走后台人工审核，暂未启用 DNS 自动校验。提交的域名不能是主站域名或 subdomain_base 及其子域。

6.3 域名状态与主域名

维度	取值
绑定状态	`pending_review` 待审核 / `active` 生效 / `disabled` 已禁用
验证状态	`pending` 待验证 / `verified` 已验证 / `failed` 验证失败
主域名	`is_primary`，每个分销商有且仅有一个主域名

主域名用于生成订单快照与对外展示的规范域名
禁用主域名时，系统会自动从其它「已生效 + 已验证」的域名中改选一个为主域名
域名审批 / 禁用后，分销域名解析缓存会即时失效，变更立即生效

7. 白标站点配置

分销商在前台「站点配置」中自定义店面外观，所有文案字段支持多语言（与主站语言一致）：

配置项	说明
站点名称	分销站标题
Logo / Favicon	站点徽标与浏览器图标
公告	首页公告内容
客服信息	客服联系方式 / 入口
SEO	标题、描述、关键词等
导航配置	顶部导航菜单
页脚链接	底部链接区
主题	站点主题 / 配色

分销商身份需为「已生效」状态才能编辑站点配置。图片通过分销控制台的上传接口提交。

8. 商品与定价

8.1 上下架

分销商可在「商品管理」按商品 / SKU 维度选择上架或下架（is_listed）
下架的商品 / SKU 不会在分销站展示，也不能被下单

8.2 定价模式

每个商品 / SKU 可独立选择定价模式：

模式	标识	计算方式
继承	`inherit`	沿用基准价，不加价（或回退到上一层规则）
百分比加价	`markup_percent`	`基准价 × (100 + 加价%) / 100`
固定加价	`fixed_markup`	`基准价 + 固定加价额`
一口价	`fixed_price`	直接指定分销价

8.3 定价层级与继承

定价按以下优先级自上而下解析，遇到非「继承」的规则即采用：

SKU 级设置  ▶  商品级设置  ▶  分销商默认加价比例  ▶  基准价（继承）

SKU 设置的模式不是 inherit 时，优先使用 SKU 规则
否则若商品设置模式不是 inherit，使用商品规则
否则若分销商「默认加价比例」> 0，按该比例加价
都未命中则直接等于基准价

8.4 定价红线（校验）

为防止平台亏本，分销价必须同时满足以下条件，否则下单与展示校验失败：

分销价 > 0
分销价 ≥ 基准价（不得低于主站售价）
若 SKU 设置了成本价（> 0），分销价 ≥ 成本价
若分销商设置了「最大加价上限」（> 0），隐含加价幅度 ≤ 上限

展示页对失效的脏配置具有容错：若某 SKU 因基准价 / 成本价 / 上限调整导致定价校验失败，仅隐藏该 SKU 并记录告警，不会让整个商品页报错。运营应据告警修正配置。

9. 订单与履约

买家在分销站下单时，系统按上述定价规则计算分销价
分销订单不参与主站的任何优惠：优惠券、会员价、活动价、批发价一律不适用，下单时这些折扣会被清零
下单时系统会生成订单定价快照（reseller_order_snapshot），记录基准价、分销价、利润、风控判定等，作为后续利润结算的依据
订单履约（发货 / 卡密发放）由主站统一处理，分销商无需自行备货

10. 利润结算

10.1 利润入账

订单支付成功后，系统按订单快照生成一条「订单利润」流水：

利润 = Σ（分销价 − 基准价）   // 按订单内各商品累计

流水类型 order_profit，初始状态 pending_confirm（待确认）
到账时间 = 支付时间 + settlement_confirm_days
利润为 0 或负、或快照判定为不计利润（见下文「风控」一节）时不入账
同一订单幂等入账，不会重复生成

10.2 确认期

后台 worker 定时任务会把已到期的 pending_confirm 流水批量转为 available（可提现），并同步刷新余额缓存。settlement_confirm_days: 0 时利润即时可提现。

10.3 退款扣减

订单退款时，系统按比例扣回已入账利润，生成 refund_deduct（负数）流水：

扣减比例以订单总额为固定分母，多次部分退款累计扣减恰好等于原始利润，绝不超扣
若对应利润仍在确认期内（pending_confirm），退款扣减流水也保持待确认并沿用同一到账时间，与利润同步到账——避免未到账利润被扣成「可用负余额」而误冻结账户
退款明细按各商品利润占比分摊

10.4 余额账户

每个分销商按币种独立记账（reseller_balance_account）：

字段	说明
可用余额	已确认、可申请提现的净额（含退款等负数流水）
锁定余额	已进入提现申请、等待审核的金额
负余额	可用净额为负时的欠款额

账户状态：normal 正常 / negative_balance 负余额 / frozen_review 冻结审查 / disabled 停用。处于负余额、冻结或停用状态时禁止提现。

10.5 流水类型与状态

流水类型：

类型	说明
`order_profit`	订单利润入账（正数）
`refund_deduct`	退款扣减（负数）
`manual_adjust`	管理员手工调整

流水状态：

状态	说明
`pending_confirm`	待确认（确认期内）
`available`	可提现
`locked`	已锁定（在提现申请中）
`withdrawn`	已提现
`canceled`	已作废

11. 提现

11.1 分销商申请

在前台「财务 / 提现」查看各币种可用余额
填写提现金额、币种、提现渠道与收款账号并提交
系统按净可用余额校验额度（含退款等负数流水），不足则拒绝
申请成功后，系统自动锁定对应金额的可提现流水；若最后一笔流水金额大于所需，会自动拆分

分销商身份须为「已生效」且结算状态为 normal 才能提现；账户处于负余额 / 冻结 / 停用时不可提现。

11.2 管理员审核

后台「分销商管理 → 提现管理」中处理（受财务权限保护）：

通过（打款）：锁定流水转为「已提现」，管理员线下完成打款
拒绝：填写拒绝原因，锁定的流水释放回「可提现」状态

12. 风控

系统在下单定价阶段进行自买风控判定，命中后该订单利润不计入分销商账户（利润照常对买家收取，仅不结算给分销商）：

拦截类型	标识	说明
本人自买	`self_dealing_owner`	下单买家即分销商本人
关联账号	`self_dealing_related_account`	买家被标记为该分销商的关联账号

此外，上文「定价红线」从源头保证分销价不低于基准价 / 成本价，平台在任何分销订单中都不会亏本。

13. 注意事项

分销商模式需在 config.yml 开启 enabled 后整体生效。
系统二级域名依赖 subdomain_base 的 wildcard DNS/TLS，自定义域名当前走人工审核。
分销订单不叠加主站任何优惠（优惠券 / 会员价 / 活动价 / 批发价）。
分销价不得低于基准价与成本价，且受最大加价上限约束。
利润确认天数、确认期内退款的同步到账逻辑由后端自动处理，确认期内退款不会误冻结账户。
提现以净可用余额为准，负余额 / 冻结 / 停用账户不可提现。
后台分销商「提现 / 财务」类接口受财务权限保护，需对应 RBAC 角色才能操作。

分销商系统 ​

1. 功能概览 ​

2. 启用分销商模式 ​

3. 整体流程 ​

4. 成为分销商（用户端） ​

4.1 提交申请 ​

4.2 申请状态 ​

5. 管理员审核（后台） ​

5.1 审核操作 ​

5.2 经营参数 ​

5.3 状态机 ​

6. 域名绑定 ​

6.1 系统二级域名 ​

6.2 自定义域名 ​

6.3 域名状态与主域名 ​

7. 白标站点配置 ​

8. 商品与定价 ​

8.1 上下架 ​

8.2 定价模式 ​

8.3 定价层级与继承 ​

8.4 定价红线（校验） ​

9. 订单与履约 ​

10. 利润结算 ​

10.1 利润入账 ​

10.2 确认期 ​

10.3 退款扣减 ​

10.4 余额账户 ​

10.5 流水类型与状态 ​

11. 提现 ​

11.1 分销商申请 ​

11.2 管理员审核 ​

12. 风控 ​

13. 注意事项 ​