docs/00-overview.md

docs/03-multi-tenancy.md

@@ -0,0 +1,54 @@
+# 03 SaaS 多租户
+
+## SaaS First
+
+系统必须从第一天支持多租户。
+
+- 采用：**单数据库 + tenant_code**
+- 第一阶段不采用：一个租户一个数据库
+
+## 需要租户隔离的表
+
+所有核心业务表原则上都需要 `tenant_code`，例如：
+
+- warehouse
+- warehouse_location
+- customer
+- product
+- sku
+- inventory
+- inbound
+- outbound
+- shipment
+- stock_log
+
+## tenant_code 是核心数据隔离维度
+
+不要依赖开发人员到处手工编写：
+
+```php
+Model::where('tenant_code', $tenantCode)
+```
+
+应建立统一的租户上下文 **TenantContext**（或类似机制）。
+
+目标：
+
+1. 当前登录用户确定当前 `tenant_code`。
+2. 业务 Service / Repository / Query 默认自动限制当前租户。
+3. 创建数据时自动写入当前 `tenant_code`。
+
+**严禁出现：租户 A 可以查询到租户 B 数据。**
+
+## 需要特别注意的场景
+
+TenantContext 不只存在于 HTTP 请求中，以下场景同样必须正确设置租户上下文：
+
+- Queue Job（在任务载荷中携带 `tenant_code`，执行时恢复上下文）
+- Scheduler / Console Command（按租户遍历执行）
+- 第三方 Webhook（根据店铺 / 应用凭证解析租户）
+- 缓存 Key、锁 Key（必须带 `tenant_code` 前缀）
+
+## 测试
+
+Tenant Isolation 是核心测试项之一，见 [14-testing.md](./14-testing.md)。