# 注册表唯一事实源 —— 架构改造全录（2026-09-24，P0+P1+P2 三轮）

> 一句话：**事实进注册表，逻辑写死在代码。** 新品牌/新站点/新平台接入 = 插行/放文件，
> 数据链（采集→ingest→清洗→API→Web）与四层审计全自动长出，零改码。
>
> 背景问答：用户问"咱们是电商 SaaS，是不是尽可能使用注册表的形式？"——盘点了全部配置散落点后
> 确立原则并当天三轮落地（P0 地基 / P1 审计参数 / P2 平台能力），全程零 LLM、全代码执行。

---

## 一、原则与判断标准

**什么进注册表**（三条满足即进）：
1. **随业务增长的枚举**：新品牌/站点/平台/租户/币种——加一行数据 ≠ 改一次代码
2. **多处消费同一事实**：采集、ingest、审计、API、Web 至少两处要用——一处事实，处处一致
3. **变更要留痕**：谁、何时、为什么改（表天然可审计）

**什么不进注册表**（有意写死）：
- 公式与口径（费用、对账、PL 计算）——架构五铁律"表结构+公式+Web 三层写死"
- RLS 安全逻辑、Web 路由
- 异构口径的品牌分支（amazon_orders 三分支 / order_fees / monthly_pl AMZ·FG 等）——新品牌接入走需求单通道

**改造前的问题**（三张皮）：采集器 MARKETS 配置、token 实际授权、注册表 marketplaces 字段
各说各话——zf SA/AE 断流 14 天才暴露的根因。注册表化后三方对账有了唯一基准。

---

## 二、八张注册表总账

| # | 注册表 | 内容 | 关键字段/键 | 消费方 |
|---|--------|------|------------|--------|
| 1 | `brands_source` | 品牌×平台管道 | `marketplaces`（回填：zf 18/fg 14/onno amz 4+noon，**UK 口径**）；`source_map` 显式键：`finances_view`（fg）、`statement_official`（zf noon） | sync_mercury / 审计 L1 / 授权探针 / onboarding |
| 2 | `marketplaces` | 站点→货币/ID | 19 国 amazon（补 CA·MX + 新增 `marketplace_id` 列） | 广告折算 CASE / brandboard / ops / aplus |
| 3 | `platforms` | 平台清单 | amazon / noon / **emag(planned)** | 平台能力矩阵的挂靠点 |
| 4 | `pipe_domains` | **平台×域断更矩阵** | (platform, domain) → table/date_col/stale_days/brand_override | metrics.pipe_stale_rows（铃铛+报警邮件） |
| 5 | `audit_known_issues` | 审计白名单/挂账 | check_key/reason/**expires_at**（NULL=永久豁免） | four_layer_audit L2 |
| 6 | `audit_thresholds` | 审计阈值 | 21 项（fresh.\*/stall.\*/twotable/ghost/pending/align） | four_layer_audit 全层 |
| 7 | `audit_baselines` | 数据质量基线 | (check_key, metric) → value（首条：orders invalid≤10%） | four_layer_audit L2 |
| 8 | `secrets/audit_tenants/*.env` | 审计测试凭据 | brand/host/email/password 四行，600 权限 | chart_value / 今日页对账 / e2e |

规律名约定（新品牌零登记自动长分支）：
- `shared.mapping_{brand}`、`{schema}.{schema}_spapi_order_items/_orders/_finances`
- noon 域 `{s}.{s}_orders/_finance_transactions/_ads_skus/_procurement_cost/...`
- 特殊口径走 source_map 显式键覆盖（fg 的扁平视图 finances、zf 的 noon 对账单）

---

## 三、三轮改造明细

### P0 地基（注册表成为唯一事实源）
1. **marketplaces 字段回填**：从采集配置核实（不猜），onno amazon=4 市场是采集口径
   （数据现实 13 国是 `v_onno_orders_unified` 历史全量，断流基准取"应然"口径）；多租户行强制一致
2. **sync_mercury 11 个 spec 注册表化**：`_pipe_registry()` 返回 (source_schema, source_map)，
   `_refresh_dynamic_specs()` 重写 sku_mapping/products/sales_daily/inventory_health/
   finance_monthly/noon 六表/monthly_pl(noon 段)/noon_statement；
   **ingest_today 也接入刷新**（原来只有全量刷→新品牌增量会断流）
