# 「最终完整架构总文档」vs 系统现状 差距分析报告

> 日期：2026-09-25 ｜ 分析对象：architecture-master-spec.md（用户上传确认的"最终定稿架构标准"）
> 方法：全部结论基于当日只读核查（pg_policies / audit_results / worker.log / 源码 grep / API 实测），证据可复现。
> 结论先行：**方向高度一致，机制各有取舍；真正要立即处理的不是架构差距，而是核查中发现的 1 个 P0 活体安全回归。**

---

## 0. 三分钟摘要

| 判定 | 数量 | 条目 |
|---|---|---|
| ✅ 已达标 | 5 | 四层数据流、多币种规则、双基线审计（超出）、禁忌红线多数、注册表驱动扩展 |
| 🟡 等价落地（机制不同） | 3 | 租户隔离（PG RLS vs ORM 拦截）、插件化（注册表 spec vs 适配器对象）、级联禁 FK（定时重算 vs 事件驱动） |
| 🟠 部分达标 | 3 | 事件驱动级联（A2 基建就绪、生产静默）、租户级调度（A4 基建就绪、cron 未迁移）、表结构标准（version/extension 覆盖低） |
| ❌ 未落地 | 2 | 五域微服务拆分、数据库账号按域硬隔离 |
| ⚠️ 语义冲突 | 1 | shop_id 维度（现系统为 brand 维度，无 shop_id 列，118 张表 0 命中） |

**置顶活体发现（比差距分析本身更要紧，今日核查新发现）：**

1. **P0 安全回归**：audit schema 42 张 `cleaned_*` 表 RLS 策略已被清洗引擎刷回两维（缺 `is_active`），停用品牌 onno 当前经 portal_app 真实可见（06:40 审计批次两项 FAIL 实证）。交接摘要"全部重建策略"描述的是 01:34 时点的状态，之后被引擎回滚。详见 §1.1。
2. **半接线四件套（HANDOFF 漏提，changelog 在案）**：旧会话今晨按用户令"全部执行"落地主控架构 A1–A4。A1 `/internal` 契约 API（5 端点）与 A3 DTO（11 模型）**已接线可用**（本次实测公网 404 隔离 ✓、容器内路由存活 ✓）；A2 事件总线与 A4 租户调度**基础设施就绪但生产静默**——全仓库无任何事件发布方、cron 仍是全局任务未迁移。推进节奏需用户拍板。详见 §1.2。
3. **P1 SQL bug**：`sync_mercury` 某结算 spec 的 `left(date, integer)` 类型错误，为 cron_audit 今日唯一 FAIL 的根因。详见 §1.3。
4. **4849 终验（服务端）通过**：`kpi-cards?platform=noon&period=rolling` 实测 `订单 2761`（预期锚点 ≈2737，差值为 09-25 当日新增订单，rolling 窗口右移所致）。前端仍需用户强刷/无痕一次确认。dashboard.py 代码级 `is_active` 过滤在位（824/1583 行），RLS 回归未污染业务数字。

---

## 1. 活体发现详述（含证据链）

### 1.1 P0：audit schema 42 张表 RLS 缺 is_active（引擎回滚型回归）

**证据链（全部当日可复现）：**

```
pg-init/61-rls-hardening-20260924.sql   三维模板（含 b.is_active）
pg-init/62-rls-is-active-fix-20260925.sql  86 条 CREATE POLICY，同时覆盖 public + audit 两 schema
01:34 UTC  audit_results 批次 4a2ef7b5：RLS 隔离实测 PASS（"scope=停用→空"）
   ↓ 01:34–06:40 之间清洗引擎运行一轮
tools/audit_clean_all.py:165-172  引擎原子换名时重建 RLS，模板为：
   brand IN (SELECT brand FROM tenant_brands WHERE tenant_id = app_tenant_id())
   ——缺 b.is_active（两维版）
06:40 UTC  audit_results 批次 c41997f3：
   RLS 策略三维完整性 FAIL「42 张缺维度」
   RLS 隔离实测(portal_app) FAIL「无scope=fittingirls,onno,zipforce scope=onno→onno」
当前  pg_policies 实测：public 44 张三维 ✓ / audit 42 张两维 ✗
```

