# B/C/D 类「注册即自动级联」改造 — 2026-10-08

> 用户令：**B/C/D 都要满足新租户注册后，相关文件数据自动生成**。
> 硬编码盘点 B/C/D 全部做到：新租户/新品牌在 `brands_source` 登记通道行后，
> 采集清单 / SP-API 路由 / 广告凭证 / 清洗归属规则 / 前端模板库与品牌色 **零代码改动**自动装配。
> 事实进注册表（`source_map` 显式键，pg-init/79 种子），逻辑写死 + 门断言。

## 0. 注册表键设计（pg-init/79-collect-registry-20261008.sql）

`brands_source.source_map`（json 列，并集须 `::jsonb` 转型）新增五键：

| 键 | 结构 | 说明 |
|---|---|---|
| `collect` | `{orders:[adapter,args...], finances:adapter, ads:[[adapter,hour],...], noon:adapter, noon_full:[adapter,...], ads_channel:"csv", sales_fba:[[adapter,分钟],...], night:[[adapter,分钟],...], settle:[[adapter,超时秒],...]}` | 全部采集通道清单。adapter 真名源=/opt/collection/config.py ADAPTERS（28 个逐一核实）；settle 按快→慢登记（字母序恰保 fg/onno 3500s 先、zf-settle-it 7200s 收尾）；ads 小时档错峰 zf@2/zf-attr@3/fg@4/onno-csv@5 |
| `spapi` | `{kind: zf_lwa\|fg_json\|onno_md, ip, markets:[站点码...], token_regions:{站点码:令牌区}}` | 值语义随 kind：zf_lwa=逻辑区大写(文件名小写 us/de/sa/ae)、fg_json=refresh_tokens 键(US/EU/AU)、onno_md=Atzr 序号(0/1/2)。站点→marketplace_id/域名查 marketplaces 全局表（`_MP_ALIAS` EU→DE / GB→UK 仅查表用，market 码原样）；API region 按平台事实 `US/CA/MX/BR→na, JP/AU→fe, 其余 eu` |
| `ads_creds` | `[creds.json, profiles.json]` | 广告执行凭证文件对 |
| `color` | `"#4f46e5"` | 品牌展示色（前端图表/标签运行时注入） |
| `consign_schema` | `"zipforce_amazon"` | 声明「货走别家卖家账号」——清洗层代卖对推导（C 类泛化） |

种子覆盖：zipforce/amazon（7 站 spapi + 5 类通道）、fittingirls/amazon（14 站，GB 非 UK）、
onno/amazon（4 站 + ads_channel=csv）、zipforce+onno/noon（noon 增量与 noon_full 两键两 adapter）。
线上已执行两轮（幂等 `||` 并集 + ON CONFLICT DO UPDATE）。

另：**listing_library 表**（模板库目录，30 条种子；表名避开 42 号规则引擎的 listing_templates）
+ **as22 文案修正**：AS22 是骨传导耳机，旧种子/旧前端文案「按摩仪」系错误，本轮一并纠正
（种子已改 + 线上 UPDATE + 前端 LEGACY 常量删除三处同步）。

## 1. B 类：采集清单注册表化（api/tasks.py，十处清单）

| 位置 | 改造前（硬编码） | 改造后（注册表驱动） |
|---|---|---|
| collection_cycle orders | 三品牌 if/elif 分支 | `_collect_channel("orders")` |
| collection_cycle finances ×2 | 逐品牌分支 | `_collect_channel("finances")` |
| settlement 周一链 | 六元组清单 + 快慢排序写死 | `_collect_plan("settle")`（注册表按快→慢登记） |
| noon 增量/全量 ×2 | `("zf-noon","onno-noon")` 等 | `_collect_channel("noon")` / `("noon_full")` |
| ads 小时档 | hour={2,3,4,5} 内嵌清单 | `_collect_plan("ads")` 任意小时档生效 |
| sales_fba/night | 4 job 硬编码 (hour,minute) | `_collect_plan("sales_fba"/"night")` 分钟档 |
| source_drift_check | 已知五 schema 写死 | `_admin_conn()` 查 `DISTINCT source_schema WHERE enabled`，`[a-z0-9_]+` 白名单校验后内联（qsource COPY 通道无参数化）；异常回退五 schema |

cron 两处：`collection_cycle_ads` minute=0（去掉 hour 限制）；`collection_cycle_sales`
minute=set(range(60))（原来 minute=0）——见 §3 死档修复。

## 2. C 类：SP-API / 广告 / 清洗归属泛化

