feat(tenant): 增加租户基础与域名解析

This commit is contained in:
yml
2026-11-15 15:37:23 +08:00
parent 79b8bc3ac1
commit ca57f604bf
24 changed files with 1329 additions and 1931 deletions
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,369 @@
# 解忧商行双站点改造方案
> 状态:MVP 基调稿 v2.0
> 更新时间:2026-11-15
> 目标:用一套后端、一套数据库和一套前端,上线大锤商行、解忧商行两个经营站点
## 1. 基调
首期只解决以下问题:
- 两个站点共享同一号库和租赁库存。
- 两个站点都有独立用户、登录、支付、钱包、后台权限和统计。
- 两个站点都能发布商品,也都能购买对方货架上的商品。
- 同一商品只能被一个租户成功锁定和出租。
- 现有分销系统继续按旧逻辑运行,不升级成经营租户。
首期不建设完整公司会计系统,不做自动公司间结算、自动打款、复杂对账、双履约状态机或跨站内部案件。公司间货款先按订单报表线下确认和结算。
## 2. 不可混淆的概念
| 概念 | 定义 |
|---|---|
| 经营租户 | 大锤商行或解忧商行,存储于 `tenants` |
| 买方租户 | 用户实际下单、支付和接受对客服务的站点 |
| 货源租户 | 商品和号主所属的站点 |
| 支付租户 | 实际收取款项的站点,首期等于买方租户 |
| 租户货架 | `tenant_listing_offers`,表示共享商品在某个站点的展示和售价 |
| 历史分销站 | 现有 `distribution_sites`,仅保留旧分销渠道语义 |
解忧不是分销站。不得把解忧写入 `distribution_sites`,不得用 `distribution_mode`、分销规则或分销结算表达经营租户。
买卖方向不固定:
- 大锤用户可以购买解忧商品。
- 解忧用户可以购买大锤商品。
- 哪个站点发布商品,哪个站点就是货源租户。
- 哪个站点的用户下单和付款,哪个站点就是买方租户和支付租户。
## 3. 首期范围
### 3.1 必须完成
- 域名到经营租户的服务端解析。
- 两个站点独立注册、登录、JWT、短信和实名。
- 共享商品、号主来源租户和双站货架。
- 双站商品列表、详情、图片、搜索、货架价格和下单校验。
- 订单记录买方租户、货源租户和支付租户。
- 两个站点互相购买。
- 支付商户、支付单和退款按租户隔离。
- 用户钱包、提现、通知和后台数据按租户隔离。
- 站点用户数、成交额、支付、退款、货源出货和号主结算统计。
- 订单、会话、缓存、文件和定时任务带租户上下文。
- 现有分销链路回归测试保持通过。
### 3.2 首期不做
- 公司间自动应收应付、总账、冲销和对账系统。
- 自动银行清算、分账和公司间打款。
- 独立的客户订单状态和货源供货状态机。
- `fulfillment_tasks`、`order_tenant_roles` 等额外订单体系。
- 客户会话、号主会话和平台内部案件三套聊天体系。
- 独立租户二维码表。
- 独立平台后台域名和租户后台域名。
- 统一跨站客服工作台。
- 双向自动铺货规则、复杂供货合同和自动追偿。
- 与首期无关的撞车、积分、邀请、成长、优质号主、线下提号和广告归因改造。
## 4. 目标架构
```text
大锤域名 / 解忧域名
|
Caddy / HTTPS
|
同一套 Go 后端
|
同一个 MySQL
|
共享号库和租赁库存
```
保持一套后端、一套数据库和一套前端代码。两个站点通过 Host 解析租户,不复制服务,不建立租户独立数据库。
生产环境只信任服务端解析的 Host。未知域名失败关闭,不使用 query、`sessionStorage` 或 `X-Distribution-Site-Code` 切换经营租户。开发环境可以使用显式租户标识模拟站点。
## 5. 最小数据模型
### 5.1 新增核心表
| 表 | 作用 |
|---|---|
| `tenants` | 租户编码、名称、状态、品牌配置和功能配置 |
| `tenant_domains` | 租户域名、域名类型和启用状态 |
| `tenant_listing_offers` | 商品在某个租户货架的展示状态和销售价格 |
首期不新增 `tenant_profiles`、`tenant_configs`、`tenant_feature_flags`、`tenant_memberships` 等重复抽象:
- 品牌和功能配置放 `tenants.profile_json`、`tenants.features_json`。
- 配置覆盖使用现有 `system_configs` 增加 `tenant_id`。
- 后台人员租户范围通过现有 `admin_user_roles` 增加 `tenant_id`。
### 5.2 现有表增加租户字段
| 表 | 字段 |
|---|---|
| `users` | `tenant_id`,手机号唯一键改为 `(tenant_id, phone)` |
| `user_realname` | `tenant_id`,身份证唯一键改为 `(tenant_id, id_no_hash)` |
| `user_payment_accounts` | `tenant_id` |
| `wallet_accounts`、`wallet_ledger` | `tenant_id` |
| `withdrawal_requests` | `tenant_id` |
| `game_accounts` | `source_tenant_id` |
| `rental_listings` | `source_tenant_id`、`owner_tenant_id` |
| `rental_orders` | `buyer_tenant_id`、`source_tenant_id`、`payment_tenant_id`、`source_amount_cent` |
| `payment_merchant_configs` | `owner_tenant_id` |
| `payment_orders` | `tenant_id` |
| `notifications`、`sms_messages` | `tenant_id`、`source_tenant_id` |
| `chat_conversations`、`chat_support_groups`、`chat_quick_replies` | `tenant_id` |
| `chat_qrcode_pool`、`chat_qrcode_delivery_tasks` | `tenant_id` |
| `announcements` | `tenant_id` |
| `file_upload_owners` | `tenant_id` |
| `system_configs` | `tenant_id`,租户唯一键为 `(tenant_id, key)` |
| `admin_user_roles` | `tenant_id`,平台角色使用 `0` |
现有 `distribution_*` 表不增加经营租户语义,继续服务历史分销。
### 5.3 订单必须保存的最小角色快照
```text
buyer_tenant_id
source_tenant_id
payment_tenant_id
source_amount_cent
```
约束:
- 首期 `payment_tenant_id = buyer_tenant_id`。
- 买方用户所属租户必须等于买方租户。
- 号主用户所属租户必须等于货源租户。
- 买方商品价格取租户货架价格。
- 货源金额取商品基础价或双方确认的供货价,并在下单时固化。
不再增加合同卖方、履约方、争议方等可由上述字段推导的角色字段。
## 6. 用户、后台和权限
- 同一手机号可以在两个租户分别注册。
- JWT 必须包含 `tenant_id` 和 `scope`。
- 用户令牌只能访问令牌所属经营租户。
- 短信验证码、登录失败、限流、实名和钱包 Key 都带租户。
- 管理员仍是全局身份,通过 `admin_user_roles.tenant_id` 获得一个或多个租户角色。
- 共享客服可以同时拥有两个租户的客服角色。
- `super_admin` 使用 `tenant_id=0` 的平台角色,可以查看全部租户。
- 首期复用同一套后台页面,通过当前 Host 确定租户;不拆独立后台域名。
- 权限缓存 Key 至少包含管理员 ID 和租户 ID。
## 7. 共享号库和双站货架
### 7.1 商品来源
- 商品和游戏账号只有一份。
- 商品发布人所属租户即为货源租户。
- 货源租户负责商品、号主、交接和号主结算。
- 买方租户不能修改货源租户的商品和号主信息。
### 7.2 货架
商品审核通过后,为大锤和解忧各创建一条 `tenant_listing_offers`:
- 两个站点默认都可见。
- 每个站点可以单独关闭展示。
- 每个站点可以设置自己的销售价格。
- 站点未启用的商品不得通过列表、详情、图片、搜索、分享链接或下单访问。
商品详情和图片必须根据当前租户货架校验,不能只依赖列表过滤。
### 7.3 库存
库存锁定继续使用 `rental_listings` 和共享账号行锁。两个租户同时下单时,只允许一笔订单成功占用商品。
## 8. 订单和双向购买
### 8.1 下单
同一数据库事务内完成:
1. 校验买方用户属于当前租户。
2. 校验租户货架已启用。
3. 锁定商品和账号。
4. 读取买方货架售价和货源金额。
5. 创建一笔 `rental_orders`。
6. 保存买方、货源、支付租户和价格快照。
7. 锁定商品并写入买方订单通知。
### 8.2 订单展示
只保留一份订单和一套现有租赁状态机,按访问者角色过滤字段和操作:
- 买方用户看到支付、客户资料、交付、归还、结账和退款操作。
- 号主看到商品、交接、归还确认和结算信息。
- 买方租户后台负责对客订单和退款。
- 货源租户后台负责号主交接和货源出货。
- 平台超级管理员可以查看完整订单。
同一订单可以在两个站点出现,但必须明确显示“本站买入”或“本站出货”,不能都叫“本站成交”。
### 8.3 跨租户流程
```text
A 站商品进入 B 站货架
-> B 站用户下单并支付到 B 站商户
-> A 站号主在 A 站处理交接
-> B 站买方在 B 站确认收号和归还
-> B 站记录客户成交和退款
-> A 站记录货源出货和号主收入
-> 两站货款线下结算
```
大锤买解忧和 解忧买大锤使用同一逻辑,不写两套代码。
## 9. 支付、退款和钱包
- 买方订单只使用买方租户的支付商户。
- 找不到本租户商户时支付失败,不回退其他租户。
- 支付回调通过支付单定位租户,不依赖回调 Host。
- 退款固定使用原支付单和原商户。
- 原商户不可用时停止自动退款并告警。
- 买方用户钱包、提现按买方租户隔离。
- 号主收入进入货源租户用户钱包。
- 支付成功不等于号主收入到账,号主结算仍由订单完成流程触发。
- 首期不生成公司间总账。跨公司应结算金额通过订单快照和报表输出。
## 10. 独立统计
每个租户至少提供以下两组口径:
| 口径 | 统计来源 |
|---|---|
| 本站用户 | `users.tenant_id` |
| 本站买入订单和客户 GMV | `rental_orders.buyer_tenant_id` |
| 本站支付和退款 | `payment_orders.tenant_id` |
| 本站卖出商品 | `rental_listings.source_tenant_id` |
| 本站出货订单 | `rental_orders.source_tenant_id` |
| 号主应结算 | 订单货源金额和号主结算金额 |
平台统计按租户分组展示,不把两个租户的内部交易重复相加为公司 GMV。
## 11. 客服、通知、文件和任务
首期使用最小隔离:
- 一笔订单创建一个订单会话,会话归属买方租户。
- 买方和货源号主按订单角色参与该会话。
- 共享客服必须拥有当前租户的客服角色才能查看和回复。
- SSE 事件带 `tenant_id`,无权限管理员不能收到会话内容。
- 二维码池增加 `tenant_id`,订单会话使用买方租户二维码。
- 通知、短信、未读统计和消息缓存按租户隔离。
- 私有文件上传和读取校验租户及业务角色。
- 定时任务从订单、支付、会话等业务记录恢复租户,无法解析时暂停并告警。
首期不做客户会话、货源会话、内部案件的复杂拆分。
## 12. 历史分销兼容
- `distribution_sites`、分销后台、分销订单和分销结算保持现有逻辑。
- 分销用户继续按 `distribution_site_id` 保持渠道归属。
- 历史分销域名继续由现有分销解析逻辑处理。
- 新经营租户订单不写分销财务快照。
- 历史分销订单不根据 `distribution_site_id` 猜测经营租户。
- 现有分销 E2E 测试必须全部保持通过。
## 13. 实施阶段
### 阶段 0:确认基调,1~2 天
- 确认两个站点都允许发布和购买。
- 确认买方租户负责收款和退款。
- 确认站间货款线下结算。
- 确认首期不建设公司总账和双状态机。
### 阶段 1:租户和域名,3~5 天
- 新增 3 张核心表。
- 实现 Host 解析和前端租户配置。
- 完成 Caddy 域名校验和未知域名失败关闭。
### 阶段 2:用户、认证和后台权限,5~7 天
- 用户、实名、收款账户、钱包和提现增加租户。
- JWT、短信和登录限流增加租户。
- 后台角色和权限增加租户范围。
- 完成同手机号双租户注册和越权测试。
### 阶段 3:共享商品和双站货架,4~6 天
- 商品增加来源租户。
- 审核通过后生成两个站点的货架。
- 列表、详情、图片、搜索和下单统一校验货架。
- 完成双站并发抢号测试。
### 阶段 4:订单和统计,6~8 天
- 订单增加买方、货源、支付租户及货源金额快照。
- 两个站点支持互相下单和角色化订单展示。
- 完成买方统计、货源统计和平台统计。
### 阶段 5:支付、退款和钱包,4~6 天
- 支付配置和支付单增加租户。
- 禁止跨租户商户回退。
- 退款固定原商户。
- 号主收入进入货源租户钱包。
### 阶段 6:客服、通知、文件和任务,4~6 天
- 会话、二维码、通知、短信和未读统计增加租户。
- 文件访问增加租户和角色校验。
- 定时任务按记录租户处理。
### 阶段 7:迁移、灰度上线,5~7 天
- 创建大锤和解忧租户。
- 回填历史大锤用户和业务数据。
- 生产库副本执行迁移和并发、支付、退款、越权测试。
- 解忧先内部访问,再灰度开放。
预计 30~40 人日。两个后端、一个前端和测试并行时,约 4~6 周进入灰度。
## 14. 迁移和回滚
迁移顺序:
1. 创建租户、域名和货架表。
2. 创建大锤、解忧两个固定租户。
3. 增加可空租户字段并回填历史大锤数据。
4. 创建货架关系和复合索引。
5. 切换新租户读写路径。
6. 验证后给关键字段增加非空约束。
现有分销表不迁移为经营租户。
启用解忧前必须保留大锤完整回归数据。启用同手机号双租户后,应用回滚不能再退回旧全局手机号版本;故障回滚通过关闭解忧域名和功能开关、保留兼容代码完成。
## 15. 上线验收
- 未知域名不会落到大锤。
- 同一手机号可以在两个租户注册。
- 大锤 JWT 不能访问解忧数据,反向同样拒绝。
- 两个站点都能看到双方开放的商品。
- 未开放商品无法通过详情、图片、搜索或分享链接访问。
- 两个租户并发购买同一账号只能成功一单。
- 大锤用户能买解忧商品。
- 解忧用户能买大锤商品。
- 支付只进入买方租户商户,缺失时失败关闭。
- 退款只使用原支付租户和原商户。
- 两个站点的用户、订单、支付、钱包和统计互不串数据。
- 无租户上下文的任务暂停并告警。
- 现有分销 E2E 全部通过。
## 16. 后续增强
以下能力单独设计,不进入本次上线:
- 公司间自动总账、对账和打款。
- 自动供货合同和追偿。
- 客户会话、货源会话、平台内部案件拆分。
- 统一跨站客服工作台。
- 独立平台后台域名和租户后台域名。
- 自动双向铺货策略和复杂定价规则。