# SaaS跨境电商系统架构规范（定稿）

架构模式：Raw‑to‑Clean单次标准化 + 领域私有存储 + 契约接口通信
核心目标：消除连锁数据故障；统一业务规则；适配多币种；支持旁路MCP‑Agent审计
架构分层：纵向四层：RawData → CleanData → API → Web
横向：按业务域划分独立模块；平台、店铺、国家、币种为行级数据标签，不独立成模块

---

## 1 整体架构总览

```
RawData（只读原始数据源）
      ↓（每个业务域专属清洗Job，【标准化只运行一次】）
CleanData（每个业务域私有数据表；域之间数据完全隔离）
      ↓（唯一对外出口：契约API，分为前端API、后端/internal内部API）
API‑Layer（契约、DTO、版本管理，所有跨域数据交换全部发生在此层）
      ↓
Web前端页面、图表、表格
```

核心公理：

1. Raw → Clean 的实体标准化、状态判定、字段规整，每个业务域只执行一次。上层业务绝不重复再做一遍实体解析。
2. Clean数据表是业务模块私有存储。其他模块禁止直接SQL访问。跨域拿数据只能调用对方发布的契约接口。
3. 数据主流向自上而下；业务流程禁止逆向回写。Clean不能修改Raw；API不能改写Clean基线；Web不能直连数据库。
4. 审计Agent属于旁路系统，不介入业务数据流，只做三方比对校验，只做告警，不能修改任何业务数据。

## 2 纵向四层详细规范

### 2.1 RawData 层

1. 来源：各平台API原始返回数据：亚马逊SP‑API、Ads‑API、Noon、Shopee等。
2. 权限：全库只读。所有业务模块只能SELECT。任何业务逻辑不允许执行 UPDATE / DELETE / INSERT。
3. 存储内容：平台返回原始字段，不做业务转换，原样落地；保留原始返回json、原始金额、原始货币代码、原始时间字符串。
4. 分表规范：按业务类型+平台拆分，示例： raw_order_amazon、raw_ad_noon。
5. 用途：系统唯一真相源；用于故障回溯；Agent审计比对基线A。

### 2.2 CleanData 层（核心设计）

1. 组织形式：按业务域拆分私有数据表。数据表归属权唯一，一张表只属于一个业务模块。
   - clean_order → 订单模块独有读写
   - clean_ad → 广告模块独有读写
   - clean_inventory → 库存模块独有读写
   - clean_finance_profit → 财务模块独有读写
2. 重要：没有全局统一的大Clean库。业务域之间数据库层面完全隔离。
3. 存储内容：经过标准化后的业务实体。存业务发生的原始币种的原始金额。
   ❗不在Clean层做货币转换、美元汇总。币种换算属于上层业务计算。
4. 通用标签字段（每一张clean业务表必须携带）
   - shop_id：店铺唯一ID
   - platform_code：平台编码(amazon / noon / shopee …)
   - country_code：国家二位代码 US / AE / SE / CA …
   - currency_code：该条记录发生时原始货币代码
5. Clean是本业务域的官方审计基线；Agent审计比对基线B。
6. 清洗Job调度：每个业务域独立调度；可以并行运行；Job只能读写自己归属的clean数据表。

### 2.3 API层：契约接口体系

接口分为两类，都强制使用DTO做入参、出参的完整定义。所有契约接口必须管理版本。

1. 面向前端的接口： /api/v1/xxx
   - 供页面、表格、图表调用；入参携带 shop_id、platform_code、country_code，模块内部基于该参数完成行级过滤。
2. 后端跨域内部接口： /internal/api/v1/xxx
   这就是业务模块之间交换数据的唯一通道。不对外开放公网，仅内网可访问。
   - 规则：内部接口，只允许做本域内数据查询与聚合；不允许写数据。
   - 禁止：内部接口返回完整全量明细数据集。业务聚合、分组、统计计算必须在本模块内部完成，向外输出聚合后的指标。

版本变更铁律：
如果业务改动会改变字段名称、字段类型、单位、业务语义，禁止直接修改v1接口。必须新建 /internal/api/v2/xxx。旧版本v1保持原有契约，供下游模块平稳迁移。
简单bug修复、修复计算逻辑，只要出参DTO定义、字段业务含义、单位不变，可以在原有版本迭代。

### 2.4 Web前端层

1. 每一个页面、业务组件，归属一个业务域；优先调用归属业务域对外API。
2. 国家、平台、店铺选择器为全局参数，随每一次接口请求传入后端；由后端在模块内部完成行级数据过滤。
3. 前端不做任何业务计算，币种换算、求和、业务过滤全部交给后端API完成。前端只负责渲染表格与图表。
4. 前端不能直接访问数据库，不能绕过API调用数据库。

## 3 完整业务领域模块清单

每一个业务模块都是完整闭环，四层链路自成一套；模块之间没有数据库层面的耦合。

### 业务域模块（对等闭环）