**spapi_client.py**
- 新增 `_spapi_reg(brand)`：读 `source_map.spapi`；异常返回 `{}`（凭证分派 fail-closed 防死库裸连）
- `_brand_lwa` 改 kind 三分派：`fg_json`→refresh_tokens[token_region]；`zf_lwa`→`zf_lwa/{token_region 小写}.json`；`onno_md`→`toks[int(token_region)]`；未登记 kind 报 400
- `brand_markets` 注册表驱动：`spapi.markets × marketplaces 全局表` 推 marketplace_id/域名；
  无全局行报 400 不猜 ID；`token_region=trs.get(code,code)`；`region=_API_REGION`
- `assert_exit_ip`：`_spapi_reg(brand).get("ip") or EXPECTED_IPS.get(brand)`（常量降级为兜底）

**ads_exec.py**：`_brand_creds(brand)` 读 `source_map.ads_creds`（len==2 则用），
异常回退 BRAND_CREDS 常量；`_load_creds` 改用之。

**clean_audit.py + tools/audit_clean_all.py（孪生同步）**
- `_consign_pairs(cur)`：从 `consign_schema` 键推导 (seller_brand, consign_brand) 对
  （线上唯一对：onno 声明 consign_schema=zipforce_amazon → (zipforce,onno)）；
  回退 `[('zipforce','onno')]` 不停摆
- `_csv_channel_brands(cur)`：从 `collect.ads_channel='csv'` 推导专表品牌集（现=[onno]）；
  回退 `['onno']`
- fees 品牌翻案与 `onno_country_dedup` 的品牌集全部走上述推导；
  **cfg 键与 log 标签保留 `onno_country_dedup` 原样**——four_layer_audit.py L458 对
  /app/clean_audit.py grep 此字面量（门断言约束）
- 引擎模板改动已按铁律 **build api + worker 两容器**（否则 2h 清洗用旧模板刷掉线上 ALTER 的分支）

## 3. 附带发现：sales/night 死档 bug（数据实证，已修）

原 `collection_cycle_sales` 用 `minute>=d` 过滤器配 cron `minute=0`——d>0 的 4 个 job
（onno-sales-fba@01:20 / onno-finances@01:20 / fg-derive@03:30 / onno-derive@03:45）
**自六期四批上线从未跑过**。mars 数据侧实锤：onno_sales/onno_fba 水位停 09-11、
onno_fin 停 09-30（皆手动跑的痕迹）。修复：分钟档精确匹配 `minute == d` +
cron `minute=set(range(60))`，恢复 01:00/01:20/03:00/03:20/03:30/03:45 全部错峰档。

## 4. D 类：前端数据面自动生成

| 文件 | 改动 |
|---|---|
| api/routers/listing.py | `/api/listing/meta` 增 `templates`：`listing_library WHERE brand=ANY(租户品牌)`（portal_app 已 GRANT，79 号） |
| api/routers/auth.py | `/api/tenant/info` 增 `brand_colors`：`brands_source WHERE brand=ANY(租户品牌) AND enabled AND color 非空` |
| web/lib/fmt.ts | `setBrandColorOverrides()` + `brandColor()` 三级回退（注入→BRAND_COLORS→灰） |
| web/components/BrandContext.tsx | TenantInfo 增 `brand_colors?`；BrandProvider 收到 info 即注入（幂等） |
| web/app/listings/page.tsx | **LEGACY 30 条硬编码常量整体删除**（as22 旧文案随删）；TemplateLib 改 meta.templates 驱动，按 (brand,grp) 分组；保持 §86 子组件 useBrand 模式与 `/listings/{slug}.html` 链接 |

新租户注册链路 = tenant_brands 插行 + brands_source 通道行 + listing_library 插行
→ 模板库/品牌色/采集通道/清洗规则全部自动出现。

## 5. 验证

**brand_markets 等价比对**（改造前基线 tools/brand_markets_baseline_20261008.json vs 新容器输出，
按 (brand,market) 逐字段）：
- 三品牌 market 码集合一致；`region` 全等
- **修正旧硬编码笔误 3 处**：zf CA `A2EUQ1WTQCTBG2`→`A2EUQ1WTGCTBG2`（Amazon.ca 官方）、
  zf EU `A1PA6795UKMFR9D`→`A1PA6795UKMFR9`（Amazon.de 官方，旧值多一个 D）、
  onno token_region 旧区域串→Atzr 序号（与 `_brand_lwa` 的 `toks[int()]` 消费端语义对齐，79 号种子一致）
