# 房屋租赁 SaaS 平台 · 架构与数据库设计

> **多租户 SaaS** · **百万级房源** · **千万级租客**
> 生产部署：**阿里云分布式集群**，灰度升级，**上线后不停机维护**
> 覆盖：房源（含 AR 看房）、合同、收租、物业工单、数字家庭 IoT、Agent、
> 第三方支付/OTA/签章/AR 集成、C 端商城/直播/团购预留
> 技术栈：Java 21 + Spring Boot 3.x + PostgreSQL 17 + 阿里云

---

## ⚠️ 版本说明

**v2（当前）** 基于「阿里云分布式 + 永不停机」前提重做。
**v1** 基于本机单机验证，部分结论已被推翻。

| v1 结论 | v2 修正 |
| --- | --- |
| 单机 PostgreSQL 即可 | **阿里云 RDS 多可用区 + 只读副本**，分阶段分库 |
| PostGIS「待定」 | **必须装**（地图选房是硬需求） |
| 未考虑外部集成 | **新增完整分布式一致性设计**（支付/OTA/签章/AR） |
| 未考虑不停机 | **新增 Expanding/Contracting + 灰度 + 回滚方案** |
| 主键用 IDENTITY | ⚠️ 分库会冲突 → **新增号段模式**（已验证） |
| 未考虑 C 端 | **新增 C/B 端物理隔离设计** |

---

## 交付状态

| 项目 | 状态 |
| --- | --- |
| 基础数据梳理（9 大业务域） | ✅ |
| 多租户隔离（RLS） | ✅ **实测验证** |
| 数据库 DDL | ✅ **102 表 / 全部执行通过** |
| 业务数据验证 | ✅ **19 项通过** |
| 分布式一致性验证 | ✅ **13 项通过** |
| 单库容量实测 | ✅ **pgbench 实测完成** |
| 阿里云架构设计 | ✅ |
| 不停机升级方案 | ✅ |
| 分布式 ID（号段） | ✅ **并发验证无重叠** |
| **产品需求文档 PRD** | ✅ **43 条需求 / 97 条业务规则** |

---

## 文档导航

### 产品需求（给业务方/产品/测试）
| 文档 | 内容 |
| --- | --- |
| **[PRD/房屋租赁SaaS平台-PRD.md](PRD/房屋租赁SaaS平台-PRD.md)** | **全平台 PRD**：5 类角色权限矩阵、九大模块 43 条需求、97 条业务规则、V1/V2/V3 版本规划、验收标准、风险清单、需求追踪矩阵 |

### 架构设计（v2 重点）
| 文档 | 内容 |
| --- | --- |
| **[分布式架构/01-阿里云分布式架构.md](分布式架构/01-阿里云分布式架构.md)** | **先读这个**：单库上限实测、分阶段分库、阿里云选型、永不停机三支柱、外部集成设计、C 端隔离 |
| **[阿里云部署/01-部署与不停机升级.md](阿里云部署/01-部署与不停机升级.md)** | 部署拓扑、规格建议、灰度流程、DDL 红线清单、回滚预案、上线检查清单 |

### 基础设计（v1，仍然有效）
| 文档 | 内容 |
| --- | --- |
| [设计文档/01-基础数据梳理.md](设计文档/01-基础数据梳理.md) | 四层数据分层、九大业务域实体清单 |
| [设计文档/02-多租户与技术栈选型.md](设计文档/02-多租户与技术栈选型.md) | 隔离方案对比、RLS 实测、Java 技术栈 |
| [设计文档/03-数据库设计.md](设计文档/03-数据库设计.md) | 表清单详解、四道数据正确性防线 |

### DDL 与验证（全部本机实测通过）
| 文件 | 内容 |
| --- | --- |
| `DDL/00-一键复现.sh` | 从空库重建 + 验证 |
| `DDL/01~04` | 核心业务表（86 表） |
| `DDL/05` `DDL/10` | 业务验证 15 项 + 分布式验证 13 项 |
| `DDL/06` `DDL/07` | 并发防超卖压测 + 反向对照 |
| `DDL/08-多租户RLS落地.sql` | RLS 生成器（自动识别 72 表） |
| **`DDL/09-分布式一致性.sql`** | **Outbox / 入站回调 / 幂等 / 支付单 / 对账 / OTA 库存 / 签章 / 灰度开关** |
| **`DDL/11-分布式ID号段.sql`** | **分布式 ID（解决分库主键冲突）** |

### 压测（实测数据来源）
| 文件 | 内容 |
| --- | --- |
| `压测/01-造数据.sh` | 造 100 万房源 / 300 万租客 / 500 万账单 |
| `压测/02-查询性能.sh` | 各场景查询延迟与执行计划 |

