# 采集/主数据侧需求单（SaaS → 采集）— 2026-09-29

**移交对象**：采集栈维护人（onno = venus 104.194.95.213；fittingirls = mercury 104.194.81.222 v2，Sales 在 venus；排名/库存快照按现有归属）
**提出方**：SaaS（mars）——本文档只定义需求与验收，不含修复动作；SaaS 侧呈现兜底见文末。
**背景**：用户就 ONNO（6 项）与 fittingirls（7 项）工作台数据问题提问，SaaS 侧完成调查分类：A 类（代码 bug）6 处与 C 类（功能缺失）3 处已于 2026-09-28 全部修复上线（四道门全绿 + 截图自检）；剩余全部为 **B 类 = 源数据缺口/主数据欠账**，立本单移交。相关前单：`db-requirements-2026-09-24.md`（R1/R2 已执行完毕）、`db-requirements-2026-09-18.md`。
**取证说明**：以下全部数字为 2026-09-29 于 SaaS 库（saas_registry 同步副本）实测，非推断。

---

## R1（P0）：onno 订单日更断流——09-26/27/28 三天整段缺失

**现象（实测 `public.amazon_orders`，北京日）**：

| 北京日 | onno 订单数 |
|---|---|
| 09-20 ~ 09-24 | 10 / 5 / 8 / 12 / 5 |
| 09-25 | 1 |
| **09-26** | **0（整日无行）** |
| **09-27** | **0（整日无行）** |
| **09-28** | **0（整日无行）** |
| 09-29 | 1（今日增量，恢复迹象未证实） |

同窗口 zipforce / fittingirls 订单均正常到 09-29——**仅 onno 断**，指向 onno 采集任务（venus 侧）自 09-26 起停摆或凭证失效。

**需求**：
1. 排查 onno 订单采集任务（cron/凭证/SP-API 配额），恢复日更
2. 回补 2026-09-26 ~ 2026-28 三天订单（按 amazon_order_id UPSERT，勿覆盖已有 09-29 数据）

**验收（SaaS 侧复验）**：
```sql
SELECT (purchase_date AT TIME ZONE 'Asia/Shanghai')::date d, count(*)
FROM public.amazon_orders WHERE brand='onno'
  AND (purchase_date AT TIME ZONE 'Asia/Shanghai')::date BETWEEN '2026-09-26' AND '2026-09-28'
GROUP BY 1 ORDER BY 1;   -- 三行均非 0，且与当周基线（5~12 单/日）量级一致
```

## R2（P0）：onno 广告日更断流——止 08-31，09-01 起 29 天缺失

**现象（实测 `public.amazon_ads_daily`）**：
- 该表仅含 onno（zf/fg 广告在 `ads_sku_daily`，见 R3）
- 最大 day = **2026-08-31**；08-25 ~ 08-31 基线 20~24 行/天
- 09-01 起 0 行——**已断 29 天**

**2026-09-29 进展（Noon 侧已由 SaaS 回补，Amazon 侧仍缺）**：
- 用户提供的 `_OVERVIEW_ALL_Report` 日报（UAE/KSA 各 25 天，09-01~09-25）已由 SaaS 会话代入库 `public.noon_ads_daily`（brand=onno，AE 41 行 + SA 37 行共 **78 行**，幂等 UPSERT，清洗层已刷新，API 实测 9 月广告 $159.06 与 SQL 逐位一致，广告页脚注已显示「数据止于 09-25」）
- SA 09-11/09-12 源报表本身 0 行（当日无广告数据），如实不入库
- **仍未解决**：① Noon 源采集（venus）仍未恢复——文件止 09-25，09-26 起继续缺，`pipe_stale` 将如实继续报警（当前 lag 4 天 > 容忍 2 天）；② Amazon 站日更（venus）未恢复，09-26 起缺（09-01~25 已由 SaaS campaign 级回补，见下方深夜进展）

**需求**：
1. 排查 onno 广告报表采集（venus 侧），恢复日更
2. 回补 2026-09-01 起全部缺失日
3. **（新，2026-09-29 深夜定案）修复 venus 双币双写**：采集器对同 campaign×日×国写两行同一笔钱——ASIN 行（ad_cost=USD + local_*=本币，正确）+ 标题行（本币值塞进 ad_cost 列且 local_*=0）——SaaS 清洗层已加 asin_twin_dedup 去重兜底（30 天修正 $257.81→$93.38），但源头应只写一行（USD+local 双列齐全的那行）；raw 表中 255 条标题行/15 条空sku重复行仍在，venus 修复后新数据不再产生即可，历史行由清洗层长期兜底

**2026-09-29 深夜进展（Amazon 侧已由 SaaS 以 campaign 级回补，FONCYE 归属定案=onno）**：
- 七维对账（sku/asin/产品名/型号/品牌/国家/账号）定案：**FONCYE=onno 的 Amazon 卖家账号**——5/5 活动名与 onno 账户数据精确同集、线级 USD 金额逐笔吻合、ON\* SKU/型号链全 onno（推翻本单 R3 节「独立卖家账号」早判，R3 的 fg 回滚结论不变）
- 57 份 FONCYE Campaign CSV 中 **483 行**（09-01~25 全窗 + 7/8 月零星真洞日，$1,327.74）以 campaign 级入 `public.amazon_ads_daily`（brand=onno，零 schema 变更，同表唯一键幂等）；372 行与库内既有 ASIN 细粒度行重叠被导入器自动跳过防双计
- onno 30 天 Amazon 广告 KPI 修正+补账后 **$1,421.12**（双计修正基线 $93.38 + 补账 $1,327.74 分毫吻合）；onno 09-26 起仍无数据（CSV 止 09-25）
- **仍未解决**：① venus 广告采集日更（09-26 起）；② 双币双写根修（上述需求 3）；③ Noon 源采集（venus）未恢复（文件止 09-25）——pipe_stale 如实继续报警

**2026-09-29 夜三扩（用户问「onno UK 的 ROAS」挖出，此前 13 国对账只对了订单/GMV 列、漏了广告列；用户点破关键事实后修正）**：**onno 在 EU/UK 的货是 zipforce 账号在卖，EU 广告走 zf 的 Amazon Ads API 管道（`zf-ads` adapter，健康日更至 09-28）——数据一直在库**，行在 `public.ads_sku_daily` brand=**zipforce**、按 **ON\* SKU** 区分（UK 实测 8/1~9/25：£179.72 spend/£173.26 sales=ROAS 0.96，$227.52/$219.32；分 SKU G25 1.55 唯一过线、灯泡 0.75、ONQ2001/ONY2002/ON1020 纯曝光零转化）。**此前误判「EU 从未采集」根因=按 brand='onno' 查**：onno 专表 `amazon_ads_daily` 仅 AE/AU/SA/US（=FONCYE CSV 范围），EU 半边在 zf brand 行里。对账基准（Excel 后台 8/1~9/25）：AU $1,097.94 vs $1,152.31（差4.7%）、US $331.63 vs $327.51（差1.2%）✅；UK 本币 £179.72 vs £197.95（差 9%，两侧同为 GBP 非汇率）——**2026-09-29 深夜定案：真缺口，根因=卖家有第二个 Amazon Ads 账户在投 UK**（UK SP 报表 09-05 起断流同根因），zf-ads adapter 只授权了其一；**需求：卖家后台把第二个 Ads 账户授权进采集管道**（授权后 adapter 并入，历史 09-05 起按报表回补）；AE/SA 反向差——我方有账（$372.06/$559.13，含 FONCYE CSV 行）vs Excel 标「无广告」，FONCYE 导出自身含 AE/SA 行故 Excel 备注疑误待同伴确认。**真问题=品牌归属**：订单侧 EU onno 已正确标 brand=onno（source=zf_resell），广告侧 brand=账号（zipforce）——onno 视图因此看不到自己的 EU 广告；需在 SaaS 广告口径层按 SKU 前缀（ON\*）或 products 归属映射（关联 R6 ON\* 撞号）把 EU 广告归入 onno，**勿动 raw 的 brand 列**（账号事实）。R2-bis 的 EU 部分无需人工导出（zf Ads API 自动流已覆盖且活）

**2026-09-29 深夜再补（Noon 对账 Excel 挖出 noon_ads_daily「SP/sp 大小写孪生」双计，SaaS 清洗层当日修复）**：
- 采集器先以 `'SP'` 后以 `'sp'` 两种大小写写同一 (brand,country,report_date,campaign,sku) 的同一笔 Noon 广告账（onno 2~7 月并存；1,008 对中 1,005 对四指标逐位相同，3 对金额差共 19.37 SAR）——raw 表直接求和会把 2~7 月双计（AE 全期 21,474 AED vs 真值 11,422 / SA 21,612 vs 12,477，**虚增 1.87 倍**）；实锤=noon 后台导出 AE 11,460 / SA 12,760（残差=09-26 后文件尾巴，见 R2-bis）
- **已修（SaaS 清洗层，asin_twin_dedup 同族）**：`tools/audit_clean_all.py` + `api/clean_audit.py` 双文件同源增 `case_twin_dedup`——组内存在小写变体时大写行不入清洗层，差额行记 dirty_data_log；raw 只增不删；镜像已重建防旧规则回退；audit_nodes 2,436 节点/18 基准 ALL PASS，zf 侧 'product'/'sp' 零同键重合不受影响
- **采集侧根修（低优先）**：Noon 广告写入路径统一 ad_type 小写规范（现状 07-02 起已自然全小写、xlsx 导入器亦写小写，新孪生不再产生，清洗层规则为长期护栏）