1. 店铺对接模块：平台授权Token管理，平台API任务调度，原始数据拉取，落地写入RawData。
2. 订单域模块：主订单、子订单、退货、取消、换货、履约单。负责raw_order → clean_order清洗与标准化。
3. 商品SKU域模块：SKU档案、Listing基础信息，多平台‑多国家SKU映射关系。
4. 广告域模块：SP/SB/SD广告、关键词、广告活动组、曝光、点击、花费、ACOS相关实体；raw_ad → clean_ad。
5. 库存域模块：FBA库存、海外仓、国内仓、在途、预留、可售、调拨。
6. 物流履约域模块：头程、尾程，物流渠道，物流跟踪，运费成本、发货履约状态。
7. 采购供应链域模块：供应商、采购订单、入库记录、补货计划。
8. 财务&成本核算域模块：平台佣金、手续费、退款扣费、各项成本分摊、SKU利润核算（核心报表）。
9. 税务域模块：各个国家VAT税费计算，税务申报数据集整理。
10. 报表统计域模块：业务大屏、自定义多维度报表（只能读取镜像库做多维JOIN分析）。
11. 告警监控域模块：业务异常告警，同步失败、库存水位、预算异常等。

### 全局共享基础模块 —— 全系统仅此一套

1. 基础字典数据：国家、地区、平台字典。
2. 汇率管理、完整多币种换算工具库。

✅铁律：任何业务模块代码，禁止自己实现汇率、币种换算逻辑。全部调用共享模块工具。

重要提醒：shop_id、platform_code、country_code、currency_code 是数据标签，不是独立业务模块。

## 4 模块之间数据交互完整规则

### 4.1 交互总原则

1. 数据库层隔离：A模块代码禁止SELECT / JOIN / UPDATE其他模块的clean数据表。
2. 全部跨域数据交互发生于API层。一共3种通路，优先级从高到低：
   1. 同步内部契约调用（日常业务计算，70%场景）
   2. 异步领域事件（数据刷新完成的通知，25%场景）
   3. 只读镜像库（仅用于报表、Agent审计；严禁用于核心业务计算，5%场景）

### 4.2 同步内部契约调用（主流）

适用场景：A模块在执行业务计算的过程中，当下需要获取B模块经过标准化、业务规则处理完成的聚合指标。

示例流程：财务核算利润，获取订单SKU维度销售指标
1. 财务模块执行利润计算Job。财务绝不读取 clean_order。
2. 财务发起内网HTTP调用订单模块的内部契约接口：
   GET /internal/api/v1/order/sku‑aggregate?shopId=xx&countryCode=xx&dateRange=xxx
3. 请求到达订单模块Controller。订单模块内部service读取自己私有clean_order，在订单域内部完成SKU维度聚合、过滤业务逻辑。
4. 按照DTO契约格式返回聚合完成的业务指标。不返回原始订单明细行。
5. 财务拿到返回的指标，在财务域内部运行自己的分摊、利润计算逻辑，写入财务私有 clean_finance_profit。

### 4.3 异步领域事件（状态变更通知）

定位：事件只做"通知铃声"，事件的payload只携带标识信息，不要传递完整业务实体数据。

示例流程：订单清洗Job执行完成，写入clean_order基线。
1. 订单模块完成全部写入操作。
2. 向消息队列发布领域事件：
```json
{
  "eventName":"OrderDomain:OrderDataRefreshed",
  "payload":{
    "shopId":1234,
    "countryCode":"US",
    "dateRange":["2026‑09‑01","2026‑09‑25"],
    "affectedSkuList":["SKU‑001","SKU‑002"]
  }
}
```
3. 订单模块代码，不知道、也不关心有哪些模块订阅这条消息。新增业务模块只需要自行订阅事件，不需要改动订单一行代码。
4. 订阅该事件的模块（财务、库存等）收到消息之后：
   - 不会从消息体拿业务数据；
   - 主动发起【同步内部契约调用】去拉取需要的业务聚合数据，再执行自身业务计算。
5. 不订阅事件的模块（广告），这条消息对它完全无任何影响。

时序处理：
收到事件不代表数据就可以直接运算。业务Job需要调用对方模块极简状态接口 /internal/status，确认该时间段数据状态=ready，才启动计算。

### 4.4 只读镜像库（分析审计专用安全阀）

1. 独立同步服务，定时（30min / 60min），调用各个业务域的内部契约接口，把接口返回的聚合数据集拉取一份副本写入镜像数据库。
2. 报表统计模块，可以直接查询镜像库做多维join、大屏可视化。
3. MCP审计Agent可以读取镜像辅助数据分析。

🔴不可突破的红线：
财务核算、库存计算、税务计算等所有核心业务计算，禁止读取镜像库。核心业务必须调用实时内部契约接口。

## 5 计算职责边界