3. **广告折算 CASE 注册表化**（9→19 国），顺手修历史错折：**CA 2047 行 EUR→CAD**
   （预算币种空的行曾被 ELSE 'EUR' 兜底错折）
4. **审计 L1 切注册表**：新鲜度/独立源交叉（onno 新纳入）/Pending 注册表循环；
   授权探针基准 = brands_source × marketplaces.marketplace_id（三张皮归一）

### P1 审计参数
1. **白名单表 + 过期复报**：挂账带 expires_at，到期次日起按原级别复报 + "挂账过期复报"提醒项
   点名——挂账再也不会永远沉默（实测插过期行验证）
2. **阈值表**：调阈值改表数据即可，不发版；代码同值兜底
3. **凭据目录**：今日页对账+图表对账遍历目录全部租户；新租户放 env 文件即被 L3 覆盖

### P2 平台能力
1. **pipe_domains**：pipe_stale_rows 的平台 if/elif → 注册表展开；未登记平台按 noon 月度兜底（原行为）
2. **L1 noon 源表新鲜度**：{s}.{s}_orders 推导自 noon 域 schema，gap≤2——治月度表 35 天兜底太钝
3. **质量基线**：invalid 率相对阈值——cleaned_amazon_orders 的 2541 invalid（6.6% 误判防护常态）
   从长期 WARN 降为 PASS

---

## 四、接入流程（从此日起生效）

**新品牌（Amazon）**：
```
① brands_source 插行: enabled + source_schema + marketplaces + source_map
   (规律名域零登记自动长; 特殊口径加显式键)
② 采集器放凭证 + mercury 建 {brand}_amazon schema
③ shared.mapping_{brand} 建映射表
→ ingest 25 spec / 审计 L1 全部检查 / 授权探针 / 货币折算 全自动
→ L3 覆盖: secrets/audit_tenants/{租户}.env 放测试凭据文件
```

**新站点（现有品牌加市场）**：brands_source.marketplaces 数组加国码 +
marketplaces 表确保有该行（country→currency→marketplace_id）→ 探针/折算/断流自动对账

**新平台（emag）**：
```
① pipe_domains 插订单/小时/广告三域行（表名指向 SaaS 水位表）
② platforms 表 status 改 active + brands_source 登记
③ mercury 建 emag schema + 采集器
→ 断更矩阵/审计/ingest 同构域自动展开
```

---

## 五、日常运维操作速查

```sql
-- 新增挂账（到期自动复报）：
INSERT INTO audit_known_issues VALUES ('断流 xxx/YY', '原因', '2026-10-31');
-- 永久豁免（语义性，如对账口径表）：expires_at 传 NULL

-- 调阈值（例：断流 FAIL 天数 4→3）：
UPDATE audit_thresholds SET value=3 WHERE check_key='stall.gap_days';

-- 加质量基线（例：某表 invalid 率常态 5%）：
INSERT INTO audit_baselines VALUES ('cleaned_xxx', 'invalid_pct_max', 5, '说明');
```
```
# 新租户纳入 L3 审计（今日页+图表对账自动遍历）：
vim secrets/audit_tenants/新租户.env    # brand/host/email/password 四行, chmod 600
# e2e 切租户跑：AUDIT_TENANT=onno python3 tools/frontend_e2e.py
```

---

## 六、顺手修掉的 bug（都有实锤验证）

| # | bug | 影响 | 修复 |
|---|-----|------|------|
| 1 | `chart_value_audit.run(brand)` 参数从未生效 | "81 图双视图"实为 zipforce 跑两遍，**onno 81 图从未真对账过** | run() 内真切换（global 重绑）；onno 首跑 FAIL 0 |
| 2 | `DATE_COLS`/`FRESH_DAYS` 常量缺失 | L2 全部 84 表新鲜度检查被 except 吞成 WARN，**全盲** | 恢复定义（P1 又迁入阈值表） |
| 3 | `_load_registry()` 模块级调用时 psql 未定义 | NameError 被吞→注册表空载（静默失效） | 移到 main() 开头 |
| 4 | L1 循环变量 `_t` 遮蔽阈值函数 `_t()` | TypeError 会炸掉整个 L1 | 改名 `_src` |
| 5 | 广告折算 ELSE 'EUR' 兜底 | CA 2047 行错折 EUR（实为 CAD） | 注册表 19 国 CASE + 重灌修正 |

