refactor(distribution): 重写分销迁移并落地利润百分比分成与货架比例

将 000064-000078 合并为 064/065/066，默认规则改为收号 35%、卖出 40%、服务费 25%。货架调价改为增加分站 1 元兑换哈夫币比例。sql-guard 仅保护 main 已发布迁移。
2026-09-08 19:02:58 +08:00
parent 48a2961245
commit d762b33f54
48 changed files with 745 additions and 1073 deletions
@@ -1,7 +1,7 @@
 # 分销网管理后台设计方案

-> 状态：草案 v0.2  
-> 更新时间：2026-09-04  
+> 状态：草案 v0.6  
+> 更新时间：2026-09-08  
 > 适用范围：分销网站正常租赁订单管理、订单分账、分销客服与支付配置

 ## 1. 文档目的
@@ -25,7 +25,7 @@
 - 客服：`chat_conversations`、`chat_messages`、客服组和二维码池。
 - 管理权限：`admin_users`、`roles`、`permissions`、角色权限关联和审计日志。

-现有系统的价格快照已包含 `seller_ratio`、`buyer_ratio`、`seller_total_price`、`buyer_total_price` 和 `platform_markup_amount`。但现有默认语义是平台加价归平台，分销计划要求销售加价归卖方，因此分销必须使用独立的分账快照，不能直接改变旧字段含义。
+现有系统的价格快照已包含 `seller_ratio`、`buyer_ratio`、`seller_total_price`、`buyer_total_price` 和 `platform_markup_amount`。挂牌比例的语义是「1 元兑换多少万哈夫币」，`价格 = 哈夫币万数 / 比例`，比例越大越便宜。分销规则里的 35% / 40% / 25% **不是**这套挂牌比例，而是卖出后利润的百分比分成，见第 7.1 节。分站货架加价改的是该站账号的挂牌兑换比例，见第 7.6 节。分销必须使用独立的分账快照，不能直接改变主站旧字段含义。

 ## 3. 总体架构

@@ -85,9 +85,9 @@ audit.go

 1. 显示正常订单中已售出账号的详情。
 2. 显示分销网站自己通过正常订单收购/接收的账号详情（卖家在分销网站上架，租客完成交易）。
-3. 配置分销网站在正常订单中的收号比例；主站卖出比例统一或按规则版本管理。
+3. 配置分销网站在正常订单中的收号分成百分比；主站卖出百分比统一或按规则版本管理（默认收号 35% / 卖出 40% / 服务费 25%）。
 4. 分销网站使用指定客服组和指定二维码池的拉群码。
-5. 查看手续费、服务费、加价、税费、分成和结算金额。
+5. 查看通道手续费、服务费（利润的 25%）、货架兑换比例、税费、分成和结算金额。
 6. 配置分销网站是否展示账号，并可单独关闭某个账号。
 7. 配置分销网站可使用的一个或多个收款支付渠道。
 8. 分销客服只读订单信息和过程记录，并可按权限处理客服消息。
@@ -181,7 +181,7 @@ distribution:chat_send

 - 订单号、商品编号、账号基本信息和账号快照。
 - 分销网站、收号方、售出方和租客。
- 收号比例、销售比例、销售基础价、销售加价和实际支付金额。
+- 收号 35%、卖出 40%、服务费 25%、该站 1 元兑换哈夫币比例、销售价和实际支付金额。
 - 退款、手续费、服务费、税费、各方收入和结算状态。
 - 交接、租用、归还、结账、退款、仲裁等过程事件。

@@ -244,44 +244,63 @@ offline

 ## 7. 比例、费用和分账口径

-### 7.1 初步默认规则（可后台调整）
+### 7.1 卖出后利润的百分比分成（已确认）

