lixu/goods

Files

T

lixu 54175238ad docs: 归档天工·商品标签(OpenGoods)规划文档

新增 docs/planning/ 规划文档归档:
- 00-final-plan: 最终规划(决策+架构+M0~M5任务清单)
- 01-detailed-design-v2.0: 分类/单位/数据库/API/治理/采集/部署/众包
- 02-advanced-topics-v3.0: OpenAPI/全表DDL/数据契约/OFF映射/中国合规/测试/安全/图片/SLA/竞品
- history/: v0.1~v1.0 演进记录
更新 README 为项目介绍并链接规划文档。

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

2026-06-08 06:05:29 +00:00

5.4 KiB

Raw Permalink Blame History

天工·商品标签 (OpenGoods) — 最终规划 (Final)

公益网站/服务：采集全网商品信息，提供商品参数查询 API。 核心原则：只采集 + 只提供信息，绝不涉及任何购买/下单/比价导购。 本文档为前几版（v0.1 → v2.0）的最终收敛版，所有关键决策已锁定。详细设计见 v2.0 附件。

0. 项目标识

中文名：天工·商品标签（呼应《天工开物》）
英文名：OpenGoods
定位：开放、中立、可溯源的"商品参数百科 + 开放 API"

1. 已锁定的全部决策

维度	决策
首批品类	食品快消
价格	只收官方标准零售价 (MSRP)：静态字段，带 currency/region/source/effective_date + 免责；不收实时电商价、无购买入口
技术栈	Go(对外只读 API/核心服务) + Python(采集/ETL/爬虫)，经 PostgreSQL + Redis/队列解耦
种子数据	Open Food Facts 食品 dump 先导入，最快有真实数据
数据许可	对外数据库用 ODbL + 署名；CC0 来源(USDA)自由混入；每条数据按来源标注许可
商品分类	GS1 GPC 四层标准码 (Segment→Family→Class→Brick) 为骨架 + 自建中文品类树映射 + 保留来源原始分类
单位管理	量纲字典；原始值 + 归一化值双存；营养统一折算到 `per_100g/per_100ml`；能量双存 kJ+kcal；用十进制(NUMERIC)防误差
质量评分	`0.4完整度 + 0.3来源权威 + 0.2多源一致 + 0.1新鲜度`
众包	一期不做众包，先纯采集；二期再开放贡献/纠错（带审核与版本化）
Go 框架	`chi` + 标准库 `net/http`（轻量）
迁移工具	`golang-migrate`（纯 SQL，两端共享 schema）
部署	初期 Docker Compose（postgres+redis+minio+go-api+python-worker）→ 后期 K8s
地域	先用 OFF 全球食品库起步，后接 GS1-China 补强中国数据

2. 架构（定稿）

 数据源: OFF dump / OFF API / USDA(CC0) / GS1-China
        │
        ▼  Python: 采集 adapters → ETL(清洗/单位归一/分类映射/去重/质量评分)
        │  写入
   ┌────▼─────────┐   图片   ┌──────────┐
   │ PostgreSQL   │◀───────▶│ MinIO/S3 │
   │ (商品档案主库)│         └──────────┘
   └────▲─────────┘
        │  只读 (+Redis 缓存/限流)
        ▼  Go: 公开 REST API + OpenAPI 文档
   各种软件 / 开发者  (无任何交易端点)

两端不直接互调，通过共享 PostgreSQL schema + 《数据契约文档》协作。

3. 仓库结构（写代码时落地）

goods/  (OpenGoods 天工·商品标签)
├── README.md
├── LICENSE                          # 代码: Apache-2.0/MIT; 数据: ODbL 说明
├── docker-compose.yml
├── docs/{data-contract.md, openapi.yaml, disclaimer.md}
├── migrations/                      # golang-migrate 共享 SQL
├── api/                             # Go 只读 API (chi)
│   ├── cmd/server/main.go
│   └── internal/{handler,store,model,middleware}/
└── ingestion/                       # Python 采集 + ETL
    ├── adapters/{openfoodfacts,usda,gs1}.py
    ├── etl/{normalize_units,map_category,dedup,quality}.py
    └── jobs/{seed_off_dump,scheduler}.py

4. 最终可执行任务清单（按里程碑）

M0 — 工程地基（~3–5d）

Go module + Python 项目骨架
docker-compose（postgres+redis+minio）
CI（Go build/vet/test；Python ruff/pytest）
docs/data-contract.md、docs/disclaimer.md（不提供购买声明）初版

M1 — 数据模型 + 分类 + 单位（~4–6d）

migrations：product / food_detail / product_msrp / product_source / brand / manufacturer / category / category_schema / unit / attribute_definition / merge_log
导入 GS1 GPC 骨架 + 建自建中文品类树 + 映射表
单位字典 + 归一化规则
索引：gtin 唯一、name trigram、JSONB GIN、category ltree

M2 — 种子数据 (Python)（~5–8d）

下载 OFF 食品 dump → 字段映射（成分/营养/过敏原/图片）
单位归一 + 分类映射入库
USDA(CC0) 营养补全（可选）

M3 — MVP API (Go)（~5–8d）

端点：barcode / id / search / nutriments / msrp / brands / categories / sources / healthz
统一响应信封、分页、fields= 裁剪、错误码
Redis 缓存 + IP 限流 + OpenAPI 文档

M4 — 采集管线 (Python)（~8–12d）

adapter：OFF API 增量 + GS1 条码补全
ETL：清洗/归一/去重合并/冲突解决/质量评分/字段级溯源
调度（定时增量更新）

M5 — 开放与规模化（~10–15d）

搜索引擎（PG 全文 → OpenSearch）、CDN
免费 API Key（防滥用+统计）
众包贡献后台（提交/审核/版本/信誉）
开发者文档站 + 开放数据许可与免责声明上线

关键路径：M0→M1→M2→M3（最快拿到可查询 MVP）；M4/M5 后续并行迭代。

5. 下一步

规划已全部定稿。你之前说"先不写代码"，所以我停在这里待命。等你说"开始"，我从 M0 工程地基 动手，搭好骨架后开 PR 给你看（也可指定先只做某几个里程碑，例如 M0+M1）。

5.4 KiB Raw Permalink Blame History Unescape Escape