M4: 采集管理（增量 / GS1 补全 / 去重冲突 / 质量评分 / 调度） #1

2026-06-08T17:27:58+08:00

lixu commented

2026-06-08 17:27:58 +08:00

目标

实现 M4 采集管理（在 M0–M3 已完成的地基/数据模型/OFF 采集/只读 API 之上），补齐持续运营所需能力：增量更新、第二数据源补全（GS1）、去重合并与字段级冲突解决、数据质量评分、定时调度。全部为 Python 侧（ingestion/），只写库、可单测。

改动

增量采集：OpenFoodFactsAdapter.fetch_modified_since() 用 OFF search API 按 last_modified_t 拉变更；etl/state.py + 新表 ingest_state（迁移 0004，可逆）持久化每源水位，GREATEST(...) 保证只前进。
GS1 补全：adapters/gs1.py（离线 JSON 映射 / GS1 风格 API 两种模式）+ etl/supplement.py，只填空缺字段（品牌/厂商/GPC/产地/净含量），记字段级溯源，源标记 gs1。
去重合并：etl/dedup.py 对非 GTIN 重复（同名+品牌+净含量）择质量最高者为主记录，子行（溯源/图片/MSRP）重指向，标 merged+canonical_id，写 merge_log。
冲突解决：etl/merge.py 多源同字段按「源权重 > 新鲜度」择优，保留 provenance。
质量评分：etl/quality.py 落到 product.quality_score，公式 0.4*完整度 + 0.3*源权重 + 0.2*多源一致 + 0.1*新鲜度，load_record()/merge_products() 写入后重算。
定时调度：jobs/schedule.py（零额外依赖的周期循环）+ jobs/update_off.py / jobs/dedup.py CLI。
文档：docs/ingestion-management.md。

测试

ruff check / ruff format --check 全过；pytest 33 passed（新增 19：纯函数 + 库集成）。
迁移 0004 up/down 可逆验证通过。
端到端核验：mock OFF → 增量 → transform → load → 水位前进（quality=0.810），去重/GS1 补全在库上验证。

注：库集成测试在无数据库或未应用 M4 迁移时自动跳过。

## 目标实现 **M4 采集管理**（在 M0–M3 已完成的地基/数据模型/OFF 采集/只读 API 之上），补齐持续运营所需能力：增量更新、第二数据源补全（GS1）、去重合并与字段级冲突解决、数据质量评分、定时调度。全部为 Python 侧（`ingestion/`），只写库、可单测。 ## 改动 - **增量采集**：`OpenFoodFactsAdapter.fetch_modified_since()` 用 OFF search API 按 `last_modified_t` 拉变更；`etl/state.py` + 新表 `ingest_state`（迁移 `0004`，可逆）持久化每源水位，`GREATEST(...)` 保证只前进。 - **GS1 补全**：`adapters/gs1.py`（离线 JSON 映射 / GS1 风格 API 两种模式）+ `etl/supplement.py`，只填**空缺**字段（品牌/厂商/GPC/产地/净含量），记字段级溯源，源标记 `gs1`。 - **去重合并**：`etl/dedup.py` 对非 GTIN 重复（同名+品牌+净含量）择质量最高者为主记录，子行（溯源/图片/MSRP）重指向，标 `merged`+`canonical_id`，写 `merge_log`。 - **冲突解决**：`etl/merge.py` 多源同字段按「源权重 > 新鲜度」择优，保留 provenance。 - **质量评分**：`etl/quality.py` 落到 `product.quality_score`，公式 `0.4*完整度 + 0.3*源权重 + 0.2*多源一致 + 0.1*新鲜度`，`load_record()`/`merge_products()` 写入后重算。 - **定时调度**：`jobs/schedule.py`（零额外依赖的周期循环）+ `jobs/update_off.py` / `jobs/dedup.py` CLI。 - **文档**：`docs/ingestion-management.md`。 ## 测试 - `ruff check` / `ruff format --check` 全过；`pytest` **33 passed**（新增 19：纯函数 + 库集成）。 - 迁移 `0004` up/down 可逆验证通过。 - 端到端核验：mock OFF → 增量 → transform → load → 水位前进（quality=0.810），去重/GS1 补全在库上验证。 > 注：库集成测试在无数据库或未应用 M4 迁移时自动跳过。

lixu added 1 commit 2026-06-08 17:27:58 +08:00

M4: ingestion management (incremental, GS1 supplement, dedup/conflict, quality, scheduler)

CI / Go (api) (pull_request) Has been cancelled

Details

CI / Python (ingestion) (pull_request) Has been cancelled

Details

CI / Migrations (postgres) (pull_request) Has been cancelled

Details

a35bcd6647

- OFF incremental fetch via search API + persistent watermark (ingest_state, migration 0004)
- GS1 barcode supplement adapter (offline mapping + GS1-style API) filling only gaps with field-level provenance
- Non-GTIN dedup with canonical selection + merge_log; field-level conflict resolution (source trust > recency)
- Quality scoring (0.4 completeness + 0.3 source trust + 0.2 multi-source + 0.1 freshness) wired into load/merge
- Jobs: update_off, dedup, schedule; docs/ingestion-management.md
- 19 new tests (pure + DB-integration), ruff clean

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

lixu merged commit 57537c880d into main

2026-06-08 17:40:26 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: lixu/goods#1