- name 展示差异 11 处（全局表官方域名 vs 旧硬编码拼名），纯展示；消费方仅 listing pt-markets 下拉，market 码为键不受影响
- 四道门无 brand_markets/token_region 断言依赖；tools/_audit_pixel_values10.py（历史像素批次工具）镜像旧笔误值，属存档不属活体门，注记不改

**新租户 dry-run**（tools/dryrun_new_tenant_20261008.py，插测试品牌 cascadetest 三件套→验证→删→备份逐行核对恢复）：**24/24 PASS**
- B 类：orders/finances/ads/settle/sales_fba/night 六清单全部自动含新品牌通道，原有 zf/onno 通道无回归
- C 类：代卖对含 (zipforce,cascadetest) 且原 (zipforce,onno) 保留；CSV 品牌集同理；brand_markets 新品牌 2 站展开（US/CA 官方 ID）；出口 IP 走注册表；ads_creds 文件对自动装配
- D 类：tenant_brands 含新品牌 → meta templates 25 行含新模板、brand_colors 含 #123456；租户2 视角不可见（隔离）
- 清理后 brands_source=8 行 / listing_library=30 行，与备份逐行一致

**四道门**（顺序跑）：pen_tests **ALL PASS**；four_layer_audit / frontend_e2e / dashboard_audit 见下。

### 四道门终态与审计基准级联修复（2026-10-08 深夜收口）

**批次演化**：41f41b44(06:43, FAIL 29=中途状态) → a8df0cb3(15:27, FAIL 7) → aee2fdd4(基准修复后, FAIL 4)
→ 83e6a6cf(16:4x, FAIL 5=本轮修复前基线) → **终版批次（见下）**。

**① §191 账号轴漏网四基准补齐**（four_layer_audit.py，修复后全部转绿）：

| 基准 | 修复前 | 修复 | 验证 |
|---|---|---|---|
| R1 KPI orders | 裸计数混入他账号行 | `seller_owner IN (SELECT account FROM tenant_accounts WHERE tenant_id=1)` 显式子查询 | 514=514 |
| R2 Noon rolling | 全品牌裸计数混入 onno 自营 51 单 | 镜像 RLS 第三子句 `brand IN (SELECT brand FROM brands_source WHERE tenant_id=1 AND platform='noon' AND enabled)`（租户1 (1,onno,noon) 行 enabled=f 不参与） | 2458=2458 |
| 今日页对账 | 同上裸计数（onno 7 vs 10 假 FAIL） | host→slug→tenants 同 login 解析租户，基准按该租户 tenant_accounts 过滤 seller_owner | onno 7=7（租户1=3 EU 代卖/租户2=7 自营分解全对） |
| chart_value onno 块 | KPI orders 460 vs 838 假 FAIL（10+ 红串） | 基准会话 `SET ROLE portal_app; SET app.tenant_id='N'`——**saas_admin 带 BYPASSRLS，`SET app.tenant_id` 单用不生效**，必须 SET ROLE 让 FORCE RLS 真正约束（与 API 同角色同 GUC） | KPI orders/revenue/dailyRev/weeklyRev/dailyCnt/cumRev/statusPie/fulfillPie 全绿 |

**② §89 窗口锚差复发破案**（chart_value zf/fg 块 KPI ~2% 假红）：
API 图表窗口=北京锚（dashboard.py `purchase_date > (now() AT TIME ZONE 'Asia/Shanghai')::date - days`），
基准=`CURRENT_DATE`(UTC)——北京 00:00-08:00 跨日期间两锚差一天，**每日 cron 06:35 恰在窗内必红**；
下午两锚同日→绿（15:27 批次绿/16:4x 批次红即此故）。差额逐单吻合：zf 07-11 一天=27 单/$361.17、
fg=101 单/$2145.83。修复=基准 WIN 改北京锚 → zf/fg 块 KPI 全绿。

**③ fg sales_channel 全链空串翻案（新 bug，已修+回填）**：
chart_value salesChan 红（api=-1, db=空串键 4483 单）追踪三段——mars 源表有真实值
（Amazon.com.au 1107/Amazon.es 659…，90 天 4593/4593=100%）→ 源视图
`v_fittingirls_order_finance_detail` 无 sales_channel 列 → **`_ORDERS_FG_TPL` 模板该位置硬编码空串**
（sync_source.py；asin_list 同为 '' 但 fg 源表真无该列，保持）。修复=模板改标量子查询取
`{so}.{so}_spapi_orders.sales_channel`；**build api+worker 两容器**（只 build api 会漏 worker——
每周全量 ingest 在 worker，旧模板会把回填刷回空串）；`ingest_all(full_orders=True)` 全量重灌
public（4483+ 全值）→ `audit_clean_all.py amazon_orders` 定向清洗 → cleaned 4494/4494=100%。
salesChan 红消除。

