分銷商系統

更新時間：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. 注意事項 ​