**验收（SaaS 侧复验）**：
```sql
SELECT max(day) FROM public.amazon_ads_daily WHERE brand='onno';
-- 修复后 ≥ 当日-2（广告 API 本身有 1~2 天滞后）
SELECT count(*) FROM public.amazon_ads_daily WHERE brand='onno' AND day >= '2026-09-01';
-- 2026-09-29 已回补 375 行（campaign 级）；venus 恢复日更后 SKU 级行数应回到 ~20-24 行/天
SELECT count(*) FROM public.amazon_ads_daily
 WHERE brand='onno' AND coalesce(advertised_sku,'')<>'' AND day >= '2026-09-26';
-- venus 恢复后 > 0（当前 0）
```

## R3（P1）：fittingirls 广告 09-18 与 09-26 两日洞

**现象（实测 `public.ads_sku_daily`）**：

| day | fg 行数 | zf 行数（对照） |
|---|---|---|
| 09-16 ~ 09-17 | 537 / 526 | — |
| **09-18** | **0（整日无行）** | 17 ✓ |
| 09-19 ~ 09-20 | 516 / 540 | — |
| 09-22 ~ 09-25 | 534 / 538 / 531 / 542 | 16 / 14 / 11 / 11 |
| **09-26** | **0（整日无行）** | 11 ✓ |
| 09-27 | 553 ✓ | 11 ✓ |
| 09-28+ | 未到（广告 API 正常 1~2 天滞后，zf 同样未到） | 未到 |

zf 同源 09-18/09-26 均有数据 → 非 API 侧整日不可用，是 fg 管道漏跑两天。

**2026-09-29 用户文件取证（Archive.zip，57 份 FONCYE Campaign CSV：07-31 + 08-01~31 + 09-01~25）**：
- **09-18 有实据**：当日 CSV 报告 11 个活动 campaign×国家行、总花费 $78.98（其余金额见文件）——即漏跑当天广告实际在投，非「当日无广告」
- 该批 CSV 为 **campaign×country 粒度、无 SKU/ASIN 列**，与 `ads_sku_daily`（SKU 级）粒度不匹配，**SaaS 无法据此回补**；文件已留存（解包于 mars `/tmp/archive_0929/`，可提供采集侧作回补参照或核对口径）
- 07-31/08 全月/09 其余各日 CSV 与库内已有数据同粒度重复，无需处理

**需求**：单独回补 fg 2026-09-18 与 2026-09-26 两天广告报表。

**2026-09-29 进展（campaign 级半侧回补，用户拍板「在原有表上增量添加」）——⚠ 当日已整段回滚，归属误判**：
- ~~`ads_sku_daily` 扩 `campaign_name` 列 + 主键扩为 5 列，该批 57 份 CSV 全量 855 行（campaign 级， sku=''）常态增量入库~~
- **回滚原因（三重证据，用户质疑「foncye 哪来的 fittingirls」后实测）**：①同账号同日同国花费必须相等——08-15 fg US $46.61 vs CSV $1.00，112 个重叠组全不符；②fg 订单市场面无 SA/AE，CSV 却有 SA 285+AE 114 行；③活动名命中 zf 搜索词库 5/6、fg=0（ON\* 型号命名跨账号撞名）；④全库 FONCYE 字样 0 条。**FONCYE=独立卖家账号（Amazon US/AU/SA/AE）+noon 品牌（用户确认），非 fittingirls**
- **已执行回滚**：`DELETE FROM public.ads_sku_daily WHERE sku='' AND campaign_name<>'';`（855 行）+ 单表重清洗；fg 30 天广告花费精确复位 $2,067.04；audit_nodes 18 基准 ALL PASS
- 保留（账号无关）：campaign_name 列+5 列主键 schema、口径守卫代码（休眠态匹配 0 行）、导入器（`--brand` 改必填无默认）
- **R3 状态回到回补前**：fg 09-18 与 09-26 两日均缺，诉求恢复为采集侧重跑/回补这两天 SKU 级报表
- **2026-09-29 深夜归属定案**：七维对查证明 FONCYE=**onno** 的 Amazon 卖家账号（非独立新账号）——该批 CSV 已以 campaign 级 483 行入 onno 名下 `amazon_ads_daily`（见 R2 进展），归属问题关闭；fg 两洞与 FONCYE 无关，仍待采集侧回补

**验收（SaaS 侧复验）**：
```sql
SELECT day, count(*) FROM public.ads_sku_daily WHERE brand='fittingirls' AND day IN ('2026-09-18','2026-09-26') GROUP BY 1;
-- 09-18: 0（曾误入 campaign 级 15 行，2026-09-29 当日回滚）
-- 09-26: 0（待采集侧回补）
```

## R4（P1）：排名监控——昨日退化故障 + 欧洲采集范围过小

**现象（实测 `public.rankings_daily`，按各国最新快照日）**：

**(a) 2026-09-28 采集退化**（用户看到的「AU/DE 只有 1 个 ASIN」即此）：
- fg@AU：基线 9 ASIN/天，09-24/25/26 曾冲到 68~78，**09-28 塌缩到 1**
- fg@DE：基线 9~10 ASIN/天，**09-28 塌缩到 1**
- fg@UK / ES / FR / NL：**09-28 快照整日缺失**（最新停在 09-27）
- fg@IT/PL/BE/SE/IE 同日降至 2~4

**(b) 范围本就过小**（基线口径，非 09-28 异常）：
- fg 欧洲各国基线仅 **9~13 ASIN/市场**（DE 9 / FR 9 / UK 9 / ES 9 / NL 9 / IT 12 / BE 12 / PL 12 / SE 11 / IE 13），而 US=94、CA=208、EU 汇总池=104——欧洲分国采集清单疑似只配了一个子集
- onno 排名近乎停摆：**EU 快照停在 09-19（10 天前）**、SA 最新仅 1 ASIN、US 仅 2 ASIN

**(c) 2026-09-29 02:33Z 补充取证——zf 侧同日退化 + 采集清单疑似当日被改**：
- zf@amazon：**AE 27→2、SA 27→6**（09-28 单日塌缩，此前基线 27）；AU 停在 09-26（7 ASIN）
- 同日 zf **新市场行首现**：BR=9、MX=19（09-28 前无）——塌缩与新增同日发生，高度疑似 09-28 采集清单/域名配置被重写（旧清单被截断 + 挂上了新市场）
- 排名页市场 chip 当前显示值（=各市场各自最新快照计数，页面如实）：fg AU·1 / DE·1 / BE·3 / IE·4 / IT·3 / PL·3 / SE·2（09-28）、UK·9 / ES·9 / FR·9 / NL·9（停在 09-27）、US·94 / CA·208 / EU·104；zf AE·2 / SA·6（09-28）；onno EU·2（停 09-19）/ SA·1 / US·2
- 注：Keepa 排名任务每日 ~05:20 UTC 跑当日份，02:33Z 时最新快照=09-28 属正常节律，非额外断流

**(d) 2026-09-29 03:3xZ 三租户全量审计补充（用户令「每个账号每个品牌每个国家都看一下」）**：
- **fg 09-28 全市场 BSR 列空**：计数在榜的市场也全空——CA 208 行/US 94 行 rating 有值但 `bsr_big` 0 非空（09-27 及之前正常）→ 排名页 BSR 列全「—」、按 BSR 排序失效、90 天趋势断
- **brainnews（租户2 第二品牌）排名零数据**：整表无一行，从未采过——该品牌完全没有排名监控
- **onno 排名总量**：全表仅 18 行（3 市场×个位数），近 7 天快照日仅 4 天（隔日节律）
- **zf@noon 排名节律**：AE/SA 近 7 天仅 4 个快照日（隔日）——请确认 noon 排名是否应日更（当前隔日）
- 全量矩阵（各市场最新快照/停更天数/在榜 vs 前7日均/30天在库 ASIN/BSR 真实度）已按品牌×平台×市场逐格核过，除上述外无新异常

**需求**：
1. 排查 09-28 排名采集运行（清单截断/部分市场失败），恢复 + 回补当日；**重点核查 09-28 当日采集清单/域名配置是否被改动**（zf AE/SA 塌缩与 BR/MX 新增同日）；**核查 fg 09-28 BSR 字段为何全空**（计数正常但 BSR 缺=抓取字段级失败）
2. fg 欧洲分国采集清单扩到与 EU 池（104 ASIN）对齐，至少覆盖在售 ASIN 全集
3. onno 排名监控恢复日更并明确 ASIN 清单（当前 SA=1 / US=2 无法使用）；**brainnews 品牌补建排名监控清单**（当前零数据）
4. 明确 zf@noon 排名目标节律（当前隔日，若应日更请调整）

