实现分销网后台基础功能与独立前端
This commit is contained in:
yml2213
@@ -0,0 +1,776 @@
|
||||
# 分销网管理后台设计方案
|
||||
|
||||
> 状态：草案 v0.2
|
||||
> 更新时间：2026-09-04
|
||||
> 适用范围：分销网站正常租赁订单管理、订单分账、分销客服与支付配置
|
||||
|
||||
## 1. 文档目的
|
||||
|
||||
本文档记录分销网管理后台的产品计划、领域模型、分账口径、接口边界、部署方案和实施顺序。
|
||||
|
||||
本文档是持续维护的设计基线。业务规则尚未确认的部分使用“待确认”标记，进入开发前必须补齐；已创建的订单必须使用规则和金额快照，不能因后续规则变更而重算历史账目。
|
||||
|
||||
## 2. 现有系统基础
|
||||
|
||||
当前 HFB Sys 是 Go + Gin + GORM + MySQL + Redis 后端，Vue 3 + Element Plus 用户端/运营后台前端，生产通过 Caddy 托管静态文件并反代单个 backend 服务。
|
||||
|
||||
可复用的现有领域：
|
||||
|
||||
- 用户：`users`、实名认证、用户状态。
|
||||
- 商品和账号：`rental_listings`、`game_accounts`、账号资产快照。
|
||||
- 正常订单：`rental_orders`、交接、归还、结账、退款和订单过程事件。
|
||||
- 订单来源：`rental_orders` 的正常租赁交易；分销网只处理卖家和租客都在网站内完成的正常订单。
|
||||
- 资金：`wallet_accounts`、`wallet_ledger`、`withdrawal_requests`。
|
||||
- 支付：`payment_merchant_configs`、支付单、退款单和支付配置使用日志。
|
||||
- 客服：`chat_conversations`、`chat_messages`、客服组和二维码池。
|
||||
- 管理权限：`admin_users`、`roles`、`permissions`、角色权限关联和审计日志。
|
||||
|
||||
现有系统的价格快照已包含 `seller_ratio`、`buyer_ratio`、`seller_total_price`、`buyer_total_price` 和 `platform_markup_amount`。但现有默认语义是平台加价归平台，分销计划要求销售加价归卖方，因此分销必须使用独立的分账快照，不能直接改变旧字段含义。
|
||||
|
||||
## 3. 总体架构
|
||||
|
||||
### 3.1 独立前端、复用后端
|
||||
|
||||
分销网管理后台独立为新的前端工程，推荐 React + TypeScript + Vite + Ant Design。现有 Vue + Element Plus 用户端和运营后台保持不变。
|
||||
|
||||
```text
|
||||
主站：https://hao858.com/
|
||||
现有运营后台：https://hao858.com/manage-xxx
|
||||
分销后台：暂定使用主域名下的独立子域名，例如 `distribution.hao858.com`
|
||||
```
|
||||
|
||||
分销后台通过独立域名提供静态资源，`/api/*` 反代到现有 Go backend：
|
||||
|
||||
```text
|
||||
distribution.hao858.com（暂定）
|
||||
├── / 独立 Ant Design 静态资源
|
||||
└── /api/* reverse_proxy backend:8080
|
||||
```
|
||||
|
||||
这样可以避免在同一个 Vue 应用中同时引入 Element Plus 和 Ant Design，也避免跨域 Cookie 和 CORS 配置。
|
||||
|
||||
### 3.2 后端暂不拆服务
|
||||
|
||||
第一阶段不新建独立分销后端服务。分销模块继续使用现有 MySQL、Redis、钱包、订单、支付、客服和权限体系，以便在同一事务中处理支付、退款、分成、税费和钱包流水。
|
||||
|
||||
建议新增后端目录：
|
||||
|
||||
```text
|
||||
backend/internal/modules/distribution/
|
||||
```
|
||||
|
||||
建议文件：
|
||||
|
||||
```text
|
||||
dto.go
|
||||
handler.go
|
||||
service.go
|
||||
repository.go
|
||||
query.go
|
||||
mutation.go
|
||||
pricing.go
|
||||
settlement.go
|
||||
payment.go
|
||||
qrcode.go
|
||||
chat.go
|
||||
presenter.go
|
||||
audit.go
|
||||
```
|
||||
|
||||
## 4. 业务目标与后台功能
|
||||
|
||||
### 4.1 分销后台功能
|
||||
|
||||
第一版需要覆盖（仅限正常租赁订单）：
|
||||
|
||||
1. 显示正常订单中已售出账号的详情。
|
||||
2. 显示分销网站自己通过正常订单收购/接收的账号详情（卖家在分销网站上架，租客完成交易）。
|
||||
3. 配置分销网站在正常订单中的收号比例；主站卖出比例统一或按规则版本管理。
|
||||
4. 分销网站使用指定客服组和指定二维码池的拉群码。
|
||||
5. 查看手续费、服务费、加价、税费、分成和结算金额。
|
||||
6. 配置分销网站是否展示账号，并可单独关闭某个账号。
|
||||
7. 配置分销网站可使用的一个或多个收款支付渠道。
|
||||
8. 分销客服只读订单信息和过程记录，并可按权限处理客服消息。
|
||||
9. 主站查看所有分销网站的收售订单、收款金额和结算数据。
|
||||
|
||||
### 4.2 建议页面
|
||||
|
||||
```text
|
||||
仪表盘
|
||||
分销网站管理
|
||||
正常订单售出账号
|
||||
分销收售订单
|
||||
佣金/分成明细
|
||||
结算管理
|
||||
比例与税费规则
|
||||
支付通道
|
||||
客服组与二维码
|
||||
账号展示管理
|
||||
报表
|
||||
操作日志
|
||||
```
|
||||
|
||||
## 5. 业务主体和权限
|
||||
|
||||
### 5.1 分销网站
|
||||
|
||||
建议使用独立主体表 `distribution_sites`。分销网站不是普通用户，也不直接等同于平台管理员。
|
||||
|
||||
分销网站至少需要保存：
|
||||
|
||||
- 编码、名称、域名和状态。
|
||||
- 联系人信息。
|
||||
- 是否允许自动展示账号。
|
||||
- 默认客服组和专属二维码池。
|
||||
- 税费开关和税率。
|
||||
- 创建、停用和更新时间。
|
||||
|
||||
### 5.2 分销网站成员
|
||||
|
||||
建议使用 `distribution_site_members` 将现有 `admin_users` 映射到一个或多个分销网站。
|
||||
|
||||
成员类型建议包括：
|
||||
|
||||
- `operator`：查看业务和账号展示。
|
||||
- `finance`：查看分成、结算和收款金额。
|
||||
- `customer_service`：查看订单、过程记录和客服消息。
|
||||
|
||||
分销网站成员只能看到所属站点的数据。前端传入的 `site_id` 不能扩大数据范围，后端必须从当前管理员成员关系中推导并校验。
|
||||
|
||||
### 5.3 权限码
|
||||
|
||||
建议新增：
|
||||
|
||||
```text
|
||||
distribution:site_view
|
||||
distribution:site_manage
|
||||
distribution:account_view
|
||||
distribution:account_display
|
||||
distribution:order_view
|
||||
distribution:process_view
|
||||
distribution:finance_view
|
||||
distribution:settlement_view
|
||||
distribution:settlement_manage
|
||||
distribution:rule_view
|
||||
distribution:rule_manage
|
||||
distribution:payment_view
|
||||
distribution:payment_manage
|
||||
distribution:qrcode_view
|
||||
distribution:qrcode_manage
|
||||
distribution:chat_view
|
||||
distribution:chat_send
|
||||
distribution:all_view
|
||||
```
|
||||
|
||||
分销客服默认只拥有：
|
||||
|
||||
```text
|
||||
distribution:order_view
|
||||
distribution:process_view
|
||||
distribution:chat_view
|
||||
distribution:chat_send
|
||||
```
|
||||
|
||||
客服禁止修改比例、支付配置、展示状态、退款、订单状态和结算结果。
|
||||
|
||||
## 6. 订单和账号展示
|
||||
|
||||
### 6.1 售出账号详情
|
||||
|
||||
分销后台需要显示：
|
||||
|
||||
- 订单号、商品编号、账号基本信息和账号快照。
|
||||
- 分销网站、收号方、售出方和租客。
|
||||
- 收号比例、销售比例、销售基础价、销售加价和实际支付金额。
|
||||
- 退款、手续费、服务费、税费、各方收入和结算状态。
|
||||
- 交接、租用、归还、结账、退款、仲裁等过程事件。
|
||||
|
||||
账号密码、实名信息等敏感字段必须按照现有后台脱敏和权限规则返回。是否允许分销成员查看完整登录信息：待确认。
|
||||
|
||||
### 6.2 分销网站正常订单收号详情
|
||||
|
||||
分销网的收号不是线下提号记录，而是正常租赁订单中的一方角色：卖家在分销网站上架账号，租客在分销网站完成支付、交接、租用和归还。该类记录应从 `rental_orders` 及分销订单参与方快照查询，不能使用 `admin_pickups` 作为数据来源。
|
||||
|
||||
正常订单需要保存分销站点和参与方快照，例如：
|
||||
|
||||
```text
|
||||
distribution_site_id
|
||||
seller_party_id
|
||||
renter_party_id
|
||||
receive_ratio
|
||||
receive_amount_cent
|
||||
rule_version
|
||||
```
|
||||
|
||||
不新增独立的线下收号流程；如需展示“分销网收号记录”，通过正常订单中的 `distributor_receive` 角色和订单状态筛选实现。
|
||||
|
||||
### 6.3 账号展示开关
|
||||
|
||||
网站级配置：
|
||||
|
||||
```text
|
||||
distribution_sites.display_account_enabled
|
||||
```
|
||||
|
||||
账号级配置：
|
||||
|
||||
```text
|
||||
distribution_site_accounts.display_status
|
||||
```
|
||||
|
||||
账号状态建议为：
|
||||
|
||||
```text
|
||||
enabled
|
||||
disabled
|
||||
sold
|
||||
offline
|
||||
```
|
||||
|
||||
关闭展示不删除账号、不影响历史订单，只阻止新展示或新订单，并写入审计日志。
|
||||
|
||||
一个账号是否允许同时挂载多个分销网站：待确认。第一版建议一个账号在同一时刻只归属一个可售分销网站，避免重复出售和归因冲突。
|
||||
|
||||
### 6.4 不纳入分销网的业务
|
||||
|
||||
以下业务不属于分销网正常订单，不进入分销订单分账：
|
||||
|
||||
- 平台或管理员线下提号（`admin_pickups`）。
|
||||
- 平台代管账号及线下交接、线下结算。
|
||||
- 撞车商品及撞车订单（`mohong`/`crash`）。
|
||||
- 分销网站之外的外部导入、私下交易或人工补录订单。
|
||||
|
||||
分销网订单必须同时满足：订单来源站点是分销网站、卖家和租客均属于该正常订单链路、支付和订单状态在平台系统内可追踪。
|
||||
|
||||
## 7. 比例、费用和分账口径
|
||||
|
||||
### 7.1 初步默认规则（可后台调整）
|
||||
|
||||
第一版先按以下规则建立默认配置，后续由平台后台调整。默认配置不是写死在代码中的常量，必须保存为可启用/停用、可版本化的后台规则：
|
||||
|
||||
```text
|
||||
两方：分销网收 3.5，主站卖出 4，服务费 2.5
|
||||
两方：分销网卖 4，主站收 3.5，服务费 2.5
|
||||
三方：主站服务费 2.5，分销 A 上架 3.5，分销 B 卖出 4
|
||||
```
|
||||
|
||||
初步配置含义：
|
||||
|
||||
| 模式 | 参与方 | 初始比例/费用 |
|
||||
| --- | --- | --- |
|
||||
| 两方-分销网收号 | 分销网收号、主站卖出 | 分销网 `3.5`，主站 `4`，服务费 `2.5` |
|
||||
| 两方-主站收号 | 分销网卖出、主站收号 | 分销网 `4`，主站 `3.5`，服务费 `2.5` |
|
||||
| 三方 | 主站服务费、分销 A 上架、分销 B 卖出 | 主站服务费 `2.5`，分销 A `3.5`，分销 B `4` |
|
||||
|
||||
以上是当前业务的初始值。后台需要允许平台管理员按分销网站、交易模式和生效时间修改比例及费用；新订单读取当前生效规则并写入快照，历史订单不跟随后台修改。
|
||||
|
||||
现有系统的比例语义是“哈夫币数量 / 比例 = 价格”，比例越大，价格越低。3.5 和 4 在分销规则中先分别作为“收号/上架方比例”和“卖出方比例”保存；如果后续确认比例含义需要调整，只影响规则解释和新订单，已结算订单仍以金额快照为准。
|
||||
|
||||
### 7.2 必须确认的口径
|
||||
|
||||
以下项目在 v0.2 中分为“已有初始值”和“仍待确认”：
|
||||
|
||||
| 项目 | 待确认内容 |
|
||||
| --- | --- |
|
||||
| 两方/三方初始比例 | 已按 7.1 建立默认值，后台可调整 |
|
||||
| 分销网站收号比例 | 已确定可按站点调整；是否设置上下限待确认 |
|
||||
| 主站统一卖出比例 | 初步按规则版本配置；是否全站固定待确认 |
|
||||
| 三方分销 | 已确定保留 A 上架、B 卖出角色；结算顺序和亏损承担待确认 |
|
||||
| 3.5 和 4 的最终业务含义 | 初步按收号/上架方与卖出方比例保存，最终文字口径待确认 |
|
||||
| 服务费 2.5 | 百分比、金额，还是比例值 |
|
||||
| 销售加价 | 是否计入服务费和税费基数 |
|
||||
| 税费税基 | 毛利、收入，还是分成后金额 |
|
||||
| 退款处理 | 重算剩余分成，还是生成反向冲正流水 |
|
||||
| 四舍五入尾差 | 统一归主站还是按最大分成方承担 |
|
||||
|
||||
### 7.3 后台调整要求
|
||||
|
||||
后台调整规则时必须：
|
||||
|
||||
1. 只允许具备 `distribution:rule_manage` 权限的管理员操作。
|
||||
2. 新增规则版本，不直接覆盖已生效版本的历史内容。
|
||||
3. 支持按分销网站、交易模式配置收号比例、卖出比例、服务费、手续费和税费开关。
|
||||
4. 支持设置生效时间；同一站点同一模式同一时刻只能有一个生效版本。
|
||||
5. 修改前展示影响范围和新旧值，确认后写入审计日志。
|
||||
6. 已创建、已支付或已结算订单继续使用其规则快照。
|
||||
7. 比例、费率和金额必须由后端校验范围，前端输入不能绕过校验。
|
||||
|
||||
### 7.4 推荐的金额模型
|
||||
|
||||
比例只负责生成金额，最终结算全部以整数分金额为准。每笔订单保存：
|
||||
|
||||
```text
|
||||
ratio_snapshot
|
||||
amount_snapshot
|
||||
rule_version
|
||||
```
|
||||
|
||||
建议所有金额字段使用 `*_cent BIGINT`，所有费率使用基点 `*_bps INT`：
|
||||
|
||||
```text
|
||||
0.5% = 50 bps
|
||||
1% = 100 bps
|
||||
```
|
||||
|
||||
### 7.5 手续费
|
||||
|
||||
计划要求手续费在分成前扣除，按退款后的实际支付金额计算，费率为 0.5%，结果四舍五入。
|
||||
|
||||
推荐公式：
|
||||
|
||||
```text
|
||||
实际支付金额 = 支付金额 - 成功退款金额
|
||||
手续费 = round_half_up(实际支付金额 × 50 / 10000)
|
||||
分成基数 = 实际支付金额 - 手续费
|
||||
```
|
||||
|
||||
“服务费 2.5”是否属于同一手续费层级：待确认。实现时必须将 `payment_fee`、`service_fee` 分成独立字段，不能合并为一个不可解释的费用。
|
||||
|
||||
### 7.6 销售加价
|
||||
|
||||
计划要求商家加价销售时，加价全部归卖方。
|
||||
|
||||
建议保存：
|
||||
|
||||
```text
|
||||
markup_amount_cent
|
||||
markup_beneficiary_type
|
||||
markup_beneficiary_id
|
||||
```
|
||||
|
||||
建议第一版按以下方式实现：
|
||||
|
||||
```text
|
||||
销售总价 - 销售基础价 = 销售加价
|
||||
销售加价全部计入卖方收入
|
||||
```
|
||||
|
||||
加价是否计入服务费和税费基数：待确认。无明确规则前，结算引擎必须分别展示基础分成和加价，避免隐含扣费。
|
||||
|
||||
### 7.7 税费
|
||||
|
||||
计划要求对分销所得利益按毛利的 1% 计税，并支持开关和可调税率；每个主体承担自己的分成税费。
|
||||
|
||||
推荐配置：
|
||||
|
||||
```text
|
||||
tax_enabled
|
||||
tax_rate_bps
|
||||
```
|
||||
|
||||
推荐公式：
|
||||
|
||||
```text
|
||||
毛利 = 该主体收入 - 该主体收号成本 - 该主体承担的费用
|
||||
税额 = round_half_up(毛利 × tax_rate_bps / 10000)
|
||||
```
|
||||
|
||||
每个主体分别计算税费，主站、分销 A、分销 B 不合并税基。毛利为负时税额暂按 0 处理，亏损如何结转：待确认。
|
||||
|
||||
### 7.8 账务不变量
|
||||
|
||||
每笔分销订单的结算必须满足：
|
||||
|
||||
```text
|
||||
实际支付金额
|
||||
= 手续费
|
||||
+ 平台服务费
|
||||
+ 各参与方收入
|
||||
+ 税费
|
||||
+ 固定规则下的舍入尾差
|
||||
```
|
||||
|
||||
退款、拒付、仲裁和结算撤销必须生成反向明细，不能直接覆盖原结算记录。
|
||||
|
||||
## 8. 建议数据模型
|
||||
|
||||
### 8.1 分销网站
|
||||
|
||||
```text
|
||||
distribution_sites
|
||||
```
|
||||
|
||||
建议字段：
|
||||
|
||||
```text
|
||||
id, site_code, site_name, domain, status
|
||||
display_account_enabled
|
||||
default_support_group_id
|
||||
tax_enabled, tax_rate_bps
|
||||
created_at, updated_at
|
||||
```
|
||||
|
||||
### 8.2 成员关系
|
||||
|
||||
```text
|
||||
distribution_site_members
|
||||
```
|
||||
|
||||
```text
|
||||
id, site_id, admin_user_id, member_type, status, data_scope
|
||||
created_at, updated_at
|
||||
```
|
||||
|
||||
### 8.3 账号展示关系
|
||||
|
||||
```text
|
||||
distribution_site_accounts
|
||||
```
|
||||
|
||||
```text
|
||||
id, site_id, account_id, listing_id, display_status
|
||||
display_started_at, display_ended_at
|
||||
created_at, updated_at
|
||||
```
|
||||
|
||||
### 8.4 规则版本
|
||||
|
||||
```text
|
||||
distribution_rules
|
||||
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
|
||||
payment_fee_bps
|
||||
tax_enabled
|
||||
tax_rate_bps
|
||||
effective_from, effective_to
|
||||
version, status
|
||||
```
|
||||
|
||||
首批默认规则按第 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_platform_receive` 的参与方方向为分销网卖出、主站收号；比例初始值为分销网 `4`、主站 `3.5`。规则字段使用参与方角色命名，避免只写 `receive_ratio`/`sell_ratio` 造成方向歧义。上面的服务费 `2.5` 先作为规则配置值保存，具体单位由后台规则字段和后续口径确认决定。默认规则必须通过迁移或初始化数据写入，不写死在前端或结算代码中。
|
||||
|
||||
### 8.5 订单参与方
|
||||
|
||||
```text
|
||||
distribution_order_parties
|
||||
```
|
||||
|
||||
```text
|
||||
order_id, site_id, party_role, user_id
|
||||
ratio, base_amount_cent, markup_amount_cent
|
||||
gross_amount_cent, fee_amount_cent, tax_amount_cent
|
||||
net_amount_cent, status
|
||||
```
|
||||
|
||||
`party_role` 建议支持：
|
||||
|
||||
```text
|
||||
platform
|
||||
distributor_a
|
||||
distributor_b
|
||||
distributor_receive
|
||||
seller
|
||||
buyer
|
||||
```
|
||||
|
||||
### 8.6 订单财务快照
|
||||
|
||||
```text
|
||||
distribution_order_financials
|
||||
```
|
||||
|
||||
```text
|
||||
order_id UNIQUE
|
||||
gross_paid_amount_cent
|
||||
refund_amount_cent
|
||||
net_paid_amount_cent
|
||||
payment_fee_bps, payment_fee_cent
|
||||
service_fee_bps, service_fee_cent
|
||||
markup_amount_cent
|
||||
tax_enabled, tax_rate_bps, tax_amount_cent
|
||||
split_base_amount_cent
|
||||
settlement_status
|
||||
rule_version
|
||||
created_at, settled_at
|
||||
```
|
||||
|
||||
### 8.7 结算批次和明细
|
||||
|
||||
```text
|
||||
distribution_settlements
|
||||
distribution_settlement_items
|
||||
```
|
||||
|
||||
结算批次保存周期、状态、审核人、付款时间和失败原因；明细保存每个站点、参与方、收入、成本、毛利、手续费、税费和钱包流水关联。
|
||||
|
||||
### 8.8 支付配置绑定
|
||||
|
||||
```text
|
||||
distribution_site_payment_configs
|
||||
```
|
||||
|
||||
一个分销网站可以绑定一个或多个现有 `payment_merchant_configs`。支付下单时保存 `site_id` 和 `payment_config_id` 快照，回调不重新依赖当前配置。
|
||||
|
||||
### 8.9 二维码和客服组
|
||||
|
||||
建议给二维码池或关联表增加：
|
||||
|
||||
```text
|
||||
distribution_site_id
|
||||
support_group_id
|
||||
```
|
||||
|
||||
取码优先匹配“分销网站 + 客服组”的专属二维码池。站点已配置专属池时，不回退到其他站点二维码。
|
||||
|
||||
## 9. API 规划
|
||||
|
||||
### 9.1 平台管理员
|
||||
|
||||
```text
|
||||
GET /api/admin/distribution/sites
|
||||
POST /api/admin/distribution/sites
|
||||
GET /api/admin/distribution/sites/:id
|
||||
PUT /api/admin/distribution/sites/:id
|
||||
POST /api/admin/distribution/sites/:id/enable
|
||||
POST /api/admin/distribution/sites/:id/disable
|
||||
|
||||
GET /api/admin/distribution/sold-orders
|
||||
GET /api/admin/distribution/sold-orders/:id
|
||||
GET /api/admin/distribution/receive-orders
|
||||
GET /api/admin/distribution/receive-orders/:id
|
||||
|
||||
GET /api/admin/distribution/rules
|
||||
POST /api/admin/distribution/rules
|
||||
PUT /api/admin/distribution/rules/:id
|
||||
|
||||
GET /api/admin/distribution/settlements
|
||||
GET /api/admin/distribution/settlements/:id
|
||||
POST /api/admin/distribution/settlements/:id/approve
|
||||
POST /api/admin/distribution/settlements/:id/reject
|
||||
|
||||
GET /api/admin/distribution/reports/summary
|
||||
GET /api/admin/distribution/reports/orders
|
||||
GET /api/admin/distribution/reports/finance
|
||||
```
|
||||
|
||||
### 9.2 分销网站成员
|
||||
|
||||
```text
|
||||
GET /api/admin/distribution/me
|
||||
GET /api/admin/distribution/orders
|
||||
GET /api/admin/distribution/orders/:id
|
||||
GET /api/admin/distribution/receive-orders
|
||||
GET /api/admin/distribution/chats
|
||||
GET /api/admin/distribution/chats/:id/messages
|
||||
POST /api/admin/distribution/chats/:id/messages
|
||||
```
|
||||
|
||||
同一套后端接口通过成员关系限制 `site_id`。平台管理员可以显式选择站点或查看全部；分销成员不能自行传入其他站点 ID。
|
||||
|
||||
## 10. 支付和域名上下文
|
||||
|
||||
生产环境建议通过请求 Host 解析分销网站：
|
||||
|
||||
```text
|
||||
请求域名 -> 服务端解析 site_id -> 校验站点状态 -> 选择绑定支付配置
|
||||
```
|
||||
|
||||
开发环境可以临时使用 `site_code`，但生产支付下单不能完全信任前端提交的站点参数。
|
||||
|
||||
支付配置选择规则：
|
||||
|
||||
1. 只读取当前站点启用的支付配置。
|
||||
2. 支持一个或多个配置，按优先级或健康状态选择。
|
||||
3. 支付单保存站点和支付配置快照。
|
||||
4. 回调、查询和退款使用支付单快照，不因后台配置变更而切换通道。
|
||||
|
||||
## 11. 独立前端工程
|
||||
|
||||
建议目录：
|
||||
|
||||
```text
|
||||
distribution-admin/
|
||||
├── package.json
|
||||
├── vite.config.ts
|
||||
├── tsconfig.json
|
||||
├── Dockerfile
|
||||
└── src/
|
||||
├── main.tsx
|
||||
├── router/
|
||||
├── layouts/
|
||||
├── stores/
|
||||
├── services/
|
||||
├── types/
|
||||
└── features/
|
||||
├── dashboard/
|
||||
├── sites/
|
||||
├── sold-orders/
|
||||
├── receive-orders/
|
||||
├── settlements/
|
||||
├── payment-configs/
|
||||
├── qrcodes/
|
||||
├── chats/
|
||||
└── reports/
|
||||
```
|
||||
|
||||
建议继续复用现有 API 响应格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "ok",
|
||||
"message": "ok",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
独立后台第一阶段可复用现有管理员登录接口和 HttpOnly Cookie，但不与现有前端共享 localStorage。是否建设分销员独立登录：待确认；如果分销员不是平台管理员，应新增独立主体和认证体系。
|
||||
|
||||
## 12. 部署方案
|
||||
|
||||
新增独立前端构建单元：
|
||||
|
||||
```text
|
||||
distribution-admin/Dockerfile
|
||||
```
|
||||
|
||||
Caddy 增加独立子域名站点。子域名名称暂定，最终以 DNS、证书和运营规划确认的名称为准：
|
||||
|
||||
```text
|
||||
distribution.hao858.com {
|
||||
handle /api/* {
|
||||
reverse_proxy backend:8080
|
||||
}
|
||||
|
||||
handle {
|
||||
root * /srv/distribution-admin
|
||||
try_files {path} /index.html
|
||||
file_server
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
主站、现有运营后台和分销后台分别构建、分别发布。数据库迁移仍由现有生产发布流程执行，后端和前端发布需要保持兼容窗口。
|
||||
|
||||
## 13. 实施阶段
|
||||
|
||||
### 阶段 0：确认业务口径
|
||||
|
||||
- 确认 3.5、4、2.5 的单位和方向。
|
||||
- 确认两方、三方参与方及亏损承担。
|
||||
- 确认加价是否计入服务费和税费。
|
||||
- 确认税费毛利计算口径。
|
||||
- 确认退款采用重算还是冲正。
|
||||
- 确认分销员和分销客服的身份模型。
|
||||
- 确认账号是否允许多站点展示。
|
||||
|
||||
### 阶段 1：数据库和计算引擎
|
||||
|
||||
新增 Goose 迁移，建议从 `000062_distribution_init.sql` 开始，包含站点、成员、展示关系、默认规则版本、订单参与方、财务快照、结算、支付绑定、二维码绑定和权限初始化。默认分账值先按第 7.1 节写入，后续通过后台规则页面调整。
|
||||
|
||||
先完成纯函数计算和单元测试，不接真实订单。
|
||||
|
||||
### 阶段 2：订单生命周期接入
|
||||
|
||||
接入：
|
||||
|
||||
```text
|
||||
支付成功
|
||||
退款成功
|
||||
订单完成
|
||||
订单仲裁
|
||||
订单取消
|
||||
```
|
||||
|
||||
要求支付回调、退款回调、订单完成和结算操作幂等；规则修改不影响已有订单；钱包流水和分销结算明细金额一致。
|
||||
|
||||
### 阶段 3：后台 API
|
||||
|
||||
完成站点、售出订单、正常订单收号记录、比例规则、结算、支付通道、二维码客服和账号展示接口，并补齐站点数据隔离测试。
|
||||
|
||||
### 阶段 4：Ant Design 前端
|
||||
|
||||
开发顺序：登录和权限、仪表盘、售出订单、正常订单收号记录、站点配置、规则、结算、支付、客服二维码、报表。
|
||||
|
||||
### 阶段 5：独立生产部署
|
||||
|
||||
接入独立子域名、DNS、Caddy 配置、前端镜像和发布脚本，完成健康检查、登录、订单查询、支付配置和客服消息冒烟测试。
|
||||
|
||||
## 14. 测试和验收标准
|
||||
|
||||
### 权限隔离
|
||||
|
||||
- 分销网站 A 不能查询分销网站 B。
|
||||
- 分销客服不能修改比例、支付配置、订单状态和结算。
|
||||
- 主站财务可查看全部站点资金数据。
|
||||
- 超级管理员可管理全部站点。
|
||||
|
||||
### 账务正确性
|
||||
|
||||
- 手续费按退款后的实际支付金额计算。
|
||||
- 手续费先扣除，再进行分成。
|
||||
- 0.5% 使用四舍五入并以分保存。
|
||||
- 销售加价归指定卖方。
|
||||
- 各主体独立计算税费。
|
||||
- 重复支付、退款和结算请求不会重复入账。
|
||||
- 分销结算明细与钱包流水一致。
|
||||
|
||||
### 业务正确性
|
||||
|
||||
- 售出订单和正常订单收号记录均可查询。
|
||||
- 线下提号、平台代管和撞车订单不会进入分销订单列表或分账。
|
||||
- 账号关闭展示后不影响历史订单。
|
||||
- 规则修改只影响新订单。
|
||||
- 支付只使用当前分销网站绑定的通道。
|
||||
- 分销网站使用指定客服组和二维码池。
|
||||
- 客服消息按站点隔离。
|
||||
|
||||
### 发布标准
|
||||
|
||||
- `./scripts/check.sh` 通过。
|
||||
- 新迁移具备 Up/Down 并通过 SQL 门禁。
|
||||
- 金额、退款、分账、税费和状态机变更包含回归测试。
|
||||
- 生产环境完成独立域名、后台登录、订单查询和支付配置冒烟验证。
|
||||
|
||||
## 15. 待确认清单
|
||||
|
||||
以下问题确认后，更新本文档版本并进入详细表结构和 API 契约设计：
|
||||
|
||||
1. 分销网站是平台合作方，还是普通用户下的分销身份？
|
||||
2. 分销客服是否使用现有 `admin_users`？
|
||||
3. 3.5、4、2.5 的确切单位和计算方向是什么？
|
||||
4. 服务费和支付手续费是否都按实际支付净额计算？
|
||||
5. 加价是否计入服务费、税费和退款基数？
|
||||
6. 税费是否只对正毛利计提？亏损是否结转？
|
||||
7. 退款后佣金是重算剩余金额，还是追加负向冲正？
|
||||
8. 一个账号能否同时展示在多个分销网站？
|
||||
9. 分销后台子域名最终使用哪个名称（当前暂定 `distribution.hao858.com`）？
|
||||
10. 分销网站是否需要独立登录入口和独立账号体系？
|
||||
11. 分销网站是否能查看完整账号登录资料？
|
||||
|
||||
---
|
||||
|
||||
后续每次确认业务规则后，优先更新第 7、15 节，再同步更新第 8、9、13、14 节，确保规则、数据、接口、实施和验收标准保持一致。
|
||||
|
||||
## 16. 当前实现基线（v0.3）
|
||||
|
||||
本分支已落地第一批可运行功能，主站域名为 `https://hao858.com/`，独立后台工程位于 `distribution-admin/`，子域名暂定 `https://distribution.hao858.com/`：
|
||||
|
||||
- Go 后端新增 `distribution_sites`、成员、账号展示、规则版本、订单财务快照、订单参与方、结算批次/明细、支付通道绑定表。
|
||||
- `rental_orders` 增加分销站点、模式和规则版本字段；只有正常租赁订单才允许写入这些字段。
|
||||
- 分账计算引擎已实现退款后净支付、0.5% 基点手续费先扣、服务费三种单位、加价单独展示、各参与方毛利税费和四舍五入。
|
||||
- 管理 API 已覆盖站点、规则、售出/收号订单查询、财务快照、账号展示开关、支付通道绑定和结算批次。
|
||||
- 后台权限使用 `distribution:*` 权限码；后续接入成员站点数据范围校验时，不能使用请求参数扩大范围。
|
||||
- `distribution-admin` 使用 React + TypeScript + Vite + Ant Design，已提供仪表盘、站点、售出订单、收号订单及结算/支付/账号/规则/客服入口和 Docker 镜像。
|
||||
|
||||
当前仍需在下一迭代接入真实支付回调、退款/订单完成结算、钱包流水、客服二维码池和成员级站点隔离；在这些链路接通前，财务快照接口只作为后台受控的幂等写入入口。
|
||||
Reference in New Issue
Block a user