### 5.1 Raw‑to‑Clean阶段（仅做一次）【✅允许】
1. 字段映射：平台五花八门字段，统一为系统标准字段名。
2. 时间标准化：把平台各类时间格式统一为系统标准UTC时间。
3. 数据去重：对平台重复推送的原始记录进行合并、去重。
4. 实体业务状态标记（最重要）：订单是否为取消订单、预下单、部分退款、全额退款；广告投放启停状态；库存类型标记。
5. 完整保留原始发生金额、原始货币代码，不对金额做任何币种换算。

### 5.2 上层业务模块允许的计算
1. 本业务域内的指标聚合、分组、统计。
2. 成本分摊、利润计算、周转率、ROI、ACOS这类业务域特有业务算法。
3. 币种换算：全部调用全局共享模块工具函数。

### 5.3 严禁执行的操作清单（黑名单）
1. ❌禁止任何业务模块直接SELECT/JOIN其他业务域的clean数据表。
2. ❌禁止一个模块在代码中直接导入另外一个模块的内部业务逻辑（绕开API契约，隐形耦合）。
3. ❌在Raw‑to‑Clean清洗Job中做币种转换、利润、分摊、指标求和。
4. ❌业务模块自己手写汇率、币种换算的代码逻辑。
5. ❌修改已有版本契约接口的字段、数据类型、单位、业务语义；破坏性变更必须新建接口版本。
6. ❌将完整业务明细、业务实体放到MQ事件payload中；事件只能传递ID、范围、标识。
7. ❌财务、库存、税务等核心业务计算逻辑读取镜像库数据。
8. ❌上层业务模块，重复实现一套本应在Raw‑to‑Clean完成的实体状态判断逻辑。

## 6 多币种业务规则（固化进系统）

1. Clean数据表永久存储业务发生时刻的原始币种原始金额，永远不能覆盖改写原始数值。
2. 所有币种换算操作，调用【全局共享基础模块】提供工具方法。
3. 单国家、单店铺内部全部业务运算、表格展示，使用该国本土货币。
4. 跨国家、跨地区做汇总求和的时候，全部统一转换为美元完成汇总计算。
5. 页面国家选择器切换国家时：把country_code参数传入后端接口；后端使用该国家本位货币输出。
6. 审计Agent校验：单国家报表输出货币=该国家本位货币；跨国合计行=USD。

## 7 MCP / Agent 旁路审计架构

三方比对流程：
1. Agent读取RawData（真相源）
2. Agent读取各个业务域的Clean私有基线表
3. Agent调用各个业务域对外的契约API

执行三组校验：
1. RawData ↔ CleanData：校验清洗逻辑是否发生漂移
2. CleanData基线 ↔ API返回数据：校验接口加工是否产生数据丢失、归零、空白、币种错误
3. API出参 ↔ Web页面渲染的输出

告警触发条件：
- 指标值为0，但根据原始raw数据预期应该存在业务数据
- 返回字段为null、空白
- 币种单位和当前选定国家规则不匹配
- Raw推演理论值和Clean、API返回的数值偏差超过业务允许阈值

## 8 业务端到端完整示例：SKU利润报表生成全链路

1. Raw‑to‑Clean（各模块并行执行Job）
2. 财务模块订阅全部刷新事件，确认数据ready
3. 财务模块依次调用各模块内部契约接口获取聚合指标
4. 在财务模块内部完成币种换算（同国家本土货币/跨国USD）
5. 执行利润分摊计算，写入财务私有表
6. 财务对外提供Web接口，前端渲染
7. MCP审计Agent旁路三方比对

场景推演：修改订单模块清洗逻辑
✔只要契约DTO出参不变，其他模块一行代码无需改动

## 9 工程落地约束与流水线检查

### 9.1 Git提交阶段（pre‑commit）
1. 静态检查：禁止从其他业务模块导入内部service
2. 数据库迁移脚本约束：一张表只能由归属业务模块管理schema变更

### 9.2 CI流水线执行清单
1. 业务规则单元测试
2. DTO契约校验
3. 黑名单规则静态扫描：检查跨域clean表SQL查询
4. 小规模数据集基线比对测试

### 9.3 数据库Schema变更流程
1. 只能修改该业务模块内的迁移脚本
2. 评审是否改变契约接口数据含义
3. 改变含义→新建v2接口，v1保留

## 10 分阶段落地实施路线

### 阶段一：基础改造（1‑2周）
1. 梳理raw数据表，确认只读
2. 划分业务域边界，确认每张表归属
3. 币种/汇率逻辑剥离到共享模块
4. 建立静态代码检查规则

### 阶段二：契约接口体系落地（3‑4周）
1. 为每个模块定义 /internal/api/v1/* 内部契约接口
2. 改造现有跨域调用为契约接口
3. 搭建消息队列，落地领域事件
4. 搭建镜像同步服务

### 阶段三：审计体系完善（持续迭代）
1. 落地MCP Agent旁路审计
2. 完善测试基线数据集
3. 存量老业务逐步迁移