**验收（SaaS 侧复验）**：
```sql
SELECT market, snap_date, count(*) FROM public.rankings_daily r
WHERE brand='fittingirls' AND snap_date >= (SELECT max(snap_date) FROM public.rankings_daily)-1
GROUP BY 1,2 ORDER BY 1;
-- ① AU/DE ≥ 9（恢复基线）且逐日不再塌缩；② UK/ES/FR/NL 快照不再整日缺失
SELECT market, snap_date, count(*) FROM public.rankings_daily WHERE brand='zipforce' AND snap_date >= '2026-09-27'
GROUP BY 1,2 ORDER BY 1,2;
-- AE/SA 恢复到 ~27 量级（或确认新清单口径并同步 SaaS）
SELECT market, max(snap_date), count(DISTINCT asin) FROM public.rankings_daily WHERE brand='onno' GROUP BY 1;
-- onno 各市场 max(snap_date) ≥ 当日-1，ASIN 数与在售清单一致
```

## R5（P1）：库存日均销量取数——fg 覆盖率 5.0%；onno 库存仅 10 行

**现象（实测 `public.inventory_health`，快照 09-28）**：

| 品牌 | 行数 | 有 daily_sales | 覆盖率 |
|---|---|---|---|
| fittingirls | 8,809 | 442 | **5.0%** |
| zipforce | 139 | 139 | 100% |
| onno | **10**（UK 5 + EU 5） | 10 | 100%（但样本近乎为零） |

- fg 分市场看：US 990 行仅 39 有销速、CA 990 行 47、MX 990 行 4、欧洲各 610 行 1~68
- onno 在售 SKU 远多于 10 个（订单表大量 SKU），**库存快照采集范围本身不足**

**2026-09-29 晚深挖定案：fg 5.0% 不是采集缺失，是真实业务长尾**（mercury 逐市场取证）：
- `daily_sales` 是**派生字段**＝该市场该 SKU 近 30 天 Shipped 订单行件数 ÷30（sync_mercury `_FG_INV` 的 v 子查询）——没卖过就是 NULL，如实而非缺数
- **管道零丢失证明**：mercury 各市场 30 天动销 SKU 数与本地 daily_sales 覆盖**逐市场完全一致**（US 39=39、CA 47=47、AU 102=102、ES 67=67、IT 55、FR 48、DE 24、UK 15、SE 19、BE 20、PL 1、MX 4、IE 0=0）；订单明细关联覆盖 1300/1322=98.3%
- **覆盖率低的算术分解**：① **72%（6,310/8,809）行零库存**（US 84% / CA 88% / MX 85% / EU ~65% / AU 42%）——断货 listing 不可能有销速，是库存事实；② 有库存组合（2,499）中 30 天动销 441 = **17.6%**，正常长尾分布（AU 50%、ES 32%、US 25%、UK 7%）
- 页面语义成立：补货预警「无动销」桶对 fg 就是**真无动销**（非缺数）
- **真缺陷仅两处（新发现，量小）**：NL 18 条 / IE 2 条订单明细 `sku` 全为空 → 这两个市场销速恒缺；及 onno 库存快照范围不足

**需求（改写后）**：
1. fg：仅修 NL/IE 订单明细 `sku` 列为空（30 天约 20 行）——其余市场销速已如实；如需更准的"有库存行"销速，可由源头接 Amazon FBA 报告自带的 sales rate / days of supply 字段（SaaS 现按订单回算已是通行做法）
2. onno 库存快照扩到全部在售 SKU/市场（当前仅 UK+EU 共 10 行）——不变

**验收（SaaS 侧复验，改写后）**：
```sql
-- ① NL/IE 明细 sku 补齐(mercury)：两市场 sold_skus 不再恒为 0
-- ② onno 行数与其在售 SKU 数同量级
-- ③ fg 覆盖率不设百分比目标(5.0% 是真实业务值)；管道健康度口径改为
--    mercury 各市场动销 SKU 数 == 本地 inventory_health 该市场 with_ds 数(逐市场一致)
```

## R6（P2 主数据素材）：products 归属纠偏 + sku_mapping 维护欠账

**现象（实测 `public.products` / `public.sku_mapping`）**：

**(a) products 表混入 ON\* SKU（违反品牌隔离铁律）**：
- zipforce 名下存在 5 行 ON 前缀 SKU：`ON1020SEU / ONY2002EU / ON3720SEU / ONQ2001EU / ONG25X0EU`（title=SKU 本身，无产品名）
- onno 全部 14 个 SKU 均为 ON 前缀——**ON\* 命名约定归属 onno**，其中 ON3720SEU / ON1020SEU / ONG25X0EU 与 onno 名下 SKU 直接撞号，跨租户数据有串号风险

**(b) sku_mapping 维护欠账**：
- **country 空**：zipforce@Noon 106 行中 **14 行 country 为空**
- **country 混用 UK/GB**：fittingirls Amazon 行 country 同时存在 `GB`(10 行) 与 `UK`(2 行)——订单数据用 GB、库存源用 UK，映射表两边都沾，靠 SaaS 端归一化兜底不是长久之计
- **命名错位**：zf/onno 两侧 `product_name` 与 `model_name` 普遍填同一值（如 pn=mn="Wifi Light Bulb Camera"，型号信息只在 model_number），产品名/型号名两列语义未分开；zf 侧另有 2 行旧式乱码 fulfillment SKU（`C6-U3IY-LOUU`、`RY-3CYY-VNH9`）与新式 `ZF230T0AEB` 并存

**需求**：
1. `products`：5 行 ON\* SKU 归属改到 onno（撞号行合并，保留 onno 侧规范行）——**涉及归属拍板，需业务确认后执行**
2. `sku_mapping`：补齐 zf@Noon 14 行 country；fg country 统一为 GB（与订单侧一致）；pn/mn 语义拆分（pn=产品名、mn=型号名）；乱码 SKU 与规范 SKU 建立映射或清理

**验收（SaaS 侧复验）**：
```sql
SELECT count(*) FROM public.products WHERE brand='zipforce' AND sku LIKE 'ON%';  -- = 0
SELECT count(*) FROM public.sku_mapping WHERE brand='zipforce' AND platform='Noon' AND coalesce(country,'')='';  -- = 0
SELECT count(*) FROM public.sku_mapping WHERE brand='fittingirls' AND country IN ('UK','GB');  -- 全部为 GB
```

---

## SaaS 侧已做的呈现兜底（无需采集侧配合，仅说明现状）
- 补货预警：无销速行 35/90 天线与缺口显「—」不显 0；紧急桶合计 shortage 为 NULL 时整体显「—」（2026-09-28 修复）
- 订单/广告/排名页：数据源止于哪天在页面脚注标明；空筛选显式「—」
- fg 广告 09-26 缺口期间：KPI 广告花费按现有天数合计，页面脚注注明数据止于

## 修复后联动（无需 SaaS 发版）
采集侧回补生效后：SaaS 增量/全量同步任务自动带回（订单 2h 增量、广告/排名/库存日快照），清洗层（audit.cleaned_\*）与 API/Web 自动跟进。R6 主数据修正涉及 SaaS 库 `public.products` / `public.sku_mapping` 两表——若由 SaaS 会话代执行，需用户放行后按上表验收。

---

## R7（2026-09-29 追加）采购成本表两条孤儿品名（dashboard_audit 持续 WARN）

`zipforce_noon.zipforce_noon_procurement_cost`（SaaS 侧镜像 `public.noon_procurement_cost`）存在两条成本行，
其 product_name 在全部 SKU 体系（Amazon sku_mapping / noon 源 sku_mapping / noon 销售表）中均无对应 SKU：

| product_name | cost_rmb | 状态 |
|---|---|---|
| Keyboard | 35.00 | ZFKB* 前缀的 SKU 实为 Cyber Line/G502/CX22，不叫 Keyboard |
| S-988 Pro | 175.00 | 全库无任何 988 线索 |

**需要采购/运营侧确认**：这两条成本行对应哪批真实 SKU（或是否为计划中产品/一次性采购）。
确认后 SaaS 侧补 `public.sku_mapping` 行即可消警（Water Bottle/Bento/iPhone Case 三条同类欠账已按镜像值回填权威表，2026-09-29）。

---

## R8（2026-09-29 追加）Dell BA 反向隧道断线 3 天——大词库三条管道静默冻结

**现象**：mercury `127.0.0.1:15432`（Dell 侧反向隧道端点，`dell-tunnel` 用户 authorized_keys
`permitlisten="localhost:15432"`）无监听。Dell 服务器上的 4972 万行 `ba_search_terms` 大词库
对 SaaS 完全不可达。

**影响面（三条管道全部冻结，全部静默降级无报错）**：
- aba-refresh 日更（mars cron 04:10）：09-26 04:15 最后一次成功，之后连续 `Connection refused`；
  本地快照 `aba_search_terms` 159 万行停留在 Dell 09-02 月度采集数据
- sourcing 实时兜底 `_dell_live_term()`：`except → [], False` 优雅降级，词不在本地快照时静默查不到
- 机会雷达（aba_radar_*，决策台 9352 候选证据管线）：随日更冻结，止 09-26

