# 工作流动态配置

## 配置源

商品身份现在统一由产品生命进程维护，目标地址和平台画像等运行参数仍保存在云端
PostgreSQL 的动态配置表。生命进程负责款式名、品牌、ERP 款式编码、各平台商品编码
以及大/小 NFC 数量；控制台“配置中心 → 款式平台配置”继续负责目标地址、画像表和启停状态。
工作流运行时将两者合并，不再读取旧配置主表
`TtoCb1NuQaDy3NsZWTpc0GIvnph/tblKCjplVAFrRwMC`。

产品采集的统一身份门是：ERP 款式编码 + 至少一个平台商品编码。只有 ERP 款式编码的
研发新款会保留在生命进程中，但不会进入商品采集；如果指定平台没有自己的商品编码，
该平台也不会触发采集。内容汇总类工作流只需要款式名和对应目标，不因缺少商品编码而被
这道商品采集门拦截。

目标飞书表仍是工作流的业务输入或输出，例如销量表、主图表、人群画像表和合作达人表；
本次下线的是集中维护这些地址和商品 ID 的旧飞书索引表，不是业务目标表本身。

## 受影响工作流

| 工作流 | 动态读取内容 | 生效入口 |
| --- | --- | --- |
| `content.summary.monthly` | 款式与每周笔记分析/生命进程目标表 | `monthly_summary_all.py`（复用周汇总配置加载器） |
| `content.summary.weekly` | 款式与每周笔记分析/生命进程目标表 | `weekly_summary_all.py` |
| `content.metrics.daily` | 合作达人目标表（自营采集暂缓） | `run_all.py`、`sync_metrics_to_cmt_notes.py` |
| `content.metrics.backfill` | 合作达人目标表 | `run_all.py` |
| `content.notes_master.daily` | 各款式合作达人及自营笔记表 | `sync_notes_master.py` |
| `product.persona.daily` | 三平台商品 ID 与人群画像目标表 | 三个平台画像采集脚本 |
| `product.daily` | 天猫/京东/抖音商品 ID、ERP 编码、销量目标表 | `orchestrate_daily_collection.py` 及平台采集脚本 |
| `product.style_analysis.interval` | 款式与平台单品分析目标表 | `analyze_style.py` |
| `product.main_image.weekly` | 京东 SPU、天猫款式和主图目标表 | 两个平台主图采集入口 |
| `product.sales_sheet.daily` | 款式与 ERP 编码 | `sync_monthly_sales_sheet.py` |
| `product.erp_all_shop_daily` | 全部款式与 ERP 编码 | `backfill_erp_all_shop_daily.py` |

共 11 个定时工作流依赖这套动态配置。维护脚本 `feishu_comment_batch.py` 和
`db/sync_sku_master.py` 也已改为读取同一项目数据库，避免从非定时入口绕回旧主表。

`product.alert.daily`、商品导入、万相台广告、视频发布和市场排行使用各自数据库或专用配置，
不依赖旧配置主表，因此不在本次切换范围内。

## 字段归属与数据模型

新模型不再把共享字段重复放在每个平台行：

| 层级 | 字段 | 使用目的 |
| --- | --- | --- |
| 产品生命进程 | 款式名、品牌、ERP 款式编码 | 统一业务身份；ERP 日采、月度销量表和款式主数据使用 |
| 产品生命进程 | `platform_product_ids` | JSONB 固定键 `tm`、`jd`、`jd_self`、`dy`，值为去重后的字符串编码数组 |
| 产品生命进程 | 大 NFC 数、小 NFC 数 | 产品规格记录，默认值为 1，允许填写 0 |
| 动态配置父表 | 销量表、主图表 | 商品日报和天猫/京东主图工作流的款式目标表 |
| 动态配置父表 | 合作达人表、自营合作达人表 | 内容采集、合作同步和笔记清单使用 |
| 动态配置父表 | 每周/每月笔记分析、平台单品分析 | 内容周月报和款式周期分析使用 |
| 动态配置子表 | 平台名、启用状态和画像目标 | 商品 ID 只保留兼容快照；运行时商品 ID 由生命进程覆盖，平台停用状态仍然生效 |
| 平台 | 本平台人群画像表 | 天猫、京东、抖音画像采集分别写入自己的目标表 |

数据库使用父子表：