-第一版先按以下规则建立默认配置，后续由平台后台调整。默认配置不是写死在代码中的常量，必须保存为可启用/停用、可版本化的后台规则：
+口头常说的 3.5 / 4 / 2.5，统一写成 **35% / 40% / 25%**。这是卖出完成后的利润分成，三方合计 100%。不是挂牌定价比例（不是 1:3.5 / 1:4），文档、字段、后台和代码都只写百分比，不再写「成」。
+
+| 分成 | 角色 |
+| --- | --- |
+| 35% | 收号 / 上架方 |
+| 40% | 卖出方 |
+| 25% | 平台服务费 |
+| 合计 100% | 切完这一笔利润，不另留大头给平台（四舍五入尾差除外） |

 ```text
-两方：分销网收 3.5，主站卖出 4，服务费 2.5
-两方：分销网卖 4，主站收 3.5，服务费 2.5
-三方：主站服务费 2.5，分销 A 上架 3.5，分销 B 卖出 4
+某方金额 = round_half_up(利润基数 × 百分比 / 100)
 ```

-初步配置含义：
+规则字段存 `35` / `40` / `25`，计算一律 `× 百分比 / 100`。

-| 模式 | 参与方 | 初始比例/费用 |
+**禁止**把口头的 3.5 / 4 / 2.5 直接存进字段再 `/ 100`（那会变成 3.5%、4%、2.5%，九成以上留给平台）。  
+**禁止**把 25% 服务费当成固定金额、或 `实付 / 2.5`。服务费与收号、卖出是同一笔利润上的三刀。
+
+默认角色（可按站点、模式出新规则版本，历史订单用快照）：
+
+| 模式 | 参与方 | 初始分成 |
 | --- | --- | --- |
-| 两方-分销网收号 | 分销网收号、主站卖出 | 分销网 `3.5`，主站 `4`，服务费 `2.5` |
-| 两方-主站收号 | 分销网卖出、主站收号 | 分销网 `4`，主站 `3.5`，服务费 `2.5` |
-| 三方 | 主站服务费、分销 A 上架、分销 B 卖出 | 主站服务费 `2.5`，分销 A `3.5`，分销 B `4` |
+| 两方-分销网收号 | 分销网收号、主站卖出 | 分销网 35%，主站 40%，服务费 25% |
+| 两方-主站收号 | 分销网卖出、主站收号 | 分销网 40%，主站 35%，服务费 25% |
+| 三方 | 主站服务费、分销 A 上架、分销 B 卖出 | 主站服务费 25%，分销 A 35%，分销 B 40% |

-以上是当前业务的初始值。后台需要允许平台管理员按分销网站、交易模式和生效时间修改比例及费用；新订单读取当前生效规则并写入快照，历史订单不跟随后台修改。
+规则字段按参与方角色命名（`distributor_receive_ratio` 等）。后台文案写「35% / 40% / 25%」。

-现有系统的比例语义是“哈夫币数量 / 比例 = 价格”，比例越大，价格越低。3.5 和 4 在分销规则中先分别作为“收号/上架方比例”和“卖出方比例”保存；如果后续确认比例含义需要调整，只影响规则解释和新订单，已结算订单仍以金额快照为准。
+默认值必须通过迁移或初始化数据写入，不写死在结算公式里。新订单读取当前生效规则并写入快照，历史订单不跟随后台修改。
+
+利润基数（与通道手续费分层，见 7.5）：
+
+```text
+利润基数 = 卖出后可供分销三方分配的利润
+        = 租客实付租金 - 号主应得 - 支付通道手续费
+```
+
+号主应得走订单原有 `owner_rent_amount_cent`（结账按实际消耗重算时用实际号主租金），不从 35% 里再扣。35% / 40% / 25% 只切上面这一笔利润。

 ### 7.2 必须确认的口径

-以下项目在 v0.2 中分为“已有初始值”和“仍待确认”：
+v0.6 已锁定 7.1 的百分比分成和 7.6 的分站加价。其余仍待确认：

-| 项目 | 待确认内容 |
+| 项目 | 状态 |
 | --- | --- |