**取证**：`backups/aba-refresh.log`（09-26 04:15 成功→之后连续 refused）、
`backups/aba-catchup.log`（117 条连续「隧道未通」，09-27 03:07 起逐 30 分钟记录）、
mercury 无 autossh/systemd/cron 隧道维持机制（隧道为 Dell 侧主动 `-R` 连入）。

**修复归属：Dell 侧运维**——需 Dell 服务器上重启反向隧道进程（`ssh -R 15432:…` 连 mercury
dell-tunnel 用户）。mars/mercury 侧无可修对象。

**自愈与告警**：
- 隧道恢复后 `aba-catchup.sh`（每 30 分钟探活+快照>20h 即追赶）自动补齐，无需人工干预
- heartbeat 已加第⑦项检查（2026-09-29）：隧道断即入异常集合发邮件，不再静默

**验收 SQL**：`ssh 222 'pg_isready -h 127.0.0.1 -p 15432'` 返回 accepting connections，
且次日 04:10 aba-refresh.log 出现「快照刷新完成」。

### R2-bis（2026-09-29 晚追加）：全域断更三条断口定案——唯一补数路径=卖家后台人工导出

四层审计「全域断更」FAIL 的三个断口（onno/amazon_ads_daily 断4天 + onno/noon_ads_daily 断4天 +
zipforce/noon_ads_daily 断29天）经全链路取证为**同一根因**：三条管道均无 API（拓扑 2026-09-10 拍板：
onno 无 Amazon Ads API→人工 CSV 投递制；zf/onno 的 Noon 广告=预留手动），唯一数据源是卖家后台导出文件。
站内（mars/mercury/venus 全查）最晚文件 08-28（mercury /root/noon-data/exports/ads，09-06 有人批量导过一次）
与 09-25（用户提供的 FONCYE CSV 与 noon xlsx）——**基础设施侧无可补之货**，SaaS 侧通道全部健康
（02~05 点同步 cron + /ads 页「广告数据上传」tab + dropbox 投递 + 每分钟 ads_import 泵，缺的只是文件本身）。

**待用户导出（唯一行动清单）**：
| 断口 | 后台 | 需导文件 | 上传方式 |
|---|---|---|---|
| onno Amazon 广告 09-26~今 | Amazon 广告后台（FONCYE 账号） | 报表 CSV（同 09-29 那批 57 份格式）打包 zip | /ads 上传 tab（onno+amazon）或投 dropbox/onno-ads/onno_amazon.zip |
| onno Noon 广告 09-26~今 | noon 卖家后台 | `_OVERVIEW_ALL_Report_日_日.xlsx` 单日单国 × AE/SA | /ads 上传 tab（onno+noon，选国家） |
| zf Noon 广告 09-01~今（29 天） | noon 卖家后台 | 同上 × AE/SA ≈58 文件（适配器拒收区间聚合文件，必须单日导出） | /ads 上传 tab（zipforce+noon，选国家） |

文件到手后 2 小时内全链路自动出数（适配器→源表→定向同步→清洗→页面），audit 全域断更自动转绿。
**若某品牌广告实际已停投**：告知即按真实停投处理（显式停投标注/零行），不再等导出。

### R10（2026-09-29 深夜追加，P1）：采集器抓单不回刷——Pending 期 0 金额单沉淀为永久空值

**现象（2026-09-29 MCP 对账事件挖出）**：
- venus 采集器在订单 **Pending 期**即抓单入库，此时 SP-API 返回 `order_total_amount=0`（或空）；
- 订单后续 Shipped 后**从不回刷**（getOrder 重拉实单）——实测 onno EU 8 月 **189 单** order_total=0、
  zf 亦有同批（07-25 窗内 20+ 单），深尾单连 order_items 金额都是 NULL（16 zf + 4 onno 四层全空）
- SaaS 侧影响已由本方兜底修复（2026-09-29）：同步链加第三级 items 兜底 + 一次性重同步 07-25 起 +
  增量窗口 3→10 天；修复后 12 国营收 vs 卖家后台全在 97~110%（GB $2,502/$2,546、US $1,781/$1,799）

**需求（采集栈——2026-09-29 cutover 后全部跑在 mars worker 容器 `/collection/run.py`，已无 venus/mercury 数据库）**：
1. 采集器对 Pending 抓到的订单，在订单转 Shipped 后回刷金额（定时重拉 getOrder 按 amazon_order_id UPSERT）——
   根治新增 0 金额单（SaaS 兜底能接 items 有值的，接不了 items 也空的深尾单）
2. 历史沉淀：源端 order_total_amount=0 的 Shipped 单（onno 8 月 189 + zf 同批）如可批量重拉最好；
   不重拉也不阻塞——SaaS 已按 order_items 实价合计兜底

**验收（SaaS 侧复验）**：
```sql
-- venus 修复后新订单不再产生 0 金额沉淀:
SELECT count(*) FROM zipforce_amazon.zipforce_amazon_spapi_orders
WHERE order_status='Shipped' AND coalesce(order_total_amount,0)=0
  AND purchase_date >= '2026-10-01';   -- 修复生效后趋近 0
```

**进展（2026-09-29 当日已修——用户拍板「直接改采集代码修掉」，本单就此关闭，见下）**：
- **修复内容（三品牌适配器，mars worker 容器 `/collection/adapters/`）**：
  1. `status_refresh` 扩「金额支路」：非取消且 `coalesce(order_total,0)=0` 的单按 `AMOUNT_REFRESH_DAYS=120` 天窗回刷（zf/fg 原回刷名单只盯 Pending/Unshipped/PartiallyShipped，永不含已 Shipped 的零额沉淀单——本 bug 直接根因）
  2. onno 此前**完全没有** status_refresh 且忽略 `--status-only`（=每 30 分钟白跑一次全量月窗拉单），已整段移植补齐；fg 的 main() 同样漏成全量，已一并修
  3. 深尾兜底：回刷后仍无金额且库内 items 无实价的单，自动重拉 `getOrderItems` 覆写 items（订单级 getOrders 不回 OrderTotal 时 items 级常有实价）；Amazon 连 items 级也无价则不动库、下轮再试（单滑出 120 天窗自然停）
- **手动回刷结果**：首轮回刷 zf 662 / fg 103 / onno 78 行；复跑收敛值 zf 147 / fg 101 / onno 73 行（=剩余零额单，Amazon 侧反复重查仍回 0）
- **终态核验（活库实测 + 抽样直打 SP-API 原始接口）**：剩余零额中「订单级+items 级都无价」的死单 = **zf 38**（SA22+AE15+GB1）+ **onno 9**（AU7+AE1+SA1）+ **fg 26**（6~9 月 Shipped；fg 另有 9 月 50 单 Pending 属正常生命周期，发运后自动回价）。抽样实锤 Amazon orderItems 对死单**不返回 ItemPrice 字段**（zf SA 样本 S02-9318976-6369111 连 OrderItemId 都是 "0"、Title="-"）——SP-API 侧无解，SaaS 维持「—」诚实呈现；其余零额单或有 items 实价（SaaS 同步链三级兜底覆盖）、或为 Pending 生命周期内
- **SaaS 侧**：07-25+ 宽窗重同步 4542 行（含 items 兜底）+ 清洗层刷新 + audit_nodes ALL PASS；残留 Shipped 零额 38 单（zf AE12+SA12 / fg AU9+US1 / onno AU4，07-25+ 窗）与源表死单集一一对应
- 上述 10-01 起的验收 SQL 自 2026-10 月起按月巡检（新沉淀应趋 0）

### R9（2026-09-29 晚追加，P2）：onno Noon 官方对账单从未生成——源表零行

**现象（09-29 实测）**：
- 源表 `onno_noon.onno_noon_statement_official`：**0 行**（结构在、从未写入）
- SaaS `public.noon_statement`：`brand='onno'` **0 行**；对照 `brand='zipforce'` 42 行到 2026-09（官方到 07 + 09-27 派生尾到当月，机制健康）
- 财务流水源 `onno_noon_finance_transactions`：1,325 行，2026-02-23 ~ **2026-09-23**（活跃）——派生原料齐备，仅缺官方行作余额锚点

**根因**：与 zf 侧「statement_official mercury 翻遍无 writer」同根（采集器对账单接口硬跳），但 zf 好歹有 2~7 月官方存量，onno 一行都没有——采集侧从未为 onno 跑通过对账单导出。

**需求（采集侧）**：从 noon 卖家后台导出 onno（AE/SA）官方对账单（Statement/Payment），有历史最好全量、最少要近 3 个月——落 `onno_noon_statement_official` 后 SaaS 派生尾机制自动续到当月。

**SaaS 侧待拍板**：是否在无官方锚点时按 opening_balance=0 起推派生尾（zf 的派生链锚在官方期末余额上，onno 没有）——口径取舍需用户拍板，未拍板前 finance 页 onno 对账单块如实空。