- `cmt_styles`：产品生命进程主表，一个款式一行，保存 ERP 编码、四个平台商品编码和 NFC 数量。
- `workflow_dynamic_styles`：一个款式一行，保存共享飞书目标及内容工作流参数。
- `workflow_dynamic_style_platforms`：一个款式可有多个平台子行，保留平台画像表、启停状态和旧商品 ID 兼容快照。
- 旧 `workflow_dynamic_configs` 保留为原始迁移审计，不再参与运行时读取。
- `erp_codes`、`item_ids` 使用 PostgreSQL 数组，页面接受中英文逗号或换行并自动去重。
- `destinations` 使用通用 JSONB 目标列表，每项包含 `key`、`label`、`url`、`description`、`enabled`；六个旧目标字段仍同步保留，保证已有工作流兼容。后续新增分析逻辑只需增加一个稳定的 `key` 和对应飞书表地址。
- 款式带递增 `revision`；整页保存和删除必须提交 `If-Match`，避免并发覆盖。
- `cmt_styles.platform_product_ids` 的四个键固定为 `tm`（天猫）、`jd`（京东旗舰店）、`jd_self`（京东自营）、`dy`（抖音）；空数组表示该平台尚未补齐。

## 首次迁移

`config/workflow-dynamic-config-seed.json` 是 2026-08-19 从旧 Base 分页导出的只读迁移快照，
共 215 条源记录。项目第一次连接一个空数据库时会：

1. 幂等创建旧迁移审计表、款式父表和平台子表；
2. 在事务和 PostgreSQL advisory lock 内导入 215 条记录；
3. 写入迁移标记 `feishu-style-config-20260819-v1`；
4. 运行 v2 归一化迁移：按款式合并共享字段，按平台合并商品 ID；旧表中集中在天猫行的三平台画像地址分别迁入对应平台子行；
5. 写入迁移标记 `workflow-style-platform-config-20260819-v2`，此后不会重复迁移。

产品生命进程身份迁移随后执行 `product-lifecycle-style-identity-20260907-v1`：

1. 为 `cmt_styles` 补齐平台商品编码和大/小 NFC 字段；
2. 将已有 `dim_style` 的 ERP、天猫、京东、京东自营、抖音编码补入生命进程的空字段；
3. 对仍没有生命进程商品编码的旧动态配置做一次兼容提升；
4. 运行时以生命进程中的非空 JSONB 固定键为准，显式空数组会清除旧动态配置中的对应编码。

因此新增款式可先只填写 ERP 款式编码，等平台商品编码补齐后再进入对应采集；不会因为动态配置表
中残留旧编码而提前采集。

### 从旧飞书表重新校准生命进程

如果需要用现有“各平台款式 ID 收集表”补齐或校准生命进程身份，使用一次性同步脚本：

```powershell
uv run --env-file 'D:/product-collector-analyze-flow/.env' `
  --project 'D:/gyxx-flow' `
  python -m gyxx_flow.migration.sync_feishu_style_identity

uv run --env-file 'D:/product-collector-analyze-flow/.env' `
  --project 'D:/gyxx-flow' `
  python -m gyxx_flow.migration.sync_feishu_style_identity --apply

uv run --env-file 'D:/product-collector-analyze-flow/.env' `
  --project 'D:/gyxx-flow' `
  python 'src/gyxx_flow/modules/product_commerce/db/sync_dim_style.py'
```

脚本按款式合并旧表的多平台行，只写入 `cmt_styles` 的品牌、ERP 编码和四个平台商品编码，
不会覆盖 NFC、图片、类目或市场标签；空源字段不会清空生命进程已有身份。拼多多等当前四键
模型之外的平台只保留在动态平台配置/审计中，不会伪装成天猫、京东或抖音编码。默认是预览，
必须显式传 `--apply` 才会写数据库。

服务器必须注入 `GYXX_POSTGRES_DSN`，或完整的 `PG_HOST/PG_PORT/PG_DB/PG_USER/PG_PASSWORD`。
没有数据库且没有数据库生成的运行缓存时，相关工作流会明确失败，不会静默回读旧飞书主表。

## 运行时路径

```text
产品生命进程 cmt_styles (商品身份)
    +
workflow_dynamic_styles + workflow_dynamic_style_platforms (目标/画像/启停)
    ↓
统一运行时聚合
    ├─ 完整身份门 → StyleConfigLoader → 商品经营工作流
    └─ 目标兼容输出 → feishu_mapping    → 内容营销工作流 → 各业务飞书目标表
```

`StyleConfigLoader` 只在数据库短暂不可用时使用最近一次数据库成功读取后生成的本地缓存；
`feishu_mapping` 的目标表字段缓存仍保留，用来减少对各业务飞书表的字段查询。