-| 两方/三方初始比例 | 已按 7.1 建立默认值，后台可调整 |
-| 分销网站收号比例 | 已确定可按站点调整；是否设置上下限待确认 |
-| 主站统一卖出比例 | 初步按规则版本配置；是否全站固定待确认 |
-| 三方分销 | 已确定保留 A 上架、B 卖出角色；结算顺序和亏损承担待确认 |
-| 3.5 和 4 的最终业务含义 | 初步按收号/上架方与卖出方比例保存，最终文字口径待确认 |
-| 服务费 2.5 | 百分比、金额，还是比例值 |
-| 销售加价 | 是否计入服务费和税费基数 |
-| 税费税基 | 毛利、收入，还是分成后金额 |
-| 退款处理 | 重算剩余分成，还是生成反向冲正流水 |
-| 四舍五入尾差 | 统一归主站还是按最大分成方承担 |
+| 35% / 40% / 25% 的含义 | **已确认**：卖出后利润的百分比分成；口头 3.5/4/2.5 不再使用 |
+| 服务费 25% | **已确认**：利润的 25%，与收号、卖出同一基数 |
+| 分站加价 | **已确认**：增加该站账号「1 元兑换哈夫币」的比例，不是叠加人民币，见 7.6 |
+| 两方/三方角色 | **已确认**：收号/上架 35%，卖出 40%，服务费 25% |
+| 利润是否扣号主、是否按结账消耗重算 | 公式已写在 7.1；结账后利润是否按实际消耗重切待确认 |
+| 分销网站收号百分比上下限 | 待确认 |
+| 三方亏损承担 | 待确认 |
+| 税费税基 | 待确认：各方分成后毛利，还是利润基数 |
+| 退款处理 | 待确认：重算剩余分成，还是生成反向冲正流水 |
+| 四舍五入尾差 | 待确认：统一归主站还是按最大分成方承担 |

 ### 7.3 后台调整要求

@@ -289,7 +308,7 @@ offline

 1. 只允许具备 `distribution:rule_manage` 权限的管理员操作。
 2. 新增规则版本，不直接覆盖已生效版本的历史内容。
-3. 支持按分销网站、交易模式配置收号比例、卖出比例、服务费、手续费和税费开关。
+3. 支持按分销网站、交易模式配置收号百分比、卖出百分比、服务费百分比、通道手续费和税费开关；三方百分比之和必须为 100。
 4. 支持设置生效时间；同一站点同一模式同一时刻只能有一个生效版本。
 5. 修改前展示影响范围和新旧值，确认后写入审计日志。
 6. 已创建、已支付或已结算订单继续使用其规则快照。
@@ -297,55 +316,71 @@ offline

 ### 7.4 推荐的金额模型

-比例只负责生成金额，最终结算全部以整数分金额为准。每笔订单保存：
+两套「比例」不能混用，快照里必须分开存：

 ```text
-ratio_snapshot
+挂牌兑换比例：1 元 = X 万哈夫币（主站 publish_ratio / buyer_ratio，分站货架加价改的是这个）
+分成百分比：35 / 40 / 25（只用于卖出后利润切分，字段存百分数不是 3.5）
+```
+
+最终结算全部以整数分为准。每笔订单保存：
+
+```text
+split_percent_snapshot  # 各方分成 35 / 40 / 25
+shelf_ratio_snapshot    # 该站下单时的 1 元兑换哈夫币比例
 amount_snapshot
 rule_version
 ```

-建议所有金额字段使用 `*_cent BIGINT`，所有费率使用基点 `*_bps INT`：
+建议所有金额字段使用 `*_cent BIGINT`。通道手续费、税率继续用基点 `*_bps INT`：

 ```text
 0.5% = 50 bps
 1%   = 100 bps
+分成 35% 存 35，计算用 × 35 / 100；不要存 3.5
 ```