**验收 SQL**：
```sql
SELECT count(*) FROM onno_noon.onno_noon_statement_official;          -- > 0
SELECT max(stmt_month) FROM public.noon_statement WHERE brand='onno'; -- ≥ 2026-09（派生）

---

## R11（2026-09-29 追加，P0）：onno 订单费用（order_fees）采集断流——08-24 周起退化、09-07 周起归零

**现象（dashboard_audit「费用覆盖」门 2026-09-29 首次报警，成熟周=≥35 天且 ≥20 单，覆盖率须 ≥90%）**：
- onno 08-24 周 FAIL：104 单中仅 55 单有 onno 名下费用行（覆盖率 53%）
- 周度退化轨迹：08-24 周 55/104 → 09-07 周 onno 名下费用行 **0**（此后全零）
- **~263 单完全没有费用行**（利润/费用/利润率口径失真，费用覆盖门将持续报警直到回补）

**分国取证（08-24 周起累计，onno 单的费用行挂在哪个品牌名下）**：
| 市场 | onno 名下 | zipforce 名下 | 双品牌各一行 | 无任何费用 |
|---|---|---|---|---|
| ES | 11 | 20 | 1 | 2 |
| FR | 8 | 26 | 5 | 3 |
| GB | 8 | 10 | 3 | 2 |
| IT | 6 | 13 | 10 | 0 |
| NL | 2 | 11 | 1 | 2 |
| SE | 2 | 2 | 1 | 2 |
| BE | 0 | 3 | 0 | 0 |
| PL | 0 | 1 | 0 | 0 |
| AU | 0 | 130 | 0 | 0 |
| SA | 0 | 66 | 0 | 0 |
| AE | 0 | 29 | 0 | 0 |
| US | 0 | 27 | 0 | 0 |

**两个问题（同族不同层）**：
1. **采集断流（本单主诉求）**：onno 名下费用写入自 08-24 退化、09-07 起死——与 R1/R2 的 venus onno 管道停摆同窗，疑同一根因的不同表现面；AU/SA/AE/US 四市场零费用（连 zipforce 名下也没有）说明 FONCYE 账号的 settlement 报表拉取也停了
2. **EU 费用归属（拍板项，非采集侧）**：EU onno 货走 zipforce 卖家账号（广告侧归属翻案同族，已由 SaaS 清洗层 brand_fix 解决），费用侧同样有 zipforce 名下的 EU 费用行——**是否按 ON\* SKU 把 zipforce 名下 EU 费用行归入 onno、双品牌各一行的单按哪条去重，属口径取舍，需用户拍板后 SaaS 清洗层执行**（方案与广告 onno_country_dedup 同族）

**进展（2026-09-29 深夜，用户拍板「归入」——归属半侧当日落地，本项关闭；采集断流主诉求仍开放）**：
- **取证定案（形态交叉）**：zf 名下×onno 订单的费用行共 224 行分两形态——**87 行新形态**（local_\* 有值=sync 09-20 修复后 fx 已折算，EUR74/GBP10/SEK2/PLN1，08-08~09-20 仍在写，全部无 onno 孪生）→ 归入即得；**137 行旧坏形态**（local 全 0、本币值占 USD 列=09-20 修复前双写孪生，EUR113/GBP17/SEK7，08-07~08-29，137/137 都有正确 onno 行）→ 整行剔除交 dirty_data_log，分毫不再需要 fx 重构
- **清洗层落地（tools/audit_clean_all.py + api/clean_audit.py 双文件同源，镜像重建烧入）**：①`fees_brand_fix`——zf 行挂 onno 订单：local 有值→brand 改判 onno（87 行）；local 全 0 且已有 onno 费用行→`fees_stale_twin` 整行不入层（137 行）；无孪生的保留标 `fee_local_missing` 不静默丢钱（当前 0 行）；②连带修 **订单侧 7 单 ON\* 漏挂**（GB、Shipped、08-15~08-30，$181.22）：amazon_orders 加 `brand_fix: sku_list`（sku_mapping 精确命中才改，多 SKU 逗号列表不命中=不动；raw 不动——sync upsert 按源 brand 回插，改 raw 必产生孪生）；③孤儿校验移位到品牌纠正之后+order_keys 用归属后口径（否则归 onno 的行按 raw 旧品牌判孤儿会误标，6 条反向行 orphan 误标同根出清）
- **效果**：onno 费用 KPI（Amazon 视图 30 天，API 同口径 SQL）**$23.63 → $604.21**（80 单有费用）；利润/利润率转诚实（费用缺席期利润原虚高）；zf 侧 KPI 零变化（这些费用行此前 join 不到任何品牌=两头都没算，非 zf 转出）
- **费用覆盖门（dashboard_audit）仍 FAIL=设计内**：门读 raw order_fees（f.brand=o.brand），清洗层归属不动 raw——真缺口（08-24 起断流 + AU/SA/AE/US 零费用）回补前门持续报警，验收 SQL 不变

**需求**：
1. 排查 onno order_fees 采集任务（与 R1/R2 是否同一停摆），恢复日更
2. 回补 2026-08-24 起全部缺失费用（按 amazon_order_id UPSERT）
3. AU/SA/AE/US（FONCYE 账号）settlement 报表拉取恢复 + 回补

**✅ 采集断流当日根治（2026-09-29 深夜，本项主体关闭）**：
- **根因①（每日崩溃）**：`onno_finances.py` 的 `normalize_finance_market` 重贴标 UPDATE 撞唯一键 `onno_finances_uniq(order,sku,posted,type,marketplace)`——1 行 SA/GB 双标签同键行（id 9974507，404-5877980-2597101/ONY2002SA/08-17）使每日 03:20 UTC 的 cron 崩死在 8 月该步，9 月永不同步。修=UPDATE 加 NOT EXISTS 守卫（撞键行保持代表市场标签，绝不阻塞月度推进）；肇事重复行按 `_deduprows_..._20260929` 惯例移档归档（可逆）。备份 `.bak-r11-normalize-20260929`
- **根因②（费用聚合 NULL 毒）**：FONCYE 表 283/283 Shipment 行 fba 四组件列含 NULL → SaaS 同步 `_FEES_ZF_BRANCH` 的 `SUM(a)+SUM(b)+SUM(c)+SUM(d)` 任一 NULL 毒整个 fba=0——「佣金有值、FBA 恒 0」的根因；zf/EU 表（zipforce_amazon_spapi_finances）四列全填 **0/12,812 行中招=zf 与 EU 数字不受扰**。修=按同文件 FG 分支既有 COALESCE 模式包齐 fba/other 全链（api/sync_mercury.py），api+worker 镜像重建烧入
- **回补+同步**：8+9 月 FONCYE finances 重拉 363 事件行（US 47/GB 68/AU 94…，raw max 09-22=适配器安全窗 now−7d 上限）；SaaS order_fees 35,598 行重同步+清洗层换新 ×2（第二次为去重后修正）
- **效果（peer 对账窗 08-01~09-25）**：费用覆盖 447/701→**601/701 (85.8%)**；佣金 $484→**$659**（vs Excel 76%）；FBA $1,916→**$3,084**（vs Excel 79%，AU $678/161 单）；onno 30 天费用 KPI **$604.21→$1,150.48**（80→170 单）；**费用覆盖门转绿（dashboard_audit FAIL 0）**；剩余差额=09-14 周起结算滞后单（12/73、0/42 未到）+09-22 后尾巴——每日 03:20 UTC cron 现已畅通按日滑窗自愈，无需人工。**滞后口径拆解（2026-09-30 改写，原「~2 周」表述混两层）**：①Amazon Finances API 自身贴出滞后 p50 **7~9 天**（两账号 12 国成熟 8 月数据实测：FONCYE AE 7.3/AU 7.6/SA 7.5/US 12.1、zf EU GB 7.8/FR 9.1/ES 9.4，尾部最长 23 天）——费用经济上 Shipped 即定但 API 只在贴出后暴露，卖家后台读内部系统故更早，此层 Amazon 侧不可修；②onno 适配器当月窗 PostedBefore 原 `now−7d` 在其上再叠 7 天——**2026-09-30 已修**（对齐 zf/fg 的 `now−5min`，备份 `.bak-r11b-window-20260930`）：重跑落 284 行、raw posted max 09-22→09-29、09-22~29 新落 78 条带费 Shipment 行、SaaS 重摄取 35,664 行（+66）；peer 窗覆盖 571/694=82.3%、30 天费用 KPI $1,150→$1,757、覆盖脚注 52%→72%（周度轨迹 71/95→5/49→0/12 即 Amazon 滞后自愈节律）
- 教训：①子进程采集器 rc≠0 无人告警=断流一个月才被覆盖门抓住——collection_cycle_sales 的 rc 已在返回值里，告警面待接（次优先）；②`SUM(x)+SUM(y)` 链式相加是 NULL 放大器，跨源模板复制时 FG 分支的 COALESCE 模式才是正确范本

**验收（SaaS 侧复验）**：
```sql
-- 成熟周(≥35天,≥20单) onno 费用覆盖率回到 ≥90%（dashboard_audit 费用覆盖门转绿）
SELECT to_char(date_trunc('week', o.purchase_date),'MM-DD') wk, count(*) n,
       round(100.0*count(*) FILTER (WHERE EXISTS (SELECT 1 FROM order_fees f
         WHERE f.brand=o.brand AND f.amazon_order_id=o.amazon_order_id))/count(*),0) cov