**影响评估（诚实口径）：**
- 跨租户隔离未破（tenant_id 维度仍在）——破的是"租户内停用品牌"这层。
- 业务数字未被污染：dashboard.py:824/1583 代码级 `is_active=true` 过滤在位，4849 锚点实测 2761 正常。
- 但纵深防御破损，且**每次清洗引擎运行都会继续回滚**——手工重放 62 号 SQL 治标不治本。

**修复方案（~30 分钟，待批准）：**
1. `audit_clean_all.py:167-168` 模板补 `b.is_active`（治本，根因在引擎模板）
2. 重放 62 号 SQL 恢复当前 42 张表
3. 跑 `four_layer_audit` L2 复核三项 RLS 检查回 PASS
4. changelog 补记 + checklist 同步

### 1.2 半接线四件套：A1/A3 已落地，A2/A4 生产静默（HANDOFF 漏提，changelog 在案）

今晨 11:15–11:21（旧会话上下文死前最后半小时）按用户令"全部执行"落地（changelog 第 58–67 条有记录，但 HANDOFF 未提）：

```
A1 ✅已接线  api/routers/internal.py — 5 个 /internal/api/v1/* 端点
   （order/sku-aggregate · order/status · ads/spend · finance/monthly · shared/fx-rate）
   X-Tenant-Id 头传租户；本次实测：公网 404 隔离 ✓、容器内路由存活 ✓
A2 🔇静默    api/domains/events.py — Redis Streams 事件总线 publish/subscribe、全局幂等 eventId
   （对齐「主控架构 A2」：事件只做通知铃声，不传业务实体）
   落地时一次性实测"发布+幂等+读回"通过，但生产零调用——总线建成至今无人按铃
A3 ✅已落地  api/dto.py — 11 个 Pydantic 契约模型
A4 🔇静默    api/domains/scheduler.py — discover_tenant_jobs() 从 brands_source×tenant_brands
   动态发现活跃「租户-品牌-平台」组合（首跑 8 组合，对齐「主控架构 A4」）
   但 arq cron_jobs 仍为全局任务清单，未迁移
+  api/domains/{ads,finance,inventory,orders,shared}/store.py 域私有存储（被 A1 端点实际调用）
```

**准确判定**：非孤儿骨架，是"基建完成、业务未接入"——A2 事件总线与 A4 租户调度恰好对应总文档第四、六章。推进节奏需拍板：

| 选项 | 内容 | 理由 |
|---|---|---|
| A | 封存现状（A1/A3 留用，A2/A4 暂不推进，README 注明状态） | 先业务流全通；静默基建无副作用 |
| B | 最小闭环接线：汇率事件一个用例跑通（daily_fx_rates 完成后 publish ExchangeRateUpdated → 财务重算订阅） | 最小代价验证总线模式，再定推广 |
| C | 全面接入：采集/清洗任务完成后均发事件 + cron 迁移租户级 | 工作量数日，P2/P3 节奏 |

### 1.3 P1：`left(date, integer)` SQL 错误

worker.log 近段 8 行 Traceback，最新一条：

```
File "/app/sync_mercury.py", line 1591, in ingest_all → qmercury(sql)
RuntimeError: mercury export failed:
ERROR:  function left(date, integer) does not exist
LINE 2: SELECT 'zipforce'::text, coalesce(market,''), left(stmt_mont...
```

mercury 侧 SQL 对 date 列直接 `left()`，PostgreSQL 无此重载。为 cron_audit 今日唯一 FAIL（"worker 日志错误"）的根因。修复：`left(stmt_month::text, 7)` 或 `to_char(stmt_month,'YYYY-MM')`。涉及 settlement/finance 域某 spec，修复前该管道持续报错。

### 1.4 交接摘要两处失实（记录在案，防止以讹传讹）

