# 跨境电商SaaS系统·最终完整架构总文档（本次会话100%全量复盘无删减）

# 跨境电商 SaaS 系统・最终完整架构总文档

## （本次会话全部讨论内容 100% 无删减、无遗漏、完整复盘终版）

> 本文档汇总本次全部沟通：需求、痛点、架构设计、隔离体系、级联机制、平台扩展机制、审计体系、工程规范、禁忌红线、落地标准。
> 所有内容为**最终定稿架构标准**，后续开发严格以此文档为准。
> 
> 

# 一、系统整体定位与核心需求（本次全部原始需求汇总）

## 1\.1 系统定位

面向多跨境电商平台的 **通用型 SaaS 数据分析 \& 财务核算系统**

- 多租户商业化 SaaS 模式

- 支持无限新增电商平台（亚马逊、Noon、Shopee、速卖通、美客多、eMag…）

- 全自动化数据同步、清洗、核算、报表、审计

- 全链路数据联动级联更新

- 多国家、多币种全自动智能换算

## 1\.2 本次明确的全部硬性核心需求

1. **严格 SaaS 多租户隔离**：租户之间数据彻底隔离，零泄露风险

2. **三层维度完整隔离**：租户隔离（安全）、平台隔离（业务）、国家隔离（币种 / 规则）

3. **全数据级联联动**：修改任意配置 / 数据，系统**全链路自动级联更新**，局部改动全局联动

4. **平台插件化扩展**：新增任意电商平台 **无需改动核心业务代码、无需新建模块、无需改表结构**

5. **全链路 SaaS 自动化**：所有任务、数据、调度、规则 **完全基于租户维度自动生成**，无全局任务、无全局数据

6. **双数据基线审计体系**：Raw 原始数据 \+ Clean 标准化数据，支持 Agent 全量数据审计比对

7. **业务域彻底解耦**：订单 / 广告 / 财务 / 店铺配置完全分域，跨域只能内部契约 API 调用

8. **多币种全自动核算体系**：本土货币展示、多国自动汇总美元、禁止错算混算

9. **禁止数据库物理级联**：全部采用业务事件驱动级联

10. **所有架构支持长期横向扩展**：平台无限加、租户无限加、国家无限加

---

# 二、系统整体架构分层（最终定稿）

## 2\.1 四层标准数据流（永久不变）

**Raw 原始数据层 → Clean 标准化基线层 → API 契约服务层 → Web 展示层**

1. **Raw 层**：第三方平台原始落库，**永久不修改历史数据，只新增 / 版本迭代**（审计原始基线）

2. **Clean 层**：系统标准化清洗后业务基线，**版本化管理，历史基线不可覆盖**

3. **API 层**：对外开放 API \+ 跨域 /internal 内部契约 API

4. **Web 层**：纯展示，**无任何计算逻辑、无币种换算、无求和**

## 2\.2 系统架构双层核心（内核永久不动 \+ 插件无限扩展）

### 上层：平台无关内核（永久零修改）

- 多租户隔离机制

- 事件总线 \& 级联机制

- 调度引擎

- 多币种核算内核

- 审计 Agent 内核规则

- 全部通用数据表结构

- 全部 DTO 契约

- 全部业务域核心逻辑

### 下层：平台插件适配器（唯一可扩展层）

所有平台差异 **100% 收敛到适配器**
新增平台只写适配器，**核心业务零改动**

---

# 三、SaaS 三层隔离体系（最终强制标准）

## 3\.1 隔离优先级（固定层级，不可颠倒）

**租户 ID（安全最高隔离） \> 店铺 ID \> 平台编码 \> 国家编码**

## 3\.2 第一层：租户隔离（安全级・强强制隔离）

### 核心定义

租户 = 商家商户主体
**租户 A 绝对无法看到、修改、触碰租户 B 任何数据**，属于系统**最高安全红线**

### 全套落地机制（完整闭环，多层兜底）

1. **ALS 异步上下文存储**
所有 HTTP 请求、队列任务、定时任务，租户 ID 唯一存储在上下文

2. **ORM 全局自动拦截**
所有 SELECT / UPDATE / DELETE **自动追加 tenant\_id 条件**
业务代码 **禁止手写 tenant\_id 条件**

3. **JWT 唯一身份来源**
租户 ID **禁止前端传参、禁止 URL 传参、禁止 Body 传参**
仅从 Token 解析

4. **内部 API 租户传递规范**
跨域 /internal 接口统一通过内网头 `X-Tenant-Id` 传递
公网网关直接拦截丢弃该头，杜绝伪造

5. **队列 Job 强制校验**
所有 Job Payload **必须携带 tenantId**，无租户直接拒绝执行