-### 7.5 手续费
+### 7.5 通道手续费与平台服务费

-计划要求手续费在分成前扣除，按退款后的实际支付金额计算，费率为 0.5%，结果四舍五入。
+支付通道手续费和平台服务费不是同一层。

-推荐公式：
+通道手续费：在算利润之前扣，按退款后的实际支付金额，费率 0.5%，四舍五入。

 ```text
 实际支付金额 = 支付金额 - 成功退款金额
-手续费 = round_half_up(实际支付金额 × 50 / 10000)
-分成基数 = 实际支付金额 - 手续费
+通道手续费   = round_half_up(实际支付金额 × 50 / 10000)
+利润基数     = 实际支付金额 - 号主应得 - 通道手续费
+平台服务费   = round_half_up(利润基数 × 25 / 100)    # 25%
+收号/上架    = round_half_up(利润基数 × 35 / 100)    # 35%
+卖出         = round_half_up(利润基数 × 40 / 100)    # 40%
 ```

-“服务费 2.5”是否属于同一手续费层级：待确认。实现时必须将 `payment_fee`、`service_fee` 分成独立字段，不能合并为一个不可解释的费用。
+`payment_fee` 与 `service_fee` 必须分字段。服务费是利润的 25%，不是通道手续费，不是固定元，也不是 `实付/2.5`。

-### 7.6 销售加价
+### 7.6 分站加价（改兑换比例，不是加人民币）

-计划要求商家加价销售时，加价全部归卖方。
-
-建议保存：
+分站加价是**增加该分站货架上账号的「1 元兑换哈夫币」比例**，与主站挂牌比例同一语义：

 ```text
-markup_amount_cent
-markup_beneficiary_type
-markup_beneficiary_id
+1 元 = 比例 w 哈夫币
+价格(元) = 哈夫币万数 / 比例
+比例越大，1 元换到的哈夫币越多，同样币数售价越低
 ```

-建议第一版按以下方式实现：
+不是在总租金上叠加人民币，不是「元/小时」。

 ```text
-销售总价 - 销售基础价 = 销售加价
-销售加价全部计入卖方收入
+分站展示比例 = 主站原兑换比例 + 该站加价比例
+分站售价     = 哈夫币万数 / 分站展示比例
 ```

-加价是否计入服务费和税费基数：待确认。无明确规则前，结算引擎必须分别展示基础分成和加价，避免隐含扣费。
+约束：
+
+1. 加价存在 `distribution_site_accounts` 上，只影响该站货架和该站订单。
+2. 主站列表、主站订单、号主回收比例不因分站加价而变。
+3. 下单必须把「该站展示比例」和算出的售价写入订单快照；之后改货架比例不影响历史单。
+4. 货架字段是比例点数，不是 `markup_amount_cent`。现有按人民币、按小时加价的实现与本口径不一致，下一迭代改掉。
+5. 「增加比例」按现有引擎会让该站标价低于主站。卖出后的利润仍按 7.1 切 35% / 40% / 25%；不要再把「加价人民币」单独加给卖方。

 ### 7.7 税费

@@ -373,13 +408,18 @@ tax_rate_bps

 ```text
 实际支付金额
-= 手续费
- + 平台服务费
- + 各参与方收入
- + 税费
- + 固定规则下的舍入尾差
+= 号主应得
+ + 通道手续费
+ + 利润基数
+利润基数
+= 收号/上架 35%
+ + 卖出 40%
+ + 平台服务费 25%
+ + 四舍五入尾差
 ```

+税费若开启，从各方分成中计，不破坏上面 100% 切完利润的关系；具体税基见 7.2。
+
 退款、拒付、仲裁和结算撤销必须生成反向明细，不能直接覆盖原结算记录。

 ## 8. 建议数据模型