| 交接摘要说法 | 当日事实 |
|---|---|
| "86+21 张表…全部重建策略" | public 44 张重建在位；audit 42 张被引擎回滚为两维 |
| "当前 113 项，FAIL 1（noon_statement）" | 引用的是 01:34 旧批次；最新 06:40 批次 118 项 FAIL 3（RLS×2 + 见 §1.3 的 worker 日志错误归入 cron_audit） |
| 对主控架构 A1–A4 四件套只字未提 | changelog 记录已按用户令"全部执行"落地：A1 /internal 5 端点 + A3 DTO 已接线，A2/A4 基建就绪静默 |

另：**keepa（05:20 首跑）与 cron_audit（07:25）两个机器人今日验证均通过**——keepa 31.4s 完成（asins 1064/pulled 509/written 442，无 ImportError，rankings_daily 三品牌 max(snap_date)=2026-09-25）；cron_audit 42 项产出正常，唯一 FAIL 即 §1.3 根因。

---

## 2. 总文档十三章逐项对照

### 第一章 核心需求（10 条硬性需求）

| # | 需求 | 现状 | 判定 |
|---|---|---|---|
| 1 | 多租户零泄露 | PG RLS 三维 + 代码级过滤双层（当前 audit schema 一层破损，见 §1.1） | 🟡 等价落地+待修 |
| 2 | 三层维度隔离 | 四维：tenant > brand > platform > country（比文档多一层品牌；无 shop 维度） | 🟡 语义差异 |
| 3 | 全链路级联 | 定时批处理重算（arq 27 任务 + 宿主 13 条），事件总线基建就绪但无发布方 | 🟠 部分达标 |
| 4 | 平台插件化零改核心 | brands_source 插一行全链路自动（P0 已落地验证）+ platform_adapters.py P2 骨架 | ✅ 精神一致 |
| 5 | 全按租户自动生成任务 | 全局任务遍历活跃品牌过滤；scheduler.py 发现机制就绪（首跑 8 组合）但 cron 未迁移 | 🟠 部分达标 |
| 6 | 双基线审计 | 四层审计 118 项 + cron_audit 42 项 + 回归审计 7 项 + 白名单/阈值/基线注册表 | ✅ 超出 |
| 7 | 业务域解耦 | 单体 FastAPI；但五域目录 + 域 store + 5 个 /internal 契约端点已落地接线（公网 404 隔离实测 ✓）；进程与 DB 账号未拆 | 🟠 契约层已落地 |
| 8 | 多币种 | 本土币存储 + fx_rates + daily_fx_rates + 前端 localCur + 多国折 USD | ✅ 已落地 |
| 9 | 禁数据库物理级联 | 无外键 CASCADE；清洗层原子换名；聚合表重算 | ✅ 已落地 |
| 10 | 无限横向扩展 | 注册表驱动，新品牌已验证全链路自动；新国家=marketplaces 数组加元素 | ✅ 路线已通 |

### 第二章 架构分层

| 文档要求 | 现状 | 判定 |
|---|---|---|
| Raw→Clean→API→Web 四层 | 完全一致，且是全团队铁律（四层审计按此分层） | ✅ |
| Web 层零计算零换算 | 前端纯展示，币种换算在 ingest/API 层完成 | ✅ |
| 内核/插件双层 | Core（core.py + metrics_store.py）+ brands_source spec + adapters 骨架 | 🟡 雏形 |

### 第三章 隔离体系

| 文档机制 | 现系统对应 | 判定 |
|---|---|---|
| ALS 异步上下文 | FastAPI Request.state + `app_tenant_id()` 会话变量 | 🟡 等价 |
| ORM 全局拦截 | PG RLS 策略（数据库层强制，比 ORM 拦截更强，绕不过） | 🟡 等价偏强 |
| JWT 唯一身份 | 会话 cookie + current_tenant(request)，租户 ID 不经前端传参 | ✅ |
| 内部 API X-Tenant-Id | 单进程内函数调用，无此风险面 | 🟡 不适用 |
| 队列 Job 强制校验 | arq 任务内部自带租户上下文 | 🟡 等价 |
| 超管白名单 | saas_admin 仅审计/运维通道，portal_app 为应用账号 | 🟡 等价 |
| SQL 审计兜底 | RLS 即兜底 + L2 实测探针（今日正是它抓住了回归） | ✅ |
| 平台隔离 | platform 列 + 各平台独立采集管道 + 消费端过滤 | ✅ |
| 国家币种隔离 | country(33 表)/currency(10 表) 列 + 本土币存储 + 禁混算（审计有专项检查） | ✅ |