**共性教训**：except 吞掉的静默降级是审计工具最危险的故障模式——"声称的覆盖 ≠ 实际的覆盖"，
审计工具自身也要被审计（靠精读 + 跑一遍实锤）。

---

## 七、验证与部署记录（2026-09-24）

- 等价性 dry-run：11 spec 表集合一致/逐字等价；mercury 真跑 10/11（唯一 error=已知挂账 noon_statement）
- 全量 ingest 前后行数 diff：仅 sales_daily +5（自然增长）
- 授权探针：zf 18 / fg 14 / onno 4 市场全对齐
- 终态四层审计：**113 项，FAIL 1（today-noon 15 分钟级时点差，非真丢单），WARN 7**
- pen_tests ALL PASS；api/worker 两次 rebuild
- 审计演进：107→109→111→113 项（每轮新增覆盖），挂账全部带到期日

## 八、部署目录地图 + 定时任务全景（2026-09-24 收编后）

### SaaS 相关文件目录（mars 本机）

| 目录 | 角色 | 说明 |
|------|------|------|
| `/opt/six-claude/workspace/saas/` | **唯一真实代码库** | api/web/tools/pg-init/secrets/Caddyfile/compose + 5 个定时脚本；所有改动只在此 |
| `/opt/saas/workspace/zipforce-hub/` | 文档工作区 | changelog/需求单/审计报告/context/截图；挂 Caddy `/srv/zipforce-hub` |
| `/opt/collection/` | 统一采集器 | compose 卷挂进 worker `/collection` |
| `/opt/saas/monitor-agent/` | 外部监控 | 刻意在 SaaS 外（监控者不住被监控者里），07:10 日报 |
| `/usr/local/bin/six-claude-monitor.sh` | 机器级监控 | 每 2 分钟，同为外部独立性设计 |
| `/opt/zipforce-hub-installer/` | 部署安装包 | install.sh/images/migrations，分发用 |
| `saas/backups/residual-workspaces-20260924/` | **已归档残留** | dashboard/finance/sourcing 三份 09-11 多窗口 saas 副本（+同名 tar.gz 双保险），防"改错库"；恢复=mv 回原位 |
| docker volume `zipforce-saas_pgdata` | 数据库本体 | `/var/lib/docker/volumes/`，backup.sh 每日 03:30 备份 |

### 定时任务两层结构

**任务定义**（做什么）：全部代码化——worker arq `cron_jobs`（api/tasks.py:881，20+ 任务：
ingest 全量/增量、采集器全家、水位/费用/漂移报警、Keepa、广告规则、fx/rankings…）
+ saas 根目录 5 个 .sh（backup/aba/kol/promotion/four_layer_audit）。

**调度触发**（何时跑）：
- arq 内部 cron —— 代码化，随仓库走 ✓
- 宿主 root crontab 12 条 —— **清单已落地 `saas/host-crontab.txt`**（逐条注释用途），
  恢复脚本 `install-host-crontab.sh`（幂等、先备份、diff 校验）。变更流程：**先改清单文件，再跑安装脚本**。
- mercury `/etc/cron.d`：**全部收编 mars**（biweekly-backfill 隔周结算回补 / zipforce-pm-backup PM 库备份，
  09-24 改 mars ssh 调度，mercury 侧文件 .disabled-20260924 留档；noon-sync/onno-sync 早前已停用）
- venus：采集 cron 已全停（六期收编，tasks.py:232 注释确认）

## 九、边界与遗留

- **仍硬编码**（异构口径，勿顺手改，新品牌接入走需求单）：amazon_orders 三分支
  （v_order_master / fg 视图 / onno 统一视图+items UNION）、order_fees、monthly_pl AMZ·FG 分支、
  inventory_health 视图分支、noon_ads_daily/amazon_ads_daily（onno 特定）、ABA_DOMAIN/keepa domainId
- 挂账不变：noon_statement `left(date,int)`（mercury 需求3）、SMTP 526、onno IT 断流（10-15 到期自动复报）
- 代码位置：`api/sync_mercury.py`（_refresh_dynamic_specs）、`api/metrics.py`（pipe_stale_rows）、
  `tools/four_layer_audit.py`（L1/L2/L3）、`pg-init/53·54`（新表 DDL）
