From 0eff43ad52e0857689bc539bc5031bbd4ee53549 Mon Sep 17 00:00:00 2001 From: yml2213 Date: Wed, 16 Sep 2026 12:49:21 +0800 Subject: [PATCH] =?UTF-8?q?docs(distribution):=20=E7=BB=9F=E4=B8=80?= =?UTF-8?q?=E9=80=9A=E9=81=93=E6=89=8B=E7=BB=AD=E8=B4=B9=E5=8F=A3=E5=BE=84?= =?UTF-8?q?=E8=87=B3=20v0.8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 代码侧 647fdc0 已把通道手续费改为主站承担、不再从分成基数中扣除，但设计文档多处仍写"扣除通道手续费"， 7.8 的结算恒等式还把通道手续费列为实付的一项，与实现互不兼容。按代码口径统一文档： - 7.1 / 7.5 公式改为 有效加价 = min(shelf_markup_cent, max(净支付额 - 号主底价, 0))， 提价利润基数 = max(净支付额 - 号主底价 - 有效加价, 0) - 7.8 恒等式左端改为净支付租金，通道手续费移出等式单独说明，平台收益行去掉" + 通道手续费" - 14 验收标准、16 实现基线同步，文档头升级 v0.8 并记录变更点 --- docs/分销网管理后台设计方案.md | 46 ++++++++++++++++++++-------------- 1 file changed, 27 insertions(+), 19 deletions(-) diff --git a/docs/分销网管理后台设计方案.md b/docs/分销网管理后台设计方案.md index 0422b26..5e1d583 100644 --- a/docs/分销网管理后台设计方案.md +++ b/docs/分销网管理后台设计方案.md @@ -1,7 +1,8 @@ # 分销网管理后台设计方案 -> 状态：草案 v0.7 -> 更新时间：2026-09-08 +> 状态：草案 v0.8 +> 更新时间：2026-09-15 +> v0.8 变更：通道手续费改由主站承担、不再计入提价利润基数，第 2、7.5、7.8、14、16 节与代码实现（`distribution/pricing.go`）对齐。 > 适用范围：分销网站正常租赁订单管理、订单分账、分销客服与支付配置 ## 1. 文档目的 @@ -27,7 +28,7 @@ 现有系统的价格快照包含 `seller_ratio`、`buyer_ratio`、`seller_total_price`、`buyer_total_price` 和 `platform_markup_amount`： - **主站提价逻辑**：收号时录入卖家底价 `seller_total_price` 与回收比例 `seller_ratio`，主站定价引擎通过固定加价（小额）或减比例加价（大额）算得面向买家的挂牌比例 `buyer_ratio` 与买家价 `buyer_total_price`。两者的差额即为**主站提价利润**（`platform_markup_amount = buyer_total_price - seller_total_price`）。 -- **分销分账本质**：分账**分的是主站提价多出来的利润**（扣除通道费后），按收号方 35% / 卖出方 40% / 平台服务费 25% 切分；号主底价作为本金成本 100% 归号主，不参与分账。 +- **分销分账本质**：分账**分的是主站提价多出来的利润**，按收号方 35% / 卖出方 40% / 平台服务费 25% 切分；号主底价作为本金成本 100% 归号主，不参与分账。支付通道手续费由主站承担，不计入提价利润基数，只落库供对账（见 7.5）。 - **分站自主加价**：分站货架可在主站挂牌价基础上进一步自主提价；**分站自己提价多挣的钱 100% 属于分站自己**，不进入三方分成池。 - **挂牌比例定义**：挂牌比例语义为「1 元兑换多少万哈夫币」，`价格 = 哈夫币万数 / 比例`，比例越小售价越贵（加价是调小比例）。分销分成的 35% / 40% / 25% 是利润分成百分比，不能与兑换比例混淆。 @@ -265,9 +266,9 @@ offline 规则字段存 `35` / `40` / `25`，计算一律 `× 百分比 / 100`。 -**核心业务口径（v0.7 锁定）**： +**核心业务口径（v0.7 锁定，v0.8 修订通道手续费口径）**： 1. **号主底价本金保底**：号主应得走订单原有 `owner_rent_amount_cent`（对应 `seller_total_price`），属于履约本金，不参与任何分销分成，100% 结算给号主。 -2. **分账分的是提价的部分**：分销分账的标的是**主站收号定价多出来的利润**（即 `platform_markup_amount = buyer_total_price - seller_total_price`）。扣除支付通道手续费后，形成供三方切分的提价利润基数。 +2. **分账分的是提价的部分**：分销分账的标的是**主站收号定价多出来的利润**（即 `platform_markup_amount = buyer_total_price - seller_total_price`）。该利润全额构成供三方切分的提价利润基数；**支付通道手续费由主站承担，不从基数中扣除**，只落库供对账（见 7.5）。 3. **分站自主加价溢价 100% 归分站自己**：若分站在货架上自主加价（或调比例加价），该加价溢价**完全属于卖出分站自己**，不进入 35/40/25 的三方分成池（详见 7.6 节）。 默认角色模式（可按站点、模式出新规则版本，历史订单用快照）： @@ -285,10 +286,13 @@ offline 提价利润基数计算： ```text -主站提价总额 = base_price_cent - owner_rent_amount_cent (= platform_markup_amount) -提价利润基数 = 主站提价总额 - 支付通道手续费 +主站提价总额 = base_price_cent - owner_rent_amount_cent (= platform_markup_amount) +有效加价 = min(shelf_markup_cent, max(净支付额 - owner_rent_amount_cent, 0)) +提价利润基数 = max(净支付额 - owner_rent_amount_cent - 有效加价, 0) ``` +通道手续费不进此式：由主站承担，只记录对账（见 7.5）。 + ### 7.2 必须确认的口径 v0.7 已锁定 7.1 的提价分成和 7.6 的分站自主加价独享。其余待确认项： @@ -349,13 +353,14 @@ rule_version 支付通道手续费和平台服务费不是同一层。 -通道手续费：按退款后的实际支付金额扣除，费率 0.5%，四舍五入。 +通道手续费：按退款后的实际支付金额计算，费率 0.5%，四舍五入；**由主站承担，不从提价利润基数中扣除**，只落库 `payment_fee_cent` 供对账。 ```text -实际支付金额 = 支付金额 - 成功退款金额 -通道手续费 = round_half_up(实际支付金额 × 50 / 10000) +净支付额 = 支付金额 - 成功退款金额 +通道手续费 = round_half_up(净支付额 × 50 / 10000) # 主站承担，不进分成基数 主站提价总额 = base_price_cent - owner_rent_amount_cent -提价利润基数 = max(主站提价总额 - 通道手续费, 0) +有效加价 = min(shelf_markup_cent, max(净支付额 - owner_rent_amount_cent, 0)) +提价利润基数 = max(净支付额 - owner_rent_amount_cent - 有效加价, 0) 平台服务费 = round_half_up(提价利润基数 × 25 / 100) # 25% 收号/上架分成 = round_half_up(提价利润基数 × 35 / 100) # 35% 卖出方提价分成 = round_half_up(提价利润基数 × 40 / 100) # 40% @@ -364,6 +369,8 @@ rule_version `payment_fee` 与 `service_fee` 必须分字段。服务费是提价利润的 25%，不是通道手续费，不是固定元，也不是 `实付/2.5`。 +通道手续费由主站自行承担：平台净收益 = 提价利润基数 × 25% + 四舍五入尾差 − 通道手续费，不向其他参与方回收。 + ### 7.6 分站货架自主提价（分站独享溢价，已确认 v0.7） 分站货架提价是分销商根据自身经营策略自主制定的加价： @@ -404,17 +411,18 @@ tax_rate_bps 每个主体分别计算税费，主站、分销 A、分销 B 不合并税基。毛利为负时税额暂按 0 处理，亏损如何结转：待确认。 -### 7.8 账务不变量与结算恒等式（已确认 v0.7） +### 7.8 账务不变量与结算恒等式（已确认 v0.7，v0.8 修订） 每笔分销订单的结算必须满足： ```text -实际支付总金额 +净支付租金 (net_paid_amount_cent) = 号主底价 (owner_rent_amount_cent) + 分站自主提价溢价 (shelf_markup_cent) [100% 归卖出分站] - + 通道手续费 (payment_fee_cent) + 提价利润基数 (split_base_amount_cent) +通道手续费 (payment_fee_cent) 不参与上式：由主站承担，只记录对账 + 提价利润基数 = 收号/上架 35% + 卖出 40% @@ -426,7 +434,7 @@ tax_rate_bps - **号主**：得到完整的 `owner_rent_amount_cent`。 - **收号方**：分得 `提价利润基数 × 35%`。 - **卖出方（分站）**：获得 `分站自主加价溢价 (shelf_markup_cent) + (提价利润基数 × 40%)`。 -- **平台**：获得 `提价利润基数 × 25% + 通道手续费 + 四舍五入尾差`。 +- **平台**：获得 `提价利润基数 × 25% + 四舍五入尾差`，并自行承担通道手续费（`payment_fee_cent` 只作记录，不从各方分成中回收）。 税费若开启，从各方分成中计，不破坏上面 100% 切完利润的关系；具体税基见 7.2。 @@ -770,7 +778,7 @@ distribution.hao858.com { ### 账务正确性 - 通道手续费按退款后的实际支付金额计算，0.5%，四舍五入，以分保存。 -- 通道手续费和号主应得先扣，得到利润基数后再切 35% / 40% / 25%。 +- 号主应得先扣，得到利润基数后再切 35% / 40% / 25%；通道手续费由主站承担，不计入利润基数。 - 收号 35%、卖出 40%、服务费 25%；字段存 35/40/25，禁止存 3.5/4/2.5 再当百分数乘。 - 分站加价改该站 1 元兑换哈夫币比例，不叠加人民币；历史订单用下单时的比例快照。 - 各主体独立计算税费。 @@ -817,16 +825,16 @@ distribution.hao858.com { 后续每次确认业务规则后，优先更新第 7、15 节，再同步更新第 8、9、13、14 节，确保规则、数据、接口、实施和验收标准保持一致。 -## 16. 当前实现基线（v0.7） +## 16. 当前实现基线（v0.8） 本分支已落地第一批可运行功能，主站域名为 `https://hao858.com/`，独立后台工程位于 `distribution-admin/`，子域名暂定 `https://distribution.hao858.com/`： - Go 后端已实现 `distribution_sites`、成员、账号货架、规则版本、订单财务快照、订单参与方、结算批次/明细、支付通道绑定表。 - `rental_orders` 增加分销站点、模式和规则版本字段，并具备 `base_price_cent`（主站基准价）与 `shelf_markup_cent`（分站自主加价溢价）快照。 -- 分账计算引擎与口径全面对齐 v0.7： +- 分账计算引擎与口径全面对齐 v0.8： 1. 利润分成百分比使用 35%（收号/上架）、40%（卖出方）、25%（平台服务费）； 2. 号主底价成本（`owner_rent_amount_cent`）保底归号主，不参与任何分成； - 3. 分账标的为主站收号提价利润（`platform_markup_amount = base_price - owner_rent`），扣除通道手续费后按 35/40/25 切分； + 3. 分账标的为主站收号提价利润（`platform_markup_amount = base_price - owner_rent`），全额按 35/40/25 切分；通道手续费由主站承担，不从基数中扣除； 4. 分站货架自主提价溢价（`shelf_markup_cent`）100% 独享归卖方分站，不参与三方切分； 5. 兑换比例提价语义明确（比例越小售价越高，提价使分站售价增加）。 - 管理 API 覆盖站点、规则、售出/收号订单查询、财务快照、账号展示开关、支付通道绑定和结算批次。