FROM amazon_orders o
WHERE o.brand='onno' AND o.purchase_date >= '2026-08-24'
  AND o.purchase_date < (now() AT TIME ZONE 'Asia/Shanghai')::date-35
  AND o.order_status NOT IN ('Canceled','Cancelled')
GROUP BY date_trunc('week', o.purchase_date) HAVING count(*) >= 20 ORDER BY 1;
```

## R12（2026-09-30 立案，P1）：onno Noon 订单 SaaS 摄取历史欠账——2~5 月 + 6 月上旬 ~515 单从未入 SaaS

- **事实**：mars raw `onno_noon.onno_noon_orders` 02~09 月全量在库（去重 34/148/102/164/202/159/134/66=1009 单含取消）；SaaS `public.noon_orders` brand='onno' 仅从 **06-12** 起（135/159/134/66）。缺 2~5 月 448 单 + 6 月上旬 ~67 单 ≈ **515 单**；财务流水佐证 2~5 月净额本币 31,883（≈$8.2k）。
- **影响**：SaaS 门户/dashboard/mars-db MCP 的 noon 全窗口径；review.onnotek.com 已用 mars raw 直读绕开（页面脚注①「至 06-12」）。
- **修法**：ingest 一次性回补 mars→SaaS（纯增量、低风险）。
- **✅ 2026-09-30 已执行闭案**（用户拍板）：根因=`_NOON_ORDERS_BRANCH` 92 天滚动窗，首同步 09-11 → 起点 06-12。去窗全史 UPSERT **85,323 行**（onno 1,124 + zf 级联 84,199——zf 同 spec 同窗 2024-01 起全缺，一并回补）；onno 逐月 34/148/102/164/202/159/134/66 与 mars 分毫一致；cleaned=public 逐位；audit_nodes ALL PASS、dashboard_audit FAIL 0；onno-10 已换脚注①上线。脚本 tools/backfill_noon_orders_full.py（进程内去窗，热路径 spec 未动）；回滚 SQL 见脚本头注释。

## R13（2026-09-30 立案，P1）：Noon 财务流水两品牌同停 09-23——**已闭案（2026-10-01 02:33 UTC 终验通过：破案结论成立，非断流）**

- **事实**：`collection_noon_deep` 每 6h 正常执行（02:13 有运行痕迹、子进程 `noon-zf-inc`/`noon-onno-inc` 均打印统计表），但 `zipforce_noon_finance_transactions`（56,798 行）与 `onno_noon_finance_transactions`（1,054/1,325 行）max(order_date) **两品牌同停 2026-09-23**，09-24 起 0 新行。zf noon 流水历史 ~60 行/天，7 天双品牌同停非自然静默。
- **破案（2026-09-30 上午）**：按 transaction_date 聚合实锤 **noon 财务为每周三批量贴出**（08-19/08-26/09-02/09-09/09-16/09-23 各 319~862 行、间隔整 7 天全周三；另有月末加批 08-31 周一 509 行；批间仅 1~3 行零星）。「~60 行/天」是批均摊错觉。手动宽窗验证（--from 2026-09-18 --finance-only）：导出成功 698 行、全部 UPSERT 命中既有行（表计数不变）——**noon 源头 09-24 后该导出里就是没有新流水**，采集器零丢失。09-23 批贴出 09-23 订单 → 下一批 09-30（周三）贴出，当日尚未落库属预期。
- **连带加固（已执行）**：deep 财务窗 days=5→**8**（`tasks.py collection_noon_deep`；周三批含 order_date 前溯 7 天的行，5 天窗每周切掉批头 2~3 天、只靠周日 days=30 兜底）；快照 `/opt/backups/code-20260930-r13/tasks.py`，镜像已 build api worker + force-recreate worker。
- **贴批时刻实证（09-30 12:40 UTC 补）**：worker.log 考古——09-23 批（+563 行）在 **09-24 02:06 UTC** 才被 01:53 deep 首次拉到（09-23 当晚 19:53 拉取仍无）。即 noon「周三批」实为周三深夜贴出、周四凌晨深同步才可见；当日 13:53/19:53 轮大概率仍空属预期。09-30 11:3x UTC 双品牌探针（--from 09-24 --finance-only）API 正常但仅 3+1 行零星，今日批尚未贴。
- **终验通过（2026-10-01 02:33~02:41 UTC，会话一次性 cron adfdd3fa 执行）**：01:53 deep 收尾后 mars 实测 `zipforce_noon_finance_transactions` max(order_date)=**2026-09-30**（69,526 行）、`onno_noon_finance_transactions` max=**2026-09-29**（1,345 行），双品牌均 ≥09-29 达标——09-30 周三批已于 10-01 凌晨贴出并被深同步拉到，与破案推演（周三深夜贴出、周四 01:53 deep 可见）完全吻合。随后双品牌增量复验（noon-zf-inc / noon-onno-inc --from 09-25 --finance-only --once）：Auth OK、报表创建下载正常、zf 643 行 / onno 20 行 UPSERT 全幂等命中（表计数不变），**增量管道本体健康，非仅深同步一次性拉取**。days=8 加固窗按设计覆盖周三批前溯 7 天。遗留观察（导出 0 行无告警面）仍开放，归入管道告警统一方案。
- **遗留观察**：采集器 rc=0 且「导出 0 行」无告警面的问题仍在（本次靠窗口节奏解释；若未来真断流仍会静默 7 天）——与 R11 教训①同型，建议纳入管道告警统一方案。

## R14（2026-09-30 立案，P2）：zf Amazon 订单 NL/IT 两市场同停 09-23——**已结案（2026-09-30：实锤源头真无单，采集零缺失）**

- **事实**：mars `zipforce_amazon_spapi_orders` 分国 max(bj_date)：主力市场全部健康（AE/SA/GB/FR 09-30，SE/BE/US 09-29），但 **NL 与 IT 同停 2026-09-23**（09-24 起 0 行）；IT 近 30 天 18 单（~0.6/天）、NL 同量级——两低量市场同时 7 天零单，自然归零联合概率 <0.1%，且与 R4「采集清单 09-28 被重写」嫌疑同嗅。PL 09-04/DE 08-02/JP 2025-12 为更早历史停更（低量市场，暂列观察）。
- **结案证据（2026-09-30 定向重拉）**：①市场清单未收窄（zf_amazon.py MARKETS 含 IT/NL，09-24 只扩未缩）；②EU token `sellers/v1/marketplaceParticipations` 实测 IT(APJ6JRA9NG5V4)/NL(A1805IZSGTT6HS) 均 participating=True、hasSuspendedListings=False；③直接 getOrders（CreatedAfter=09-01、CreatedBefore=now-5min，与适配器同参）实测：**IT 九月 34 单、最晚 2026-09-23T06:53Z，库内九月 34 行分毫吻合；NL API 13 单、库内 15 行（库为超集，含 2 笔源头已移除的取消单）、最晚 09-23T07:50Z**——Amazon 侧 09-23 后 IT/NL 就没有新订单，采集器持有源头全部。「联合概率 <0.1%」的独立泊松假设不成立：低量市场一周零单是业务事件（疑似 FBA 断货/广告停投/listing 转化停止，业务侧自查），非管道故障。R4「采集清单被重写」嫌疑与本案件无关。
- **探针陷阱（重要，记入方法论）**：getOrders 的 **CreatedBefore 传未来时间 → SP-API 静默返回 200+空 Orders**（不报 400）。本次第一轮探针 0 单由此误判，二分后识破。适配器用 now-5min 无此问题；任何人做 SP-API 对账探针务必 CreatedBefore ≤ now。
- **验收**：满足「实锤源头无单」分支。审计基线无需标注缺口（数据=源头真值）。

---

## R15（2026-09-30 立案，P1）：清洗层 USD 折算固定常数 → 逐日汇率日表——**已执行（2026-09-30）**

- **事实（现状）**：SaaS 摄取链折 USD 用**写死常数**：AUD 0.6452（市场 ~0.699，**低 7.7%**）、EUR 1.0869（低 ~5%）、SEK 0.0952（低 ~10%）、PLN 0.2564；AED/SAR/USD 锚定货币无恙。原币列（local_amount 等）干净无恙——**问题只在 USD 折算列**，本币口径不受任何影响。
- **方案（若执行）**：摄取链 `fx()` 改查自家 `saas.public.fx_rates` **逐日日表**（worker 06:05 每日刷新，exchangerate-api 源）；缺日回退最近一日（前向填充），再缺回退现常数并记 `dirty_data_log` 兜底不静默。**不用** peer 的 frankfurter 源（口径源须单一自有）。
- **影响面（最大爆炸半径）**：全部 EUR/AUD/SEK/PLN 区**历史 USD 数字整体上移 ~3.3%**（区间 +5%~+10%）。具体消费面：`cleaned_amazon_orders.revenue_usd`/net/费用列、`sales_daily`/`sales_hourly` revenue、`ads_sku_daily` spend/sales USD 列、`finance_monthly`、工作台 KPI/趋势/矩阵、mars-db MCP 4 工具（09-30 刚迁清洗层，同受影响）、audit_nodes **18 基准全部重冻结**、dashboard_audit 基线、`metric_calibers` 注册表。
- **纪律（口径变更三件套，09-28 教训——51 假 FAIL）**：代码 + 基线 + 注册表**同日同步**，changelog 与各页面脚注同步刷新；禁止分日分批。
- **与 peer 口径关系**：管道改逐日后与 peer Excel 固定汇率口径**再分叉（预期内，各自脚注）**；对账以原币列 local_amount 为锚（币种无关，两侧恒可比）。
- **验收（若执行）**：① fx_rates 窗内每日每币有行（覆盖率 100%）；② 抽样对账：同 SKU 同日 `local_amount ÷ fx_rates.rate ≈ 新 revenue_usd`（±0.5%）；③ audit_nodes/dashboard_audit 重冻结后全绿；④ 工作台 30 天营收前后差 ≈ 预估 +3.3%（EUR 区）；⑤ 本币列逐位不变。
- **状态**：**2026-09-30 用户拍板「R15 执行」——当日执行完毕，双门全绿**。

**执行记录（2026-09-30）**：
1. **历史汇率源拍板**：ECB/frankfurter 一次性种子 2024-01-01~2026-09-08（5,512 行入 saas fx_rates，source='ecb-frankfurter-backfill'，ON CONFLICT DO NOTHING 绝不覆写活水行）；活水仍是自家 exchangerate-api（06:05）。mars 侧建 `public.fx_daily` 读表（worker 全量镜像，5,643 行）+ `fxd(day,cur)` 函数（当日→前向填充→旧 fx() 常数→1，常数逐值一致）。8 浮动币各 699 行（2023-12-29~2026-09-29），23 个缺口=ECB 假日（前向填充覆盖）；**MXN：ECB 2026-09 停发参考价、数据止 09-08，活水 exchangerate-api 已接棒（09-30 实测至 09-30）**，daily_fx_rates CURS 补 MXN。
2. **双陷阱（表面替换修不出真口径）**：① 三品牌 `spapi_orders.revenue_usd` 是采集器**写库时烘焙常数的存储列**（实测=total_amount/常数 分毫吻合）——spec 层 COALESCE 首位透传使 fxd 永不生效 → 全部调序为**重算优先、存储列退兜底**；② zf 表 `order_total_amount` 2025-08 245/245 全 0/NULL（R10 病灶，SP-API 原始字段），真实本币金额在 `total_amount`/`currency` → ot lateral 配对 `CASE WHEN coalesce(order_total_amount,0)>0 THEN order_total_* ELSE total_*`（订单 835 行 507→全量可用）。
3. **改动面**：spec 端 orders 三分支（zf 调序+ot 配对 / fg spec 层重算 / onno 原本重算优先）+ it_raw×4 + fin 分支×2 + order_fees（`min(posted_date)::date`）；mars 视图 4 张 fx( 残留清零（v_order_finance_detail 21 点 + v_monthly_overhead 3 + v_fittingirls_shipment_agg 22 + v_fittingirls_monthly_overhead 5）；spec 端 fx( 仅剩 RMB 成本钉死路径（故意保留）。**教训两条**：前段「v_monthly_overhead 零读者」结论错误（实为 v_order_finance_detail 读取）——「零读者结论执行前必须对执行对象重 grep」铁律再次应验；EXPLAIN 清单漏了 finance_monthly → 全量摄取当场暴露 `fxd(timestamptz)` 漏 cast（fg 视图 posted_date），即修即重跑（5,000 行）。
4. **回补（spec 自愈单一口径路径，无旁路 UPDATE）**：全量摄取 `ingest_all(full_orders=True)`（41,375 行，_orders_reconciled 0 幽灵行）+ `tools/backfill_sales_daily_fx_full.py` R12 式去窗（订单窗 30d→2024-01-01 / 广告窗→2026-01-01，进程内 patch 模板不落盘）sales_daily 3,224→26,715 行（zf 至 2024-01-11 / fg 至 2025-05-27 / onno 自 2026-08-01 起）。
5. **验收全过**：冻结窗逐分吻合（2025-08 全品牌 20,891.79 = 探针 n=1026 分毫不差；2024H2-float 21,443.43 n=997 同）；锚点三品牌 0 偏差（zf 2025-08 706 行/fg 172/onno 30d 289，`local_amount÷fxd(日,币)≈revenue_usd` ±0.01）；本币列逐位不变（zf 854 行 vs v_order_master 0 不一致，115 行 m 零值走既有兜底）；30d 活对照 n 逐行相等（2,202，sum 差 0.13%=采集活水漂移）；sales_daily 跨表对账 zf 2025-08 16,937.42 vs orders 16,937.60（0.001% 舍入）；audit_nodes 18 基准全绿 + dashboard_audit FAIL 0（基线均为 SQL 直算随清洗层同移，无需手工重冻结）。**方向数字**：30d ~+6%（AUD/EUR 区）、2025-08 +2.3%、2024H2-float −5.0%（2024 下半年欧元疲弱日率>0.92 常数，USD 下修为诚实方向；需求单「整体上移 ~3.3%」为 2025-26 区间表述）。sales_daily 159 行 fg units 变动=源端 Pending 回刷/数量修订（09-24 立过案的 fg 老问题）被 spec 自愈修到当前源真值，非口径变更。
6. **注册表**：metric_calibers 新增 `fx_daily` 行（id=13）+ id=6 `fx_pegged` 注记（浮动币已迁逐日、锚定路径不变）。
7. **回滚路径**：视图=重跑旧 def；spec=以 `backups/code-20260930-r15/` 旧代码同法去窗重跑（常数口径回归）；fx_rates/fx_daily=`DELETE WHERE source='ecb-frankfurter-backfill'` + `DROP FUNCTION fxd` + `DROP TABLE fx_daily`；sales_daily 次日 30 天窗自然收口近端。

## R16（2026-09-30 立案，P1）：采集层三缺陷 + VAT 口径发现——onno-10 回款口径改造中通报。**2026-09-30 全修完毕（全栈审计 3 发现 → 用户拍板「全修」→ ①②③+P1/P3 三级当日闭环，见下方全修执行记录）**

**提出方**：onno-10（采集侧回款口径改造过程挖出）。页面侧已绕开（EU 用 zf finances net−tax，4 国用 settlement_items），本单修复后 51 单兜底与 AU/US 促销缺口才可能收敛。

1. **onno_amazon_spapi_finances 双缺陷（SA 侧不可用）**：① 存在 2× 重复 fetch 行——SA 单 171-2614577-4469141 Shipment/Refund 各两条，DISTINCT 全业务列不收缩（疑 id/created_at 不同）；② **net_item_total 算错**：该单 129.99 收入、total_fees −22.63，净额应 107.36，库存却存 159.62。聚合层面 SA 净额 17,899 SAR vs 结算明细 5,977、营收 7,774——**SA 侧 finances 聚合不可用**。
2. **settlement_items（zf/onno 两侧）charge 侧丢 Promotion 组件**：GB Vine 单 205-3947921-0649150 items 只剩 charge 39.99 / fee −3.37（隐含 +36.62 付钱给 Vine）；zf finances 同单净额 −3.37 才是对的。
3. **cleaned_order_fees 无 VAT 站内扣项（SaaS 侧口径，关联 R15）**：EU Amazon 代扣 VAT（用户确认「EU 是代扣 VAT 的」）——PL 单 132.99 PLN 里 tax 24.87=23% 分毫不差，Excel 后台毛利即扣税口径（扣税后 17.80 vs 后台 17.81 闭环）。清洗层费用四桶（佣金/FBA/promo/other）不含税，凡算回款需另扣。

**状态**：①②仅立案（采集源侧：重复行治理 + 组件补齐）。③ **2026-09-30 用户拍板执行完毕**，见下方执行记录。onno-10 同时确认：其页面读 mars raw + 自持固定汇率，R12/R15 均不受影响，各自脚注。

**③ 执行记录（2026-09-30，cleaned_order_fees 增 vat/local_vat 列）**：
1. **口径**：订单级 EU+UK 代扣 VAT 净额（退款负税自然冲抵），源=finances.tax 逐行 SUM；代扣集={PL,DE,FR,IT,ES,NL,SE,BE,IE,GB}（zf/onno 分支按 marketplace_name、fg 视图按 country）；非代扣市场（US/CA/MX/JP/AU 等）记 **0 不留空**（US 市场税 Amazon 代收代缴不进结算单，定案）。**vat 是从 principal 扣的非费用项：四桶（commission/fba/promo/other）与 total 口径一字不动**，消费侧算回款/毛利需另减本列。USD 列=abs(local_vat)/fxd(首贴现日,币) 与四桶同法（R15）。
2. **改动面**：sync_mercury.py `_FEES_ZF_BRANCH`/`_FEES_FG_BRANCH`/order_fees spec（列 12→14）+ clean_audit.py amount_cols 补 vat；DDL：public.order_fees 与 audit.cleaned_order_fees 各 ADD vat double precision + local_vat numeric(14,2)；快照 /opt/backups/code-20260930-r16c/；镜像 build api worker + force-recreate 两容器；定向摄取 `ingest_all(tables=['order_fees'])` 35,720 行全史自动回补（spec 无窗全量）+ 单表清洗。
3. **验收**：①PL 锚点单 402-8857872-1497907（onno 归属 brand_fix 生效）local_vat=**24.87 PLN**（=132.99×23/123 分毫），vat=6.69 USD；②UK 203-6478165-8946713 local_vat=3.33 GBP（20%）；③排除面实证：VAT 汇总仅现 EUR/GBP/PLN/SEK 四币（fg 45,408.90 EUR 大头+SEK 22,107.87/zf SEK 46,111.19/onno 214 行），无任何 USD/AED/SAR/MXN/CAD 行；④四桶+total 逐位不变（spec 增列不触旧列表达式）；⑤audit_nodes ALL PASS 2,438 节点/18 基准。
4. **注册表**：metric_calibers 新增 `vat_withheld`（id=14，含代扣集/性质/锚点/USD 折算法）。
5. **连带发现（非本案引入）**：dashboard_audit FAIL 2=noon nPast24h/nLast24hCountry「api=0 vs base=1」——实锤为 SaaS noon 订单 cleaned 层摄取滞后（raw max 09-30 08:17 vs cleaned 05:43，样本量 1 单的 0/1 翻转），下轮摄取自愈，与 VAT/窗口改动无关；若持续到 10-01 另立新案。

**2026-09-30 追加定案（onno-10 回款对账破案，AU/US 差额根因=Vine 单）**：AU 33 笔/US 30 笔 Vine（订单号 503- 前缀）结算事实=Principal 与 PromotionList 全额冲抵、费用全 0 → 真实净额 0；旧口径当足额付款单，AU 虚 +$1,508/US 虚 +$1,071。缺陷链三条（全在 onno_amazon 侧，zf 无恙）：① `onno_amazon_spapi_finances.promo_rebates` 从未被 normalize 填充（全表 0）但 event_data JSON 里 PromotionList 完整（与 ItemChargeList 平级、键 PromotionAmount）；② 同表 country/marketplace 错标孪生行（SA/AE 单贴 SA+GB 双标签=R11 撞键残留，settlements 头表同污）；③ settlement_items Refund 行 charge_amount=0（退款本金冲销丢失：AUD 12/AED 5/SAR 8）。页面侧已绕开（直解 event_data：ItemChargeList+PromotionList+ItemFeeList，f.country=订单国剔孪生），12 国收敛至 Excel 后台毛利 ±$55，锚点 PL 17.80/17.81、AU ONQ2001 287.00/287.34；修正后全窗净利 +2,282→−734.61（Vine 幻影利润 ~$3,017 剔除）。**税的两种性质定案**：EU 代扣 VAT 从 principal 里扣（回款已减、单列）；US 市场税不进结算单（Amazon 代收代缴）——回款口径不计、勿混进「代扣税」展示。R16 修复验收直接用上述锚点。可复用经验（原文留档）：原始 event_data JSON 是唯一真相源，对账对不上先回 raw 解析别在派生层修补；对账先做表内自洽检查（对方 GMV−佣金−FBA−广告≠毛利 ⇒ 毛利另有数据源）；逐 SKU 分毫锚点先于站点级收敛；加载器缺陷绕开优先于等待。

**全修执行记录（2026-09-30，用户拍板「全修」）**：审计基于 R16 挖出 3 发现——F1 **VAT 死列**（R16-③ 只建列，SaaS 全部净额/利润公式从未消费 f.vat，365d 利润虚增 **$65,776**：fg 59,198 / zf 5,455 / onno 1,124，fee-covered 口径）；F2 **141 行 NULL-vat 陈尸**（mars 已将这些订单 brand 翻案为 onno——EU 代卖归属，SaaS public.order_fees 旧行为翻案前残留；实证 141 行 100% 存在 (onno,同单) 带 vat 新行顶替，删除是纯去陈尸非毁数据）；F3 **Vine 幻影利润**（AU 100 promo 单中 40 笔全冲抵 principal+promo=0，净 Σ=−38.80 AUD 恰等于费用项——恒等式闭合即真净额 0）。
1. **P1 API 层（6 文件 24 处公式）**：净额统一式 `rev−|comm|−|fba|−|other|−|promo|−vat−adsp`。finance.py 16 处 net/net_usd + dashboard.py（KPI profit、fees30 倒算后减回 vat——费用卡不含 VAT，注册表 id=14 裁决、月/周趋势）+ ai.py 3 处 + matrix.py（利润对比/国家热力图）+ mcp.py 1 处 + tools/dashboard_audit.py 基准三处同步。锚点 402-8713043-3112317 回款恒等式分毫闭合。
2. **P2 采集层+mars**：① 采集器 onno 三缺陷根治（promo_rebates normalize / 孪生标签 / 退款本金）；② settlement_items charge 侧 Promotion 并入——zf 适配器重跑 538 结算单 11,736 items 0 错，锚点 GB Vine 205-3947921-0649150 charge 39.99→0.00 + fee −3.37 = finances 真值分毫，聚合足迹 314 行全冲抵 Shipment，非 DebtRecovery 组头表对账与未触碰组同构（avg 236 vs 184 同量级，无回归）；③ mars 141 陈旧行 DELETE（备份 /opt/backups/mars-r16-20260930/saas_order_fees_stale_nullvat_141.csv）+ onno 孪生 DELETE + 单表重清洗——**vat 总额 78,826.55 修复前后分毫不变**（纯品牌间再归属：fg 59,211.44 / onno 1,124.13 / zf 18,490.98），promo 差额 −2,725.50 属 fees_brand_fix 既有防双计设计。
3. **P3 spec**：promo→abs()（promo 桶=正成本量级）+ onno promo 硬清零移除 + vat USD coalesce-to-0。
4. **回归门**：pen_tests ALL PASS / audit_nodes 2,445 节点·18 基准 ALL PASS / dashboard_audit FAIL 0（余 7 WARN 全为既有已知）。**量化终值（365d）**：vat −65,776 + promo −14,272（onno 8,317 / zf 5,955）→ 修正后净额 360,651（fee-covered 营收 649,566）。
5. **截图自检**：8 张（双品牌×双视口×首页/财务）存 screenshots/2026-09-30-r16-vat-promo-*.png，视觉确认 3 张关键图全正常（移动端新费用卡脚注「不算 EU 代付 VAT」正确渲染）。
6. **口径拍板（2026-09-30 用户拍板「Vine 就按 mars 真值展示」）**：AU Vine 全冲抵/部分冲抵单净额一律按 mars 结算真值（全冲抵净=费用项）照实展示，不采 peer「强制费 0」口径（mars 未复现）；SaaS 近似式 `rev−|comm|−|fba|−|other|−|promo|−vat` 天然收敛至真值，无代码改动；已登记 `metric_calibers` **vine_net（id=15）**，锚点 AU 40 笔净 Σ=−38.80 AUD。
7. **回滚**：API 层 /opt/backups/code-20260930-r16c/；mars 层 /opt/backups/mars-r16-20260930/（141 行 CSV 回插+旧 promo 值）；SaaS 数据层单表重摄取自愈。

## R17（2026-10-08 立案，P1）：zf Amazon SPAPI finances SA/AE 两市场贴现停更 09-08/09——330+ 单费用行缺失，利润/回款口径失真

- **发现方**：dashboard_audit 费用覆盖门（`[费用覆盖] zipforce 08-31周(22单): api=0 base=1`）——该周 10-08 满滑入 ≥35 天成熟窗首次触发，非部署回归。
- **事实（SaaS 侧）**：zipforce SA/AE 订单费用覆盖率按周：08-24 周前 100%，**08-31 周起几乎全缺**（08-31 周 51/60、09-07 周 85/85、09-14 周 62/62、09-21 周 54/54、09-28 周 53/53、10-05 周 25/25）；其他站点（UK/FR/IT/ES/SE/NL/BE）成熟窗 0 缺。截至 10-08 共 **330 单**（08-31~10-08，每日递增）无 order_fees 行。
- **源头（mars 实测）**：`zipforce_amazon.zipforce_amazon_spapi_finances` 分市场 max(posted_date)：**Amazon.sa=2026-09-09、Amazon.ae=2026-09-08**，其余市场流至 10-05~10-07。抽查 12 张 08-31~09-02 缺费订单（如 403-4251966-7827522/171-8566026-8841115）源头 **0 行**。而同期 SA/AE 订单流持续（330 单）——订单在采、贴现停拉。
- **影响面**：SA/AE 区利润/费用/回款/VAT 全链失真（净额=rev−费用，费用缺=利润虚高）；dashboard_audit 费用覆盖门持续红（真阳性，非误报）。
- **建议排查方向（采集侧）**：zf_amazon.py finances 拉取的市场清单/循环在 ~09-08/09 前后是否掉 SA/AE（对照 R14 曾核过的 MARKETS 清单为 orders 侧；finances 侧独立）；或 SP-API finances 分市场接口对 SA/AE 报错被静默吞（R11 教训①同型：导出 0 行无告警面）。恢复后 SaaS 侧无需任何改动——order_fees spec 全量幂等摄取自动回补全史。
- **SaaS 侧动作**：无（守卫/基线不动，门红=诚实状态）；需求单移交源头。