@@ -419,6 +459,7 @@ distribution_site_accounts

 ```text
 id, site_id, account_id, listing_id, display_status
+shelf_ratio_delta            # 该站加价：增加的 1 元兑换哈夫币比例点数，不是人民币
 display_started_at, display_ended_at
 created_at, updated_at
 ```
@@ -435,14 +476,14 @@ distribution_rule_versions
 ```text
 site_id
 mode: two_party / three_party
-platform_receive_ratio
-platform_sell_ratio
-distributor_receive_ratio
-distributor_sell_ratio
-distributor_a_ratio
-distributor_b_ratio
-service_fee_value
-service_fee_unit: percent / fixed_amount / ratio
+platform_receive_ratio       # 百分比，默认 35
+platform_sell_ratio          # 百分比，默认 40
+distributor_receive_ratio    # 百分比，默认 35
+distributor_sell_ratio       # 百分比，默认 40
+distributor_a_ratio          # 百分比，默认 35
+distributor_b_ratio          # 百分比，默认 40
+service_fee_value            # 百分比，默认 25
+service_fee_unit: percent    # 只表示百分数；禁止 fixed_amount / 金额÷value
 payment_fee_bps
 tax_enabled
 tax_rate_bps
@@ -450,15 +491,15 @@ effective_from, effective_to
 version, status
 ```

-首批默认规则按第 7.1 节初始化：
+同一规则里收号 + 卖出 + 服务费必须等于 100。首批默认规则按第 7.1 节初始化：

 ```text
-two_party_distributor_receive: distributor_receive_ratio=3.5, platform_sell_ratio=4, service_fee_value=2.5
-two_party_platform_receive: platform_receive_ratio=3.5, distributor_sell_ratio=4, service_fee_value=2.5
-three_party: distributor_a_ratio=3.5, distributor_b_ratio=4, service_fee_value=2.5
+two_party_distributor_receive: distributor_receive_ratio=35, platform_sell_ratio=40, service_fee_value=25
+two_party_platform_receive: platform_receive_ratio=35, distributor_sell_ratio=40, service_fee_value=25
+three_party: distributor_a_ratio=35, distributor_b_ratio=40, service_fee_value=25
 ```

-其中 `two_party_platform_receive` 的参与方方向为分销网卖出、主站收号；比例初始值为分销网 `4`、主站 `3.5`。规则字段使用参与方角色命名，避免只写 `receive_ratio`/`sell_ratio` 造成方向歧义。上面的服务费 `2.5` 先作为规则配置值保存，具体单位由后台规则字段和后续口径确认决定。默认规则必须通过迁移或初始化数据写入，不写死在前端或结算代码中。
+字段按参与方角色命名。库里存百分数 35 / 40 / 25，计算一律 `× 百分比 / 100`。已写入的 3.5 / 4 / 2.5 不能当百分数用，迁移时换算成 35 / 40 / 25。默认规则必须通过迁移或初始化数据写入，不写死在结算代码中。

 ### 8.5 订单参与方