6. **超级管理员白名单机制**
`@TenantBypass()` 装饰器全局严控，数量受限、日志全记录、需人工评审

7. **SQL 审计兜底防护**
所有业务表 SQL 若无租户条件，直接拦截报错

### 最终效果

**无论代码 BUG、逻辑错误、人为失误，绝对无法跨租户泄露数据**

## 3\.3 第二层：平台隔离（业务级隔离）

### 核心定义

同一租户下，多平台数据**业务彻底隔离、不可混算、不可错乱**

- 亚马逊 / Noon / 速卖通 / 美客多 /eMag 互不干扰

- 可自主多平台汇总，但**必须通过内核统一聚合逻辑**

### 落地规则

1. 各平台独立同步 Job、独立适配器、独立数据源

2. 数据落库强制携带 `platform_code`

3. 清洗逻辑 **平台差异化收敛到适配器钩子**

4. 业务查询、报表、统计必须携带平台筛选参数

5. 不同平台原始货币 **禁止直接相加**

## 3\.4 第三层：国家 \& 币种隔离（财务核算核心隔离）

### 核心定义

同一租户、同一平台下，**按国家站点隔离税率、币种、核算规则**

### 强制业务规则

1. 原始数据永久存储 **本土原始货币金额**，绝不篡改、绝不预换算

2. **单国家展示：本土货币**

3. **多国家汇总：明细保留本土货币，合计统一换算 USD 美元**

4. 禁止不同国家本土货币直接相加（最高级业务错误）

5. 国家 \- 币种映射源头：适配器 `resolveCountryCurrency`

---

# 四、全系统级联联动架构（最终方案：弃用数据库级联，采用事件业务级联）

## 4\.1 架构重大决策（本次确定核心基调）

### 永久禁止：数据库外键 CASCADE 级联

**完全禁用、永久禁用**
原因：

1. 会篡改审计基线历史数据，导致审计彻底失效

2. 无法支持多租户隔离，存在跨租户数据风险

3. 跨业务域无法生效

4. 大批量更新锁表、雪崩风险高

## 4\.2 最终方案：**事件驱动・全系统业务级联**

### 核心能力

修改任意一处配置 / 数据 → **全系统所有关联统计表、报表、财务数据自动级联重算更新**
用户体验 = 全表联动
底层架构 = 原始数据不动、聚合数据重算（保证审计安全）

## 4\.3 可级联 \& 不可级联数据铁律

### ✅ 允许级联重算（聚合衍生数据）

- SKU 聚合统计

- 利润报表

- 广告指标汇总

- 全部图表、合计、统计数据

### ❌ 禁止任何修改（审计基线原始数据）

- Raw 全量表

- Clean 明细基线表

> 数据变更仅新增版本、保留历史，**永不原地 UPDATE 覆盖**
> 
> 

## 4\.4 系统标准事件结构（全局统一）

所有事件必带完整 SaaS 四维：
`tenantId / shopId / platformCode / countryCode`
事件全局幂等（eventId），杜绝重复级联错乱

### 核心事件

1. RawDataChanged（原始数据新增）

2. CleanDataRefreshed（清洗完成）

3. ShopConfigUpdated（店铺配置变更）

4. ExchangeRateUpdated（汇率变更）

## 4\.5 级联完整链路

配置 / 数据变更 → 发布标准事件 → 各业务域订阅 → 压入异步 Job → 租户隔离环境重算聚合数据 → 全系统报表自动刷新

---

# 五、插件化平台扩展架构（核心能力：无限新增平台零改核心）

## 5\.1 架构终极能力（你本次重点要求）

\*\*新增电商平台：美客多、eMag、速卖通等
不需要改业务代码
不需要改表结构
不需要改清洗逻辑
不需要改报表
不需要改财务
不需要改前端页面
不需要改审计规则\*\*

只需要：**新建一个平台适配器插件 \+ 一行配置注册**

## 5\.2 双层解耦架构

### 1）内核层（平台完全无关）

- 表结构通用

- 租户隔离通用

- 事件总线通用

- 级联机制通用

- 币种换算通用

- 审计规则通用

- 契约 API 通用

### 2）适配器插件层（唯一扩展点）

所有平台差异收敛到适配器：

- API 对接

- 原始数据归一化

- 国家币种映射

- 状态映射钩子

- 店铺授权表单 Schema

- 平台专属审计规则

## 5\.3 统一适配器抽象基类

所有平台强制继承统一基类，接口标准化，系统自动识别、自动调度、自动适配

## 5\.4 新增平台完整零侵入效果

1. 自动生成该租户该平台的同步调度任务

2. 自动落库通用 Raw/Clean 表

3. 自动触发标准清洗流水线

4. 自动触发全系统级联重算

5. 自动适配多币种规则