---

## 核心实测数据（本机 PG 17.11，默认配置）

| 场景 | 延迟 | TPS |
| --- | --- | --- |
| 主键点查 | **0.076 ms** | 211,409 |
| 房源列表页 | **0.078 ms** | 203,941 |
| 逾期账单统计 | 1.4 ms | ~16,000 |
| 混合读写 9:1 | 0.667 ms | 23,882 |
| 出租率聚合看板 | **66 ms** ⚠️ | 241 |

**换算阿里云生产（shared_buffers 128MB→8GB）：预计 2~5 倍。**

---

## 最重要的三个实测教训

### 1. 索引列顺序决定生死（差距 1250 倍）

| 问题 | 修复前 | 修复后 |
| --- | --- | --- |
| 按房号查（缺 `tenant_id` 前导） | 72.8 ms | **0.042 ms**（1733×） |
| 房源列表页（部分索引用不上） | 43.7 ms | **0.035 ms**（1250×） |

**硬约束：RLS 架构下，所有高频查询必须有以 `tenant_id` 打头的索引。**

### 2. 统计信息滞后比索引更致命（差距 280 倍）
同一查询 `ANALYZE` 前 396ms，后 1.4ms。
**生产必须调优 autovacuum 并监控，CI 中禁止大事务。**

### 3. 大事务会拖死数据库
实测：单事务插入 500 万行 **12 分钟未完成**被中断。
**所有批量操作必须分批（5000~10000 行/批）。**

---

## 三个必须回答你的结论

### Q：能不能先不分库，后续再分？
**能，而且应该这样。**

分阶段方案：
| 阶段 | 房源量 | 架构 | 触发升级的条件 |
| --- | --- | --- | --- |
| 一期 | < 30 万 | 单主库 + 只读副本 + 分区 | 上线即用 |
| 二期 | 30~100 万 | 1 主 2 从 + 读写分离 | 主库 CPU > 50% |
| 三期 | > 100 万 | 按 `tenant_id` 分库 | 单库 > 2TB 或写 TPS > 5 万 |

**一期不分库的理由**：分库会失去跨库 JOIN 与事务，
账单核销这类强关联业务会直接崩坏。**没到瓶颈就分库是纯负债。**

**但一期必须做好 5 项准备**（否则后期分库要重构）：
① 所有表带 `tenant_id`（✅ 已满足）
② 所有查询带 `tenant_id`（✅ RLS 强制）
③ 避免跨租户 JOIN（✅ 已满足）
④ **分布式 ID（⚠️ 原设计缺失 → 已补号段方案并验证）**
⑤ 无跨库事务方案（建议 Saga/最终一致）

### Q：单库上限在哪里？
- **存储**：单实例 2~3 TB 舒适区（本机实测 500 万账单 = 3.5GB）
- **TPS**：本机 2.4 万混合读写，阿里云生产估算 **5~10 万**
- **真正的瓶颈不是 TPS**，而是：单机故障、DDL 锁表、备份窗口、跨可用区容灾
- **唯一必须出 PG 的场景**：出租率看板（实测 66ms 实时聚合不可接受）→ ClickHouse/物化视图

### Q：千万级租客、百万级房源要什么资源？
| 组件 | 一期规格 |
| --- | --- |
| RDS PostgreSQL | **16C64G**，ESSD PL1 1TB，多可用区 |
| RDS 只读实例 | 8C32G × 2 |
| Redis 集群版 | 8G × 3 分片，双副本 |
| ACK 节点 | 8C32G × 3，多可用区 |
| RocketMQ | 专业版 4C8G |

> **资源余量要留在数据库上**：数据库升级需要切换，
> 应用扩缩容是滚动无感的。

---

## 快速开始

```bash
cd DDL
./00-一键复现.sh rental_saas_dev
```

---

## 待确认

| # | 问题 | 建议 |
| --- | --- | --- |
| 1 | 首个上线租户规模？ | 决定一期 RDS 规格 |
| 2 | 是否已有阿里云账号与资源配额？ | 影响部署排期 |
| 3 | 支付渠道（支付宝/微信/银联）先接哪个？ | 建议先支付宝 H5 |
| 4 | OTA 先接哪家（携程/美团/飞猪）？ | 建议先携程，接口最规范 |
| 5 | 签章供应商选定？ | 建议法大大或 e签宝 |

---

## 落盘位置

`/Volumes/Extreme Pro/Workspace/rental-saas-20261018/`

*更新：2026-10-18（v2 · 阿里云分布式架构）*