@@ -666,9 +707,10 @@ distribution.hao858.com {

 ### 阶段 0：确认业务口径

- 确认 3.5、4、2.5 的单位和方向。
- 确认两方、三方参与方及亏损承担。
- 确认加价是否计入服务费和税费。
+- ~~确认 3.5、4、2.5 的单位和方向。~~ **已确认（v0.6）**：卖出后利润分成 35% / 40% / 25%，文档与字段只写百分比。
+- ~~确认加价形态。~~ **已确认（v0.6）**：分站加价增加该站「1 元兑换哈夫币」比例，不是叠加人民币。
+- 确认两方、三方亏损承担。
+- 确认结账后利润是否按实际消耗重切。
 - 确认税费毛利计算口径。
 - 确认退款采用重算还是冲正。
 - 确认分销员和分销客服的身份模型。
@@ -717,10 +759,10 @@ distribution.hao858.com {

 ### 账务正确性

- 手续费按退款后的实际支付金额计算。
- 手续费先扣除，再进行分成。
- 0.5% 使用四舍五入并以分保存。
- 销售加价归指定卖方。
+- 通道手续费按退款后的实际支付金额计算，0.5%，四舍五入，以分保存。
+- 通道手续费和号主应得先扣，得到利润基数后再切 35% / 40% / 25%。
+- 收号 35%、卖出 40%、服务费 25%；字段存 35/40/25，禁止存 3.5/4/2.5 再当百分数乘。
+- 分站加价改该站 1 元兑换哈夫币比例，不叠加人民币；历史订单用下单时的比例快照。
 - 各主体独立计算税费。
 - 重复支付、退款和结算请求不会重复入账。
 - 分销结算明细与钱包流水一致。
@@ -748,9 +790,9 @@ distribution.hao858.com {

 1. 分销网站是平台合作方，还是普通用户下的分销身份？
 2. 分销客服是否使用现有 `admin_users`？
-3. 3.5、4、2.5 的确切单位和计算方向是什么？
-4. 服务费和支付手续费是否都按实际支付净额计算？
-5. 加价是否计入服务费、税费和退款基数？
+3. ~~3.5、4、2.5 的确切单位和计算方向是什么？~~ **已确认**：利润分成 35% / 40% / 25%，只写百分比，见 7.1。
+4. ~~服务费和支付手续费是否都按实际支付净额计算？~~ **已确认**：通道手续费按实付净额 0.5%；服务费是利润的 25%。
+5. ~~加价是否计入服务费、税费和退款基数？~~ **已确认加价形态**：改兑换比例，不是人民币；利润仍按 7.1 切 35% / 40% / 25%。
 6. 税费是否只对正毛利计提？亏损是否结转？
 7. 退款后佣金是重算剩余金额，还是追加负向冲正？
 8. 一个账号能否同时展示在多个分销网站？
@@ -762,13 +804,13 @@ distribution.hao858.com {

 后续每次确认业务规则后，优先更新第 7、15 节，再同步更新第 8、9、13、14 节，确保规则、数据、接口、实施和验收标准保持一致。

-## 16. 当前实现基线（v0.4）
+## 16. 当前实现基线（v0.4，口径落后于 v0.6）

 本分支已落地第一批可运行功能，主站域名为 `https://hao858.com/`，独立后台工程位于 `distribution-admin/`，子域名暂定 `https://distribution.hao858.com/`：

 - Go 后端新增 `distribution_sites`、成员、账号展示、规则版本、订单财务快照、订单参与方、结算批次/明细、支付通道绑定表。
 - `rental_orders` 增加分销站点、模式和规则版本字段；只有正常租赁订单才允许写入这些字段。
- 分账计算引擎已实现退款后净支付、0.5% 基点手续费先扣、服务费三种单位、加价单独展示、各参与方毛利税费和四舍五入。
+- 分账计算引擎已实现退款后净支付、0.5% 基点手续费先扣、服务费三种单位、加价单独展示、各参与方毛利税费和四舍五入。**与 v0.6 口径不一致**：库和默认规则仍存 3.5 / 4 / 2.5，代码按 `分成基数 × 3.5 / 100`（当成 3.5%）切；服务费 `ratio` 单位是 `实付/2.5`；货架加价是人民币而不是兑换比例。生产结算/提现继续冻结。下一迭代把规则改存 35 / 40 / 25，公式 `× 百分比 / 100`，并改货架比例字段。
 - 管理 API 已覆盖站点、规则、售出/收号订单查询、财务快照、账号展示开关、支付通道绑定和结算批次。
 - 后台权限使用 `distribution:*` 权限码；后续接入成员站点数据范围校验时，不能使用请求参数扩大范围。
 - `distribution-admin` 使用 React + TypeScript + Vite + Ant Design，已提供仪表盘、站点、售出订单、收号订单及结算/支付/账号/规则/客服入口和 Docker 镜像。