**④ skuRev 基准近似→精确**：旧基准 `GROUP BY sku_list`（单 SKU 整单聚合）vs API 订单内 SKU 拆分
set 去重+金额按 SKU 数均摊（dashboard.py 2026-09-24 口径）→ Top1 恒偏低（fg 实测差 24% 假 FAIL）。
基准改 unnest 拆行+窗口计数均摊同口径 → fg/zf 块 FAIL 0。

**⑤ zf/ads_sku_daily 断 3 天=部署窗口撞档（非故障）**：collection_cycle_ads 按 UTC hour 分档
（zf-ads=UTC 02:00=北京 10:00），恰逢本日 B/C/D build/重启窗口错过档；15:27 批次 gap=2 未触发
阈值、16:4x 批次北京跨日 gap=3 报红（时间线全吻合）。处置=worker 容器内 detached 手动补跑
zf-ads（147 报表/日，幂等），此后恢复常规档。

**⑥ frontend_e2e Noon tab 点击超时=偶发**：83e6a6cf 批次一次 Timeout 4000ms，单独重跑
**ALL PASS**（27 页+组合扫+像素空白全过）。

**chart_value 终态**：zf FAIL 0 / fg FAIL 0 / onno FAIL 2=orderCur×2
（41 行 AU/SA/AE/US `currency=''` 源头 mars 采集缺口：raw 三币种列全空 2026-08-12→今+API
`or "USD"` falsy 兜底把 106 伪装成 65+41——**源头需求单，非 SaaS 层**）。

**终版四道门**：pen_tests ALL PASS｜frontend_e2e ALL PASS｜dashboard_audit FAIL 1=既有 R17
（IL 费用覆盖 zipforce 08-31 周，SA/AE settlement 滞后 4-5 周已立案）｜four_layer_audit
**batch=2026-10-08-a1b33816：152 项 FAIL 4 WARN 4，四红全部定性**——①onno/amazon_ads_daily
断 14 天（CSV 人工通道，R2-bis 家族 09-23 需求单挂账）②ads_rule_config RLS missing_brand_scope
（≥10-05 既有）③chart_value onno 块 orderCur×2（源头币种缺口）④IL R17（既有）。本日内演化：
06:43 FAIL 29（中途）→15:27 FAIL 7→基准修复后 FAIL 4→83e6a6cf FAIL 5（跨日锚差+撞档暴露）→
终版 FAIL 4 全定性；zf/fg chart_value 两块**首次双 FAIL 0**（81 图对账），zf ads 断更红消失，
e2e Noon timeout 偶发定性成立（重跑+终版批次双 ALL PASS）。

**遗留挂账**（非本轮范围）：onno/amazon_ads_daily 断 14 天（CSV 人工通道，R2-bis 家族 09-23 需求单）；
ads_rule_config RLS missing_brand_scope（≥10-05 每日红）；onno AU/SA/AE/US 币种列源头缺口；
`docker compose build api` 只 build 单服务镜像的坑（worker 须显式 build）。

**截图自检**（tools/_shot_1008_cascade.py，双视口存档 screenshots/1008-cascade-*）：
- listings 资源 tab：模板库五组 24 卡（zf 9+5+4 / onno 6），fittingirls 组不出现；
  **as22 卡显示「AS22 骨传导耳机」**，旧「按摩仪」全文不出现（DOM 断言+视觉双确认）；
  底部说明更新为「目录动态按本租户品牌生成」
- /today 回归抽查正常；mobile 390 视口单列堆叠正常

## 6. 文件清单

- pg-init/79-collect-registry-20261008.sql（新）
- api/tasks.py、api/spapi_client.py、api/ads_exec.py、api/clean_audit.py、
  api/routers/listing.py、api/routers/auth.py
- tools/audit_clean_all.py、tools/dryrun_new_tenant_20261008.py（新）、
  tools/_shot_1008_cascade.py（新）、tools/brand_markets_baseline_20261008.json（新，等价基线）、
  tools/brands_source_backup_20261008.json（新，dry-run 前备份）
- web/lib/fmt.ts、web/components/BrandContext.tsx、web/app/listings/page.tsx
- 容器：api / worker / web 三镜像重建并 up