**结论：隔离一章语义 100% 达标，机制实现与文档措辞不同（RLS vs ORM），且 RLS 更强。唯一窟窿是 §1.1 的 is_active 回归。**

### 第四章 级联机制

| 文档要求 | 现状 | 判定 |
|---|---|---|
| 禁外键 CASCADE | 无 FK CASCADE | ✅ |
| 事件驱动+幂等 | events.py 骨架（Redis Streams + eventId 幂等）已建**未接线** | 🟠 |
| Raw/Clean 只增不改 | 清洗层版本化原子换名，历史可追溯 | ✅ |
| 汇率变更触发重算 | 现为每日定时重算，非事件触发 | 🟠 |

### 第五~六章 插件化与全自动化

| 文档要求 | 现状 | 判定 |
|---|---|---|
| 新平台=适配器+一行注册 | 新**品牌**已实现一行注册（brands_source）；新**平台**（全新 API 对接）仍需写采集代码（sync_mercury spec + adapter），这是客观现实：平台 API 对接本身无法零代码 | 🟡 品牌级已达标，平台级为 P3 直连规划 |
| 停用店铺自动暂停 | 停用品牌经 is_active 全链路过滤（正是本次回归要守住的那层） | ✅（修复后） |
| 租户专属 Job | scheduler.py 骨架未接线 | 🟠 |

### 第七章 业务域解耦

| 文档要求 | 现状 | 判定 |
|---|---|---|
| 五域拆分 | api/domains/ 五域目录 + 域 store 已落地并被 /internal 端点调用；仍单进程 | 🟠 域模块落地、进程未拆 |
| DB 账号硬隔离 | 仅 saas_admin（运维）+ portal_app（应用）两个账号，无按域账号 | ❌ 未落地 |
| /internal 契约 API | internal.py 5 端点（X-Tenant-Id 头、公网 404 隔离，本次实测 ✓） | ✅ 已落地 |

### 第八章 表结构标准

实测（information_schema，118 张 public 基表）：`tenant_id` 66 张、`brand` 46 张、`platform` 18 张、`country` 33 张、`currency` 10 张、`version` 2 张、`extension` 0 张、`shop_id` 0 张。

- 四维标签覆盖：核心业务表全覆盖 ✓
- `version`/`extension(jsonb)`：几乎未采用——清洗层用"版本化表+原子换名"实现同等语义，但列级标准未对齐 🟠
- 业务 ID String：已遵行（order_nr 等皆 text）✓

### 第九章 多币种：✅ 全部达标（略，见第一章第 8 条）

### 第十章 审计体系：✅ 超出达标（双基线之上还有 api/web 两层 + 回归审计 + 已知问题白名单 + 阈值/基线注册表）

### 第十一章 禁忌红线（10 条）

| 红线 | 遵守情况 |
|---|---|
| 禁 FK 级联 | ✅ |
| 禁手写 tenant_id 条件 | 🟡 代码有显式过滤（与文档"ORM 自动追加"机制不同，RLS 兜底） |
| 禁前端传租户 ID | ✅ |
| 禁全局无租户任务 | 🟡 任务定义全局、执行按租户/品牌过滤（scheduler 骨架即为对齐此条而建） |
| 禁改 Raw/Clean 基线 | ✅ 原子换名版本化 |
| 禁跨币种相加 | ✅ 审计专项 |
| 禁平台差异入内核 | ✅ 注册表/适配器收敛 |
| 禁统计字段入 JSON | ✅ source_map 仅存映射配置 |
| 禁跨域直连 DB | 🟡 单体内无"跨域"概念，Core 统一出口 |
| 禁新平台改内核 | 🟡 品牌级达成，平台级需新增采集代码 |