6. 自动适配前端下拉、动态表单

7. 自动适配 Agent 审计

---

# 六、SaaS 全自动化机制（全部数据基于租户自动生成）

## 6\.1 无全局任务、无全局数据、无全局事件

系统**不存在任何脱离租户的全局操作**

## 6\.2 租户维度全自动能力

租户开通店铺后，系统**全自动生成**：

1. 该租户专属数据同步定时 Job

2. 该租户专属清洗 Job

3. 该租户专属级联重算链路

4. 该租户专属事件流

5. 该租户专属审计任务隔离域

## 6\.3 调度机制核心

- 不写死 Cron 全局遍历

- 每店铺独立 Job 定义

- 停用店铺自动暂停任务

- 删除租户自动销毁任务

---

# 七、业务域解耦 \& 数据库隔离规范

## 7\.1 业务域完全拆分

- domain\-shop 店铺 \& 配置 \& 汇率

- domain\-order 订单数据

- domain\-advertisement 广告数据

- domain\-finance 利润核算

- domain\-audit Agent 审计任务

## 7\.2 数据库账号硬隔离

每个业务域独立数据库账号
**只能访问自己的表**
彻底杜绝跨域直连数据库漏洞

## 7\.3 跨域唯一通信方式

仅允许：`/internal` 内部契约 API
禁止跨域 import、禁止跨域 Repo、禁止跨域 DB 访问

---

# 八、数据表统一标准结构（全平台通用永久结构）

所有 Raw、Clean、聚合表强制固定前置字段：

```Plain Text
tenant_id
shop_id
platform_code
country_code
currency_code
version
extension(jsonb)
```

### 强制规范

1. 索引最左前置四维字段

2. 业务 ID 全部 String（防止溢出）

3. 所有计算字段顶层定义

4. 平台独有非计算字段放入 extension

5. 严禁业务字段存入 JSON

---

# 九、多币种完整最终业务规则

1. 原始数据**永久原始币种存储**

2. 不预换算、不篡改原始金额

3. 单国家页面 = 本土货币

4. 多国混合明细 = 各本土货币

5. 多国合计汇总 = 统一 USD 换算

6. 汇率修改触发全局级联财务重算

---

# 十、Agent 审计完整体系（全平台通用）

## 10\.1 审计基线

Raw（外部原始）\+ Clean（系统标准）双基线比对

## 10\.2 通用审计规则（所有平台自动生效）

- 租户隔离校验

- 字段完整性校验

- 0 值 / 空值 / 空白图表异常校验

- 币种国家匹配校验

- 禁止跨币种混算校验

- Raw\-Clean 基线一致性校验

## 10\.3 平台扩展审计

适配器可选追加平台专属审计规则，**不改动主审计逻辑**

---

# 十一、全系统禁忌红线（绝对禁止开发行为）

1. ❌ 禁止数据库外键级联

2. ❌ 禁止业务代码手写 tenant\_id 条件

3. ❌ 禁止前端传递租户 ID

4. ❌ 禁止全局无租户任务

5. ❌ 禁止修改历史 Raw/Clean 基线数据

6. ❌ 禁止不同本土货币直接相加

7. ❌ 禁止平台差异化代码写在内核、shared、业务域

8. ❌ 禁止把统计字段存入 JSON 扩展字段

9. ❌ 禁止跨业务域直连数据库

10. ❌ 禁止新增平台修改内核代码

---

# 十二、新增平台完整落地 CheckList（终版）

## 适配器开发

- 实现完整基类接口

- 完成 API 对接

- 完成数据归一化

- 完成国家币种映射

- 可选：表单 Schema、状态钩子、审计规则

## 系统配置

- 平台注册表一行配置注册

## 自动生效能力（零代码）

- 自动调度任务

- 自动数据落库

- 自动清洗

- 自动级联更新

- 自动报表展示

- 自动前端渲染

- 自动审计覆盖

---

# 十三、本次全部需求最终达成总结

## 你全部需求 100% 实现

1. ✅ SaaS 多租户彻底隔离

2. ✅ 租户 / 平台 / 国家三层完整隔离

3. ✅ 全系统数据级联联动（改一处、全局联动）

4. ✅ 新增平台零侵入、零改核心代码

5. ✅ 所有数据、任务、事件、调度完全基于租户自动生成

6. ✅ 双基线数据审计体系完整闭环

7. ✅ 多币种全自动智能核算

8. ✅ 业务域彻底解耦、安全闭环

9. ✅ 支持未来无限平台扩展

10. ✅ 支持未来无限租户、无限国家扩展

## 架构最终特质

**高安全、强隔离、可无限扩展、全自动化、全联动、可审计、零重构、长期稳定**

> （注：部分内容可能由 AI 生成）