### 第十二~十三章（CheckList 与总结）：为前述内容的汇总，不单独对照。

---

## 3. 分级改造清单（建议，全部待用户拍板）

### P0 — 立即（安全回归，~30 分钟）
| 项 | 内容 | 风险 |
|---|---|---|
| P0-1 | audit_clean_all.py RLS 模板补 `b.is_active`（治本） | 低：模板与 61/62 号 SQL 对齐 |
| P0-2 | 重放 62 号 SQL 修复当前 42 张 audit 表 | 低：DROP+CREATE POLICY 不动数据 |
| P0-3 | 复核审计 L2 三项回 PASS + changelog 补记 | — |

### P1 — 本周
| 项 | 内容 | 说明 |
|---|---|---|
| P1-1 | 修 `left(date,integer)` SQL（spec 改 `to_char`） | cron_audit 唯一 FAIL 根因 |
| P1-2 | 4849 前端终验 | 服务端已过（2761）；用户强刷/无痕一次即闭环 |
| P1-3 | 孤儿骨架处置 | §1.2 选项 A/B/C |

### P2 — 按需（架构对齐，先设计后动手）
| 项 | 内容 | 前置条件 |
|---|---|---|
| P2-1 | 事件总线最小闭环（汇率→财务重算单用例） | 用户选 §1.2-B；先出设计单 |
| P2-2 | 新表结构标准：新建表强制带 version/extension | 写进 pg-init 规范注释，不动存量 |
| P2-3 | 适配器 P3 直连版 | 真有新平台需求时做 |

### P3 — 明确不建议现在做（与"先业务流全通再优化"冲突）
| 项 | 理由 |
|---|---|
| 五域微服务拆分 + DB 按域账号 | 单体 + Core + RLS 已达成隔离与解耦效果；拆分是高成本高风险纯架构动作，无当前业务收益 |
| shop_id 维度引入 | 与 brand 维度语义重叠，118 张表 0 列支持；若真要多店铺语义应先定义 brand↔shop 关系，属需求级决策 |
| 存量表全量补 version/extension 列 | 清洗层已用版本化表实现同等语义，全量 DDD 改造收益不成比例 |

---

## 4. 术语翻译表（文档 → 本系统落地语义）

文档含 NestJS/TS 生态词汇（ALS、@TenantBypass、DTO、/internal），落地时应取语义不照搬机制：

| 文档术语 | 本系统落地 |
|---|---|
| ALS 异步上下文存储 | FastAPI Request.state + PG 会话变量 app_tenant_id() |
| ORM 全局自动拦截 | PostgreSQL RLS 策略（数据库层强制，强于 ORM） |
| @TenantBypass 超管白名单 | saas_admin 运维账号（仅审计/运维，应用走 portal_app） |
| DTO 契约 | api/dto.py + Core 层函数签名 |
| /internal 内部契约 API | 同进程 Core(metrics_store) 调用 |
| 事件总线 | domains/events.py（Redis Streams，待接线） |
| resolveCountryCurrency | brands_source.marketplaces + source_map 注册表 |

---

## 5. 总结论

1. **方向对齐度高**：四层流、注册表驱动、RLS 隔离、多币种、双基线审计、禁物理级联——文档的"魂"已是系统现实，部分地方（审计）超出文档。
2. **真正欠账集中在两处**：事件驱动级联（A2 基建就绪、生产静默）与业务域物理拆分（明确建议不做，见 P3）。
3. **当务之急是 P0 安全回归**（§1.1）——这不是架构差距，是已批准修复被引擎模板回滚，修复方案已备好待批。
4. 文档定位建议：作为**长期架构愿景 + 语义标准**（选项 A+B 折中），改造按 §3 清单分级推进，不以"逐条对齐"为目标。

---

*核查证据均取自 2026-09-25 当日：pg_policies / audit_results（批次 c41997f3、4a2ef7b5）/ worker.log / cron-audit-20260925.txt / API 实测（kpi-cards values.units30.foot="订单 2761"）。*
