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
30 changed files with 1486 additions and 574 deletions
@@ -1,45 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-
-jobs:
-  go:
-    name: Go (api)
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: api
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-go@v5
-        with:
-          go-version: "1.23"
-          cache-dependency-path: api/go.sum
-      - name: Verify gofmt
-        run: test -z "$(gofmt -l .)"
-      - run: go vet ./...
-      - run: go build ./...
-      - run: go test ./...
-
-  python:
-    name: Python (ingestion)
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: ingestion
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-      - name: Install
-        run: pip install -e ".[dev]"
-      - name: Ruff lint
-        run: ruff check .
-      - name: Ruff format check
-        run: ruff format --check .
-      - name: Pytest
-        run: pytest -q
@@ -1,25 +0,0 @@
-# Go
-/api/server
-*.test
-*.out
-
-# Python
-__pycache__/
-*.py[cod]
-.venv/
-.pytest_cache/
-.ruff_cache/
-*.egg-info/
-build/
-dist/
-
-# Env / local
-.env
-.env.*
-!.env.example
-
-# OS / editors
-.DS_Store
-*.swp
-.idea/
-.vscode/
@@ -1,2 +1,24 @@
-# goods
-商品档案公开API
+# 天工·商品标签 (OpenGoods)
+
+商品档案公开 API —— 公益网站/服务：**采集全网商品信息，对外提供商品参数查询 API**。
+
+> 核心原则：**只采集 + 只提供信息，绝不涉及任何购买/下单/比价导购。**
+
+## 这是什么
+
+- 开放、中立、可溯源的「商品参数百科 + 开放 API」
+- 首批聚焦 **食品快消**，对外提供按条码/名称查询商品参数（成分、营养、规格、官方建议零售价等）
+- 技术栈：**Go**（对外只读 API） + **Python**（采集/ETL），经 PostgreSQL + Redis/队列解耦
+
+## 项目状态
+
+规划阶段。完整方案见 [`docs/planning/`](./docs/planning/README.md)：
+
+- [最终规划](./docs/planning/00-final-plan.md)（决策 + 架构 + 任务清单）
+- [详细设计 v2.0](./docs/planning/01-detailed-design-v2.0.md)（分类/单位/数据库/API/治理/采集/部署）
+- [进阶专题 v3.0](./docs/planning/02-advanced-topics-v3.0.md)（OpenAPI/DDL/合规/测试/安全/SLA/竞品）
+
+## 许可
+
+- 代码：拟用 Apache-2.0 / MIT（待定）
+- 数据：拟用 **ODbL + 署名**（因采用 Open Food Facts 等开放数据源）
@@ -1,13 +0,0 @@
-# Build stage
-FROM golang:1.23-alpine AS build
-WORKDIR /src
-COPY go.mod go.sum ./
-RUN go mod download
-COPY . .
-RUN CGO_ENABLED=0 go build -o /out/server ./cmd/server
-
-# Runtime stage
-FROM gcr.io/distroless/static-debian12
-COPY --from=build /out/server /server
-EXPOSE 8080
-ENTRYPOINT ["/server"]
@@ -1,26 +0,0 @@
-// Command server starts the OpenGoods public read-only API.
-package main
-
-import (
-	"log"
-	"net/http"
-	"time"
-
-	"github.com/baicai2026-baicai/goods/api/internal/config"
-	"github.com/baicai2026-baicai/goods/api/internal/handler"
-)
-
-func main() {
-	cfg := config.Load()
-
-	srv := &http.Server{
-		Addr:              cfg.Addr,
-		Handler:           handler.Router(),
-		ReadHeaderTimeout: 10 * time.Second,
-	}
-
-	log.Printf("OpenGoods API listening on %s", cfg.Addr)
-	if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-		log.Fatalf("server error: %v", err)
-	}
-}
@@ -1,5 +0,0 @@
-module github.com/baicai2026-baicai/goods/api
-
-go 1.23.4
-
-require github.com/go-chi/chi/v5 v5.1.0
@@ -1,2 +0,0 @@
-github.com/go-chi/chi/v5 v5.1.0 h1:acVI1TYaD+hhedDJ3r54HyA6sExp3HfXq7QWEEY/xMw=
-github.com/go-chi/chi/v5 v5.1.0/go.mod h1:DslCQbL2OYiznFReuXYUmQ2hGd1aDpCnlMNITLSKoi8=
@@ -1,30 +0,0 @@
-package config
-
-import (
-	"os"
-)
-
-// Config holds runtime configuration for the OpenGoods API server.
-// Values are read from environment variables with sensible defaults so the
-// server can boot in a local Docker Compose setup without extra configuration.
-type Config struct {
-	Addr        string
-	DatabaseURL string
-	RedisURL    string
-}
-
-// Load reads configuration from the environment.
-func Load() Config {
-	return Config{
-		Addr:        getenv("OPENGOODS_ADDR", ":8080"),
-		DatabaseURL: getenv("OPENGOODS_DATABASE_URL", "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable"),
-		RedisURL:    getenv("OPENGOODS_REDIS_URL", "redis://localhost:6379/0"),
-	}
-}
-
-func getenv(key, fallback string) string {
-	if v, ok := os.LookupEnv(key); ok && v != "" {
-		return v
-	}
-	return fallback
-}
@@ -1,68 +0,0 @@
-// Package handler wires up the public, read-only OpenGoods HTTP API.
-//
-// The OpenGoods service is a public-good product information API: it only
-// collects and serves product facts. It exposes no purchase, checkout, or
-// commerce endpoints by design.
-package handler
-
-import (
-	"encoding/json"
-	"net/http"
-
-	"github.com/go-chi/chi/v5"
-	"github.com/go-chi/chi/v5/middleware"
-)
-
-// APIVersion is the current public API version prefix.
-const APIVersion = "v1"
-
-// Router builds the top-level HTTP handler with middleware and routes mounted.
-func Router() http.Handler {
-	r := chi.NewRouter()
-	r.Use(middleware.RequestID)
-	r.Use(middleware.RealIP)
-	r.Use(middleware.Recoverer)
-
-	r.Get("/healthz", Healthz)
-
-	r.Route("/api/"+APIVersion, func(r chi.Router) {
-		r.Route("/products", func(r chi.Router) {
-			r.Get("/barcode/{gtin}", notImplemented)
-			r.Get("/search", notImplemented)
-			r.Get("/{id}", notImplemented)
-			r.Get("/{id}/nutriments", notImplemented)
-			r.Get("/{id}/msrp", notImplemented)
-		})
-		r.Get("/brands", notImplemented)
-		r.Get("/categories", notImplemented)
-		r.Get("/sources/{id}", notImplemented)
-	})
-
-	return r
-}
-
-// Healthz reports liveness of the service.
-func Healthz(w http.ResponseWriter, r *http.Request) {
-	writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
-}
-
-// notImplemented is a placeholder for endpoints scoped to later milestones.
-func notImplemented(w http.ResponseWriter, r *http.Request) {
-	writeError(w, r, http.StatusNotImplemented, "not_implemented", "endpoint not implemented yet")
-}
-
-func writeJSON(w http.ResponseWriter, status int, body any) {
-	w.Header().Set("Content-Type", "application/json; charset=utf-8")
-	w.WriteHeader(status)
-	_ = json.NewEncoder(w).Encode(body)
-}
-
-func writeError(w http.ResponseWriter, r *http.Request, status int, code, message string) {
-	writeJSON(w, status, map[string]any{
-		"error": map[string]string{
-			"code":       code,
-			"message":    message,
-			"request_id": middleware.GetReqID(r.Context()),
-		},
-	})
-}
@@ -1,38 +0,0 @@
-package handler
-
-import (
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-)
-
-func TestHealthz(t *testing.T) {
-	req := httptest.NewRequest(http.MethodGet, "/healthz", nil)
-	rec := httptest.NewRecorder()
-
-	Router().ServeHTTP(rec, req)
-
-	if rec.Code != http.StatusOK {
-		t.Fatalf("expected status %d, got %d", http.StatusOK, rec.Code)
-	}
-
-	var body map[string]string
-	if err := json.NewDecoder(rec.Body).Decode(&body); err != nil {
-		t.Fatalf("failed to decode body: %v", err)
-	}
-	if body["status"] != "ok" {
-		t.Fatalf("expected status ok, got %q", body["status"])
-	}
-}
-
-func TestProductEndpointNotImplemented(t *testing.T) {
-	req := httptest.NewRequest(http.MethodGet, "/api/"+APIVersion+"/products/barcode/3017624010701", nil)
-	rec := httptest.NewRecorder()
-
-	Router().ServeHTTP(rec, req)
-
-	if rec.Code != http.StatusNotImplemented {
-		t.Fatalf("expected status %d, got %d", http.StatusNotImplemented, rec.Code)
-	}
-}
@@ -1,61 +0,0 @@
-services:
-  postgres:
-    image: postgres:16-alpine
-    environment:
-      POSTGRES_USER: opengoods
-      POSTGRES_PASSWORD: opengoods
-      POSTGRES_DB: opengoods
-    ports:
-      - "5432:5432"
-    volumes:
-      - pgdata:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U opengoods"]
-      interval: 5s
-      timeout: 5s
-      retries: 5
-
-  redis:
-    image: redis:7-alpine
-    ports:
-      - "6379:6379"
-    healthcheck:
-      test: ["CMD", "redis-cli", "ping"]
-      interval: 5s
-      timeout: 5s
-      retries: 5
-
-  minio:
-    image: minio/minio:latest
-    command: server /data --console-address ":9001"
-    environment:
-      MINIO_ROOT_USER: opengoods
-      MINIO_ROOT_PASSWORD: opengoods123
-    ports:
-      - "9000:9000"
-      - "9001:9001"
-    volumes:
-      - miniodata:/data
-    healthcheck:
-      test: ["CMD", "mc", "ready", "local"]
-      interval: 5s
-      timeout: 5s
-      retries: 5
-
-  api:
-    build: ./api
-    depends_on:
-      postgres:
-        condition: service_healthy
-      redis:
-        condition: service_healthy
-    environment:
-      OPENGOODS_ADDR: ":8080"
-      OPENGOODS_DATABASE_URL: "postgres://opengoods:opengoods@postgres:5432/opengoods?sslmode=disable"
-      OPENGOODS_REDIS_URL: "redis://redis:6379/0"
-    ports:
-      - "8080:8080"
-
-volumes:
-  pgdata:
-  miniodata:
@@ -1,36 +0,0 @@
-# 数据契约 (Data Contract) v0.1
-
-本契约是 Go(API) 与 Python(ingestion) 两端共享的"事实约定"，避免两端对字段含义理解不一致。
-
-> 写入责任：**仅 Python (ingestion) 通过 ETL 写入数据库**；Go (API) **只读**。所有写入必须经过单位归一化与字段级溯源。
-
-## 1. 边界原则
- 系统只采集与提供**客观商品信息**；不包含任何购买/交易语义的字段或端点。
- 价格仅收录**官方建议零售价 (MSRP)** 的静态快照，必须带 `currency`/`region`/`source`/`effective_date`。
-
-## 2. 固定枚举
-| 字段 | 取值 |
-|------|------|
-| `product.status` | `active` / `merged` / `deprecated` |
-| `food_detail.nutrition_basis` | `per_100g` / `per_100ml` / `per_serving` |
-| `unit.dimension` | `mass` / `volume` / `energy` / `count` / `ratio` / `length` / `duration` |
-| `source.license` | `ODbL` / `CC0` / `proprietary` / ... |
-| `product_image.kind` | `front` / `ingredients` / `nutrition` / `other` |
-
-## 3. 单位规则
- 数值字段同时保存**原始值 + 单位**与**归一化值 + 基准单位**（canonical）。
- 质量 → `g`，体积 → `ml`，能量 → `kJ`（同时保留 `kcal`）。
- 归一化逻辑由 `ingestion/opengoods/units.py` 提供（纯函数，含测试），换算因子是唯一事实来源。
- 营养成分统一折算到品类模板规定的基准（`per_100g` / `per_100ml`）。
-
-## 4. 标识与可空性
- `product.gtin`：8/12/13/14 位数字，可空（无条码商品），非空时全局唯一。
- `product.quality_score` ∈ [0, 1]。
- 货币用 ISO 4217（`CNY` 等），国家/地区用简短代码（`CN` 等）。
-
-## 5. 溯源 (Provenance)
- 每条数据通过 `product_source` 记录来源、URL、贡献字段、抓取时间与原始快照。
- 对外 API 在 `sources` 中透明返回来源与其许可。
-
-## 6. 版本
- 本契约随 schema 演进版本化；任何 schema 变更需同步更新：迁移(SQL) + 本契约 + `docs/openapi.yaml`。
@@ -1,11 +0,0 @@
-# 免责声明 (Disclaimer)
-
-天工·商品标签 (OpenGoods) 是一个**公益信息平台**。
-
- 本站**仅提供商品参数信息，不提供任何购买、下单、比价或导购服务**，不包含任何购买入口或交易链接。
- 商品参数（成分、营养、规格等）来自多个数据来源并标注出处，可能存在误差或滞后；**请以商品实物标签为准**。
- 价格字段仅为**官方建议零售价 (MSRP) 的历史快照**，标注来源与时间，实际售价以零售商为准，**不构成消费或购买建议**。
- 本站不提供医疗、健康或功效宣称。
- 数据按各来源许可使用（详见各条数据的 `sources` 字段与来源说明）；权利方可通过公开渠道申请更正或下架。
-
-> The OpenGoods service only collects and serves product information for public benefit. It provides **no purchase, checkout, price-comparison, or shopping-guide functionality**.
@@ -0,0 +1,115 @@
+# 天工·商品标签 (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）。
@@ -0,0 +1,373 @@
+# 商品档案公益 API 系统 — 深化规划 (v2.0)
+
+> 在 v1.0 定稿基础上，全面展开 8 个方向，并新增 **商品分类体系** 与 **单位管理体系** 两章。
+> 不变原则：**只采集 + 只提供信息，绝不涉及购买/交易行为。** 全文仍为规划，未写代码。
+
+**目录**
+- A. 商品分类体系（新增）
+- B. 单位管理体系（新增）
+- 1. 数据库详细设计
+- 2. API 详细契约
+- 3. 数据治理（去重/冲突/质量评分/溯源）
+- 4. 采集合规细则
+- 5. 部署与运维
+- 6. 众包贡献流程
+- 7. 项目治理（域名/许可/免责）
+- 8. 时间与里程碑估算
+
+---
+
+## A. 商品分类体系（Taxonomy）
+
+商品分类是整个档案库的骨架，直接影响搜索、参数模板、去重。建议**对齐国际标准 + 自建可读品类树**双轨。
+
+### A.1 采用 GS1 GPC 作为标准骨架
+GS1 **GPC（Global Product Classification）** 是四层、规则化的全球商品分类，8 位数字编码：
+
+```
+Segment(段) → Family(族) → Class(类) → Brick(砖)
+47000000     47100000      47101800    10000xxx
+清洁/卫生     清洁用品       ...          具体品类(GTIN挂这里)
+```
+- 全球 44 个 Segment，食品快消主要落在 **Food/Beverage/Tobacco** 与 **Cleaning/Hygiene** 等段。
+- **Brick** 是最细粒度，商品(GTIN)挂在 brick 上；每个 brick 可带 ≤25 个属性，正好对应我们的"品类参数模板"。
+- 好处：与 GS1/电商/数据池天然对齐，便于将来对接 OFF、USDA、GS1-China。
+
+### A.2 三层映射策略
+| 层 | 用途 | 来源 |
+|----|------|------|
+| **标准码 (gpc_brick_code)** | 机器对齐、跨源映射 | GS1 GPC |
+| **自建品类树 (category)** | 人类可读、网站导航、中文友好 | 自建，映射到 GPC |
+| **来源原始分类 (source_category)** | 保留溯源 | OFF categories / USDA / GS1 |
+
+> OFF 有自己的 categories taxonomy（标签式、多语言），导入时做 `OFF category → 自建 category → GPC brick` 的映射表，未命中的进人工/众包校对队列。
+
+### A.3 品类参数模板（Category Schema）
+每个叶子品类定义"应有哪些参数"，用于：① 数据完整度评分 ② 录入/校验约束 ③ API 返回结构提示。
+```jsonc
+// category_schema 示例: 包装水
+{
+  "category_id": "beverage/packaged_water",
+  "gpc_brick_code": "10000159",
+  "required_attributes": ["net_content", "shelf_life"],
+  "recommended_attributes": ["ph", "tds", "water_type"],
+  "nutriment_basis": "per_100ml"
+}
+```
+
+### A.4 分类落地要点
+- 分类树存为**邻接表 + 物化路径**（`path` 列，便于子树查询）。
+- 多对一：一个商品归一个主品类(primary)，可挂多个辅助标签(labels)。
+- 分类可演进：用 `category_version` 管理重命名/合并，旧 ID 重定向不破坏 API。
+
+---
+
+## B. 单位管理体系（Units）
+
+食品参数单位混乱（g/kg/ml/L/份/%/kcal/kJ…），必须有统一的**单位字典 + 量纲 + 归一化**机制，否则无法比较和检索。
+
+### B.1 量纲与基准单位
+| 量纲 (dimension) | 基准单位 (canonical) | 常见单位 |
+|------------------|----------------------|----------|
+| 质量 mass | g | mg, g, kg, 斤, oz, lb |
+| 体积 volume | ml | ml, L, cl, fl oz |
+| 能量 energy | kJ | kJ, kcal（同时存两者） |
+| 数量 count | 个 | 个/瓶/包/片/粒 |
+| 比例 ratio | %（或无量纲） | %, ‰, mg/100g |
+| 长度 length | mm | mm, cm, m, in |
+| 时间(保质期) duration | 天 | 天/月/年 |
+
+### B.2 单位字典 `unit`
+```jsonc
+{
+  "code": "kg",
+  "dimension": "mass",
+  "to_canonical_factor": 1000,     // 1 kg = 1000 g
+  "canonical": "g",
+  "aliases": ["千克", "公斤", "kgs"],
+  "display": "kg"
+}
+```
+
+### B.3 归一化规则
+- **入库双存**：原始值/单位 `{value, unit}` + 归一化值 `{canonical_value, canonical_unit}`，原始保留供溯源与展示。
+- **营养基准统一**：全部折算到 `per_100g` 或 `per_100ml`（按品类模板决定），并保留 `serving_size` 原值。
+- **能量双单位**：同时存 kJ + kcal（1 kcal ≈ 4.184 kJ），缺一个则自动换算并标记 `derived=true`。
+- **不可换算**：count（个/瓶）等不跨量纲换算；只做单位别名归一。
+- **精度与舍入**：用十进制（`NUMERIC`）避免浮点误差；记录有效数字。
+- **冲突处理**：单位无法识别 → 入"待清洗队列"，不丢数据。
+
+### B.4 单位与 API
+- API 默认返回**原始单位 + 归一化值**两套；可加 `?unit_system=metric|original` 控制展示。
+- 搜索/过滤一律基于 canonical 值（如"热量<200kcal/100g"）。
+
+---
+
+## 1. 数据库详细设计
+
+PostgreSQL。核心：关系表 + JSONB 灵活属性 + 结构化营养子表。以下为 DDL 草案（写代码时落到 `migrations/`）。
+
+### 1.1 ER 概览
+```
+brand 1───* product *───1 category ───* category_schema
+manufacturer 1───* product
+product 1───1 food_detail
+product 1───* product_msrp
+product 1───* product_source     (溯源, 字段级)
+product *───* attribute (via product_attribute, 或 JSONB)
+unit (字典)   attribute_definition (参数字典)
+contribution / merge_log / source (治理与登记)
+```
+
+### 1.2 关键建表草案（节选）
+```sql
+CREATE TABLE product (
+  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  gtin          VARCHAR(14) UNIQUE,            -- 可空(无条码商品)
+  name          TEXT NOT NULL,
+  brand_id      UUID REFERENCES brand(id),
+  manufacturer_id UUID REFERENCES manufacturer(id),
+  category_id   UUID REFERENCES category(id),
+  gpc_brick_code VARCHAR(8),
+  net_content_value   NUMERIC,
+  net_content_unit    VARCHAR(16),
+  net_content_canonical NUMERIC,               -- 归一化(g/ml)
+  country_of_origin   VARCHAR(64),
+  shelf_life_days     INT,
+  storage       TEXT,
+  attributes    JSONB DEFAULT '{}',            -- 灵活参数
+  quality_score NUMERIC(4,3) DEFAULT 0,
+  status        VARCHAR(16) DEFAULT 'active',
+  created_at    TIMESTAMPTZ DEFAULT now(),
+  updated_at    TIMESTAMPTZ DEFAULT now()
+);
+
+CREATE TABLE food_detail (
+  product_id    UUID PRIMARY KEY REFERENCES product(id) ON DELETE CASCADE,
+  ingredients_text TEXT,
+  ingredients   JSONB,                          -- [{name,rank}]
+  allergens     TEXT[],
+  additives     TEXT[],
+  nutriments    JSONB,                           -- 见单位章, 归一到 per_100g/ml
+  nutrition_basis VARCHAR(16),
+  serving_size  VARCHAR(32),
+  nutri_score   CHAR(1),
+  labels        TEXT[]
+);
+
+CREATE TABLE product_msrp (
+  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  product_id    UUID REFERENCES product(id) ON DELETE CASCADE,
+  amount        NUMERIC(12,2) NOT NULL,
+  currency      CHAR(3) NOT NULL,               -- ISO 4217
+  region        VARCHAR(8) DEFAULT 'CN',
+  source_id     UUID REFERENCES source(id),
+  source_url    TEXT,
+  effective_date DATE,
+  note          TEXT,
+  created_at    TIMESTAMPTZ DEFAULT now()
+);
+
+CREATE TABLE product_source (                    -- 字段级溯源
+  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  product_id    UUID REFERENCES product(id) ON DELETE CASCADE,
+  source_id     UUID REFERENCES source(id),
+  url           TEXT,
+  fields        TEXT[],                          -- 该来源贡献了哪些字段
+  fetched_at    TIMESTAMPTZ,
+  raw           JSONB                             -- 原始快照
+);
+```
+
+### 1.3 索引策略
+- `product.gtin` 唯一索引；`product.name` 用 `pg_trgm` GIN（模糊搜索）。
+- `product.attributes` 与 `food_detail.nutriments` 建 **JSONB GIN** 索引（参数检索）。
+- `category.path` 用 `ltree` 或前缀索引（子树查询）。
+- 全文检索：初期 `tsvector`(name+brand+ingredients) GIN；规模化后迁 OpenSearch。
+- 时间列 `updated_at` 索引（增量同步）。
+
+---
+
+## 2. API 详细契约
+
+只读、版本化、统一信封。下面给核心端点的示例。
+
+### 2.1 按条码查询（最常用）
+```
+GET /api/v1/products/barcode/3017624010701?fields=name,brand,nutriments,msrp
+```
+```jsonc
+{
+  "data": {
+    "id": "…", "gtin": "3017624010701",
+    "name": "示例牌 巧克力榛子酱 400g", "brand": "示例牌",
+    "category": "食品/酱料/巧克力酱",
+    "net_content": {"value":400,"unit":"g","canonical":{"value":400,"unit":"g"}},
+    "food": {
+      "nutriments": {"energy_kcal":539,"energy_kj":2255,"fat_g":30.9,"sugars_g":56.3,"salt_g":0.107},
+      "nutrition_basis":"per_100g", "allergens":["坚果","乳","大豆"]
+    },
+    "msrp": {"amount":29.90,"currency":"CNY","region":"CN","effective_date":"2026-01-01",
+             "note":"官方建议零售价, 本站不提供购买"}
+  },
+  "meta": {"version":"v1"},
+  "sources": [{"source":"Open Food Facts","url":"…","fetched_at":"…","license":"ODbL"}]
+}
+```
+
+### 2.2 搜索
+```
+GET /api/v1/products/search?q=巧克力&brand=示例牌&category=酱料&allergen_free=花生&page=1&size=20&fields=…
+```
+返回 `data:[…]` + `meta:{page,size,total,total_pages}`。
+
+### 2.3 端点清单 & 错误码
+| 端点 | 说明 |
+|------|------|
+| `GET /products/barcode/{gtin}` | 条码查 |
+| `GET /products/{id}` | ID 查 |
+| `GET /products/search` | 搜索/过滤/分页 |
+| `GET /products/{id}/nutriments` | 仅营养 |
+| `GET /products/{id}/msrp` | 仅官方价(含免责) |
+| `GET /brands` `GET /categories` | 品牌 / 品类树 |
+| `GET /sources/{id}` | 数据来源透明说明 |
+| `GET /healthz` `GET /openapi.json` | 健康检查 / 机读文档 |
+
+错误码：`400`(参数错) `404`(未找到, 返回 `{error:{code:"not_found"}}`) `429`(限流, 带 `Retry-After`) `5xx`(服务端)。统一错误信封 `{error:{code,message,request_id}}`。
+
+### 2.4 跨切面
+- **版本化** `/v1/`；破坏性变更升 `/v2/`，旧版保留过渡期。
+- **限流**：匿名 IP 默认 60 req/min（可调）；免费 API Key 提配额。响应头 `X-RateLimit-*`。
+- **缓存**：`Cache-Control` + ETag；CDN + Redis；条码查命中率高。
+- **CORS**：开放 GET（公益 API）。
+- **分页**：`page/size`（上限 100）；大结果集用 `search_after` 游标（OpenSearch 阶段）。
+
+---
+
+## 3. 数据治理
+
+### 3.1 实体去重 / 匹配
+1. **强匹配**：相同 `gtin` → 同一商品（条码是天然主键）。
+2. **弱匹配**（无 gtin 或 gtin 缺失）：`(规范化品牌 + 规范化型号/名称 + 净含量)` 相似度（trigram/编辑距离）+ 阈值；命中候选进**人工/众包确认**，不自动硬合并。
+3. **合并**：保留一条 canonical，其余标 `status=merged` 并写 `merge_log`（可回滚）。
+
+### 3.2 多源字段冲突解决
+- 每个字段记录来源 + 时间 + 来源可信度权重。
+- 冲突时：① 按**来源可信度**（GS1官方 > 厂商官网 > OFF众包 > 第三方）② 同级取**最新** ③ 数值类可取多数/中位数。
+- 保留所有来源值于 `product_source.raw`，对外 `sources` 字段透明展示"该字段来自谁"。
+
+### 3.3 质量评分公式（0~1）
+```
+quality_score = 0.4*完整度 + 0.3*来源权威度 + 0.2*多源一致性 + 0.1*新鲜度
+  完整度   = 命中品类模板 required/recommended 字段的比例
+  权威度   = 贡献字段的来源权重加权
+  一致性   = 多源同字段一致的比例
+  新鲜度   = 最近更新时间衰减
+```
+低分商品在搜索中降权，并进入"待补全"队列（可派给众包）。
+
+### 3.4 溯源（Provenance）
+字段级溯源：每条数据可回答"这个营养值/价格来自哪个来源、什么时间、什么许可"。这是公益项目可信度的核心，也用于许可合规标注。
+
+---
+
+## 4. 采集合规细则
+
+### 4.1 通用护栏
+- 严格遵守 `robots.txt` 与各源服务条款；礼貌限速（OFF 读 ≤15 req/min/IP）；错峰；明确 `User-Agent` 标识本项目身份与联系方式。
+- 只采**客观参数**；不照搬受版权保护的营销文案/评测原文（链接来源即可）。
+- 增量优先：用 `last_modified`/dump 差异做增量，避免重复抓取。
+
+### 4.2 各源接入步骤
+| 源 | 步骤 | 许可 |
+|----|------|------|
+| **OFF dump**（首批种子） | 下载 `en.openfoodfacts.org.products.csv.gz`(~0.9G压缩) → 解析 → 映射字段 → 入库 | ODbL（衍生库需 ODbL+署名） |
+| **OFF API**（增量） | 按 gtin 拉取/按更新时间增量；遵守限速 | 同上 |
+| **USDA FoodData Central** | 申请免费 API key；或下载 Branded/Foundation JSON；补全营养 | CC0（最宽松） |
+| **GS1 / 中国商品信息服务平台** | 条码→品牌/规格/厂商；API ≤1000 GTIN/次（需授权） | 受限，按授权使用 |
+| **厂商官网** | 逐站 adapter，遵守 robots，取官方规格表/MSRP | 取客观参数 |
+
+### 4.3 许可合规
+- OFF=ODbL（传染性，衍生数据库须同样开放+署名 OFF）；USDA=CC0。
+- 对外数据库整体采用 **ODbL + 署名**；每条数据按 `sources[].license` 标注其来源许可，避免冲突。
+
+---
+
+## 5. 部署与运维
+
+### 5.1 演进路径
+- **初期**：Docker Compose 一键起 `postgres + redis + minio + go-api + python-worker`，单机即可跑通 MVP。
+- **成长期**：API 多副本 + 读副本数据库 + CDN；worker 横向扩展。
+- **规模化**：K8s（API Deployment + HPA、worker Job/CronJob）、OpenSearch 集群、对象存储用云 S3。
+
+### 5.2 可观测性
+- 指标：Prometheus（QPS、延迟、缓存命中、限流计数、采集成功率）。
+- 日志：结构化日志 + request_id 贯穿。
+- 链路：OpenTelemetry（API → DB）。
+- 告警：错误率/延迟/采集失败/磁盘。
+
+### 5.3 备份与可靠性
+- Postgres 每日全量 + WAL 归档；定期恢复演练。
+- 对象存储多版本/冗余。
+- 采集 worker 幂等 + 重试 + 死信队列。
+
+### 5.4 成本（量级估算，公益项目控成本）
+- MVP：单台小型云主机（2C4G）+ 对象存储即可（月成本很低）。
+- OFF 食品子集约数百万条，PG 单实例可承载；图片走对象存储 + CDN（按流量）。
+- 详细预算待定（取决于云厂商与访问量），可后续出一版成本表。
+
+---
+
+## 6. 众包贡献流程
+
+公益库靠社区补全/纠错。流程：
+1. **提交**：用户对某商品提交新增/修改（带可选来源链接、照片）。
+2. **校验**：单位/格式/品类模板校验 + 反垃圾（限频、信誉分、验证码）。
+3. **审核**：低风险字段自动接受并标 `source=community`；高风险（价格、品牌）进人工/资深用户审核队列。
+4. **版本化**：每次修改存历史版本，可 diff、可回滚（类似 wiki）。
+5. **信誉系统**：贡献被采纳提升信誉；高信誉用户审核权更大。
+6. **溯源透明**：众包数据与官方数据在 `sources` 中明确区分。
+
+> 注意：众包内容也要遵守"只客观信息、不导购"，并保留权利方下架通道。
+
+---
+
+## 7. 项目治理（域名/许可/免责）
+
+- **品牌/域名**：建议中性、表意清晰的名字（如 *商品档案 / OpenGoods* 之类），后续选定。
+- **代码许可**：开源（如 MIT/Apache-2.0），鼓励复用。
+- **数据许可**：**ODbL + 署名**（因含 OFF）；API 文档明示再利用条款。
+- **隐私**：不收集个人数据(PII)，只处理商品信息；众包账号信息最小化。
+- **免责声明（站点显著位置）**：
+  - "本站为公益信息平台，**仅提供商品参数信息，不提供任何购买/交易服务**。"
+  - "价格为官方建议零售价历史快照，实际售价以零售商为准，**不构成消费或购买建议**。"
+  - "数据来自多来源并标注出处，可能存在误差；欢迎纠错，权利方可申请更正/下架。"
+- **下架/纠错渠道**：公开邮箱/表单，承诺响应时限。
+
+---
+
+## 8. 时间与里程碑估算
+
+> 仅为相对工作量估算（以"理想工作日"计，非承诺排期）；实际取决于投入人力与数据源接入难度。
+
+| 里程碑 | 内容 | 估算 | 依赖 | 主要风险 |
+|--------|------|------|------|----------|
+| **M0 地基** | Go/Python 骨架、Compose、CI、数据契约 | 3–5 d | — | 低 |
+| **M1 数据模型** | 迁移、分类树、单位字典、参数模板 | 4–6 d | M0 | 分类/单位建模需打磨 |
+| **M2 种子数据** | OFF dump 导入 + 单位归一 + 分类映射 | 5–8 d | M1 | dump 体量大、字段映射脏 |
+| **M3 MVP API(Go)** | 端点 + 缓存/限流 + OpenAPI | 5–8 d | M1,M2 | 检索性能调优 |
+| **M4 采集管线(Python)** | OFF/GS1 adapter + ETL + 去重 + 质量分 + 调度 | 8–12 d | M2 | 去重/冲突算法、合规 |
+| **M5 开放/规模化** | 搜索引擎、CDN、API Key、众包后台、文档站 | 10–15 d | M3,M4 | 众包审核与防滥用 |
+
+关键路径：M0→M1→M2→M3（最快拿到可查询 MVP）；M4/M5 可与后续并行迭代。
+
+---
+
+## 9. 待确认（本版新增点）
+1. **分类标准**：认同以 **GS1 GPC** 为标准骨架 + 自建中文品类树映射吗？
+2. **单位策略**：营养统一折算到 `per_100g/per_100ml`、能量双存 kJ+kcal，认同吗？
+3. **质量评分权重**：上面的 0.4/0.3/0.2/0.1 权重是否合适，或你有偏好？
+4. **众包**：第一阶段就要做众包贡献，还是先纯采集、后期再开放众包？
+5. **项目命名/域名**：有想好的名字吗？没有的话我可以提几个候选。
+
+> 确认后我把 v2.0 收敛为可执行的工程任务清单。需要动手写代码时你说一声，我从 M0 开始搭骨架开 PR。
@@ -0,0 +1,408 @@
+# 天工·商品标签 (OpenGoods) — 深化规划 (v3.0)
+
+> 在最终版基础上，展开全部 10 个进阶方向。仍为规划，未写代码。
+> 原则不变：**只采集 + 只提供信息，绝不涉及购买/交易。**
+
+**目录**
+1. 完整 OpenAPI 规范草案
+2. 完整数据库 DDL
+3. 数据契约文档
+4. OFF 字段映射表
+5. 中国合规专项
+6. 测试与数据质量保障
+7. 安全与反滥用
+8. 商品图片处理
+9. 可用性与 SLA
+10. 竞品 / 同类项目分析
+
+---
+
+## 1. 完整 OpenAPI 规范草案（节选骨架，写代码时落到 `docs/openapi.yaml`）
+
+```yaml
+openapi: 3.1.0
+info:
+  title: OpenGoods API (天工·商品标签)
+  version: "1.0.0"
+  description: >
+    公益商品参数查询 API。只提供信息，不提供购买/交易。
+    数据采用 ODbL 许可并署名来源。
+  license: {name: ODbL-1.0, url: https://opendatacommons.org/licenses/odbl/}
+servers:
+  - {url: https://api.opengoods.org/api/v1}
+paths:
+  /products/barcode/{gtin}:
+    get:
+      summary: 按条码查询商品档案
+      parameters:
+        - {name: gtin, in: path, required: true, schema: {type: string, pattern: '^[0-9]{8,14}$'}}
+        - {name: fields, in: query, schema: {type: string}, description: 逗号分隔字段裁剪}
+      responses:
+        '200': {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/ProductEnvelope'}}}}
+        '404': {description: 未找到, content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}}
+        '429': {description: 限流, headers: {Retry-After: {schema: {type: integer}}}}
+  /products/{id}:
+    get: { summary: 按ID查询, parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}], responses: {'200': {description: OK}} }
+  /products/search:
+    get:
+      summary: 搜索/过滤/分页
+      parameters:
+        - {name: q, in: query, schema: {type: string}}
+        - {name: brand, in: query, schema: {type: string}}
+        - {name: category, in: query, schema: {type: string}}
+        - {name: allergen_free, in: query, schema: {type: string}}
+        - {name: page, in: query, schema: {type: integer, default: 1}}
+        - {name: size, in: query, schema: {type: integer, default: 20, maximum: 100}}
+      responses: {'200': {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/SearchEnvelope'}}}}}
+  /products/{id}/nutriments: {get: {summary: 仅营养}}
+  /products/{id}/msrp:       {get: {summary: 仅官方零售价(含免责)}}
+  /brands:      {get: {summary: 品牌列表}}
+  /categories:  {get: {summary: 品类树}}
+  /sources/{id}:{get: {summary: 数据来源透明说明}}
+  /healthz:     {get: {summary: 健康检查}}
+components:
+  schemas:
+    ProductEnvelope:
+      type: object
+      properties:
+        data: {$ref: '#/components/schemas/Product'}
+        meta: {type: object}
+        sources: {type: array, items: {$ref: '#/components/schemas/SourceRef'}}
+    Product:
+      type: object
+      properties:
+        id: {type: string, format: uuid}
+        gtin: {type: string}
+        name: {type: string}
+        brand: {type: string}
+        category: {type: string}
+        net_content: {$ref: '#/components/schemas/Quantity'}
+        food: {$ref: '#/components/schemas/FoodDetail'}
+        msrp: {$ref: '#/components/schemas/Msrp'}
+        quality_score: {type: number}
+    Quantity:
+      type: object
+      properties: {value: {type: number}, unit: {type: string}, canonical: {type: object}}
+    FoodDetail:
+      type: object
+      properties:
+        ingredients_text: {type: string}
+        allergens: {type: array, items: {type: string}}
+        additives: {type: array, items: {type: string}}
+        nutriments: {type: object}
+        nutrition_basis: {type: string, enum: [per_100g, per_100ml, per_serving]}
+        nutri_score: {type: string}
+    Msrp:
+      type: object
+      properties:
+        amount: {type: number}
+        currency: {type: string}
+        region: {type: string}
+        effective_date: {type: string, format: date}
+        note: {type: string, default: "官方建议零售价, 本站不提供购买"}
+    SourceRef:
+      type: object
+      properties: {source: {type: string}, url: {type: string}, fetched_at: {type: string}, license: {type: string}}
+    Error:
+      type: object
+      properties: {error: {type: object, properties: {code: {type: string}, message: {type: string}, request_id: {type: string}}}}
+```
+
+> 该 `openapi.yaml` 既是契约也是文档源：Go 端用它做路由校验/生成 Swagger UI，客户端可由它生成 SDK。
+
+---
+
+## 2. 完整数据库 DDL（全部表）
+
+```sql
+-- 扩展
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+CREATE EXTENSION IF NOT EXISTS ltree;
+-- gen_random_uuid() 由 pgcrypto 提供
+
+CREATE TABLE source (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name TEXT NOT NULL,                  -- Open Food Facts / USDA / GS1-China ...
+  homepage TEXT,
+  license TEXT,                        -- ODbL / CC0 / proprietary
+  trust_weight NUMERIC(3,2) DEFAULT 0.5, -- 来源可信度(冲突解决用)
+  notes TEXT
+);
+
+CREATE TABLE brand (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name TEXT NOT NULL,
+  normalized_name TEXT,                -- 规范化(去空格/大小写/全半角)用于匹配
+  aliases TEXT[],
+  UNIQUE(normalized_name)
+);
+
+CREATE TABLE manufacturer (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name TEXT NOT NULL,
+  normalized_name TEXT,
+  country VARCHAR(64),
+  UNIQUE(normalized_name)
+);
+
+CREATE TABLE category (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name_zh TEXT NOT NULL,
+  name_en TEXT,
+  parent_id UUID REFERENCES category(id),
+  path LTREE,                          -- 物化路径, 子树查询
+  gpc_brick_code VARCHAR(8),           -- 映射到 GS1 GPC
+  level INT,
+  UNIQUE(path)
+);
+
+CREATE TABLE category_schema (         -- 品类参数模板
+  category_id UUID PRIMARY KEY REFERENCES category(id),
+  required_attributes TEXT[],
+  recommended_attributes TEXT[],
+  nutriment_basis VARCHAR(16)
+);
+
+CREATE TABLE unit (                    -- 单位字典
+  code VARCHAR(16) PRIMARY KEY,
+  dimension VARCHAR(16) NOT NULL,      -- mass/volume/energy/count/ratio/length/duration
+  canonical VARCHAR(16) NOT NULL,
+  to_canonical_factor NUMERIC,         -- code -> canonical 的换算因子
+  aliases TEXT[],
+  display TEXT
+);
+
+CREATE TABLE attribute_definition (    -- 参数字典(标准名/别名/单位)
+  key VARCHAR(64) PRIMARY KEY,
+  label_zh TEXT, label_en TEXT,
+  dimension VARCHAR(16),
+  default_unit VARCHAR(16) REFERENCES unit(code),
+  aliases TEXT[]
+);
+
+CREATE TABLE product (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  gtin VARCHAR(14) UNIQUE,
+  name TEXT NOT NULL,
+  brand_id UUID REFERENCES brand(id),
+  manufacturer_id UUID REFERENCES manufacturer(id),
+  category_id UUID REFERENCES category(id),
+  gpc_brick_code VARCHAR(8),
+  net_content_value NUMERIC,
+  net_content_unit VARCHAR(16),
+  net_content_canonical NUMERIC,
+  country_of_origin VARCHAR(64),
+  shelf_life_days INT,
+  storage TEXT,
+  attributes JSONB DEFAULT '{}',
+  quality_score NUMERIC(4,3) DEFAULT 0,
+  status VARCHAR(16) DEFAULT 'active', -- active/merged/deprecated
+  canonical_id UUID REFERENCES product(id), -- 被合并到哪个
+  search_tsv TSVECTOR,
+  created_at TIMESTAMPTZ DEFAULT now(),
+  updated_at TIMESTAMPTZ DEFAULT now()
+);
+
+CREATE TABLE food_detail (
+  product_id UUID PRIMARY KEY REFERENCES product(id) ON DELETE CASCADE,
+  ingredients_text TEXT,
+  ingredients JSONB,
+  allergens TEXT[],
+  additives TEXT[],
+  nutriments JSONB,
+  nutrition_basis VARCHAR(16),
+  serving_size VARCHAR(32),
+  nutri_score CHAR(1),
+  labels TEXT[]
+);
+
+CREATE TABLE product_msrp (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  product_id UUID REFERENCES product(id) ON DELETE CASCADE,
+  amount NUMERIC(12,2) NOT NULL,
+  currency CHAR(3) NOT NULL,
+  region VARCHAR(8) DEFAULT 'CN',
+  source_id UUID REFERENCES source(id),
+  source_url TEXT,
+  effective_date DATE,
+  note TEXT,
+  created_at TIMESTAMPTZ DEFAULT now()
+);
+
+CREATE TABLE product_image (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  product_id UUID REFERENCES product(id) ON DELETE CASCADE,
+  url TEXT,                            -- 对象存储 URL
+  kind VARCHAR(16),                    -- front/ingredients/nutrition
+  license TEXT,
+  source_id UUID REFERENCES source(id)
+);
+
+CREATE TABLE product_source (          -- 字段级溯源
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  product_id UUID REFERENCES product(id) ON DELETE CASCADE,
+  source_id UUID REFERENCES source(id),
+  url TEXT,
+  fields TEXT[],
+  fetched_at TIMESTAMPTZ,
+  raw JSONB
+);
+
+CREATE TABLE merge_log (               -- 合并/回滚
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  kept_id UUID, merged_id UUID,
+  reason TEXT, by TEXT, created_at TIMESTAMPTZ DEFAULT now()
+);
+
+-- 索引
+CREATE UNIQUE INDEX idx_product_gtin ON product(gtin) WHERE gtin IS NOT NULL;
+CREATE INDEX idx_product_name_trgm ON product USING gin (name gin_trgm_ops);
+CREATE INDEX idx_product_attrs ON product USING gin (attributes);
+CREATE INDEX idx_food_nutriments ON food_detail USING gin (nutriments);
+CREATE INDEX idx_product_tsv ON product USING gin (search_tsv);
+CREATE INDEX idx_category_path ON category USING gist (path);
+CREATE INDEX idx_product_updated ON product(updated_at);
+```
+
+---
+
+## 3. 数据契约文档（`docs/data-contract.md` 概要）
+
+两端共享的"事实约定"，避免 Go/Python 理解不一致：
+- **枚举固定**：`status`(active/merged/deprecated)、`nutrition_basis`(per_100g/per_100ml/per_serving)、`dimension`、`source.license`、`image.kind`。
+- **字段含义与可空性**：逐字段写明（如 `gtin` 可空、唯一；`quality_score` ∈ [0,1]）。
+- **单位规则**：原始 + canonical 双存；能量双存 kJ/kcal；换算因子来自 `unit` 表。
+- **写入责任**：仅 Python(ingestion) 写库；Go 只读。所有写入走 ETL，保证归一化与溯源。
+- **版本**：契约本身版本化；schema 变更需同步更新契约 + 迁移 + OpenAPI。
+- **示例**：附 1 条完整 product JSON 作为"黄金样例"，两端测试都对它断言。
+
+---
+
+## 4. OFF（Open Food Facts）字段映射表（导入直接用）
+
+| OFF 字段 (CSV) | OpenGoods 字段 | 处理 |
+|----------------|----------------|------|
+| `code` | `product.gtin` | 校验 8/12/13/14 位 + 校验位 |
+| `product_name` / `product_name_zh` | `product.name` | 优先中文, 回退英文 |
+| `brands` | `brand.name` | 拆分取首个, 规范化, upsert brand |
+| `categories` / `categories_tags` | `source_category` → `category` | 走 OFF→自建→GPC 映射表 |
+| `quantity` | `net_content_*` | 解析数值+单位 → 归一化 |
+| `countries` | `country_of_origin` | 取销售国/产地 |
+| `ingredients_text` | `food_detail.ingredients_text` | 原文保留 |
+| `allergens_tags` | `food_detail.allergens` | 标签清洗为中文 |
+| `additives_tags` | `food_detail.additives` | E-number 解析 |
+| `energy-kj_100g` / `energy-kcal_100g` | `nutriments.energy_kj/kcal` | 缺一个则换算, 标 derived |
+| `fat_100g` `saturated-fat_100g` `carbohydrates_100g` `sugars_100g` `proteins_100g` `salt_100g` | `nutriments.*` | 归一 per_100g |
+| `nutriscore_grade` | `food_detail.nutri_score` | A–E |
+| `serving_size` | `food_detail.serving_size` | 原值 |
+| `image_url` / `image_front_url` 等 | `product_image.url` | 下载转存对象存储, 记 CC-BY-SA |
+| `last_modified_t` | `product_source.fetched_at` | 增量基准 |
+| (整行) | `product_source.raw` | 存原始快照 |
+
+> 许可：OFF 数据=ODbL（衍生库需同样开放+署名）；图片=CC-BY-SA。映射时全程记 `source_id=OFF`。
+
+---
+
+## 5. 中国合规专项（公益网站落地关键）
+
+> 以下为工程与运营层面的合规要点梳理，**非法律意见**；正式上线前建议咨询专业法务。
+
+### 5.1 网站备案
+- 服务器在中国大陆 → 需 **ICP 备案**（公益网站可走非经营性 ICP 备案）；部分地区/类目可能涉 **公安联网备案**。
+- 若用境外/港澳服务器可免 ICP，但访问速度与合规另作权衡。
+
+### 5.2 数据合规（网络安全法 / 数据安全法 / 个人信息保护法）
+- 本项目**只处理商品信息、不收集个人信息(PII)**，PIPL 风险低；众包阶段涉及用户账号时再做最小化收集 + 隐私政策。
+- 《数据安全法》要求数据收集合法正当；做好数据分级与安全保护义务。
+
+### 5.3 网络爬虫法律边界（重点）
+依据中央网信办公开文章与司法实践，判断标准是**客观结果**——是否妨碍目标网站正常运行 / 危害合法权益：
+- **守 robots.txt**、礼貌限速、错峰，**不得对目标站造成 DDoS 式压力**（否则可能触及破坏计算机信息系统罪等）。
+- **不抓取非公开/需登录/绕过反爬**的数据（可能涉非法获取计算机信息系统数据罪）。
+- 只采**客观公开的商品参数**；不抓取受版权保护内容、不抓个人信息。
+- 优先用**官方开放数据/API/数据 dump**（OFF dump、USDA、GS1 授权）——从源头规避爬虫风险。
+
+### 5.4 食品信息合规
+- 展示食品参数时注明"信息仅供参考，以实物标签为准"；营养/成分以官方/厂商标签为准。
+- 不做医疗/功效宣称；不构成消费建议。
+
+### 5.5 价格与"不导购"
+- 价格仅为**官方建议零售价历史快照**，显著标注；**全站无购买/下单/跳转购买链接**，避免被认定为经营性电商导购。
+
+---
+
+## 6. 测试与数据质量保障
+
+### 6.1 代码测试
+- **Go**：handler 单元测试 + store 层用 `testcontainers`/临时 PG 集成测试 + API 契约测试（对 openapi.yaml 校验响应）。
+- **Python**：ETL 纯函数单测（单位归一、分类映射、去重打分）+ adapter 用录制的样例数据测试（不打真实站点）。
+- **CI**：PR 必跑 lint + test；覆盖率门槛（如 ETL 核心 ≥80%）。
+
+### 6.2 数据质量
+- **入库校验**：gtin 校验位、单位可识别、营养数值合理区间、必填字段（按品类模板）。
+- **质量评分**：见 v2.0 公式，低分进"待补全"队列。
+- **数据回归**：黄金样例集 + 定期跑"数据健康检查"（孤儿记录、单位异常、重复 gtin、营养越界）。
+- **可观测**：导入报表（新增/更新/拒绝条数、拒绝原因 top）。
+
+---
+
+## 7. 安全与反滥用
+
+- **API 防刷**：IP 限流 + 可选 API Key 分级配额；异常流量识别（突发高频降级/挑战）。
+- **缓存挡压**：热点条码走 CDN/Redis，降低数据库压力，也抗刷。
+- **输入校验**：所有参数严格校验（gtin 正则、size 上限），防注入（参数化查询，禁拼 SQL）。
+- **密钥管理**：DB/对象存储/第三方 key 走环境变量/密钥管理，不入库不入仓。
+- **最小权限**：Go 端用**只读** DB 账号；写权限仅 ingestion。
+- **采集端被封应对**：合规限速 + 失败退避 + 死信队列 + 切换为官方 dump/API。
+- **DDoS**：CDN + 速率限制 + 云厂商防护；公益服务以可降级（只读缓存）保命。
+- **依赖安全**：Go `govulncheck`、Python `pip-audit`，CI 中扫描。
+
+---
+
+## 8. 商品图片处理
+
+- **版权**：OFF 图片为 CC-BY-SA，须署名 + 同样开放；逐图记 `license` 与来源。
+- **存储**：对象存储(MinIO/S3)，路径按 `gtin/kind`；原图 + 生成多档缩略图(thumb/medium)。
+- **处理管线**：下载 → 校验(类型/大小) → 去重(感知哈希避免重复) → 压缩 → 生成缩略图 → 记录。
+- **分发**：CDN 加速；API 只返回图片 URL，不内嵌二进制。
+- **合规**：不展示含个人信息的图；提供权利方下架通道。
+- **降级**：图片缺失返回占位；图片服务故障不影响参数 API。
+
+---
+
+## 9. 可用性与 SLA
+
+| 项 | 目标(建议) |
+|----|-----------|
+| API 可用性 | 99.5%（公益项目务实目标，先保只读可用） |
+| 读延迟 | p95 < 200ms（缓存命中 < 50ms） |
+| 数据新鲜度 | 增量同步 T+1（每日） |
+| 降级策略 | DB 故障 → 只读缓存兜底；图片/搜索故障不影响核心参数查询 |
+| 灾备 | 每日备份 + 异地副本；恢复演练季度一次 |
+| 维护窗口 | 采集/重建索引放低峰；API 滚动发布不停服 |
+
+> 公益项目优先"省成本 + 稳定只读"；写入(采集)可异步、可补偿，读路径要稳。
+
+---
+
+## 10. 竞品 / 同类项目分析
+
+| 项目 | 性质 | 数据 | 借鉴点 | 与我们差异 |
+|------|------|------|--------|------------|
+| **Open Food Facts** | 公益食品库 | ODbL, 海量, 可贡献, 有 dump/API | 字段模型、众包、Nutri-Score、API 设计 | 我们多语言架构(Go API)、聚焦中文/GPC、收 MSRP |
+| **USDA FoodData Central** | 政府营养库 | CC0, 权威营养 | 营养数据补全、公共领域许可 | 偏美国/营养, 无条码生态 |
+| **GS1 / Verified by GS1** | 官方条码登记 | 受限, 权威, 2亿+ | 条码→品牌/规格权威源 | 非开放、需授权 |
+| **Wikidata** | 通用知识库 | CC0, 有 GTIN 属性(P3962) | 实体链接、结构化、开放 | 非商品专用、参数不规整 |
+| **schema.org Product/gtin** | 数据标准 | 标准而非数据 | 用其词汇做对外结构化(SEO/互操作) | 仅规范, 需我们填数据 |
+| **brocade.io / 各条码库** | 开放/商业条码库 | 参差 | 条码补全兜底 | 数据量/质量有限或收费 |
+
+**结论与定位**：
+- 我们不是再造 OFF，而是做**面向中文世界、与 GS1 GPC 对齐、聚焦"商品参数标签"**的公益 API；
+- **站在巨人肩上**：OFF/USDA 做种子与营养，GS1 做条码权威，Wikidata/schema.org 做实体与互操作标准；
+- 差异化：中文优先、品类参数模板规整、官方 MSRP、字段级溯源、Go 高并发只读 API。
+
+---
+
+## 11. 小结
+v3.0 已把工程落地与公益合规的关键面全部展开。规划层面已相当完整。
+你之前说先不写代码，我**继续待命**：可以再深化任何一块，或等你说"开始"，从 M0 搭骨架开 PR。
@@ -0,0 +1,40 @@
+# 天工·商品标签 (OpenGoods) — 规划文档归档
+
+本目录归档了项目从立项到方案定稿的全部规划文档。
+
+## 项目一句话
+公益网站/服务：**采集全网商品信息，对外提供商品参数查询 API**。
+核心原则：**只采集 + 只提供信息，绝不涉及任何购买/下单/比价导购。**
+
+## 当前文档（最新，建议优先阅读）
+
+| 文档 | 内容 |
+|------|------|
+| [00-final-plan.md](./00-final-plan.md) | **最终规划**：锁定的全部决策 + 架构 + 仓库结构 + M0~M5 可执行任务清单 |
+| [01-detailed-design-v2.0.md](./01-detailed-design-v2.0.md) | **详细设计**：商品分类体系(GS1 GPC)、单位管理、数据库设计、API 契约、数据治理、采集合规、部署运维、众包、里程碑估算 |
+| [02-advanced-topics-v3.0.md](./02-advanced-topics-v3.0.md) | **进阶专题**：完整 OpenAPI、全表 DDL、数据契约、OFF 字段映射、中国合规专项、测试、安全反滥用、图片处理、SLA、竞品分析 |
+
+## 演进历史（History）
+
+| 文档 | 阶段 |
+|------|------|
+| [history/v0.1-initial-plan.md](./history/v0.1-initial-plan.md) | 初版总体规划 |
+| [history/v0.2-go-python-foodfmcg.md](./history/v0.2-go-python-foodfmcg.md) | 确定 Go+Python 架构、聚焦食品快消、数据源调研 |
+| [history/v1.0-locked-decisions.md](./history/v1.0-locked-decisions.md) | 决策定稿（默认值） |
+
+## 已锁定的关键决策（速览）
+
+| 维度 | 决策 |
+|------|------|
+| 首批品类 | 食品快消 |
+| 价格 | 只收官方标准零售价 (MSRP)，静态字段，无购买入口 |
+| 技术栈 | Go（对外只读 API） + Python（采集/ETL），经 PostgreSQL + Redis/队列解耦 |
+| 种子数据 | Open Food Facts 食品 dump |
+| 数据许可 | 对外 ODbL + 署名；CC0 来源(USDA)自由混入 |
+| 商品分类 | GS1 GPC 四层标准码 + 自建中文品类树映射 |
+| 单位管理 | 原始值+归一化双存；营养统一 per_100g/ml；能量双存 kJ+kcal |
+| 质量评分 | 0.4 完整度 + 0.3 来源权威 + 0.2 多源一致 + 0.1 新鲜度 |
+| 众包 | 一期不做，先纯采集；二期开放 |
+| Go 框架 / 迁移 / 部署 | chi + 标准库 / golang-migrate / Docker Compose |
+
+> 注：文档中"中国合规专项"为工程与运营层面梳理，**非法律意见**；正式上线前请咨询专业法务。
@@ -0,0 +1,216 @@
+# 商品档案公益 API 系统 — 规划方案 (v0.1)
+
+> 一个公益性质的网站/服务：**采集全网商品信息**，对外提供**商品参数查询 API**。
+> 核心原则：**只收集信息、只提供信息，不涉及任何购买、下单、比价导购等交易行为。**
+
+---
+
+## 1. 项目定位与原则
+
+| 维度 | 说明 |
+|------|------|
+| 定位 | 公益的"商品参数百科 / 商品档案库"，类似商品界的 Wikipedia + 开放 API |
+| 提供什么 | 商品的客观参数（规格、型号、成分、能效、尺寸、条码等） |
+| **不提供什么** | 价格交易、加购物车、下单、跳转购买链接、联盟分佣、比价导购 |
+| 服务对象 | 第三方软件 / 开发者，通过 API 查询商品参数 |
+| 数据态度 | 客观、中立、可溯源（每条数据标注来源与采集时间） |
+
+> ⚠️ 关于价格：建议**默认不收录价格**。价格属于交易属性，且实时性强、争议大。如果一定要做，只做"历史参考价"且明确标注来源时间，绝不提供购买入口。**这一点需要你确认。**
+
+---
+
+## 2. 系统总体架构
+
+```
+                        ┌─────────────────────────────┐
+                        │        数据来源 (Sources)     │
+                        │  官网/厂商 / 开放数据 / GS1   │
+                        │  条码库 / 用户贡献 / 监管公开 │
+                        └──────────────┬──────────────┘
+                                       │
+            ┌──────────────────────────▼──────────────────────────┐
+            │            采集层 Ingestion (Workers)                │
+            │  爬虫调度 + 适配器 + 限速 + robots 合规 + 去重        │
+            └──────────────────────────┬──────────────────────────┘
+                                       │  原始数据 (raw)
+            ┌──────────────────────────▼──────────────────────────┐
+            │         清洗/标准化 ETL (Normalize & Dedup)          │
+            │  字段映射 / 单位归一 / 实体匹配 / 质量评分            │
+            └──────────────────────────┬──────────────────────────┘
+                                       │  结构化商品档案
+            ┌──────────────────────────▼──────────────────────────┐
+            │             存储层 Storage                            │
+            │  PostgreSQL(主) + 对象存储(图片) + 搜索引擎(检索)     │
+            └──────────────────────────┬──────────────────────────┘
+                                       │
+            ┌──────────────────────────▼──────────────────────────┐
+            │            公开 API 服务 (FastAPI)                    │
+            │  REST/JSON + 文档 + 限流 + 缓存 + API Key(可选)       │
+            └──────────────────────────┬──────────────────────────┘
+                                       │
+                        ┌──────────────▼──────────────┐
+                        │   消费者：各种软件/开发者     │
+                        └─────────────────────────────┘
+```
+
+分为四个相对独立的子系统：
+1. **采集子系统**（爬虫/适配器，离线运行）
+2. **数据处理子系统**（清洗、标准化、去重、质量评分）
+3. **存储子系统**（关系库 + 搜索 + 对象存储）
+4. **API 子系统**（对外只读公开 API + 文档站）
+
+---
+
+## 3. 核心数据模型（商品档案 Schema）
+
+商品的本质是"一个实体 + 一组可扩展的参数"。建议采用 **核心字段 + 灵活属性(KV)** 的混合模型，以适配不同品类（手机、食品、家电、化妆品……参数差异极大）。
+
+### 3.1 核心实体
+
+```jsonc
+// Product 商品档案
+{
+  "id": "uuid",                       // 内部唯一ID
+  "gtin": "6901234567892",            // 全球贸易项目代码(条码), 可空
+  "name": "示例牌 1.5L 纯净水",
+  "brand": "示例牌",                   // -> Brand 实体
+  "manufacturer": "示例食品有限公司",
+  "category": "饮料/包装水",            // -> Category 树
+  "model": "型号/SKU标识",
+  "description": "客观描述, 非营销文案",
+  "images": ["对象存储URL", ...],
+  "attributes": [                      // 灵活参数(见下)
+    {"key": "容量", "value": "1.5", "unit": "L"},
+    {"key": "保质期", "value": "12", "unit": "月"}
+  ],
+  "identifiers": {                     // 其他标识
+    "ean": "...", "upc": "...", "asin": "...", "mpn": "..."
+  },
+  "sources": [                         // 数据溯源(每个字段可标来源)
+    {"source_id": "...", "url": "...", "fetched_at": "2026-06-08T...", "field": "容量"}
+  ],
+  "quality_score": 0.87,               // 数据质量/可信度评分
+  "status": "active|merged|deprecated",
+  "created_at": "...", "updated_at": "..."
+}
+```
+
+### 3.2 灵活属性 (EAV / JSONB)
+- 不同品类参数差异巨大，核心表存通用字段，品类专属参数存 `attributes`（PostgreSQL `JSONB`，可建 GIN 索引）。
+- 配合**品类参数模板**（Category Schema）约束某品类应有哪些参数，保证质量。
+
+### 3.3 辅助实体
+- `Brand`（品牌）、`Manufacturer`（厂商）、`Category`（品类树）、`Source`（数据来源登记）、`AttributeDefinition`（参数字典：标准名/别名/单位）。
+- 实体去重/合并需要 `merge` 机制（同一商品多来源 → 合并为一条，保留溯源）。
+
+---
+
+## 4. 数据采集策略（最关键、也最需合规）
+
+### 4.1 来源优先级（从"最合规"到"需谨慎"）
+1. **官方开放数据 / 标准库**：GS1 条码库、各国监管公开数据（能效标识、食品备案、药品/化妆品备案等）。✅ 最佳
+2. **厂商官网 / 官方规格表**：参数最权威。需遵守 robots.txt。
+3. **厂商/平台开放 API**：若有官方 API 走 API。
+4. **用户/社区贡献**：众包补全与纠错（带审核）。
+5. **第三方网页抓取**：⚠️ 合规风险最高，需严格遵守 robots、限速、只取客观参数、标注来源。
+
+### 4.2 采集器设计
+- **适配器模式**：每个来源一个 adapter（解析规则独立、可热插拔）。
+- **调度**：任务队列（Celery / RQ / arq）+ 定时（cron）+ 增量更新。
+- **合规护栏**：尊重 `robots.txt`、礼貌限速、`User-Agent` 标识身份、错峰、缓存避免重复抓取。
+- **去重与匹配**：以 GTIN/条码为主键，无条码时用 (品牌+型号+关键参数) 做模糊匹配。
+
+### 4.3 数据质量
+- 每个字段记录来源 + 时间；多来源冲突时按来源可信度加权。
+- 质量评分 `quality_score`：字段完整度 + 来源权威度 + 一致性。
+
+---
+
+## 5. 公开 API 设计（只读、RESTful）
+
+基础原则：**只读、无副作用、无购买入口、稳定版本化、有文档**。
+
+```
+GET  /api/v1/products/{id}                 # 按内部ID查询商品档案
+GET  /api/v1/products/barcode/{gtin}       # 按条码(GTIN/EAN/UPC)查询  ★最常用
+GET  /api/v1/products/search               # 搜索: ?q=&brand=&category=&page=&size=
+GET  /api/v1/products/{id}/attributes      # 仅取参数
+GET  /api/v1/brands / categories           # 品牌/品类树
+GET  /api/v1/sources/{id}                  # 数据来源说明(透明溯源)
+GET  /healthz  /  /api/v1/openapi.json     # 健康检查 / 机读文档
+```
+
+设计要点：
+- **版本化** `/api/v1/`，破坏性变更升 `v2`。
+- **分页 + 字段筛选**（`fields=` 减少传输）。
+- **限流**：匿名按 IP 限流；可选 API Key 提升配额（免费，仅用于防滥用与统计）。
+- **缓存**：CDN + 服务端缓存（商品参数变化慢，缓存命中率高）。
+- **响应统一**：JSON，含 `data` / `meta`(分页) / `sources`(溯源)。
+- **开放协议**：数据采用开放许可（如 CC BY / ODbL），鼓励署名引用。
+- **自动文档**：FastAPI 自带 Swagger UI / ReDoc。
+
+---
+
+## 6. 技术选型建议
+
+| 层 | 选型 | 理由 |
+|----|------|------|
+| API 框架 | **Python + FastAPI** | 与仓库定位一致、异步性能好、自带 OpenAPI 文档 |
+| 主数据库 | **PostgreSQL** (JSONB) | 关系 + 灵活属性兼得，GIN 索引支持检索 |
+| 搜索 | **OpenSearch / Elasticsearch / 或 PG 全文** | 商品名/参数全文与分面检索 |
+| 缓存 | **Redis** | 热点缓存 + 限流计数 + 任务队列后端 |
+| 采集任务 | **arq / Celery / RQ** | 异步调度爬虫与 ETL |
+| 爬虫 | **httpx + selectolax/BeautifulSoup**，动态页用 **Playwright** | 轻量为主，必要时浏览器渲染 |
+| 对象存储 | **S3 兼容 (MinIO / 云)** | 存商品图片 |
+| 部署 | **Docker + Compose**(初期) → K8s(规模化) | 渐进式 |
+| 文档站 | FastAPI 文档 + 静态站(MkDocs) | 开发者文档 |
+
+> 如果你更偏好 Node.js / Go 也可以，我按你的偏好调整。仓库描述像是 FastAPI，所以我默认 Python。
+
+---
+
+## 7. 合规与法律（公益项目尤其重要）
+
+- **爬取合规**：遵守 robots.txt、服务条款、合理限速；只采集**客观商品参数**，不抓取受版权保护的营销文案/评测原文（可链接来源）。
+- **数据来源透明**：每条数据可溯源，标注来源与时间，尊重原始来源。
+- **隐私**：只处理商品信息，不涉及个人数据（无 PII）。
+- **商标/品牌**：品牌名仅用于客观标识商品，不做背书或贬损。
+- **明确边界**：网站显著声明"仅提供信息、不提供购买、不构成消费建议"。
+- **数据开放许可**：选择 CC BY 4.0 或 ODbL，明确他人使用条款。
+- **下架机制**：提供来源方/权利方的纠错与下架联系渠道。
+
+> 建议这块后续找法务/合规确认，我可以先把"合规护栏"写进采集器与站点声明。
+
+---
+
+## 8. 建议的实施路线图（分阶段，先跑起来再扩展）
+
+**阶段 0 — 地基（先做）**
+- 仓库工程化：FastAPI 项目骨架、PostgreSQL、Docker Compose、CI、代码规范。
+- 定义核心数据模型 + 迁移。
+
+**阶段 1 — MVP API**
+- 实现只读 API：按条码/ID 查询 + 搜索 + 自动文档。
+- 导入一批种子数据（用开放数据/手工录入几百条），让 API 真正可用。
+
+**阶段 2 — 采集管线**
+- 1~2 个合规来源的 adapter + 调度 + 清洗/去重/入库。
+- 质量评分与溯源。
+
+**阶段 3 — 规模化与开放**
+- 搜索引擎、缓存/CDN、限流、API Key、众包贡献与审核后台。
+- 开放数据许可与开发者文档站上线。
+
+---
+
+## 9. 需要你拍板的关键问题
+
+1. **是否收录价格？**（建议默认不收录，只做客观参数）
+2. **首批聚焦哪些品类？**（如：食品/快消、3C 数码、家电…… 建议先聚焦 1~2 个品类把模型打磨好）
+3. **技术栈确认 Python + FastAPI 吗？**（还是有其他偏好）
+4. **数据来源**：你手上有没有已知的合规数据源 / 官方 API / 已有数据集？
+5. **首要交付**：先搭"可查询的 MVP API + 一批种子数据"，还是先做"采集管线"？（建议先 MVP API）
+
+---
+
+> 这是 v0.1 规划草案，确认大方向后我会细化成可执行的工程任务，并开始搭建仓库骨架 + MVP。
@@ -0,0 +1,203 @@
+# 商品档案公益 API 系统 — 规划方案 (v0.2)
+
+> 公益网站/服务：**采集全网商品信息**，对外提供**商品参数查询 API**。
+> 原则：**只收集 + 只提供信息，不涉及任何购买/下单/比价导购**。
+> 本版根据你的反馈定稿四件事：① 收录**官方标准零售价(MSRP)** ② 首批聚焦**食品快消** ③ **Go(系统) + Python(采集)** 多语言架构 ④ 附**开放数据源清单**。
+
+---
+
+## 0. 你已确认的决策
+
+| # | 决策 | 说明 |
+|---|------|------|
+| 1 | **价格 = 官方标准零售价 (MSRP)** | 厂商指导价/官方建议零售价，属**静态属性**，带来源+时间+币种标注；**不收录实时电商售价、不提供购买入口** |
+| 2 | **首批品类 = 食品快消 (Food & FMCG)** | 先把食品的数据模型打磨好（成分、营养、过敏原、规格、保质期…） |
+| 3 | **技术栈 = Go + Python** | Go 写对外 API/核心服务；Python 写采集/ETL/爬虫；通过 PostgreSQL + 消息队列解耦 |
+| 4 | **数据源 = 暂无，后期提供** | 本版先给出可立即接入的开放数据源清单 |
+
+---
+
+## 1. Go + Python 多语言架构（核心）
+
+这是一个很经典且合理的组合。两端**不直接互相调用**，而是通过**共享数据库 + 消息队列**解耦，各自独立部署、独立扩展。
+
+```
+            ┌────────────────────── Python 侧 (采集/数据) ──────────────────────┐
+            │                                                                    │
+   数据源 ─▶│  采集 Workers (爬虫/适配器)  ─▶  ETL 清洗/标准化/去重  ─▶  入库     │
+            │  httpx / Playwright / scrapy     pandas / 规则引擎                  │
+            └───────────────────────────┬────────────────────────────────────────┘
+                                        │ 写入
+                                ┌───────▼────────┐        ┌──────────────┐
+                                │  PostgreSQL    │◀──────▶│  对象存储 S3  │ (商品图)
+                                │  (商品档案主库) │        └──────────────┘
+                                └───────▲────────┘
+                                        │ 只读
+            ┌───────────────────────────┴────────────────────────────────────────┐
+            │                          Go 侧 (对外服务)                            │
+            │  公开 API (REST/JSON)  +  Redis 缓存/限流  +  搜索网关  +  OpenAPI    │
+            │  Gin/Echo/Chi/标准库                                                 │
+            └───────────────────────────┬────────────────────────────────────────┘
+                                        │
+                              各种软件 / 开发者消费
+```
+
+### 1.1 职责划分
+
+| 子系统 | 语言 | 职责 |
+|--------|------|------|
+| **公开 API 服务** | **Go** | 对外只读 API、限流、缓存、鉴权(可选 API Key)、检索网关、高并发承载 |
+| **采集 Workers** | **Python** | 每个数据源一个 adapter，抓取/调用 API、遵守 robots、限速、产出原始数据 |
+| **ETL / 数据处理** | **Python** | 清洗、字段映射、单位归一、实体去重与合并、质量评分 |
+| **调度 / 队列** | Python(worker) + Redis/消息队列 | 定时任务、增量更新、任务分发 |
+| **存储** | PostgreSQL + Redis + S3 | 主库 / 缓存+限流 / 图片 |
+| **检索** | 初期 PG 全文 → 后期 OpenSearch | 商品名/参数搜索与分面 |
+
+### 1.2 为什么这样分？
+- **Go 做 API**：编译型、单二进制部署、并发模型适合高 QPS 的只读公益 API，运维简单。
+- **Python 做采集**：爬虫/解析/数据处理生态最强（scrapy、playwright、pandas），迭代快。
+- **解耦点 = 数据库**：Go 端**只读**主库（或读副本），Python 端负责写入。两端通过稳定的表结构约定协作，互不阻塞；将来任一端换语言/重写都不影响另一端。
+- **契约**：用数据库 schema + 一份内部「数据契约文档」固定字段含义，避免两端理解不一致。
+
+---
+
+## 2. 食品快消数据模型（细化）
+
+食品参数差异大，沿用 **核心字段 + JSONB 灵活属性 + 营养结构化子表**。字段设计大量参考 Open Food Facts（成熟的食品开放库）。
+
+### 2.1 商品主表 `product`
+```jsonc
+{
+  "id": "uuid",
+  "gtin": "6901234567892",            // 条码(主键标识), EAN-13/UPC/EAN-8
+  "name": "示例牌 巧克力榛子酱 400g",
+  "brand": "示例牌",                   // -> brand
+  "manufacturer": "示例食品有限公司",   // 生产商
+  "category": "食品/酱料/巧克力酱",     // -> category 树 (可对齐 GS1 GPC / OFF categories)
+  "net_content": {"value": 400, "unit": "g"},   // 净含量
+  "country_of_origin": "中国",
+  "shelf_life": {"value": 12, "unit": "月"},     // 保质期
+  "storage": "常温避光保存",
+  "images": ["S3_URL", ...],
+  "msrp": { ... },                    // 官方标准零售价, 见 2.3
+  "food": { ... },                    // 食品专属结构化字段, 见 2.2
+  "attributes": [ {"key":"","value":"","unit":""} ],  // 其余灵活参数(JSONB)
+  "identifiers": {"ean":"", "upc":"", "off_id":""},
+  "sources": [ {"source":"", "url":"", "fetched_at":"", "fields":["msrp"]} ],
+  "quality_score": 0.0,
+  "status": "active|merged|deprecated",
+  "created_at": "", "updated_at": ""
+}
+```
+
+### 2.2 食品专属字段 `food`（结构化）
+```jsonc
+{
+  "ingredients_text": "白砂糖, 棕榈油, 榛子(13%), ...",   // 配料表原文
+  "ingredients": [ {"name":"白砂糖","rank":1}, ... ],     // 解析后(可选)
+  "allergens": ["坚果", "大豆", "乳"],                    // 过敏原
+  "additives": ["E322 卵磷脂"],                           // 添加剂
+  "nutriments": {                                         // 营养成分(每100g/100ml)
+    "energy_kj": 2252, "energy_kcal": 539,
+    "fat_g": 30.9, "saturated_fat_g": 10.6,
+    "carbohydrates_g": 57.5, "sugars_g": 56.3,
+    "protein_g": 6.3, "salt_g": 0.107
+  },
+  "nutrition_basis": "per_100g",                          // per_100g | per_100ml | per_serving
+  "serving_size": "15g",
+  "is_vegetarian": null, "is_vegan": null,                // 可空
+  "nutri_score": "C",                                     // 若引用 OFF
+  "labels": ["无添加", "清真"]                             // 认证/标签
+}
+```
+
+### 2.3 官方标准零售价 `msrp`（重点）
+```jsonc
+{
+  "amount": 29.90,
+  "currency": "CNY",
+  "type": "msrp",                      // 仅 msrp/官方指导价; 不存实时电商成交价
+  "region": "CN",                      // 适用地区(价格随地区不同)
+  "source": "厂商官网/官方价目表",
+  "source_url": "https://...",
+  "effective_date": "2026-01-01",      // 价格生效/采集时间
+  "note": "官方建议零售价, 实际售价以零售商为准; 本站不提供购买"
+}
+```
+> 设计要点：价格是**带时间戳的历史快照**而非实时报价；明确 `type=msrp`、标注地区与来源；响应里附免责说明。**坚决不出现购买/跳转链接。**
+
+### 2.4 辅助实体
+`brand` / `manufacturer` / `category`(品类树) / `source`(数据来源登记) / `attribute_definition`(参数字典: 标准名·别名·单位) / `merge_log`(实体合并记录, 保留溯源)。
+
+---
+
+## 3. 可立即接入的开放数据源清单（食品快消）
+
+按"合规性 / 可用性"排序。这些可作为**种子数据 + 采集 adapter 的首批对象**。
+
+| 数据源 | 内容 | 许可 | 接入方式 | 备注 |
+|--------|------|------|----------|------|
+| **Open Food Facts** ⭐ | 全球食品(成分/营养/过敏原/Nutri-Score/图片) | **ODbL**(数据)+DbCL+CC-BY-SA(图) | REST API + **每夜全量 dump**(CSV/MongoDB, ~9GB) | 食品首选；可贡献回写；限速 15 req/min/IP(读) |
+| **USDA FoodData Central** ⭐ | 美国食品营养成分(含 Branded 品牌库) | **CC0(公共领域)** | REST API(需免费 key) + JSON/CSV 下载 | 营养数据权威；商业可用 |
+| **GS1 / Verified by GS1**（中国商品信息服务平台） | 条码→品牌/规格/厂商(官方登记) | 受限(需企业/接口授权) | 网页查询 + API(≤1000 GTIN/次) | **条码→商品**最权威来源；2亿+条；中国数据首选 |
+| **brocade.io** | 开放 GTIN/条码产品库 | 开源/开放 | 免费 REST(免鉴权读) | 数据量有限，可作补充 |
+| **3023data 等条码接口** | 中国物品编码+UPC+ISBN | 商业(0.005~0.02元/次) | REST API | **付费**，作兜底补全，非首选 |
+| 各国**监管公开数据** | 食品备案/标签/能效等 | 多为公开 | 各平台 | 后续按需逐个评估合规 |
+
+**参考用开源项目（架构/数据模型借鉴，非数据源）**：
+- Open Food Facts Server (Product Opener) — 食品库的完整实现，可学其字段与流程
+- UnoPIM / PCMT / brocade.io — 开源 PIM / 商品主数据系统，借鉴建模与去重
+
+> 建议：**先用 Open Food Facts 全量 dump 作种子数据**（直接有海量真实食品），再用 GS1/USDA 做补全与校验。这样 MVP 阶段就有真实可查的数据。
+
+---
+
+## 4. 公开 API 契约（Go 实现，只读）
+
+```
+GET /api/v1/products/barcode/{gtin}     # ★最常用: 条码查档案
+GET /api/v1/products/{id}               # 内部ID查
+GET /api/v1/products/search             # ?q=&brand=&category=&allergen_free=&page=&size=&fields=
+GET /api/v1/products/{id}/nutriments    # 仅营养
+GET /api/v1/products/{id}/msrp          # 仅官方零售价(含来源/时间/免责)
+GET /api/v1/brands  |  /categories      # 品牌 / 品类树
+GET /api/v1/sources/{id}                # 数据来源透明说明
+GET /healthz  |  /api/v1/openapi.json   # 健康检查 / 机读文档
+```
+约定：版本化 `/v1/`；统一响应 `{data, meta(分页), sources(溯源)}`；分页 + `fields=` 裁剪；匿名按 IP 限流，可选免费 API Key 提配额；CDN+Redis 缓存（参数变化慢，命中率高）；数据采用开放许可（CC BY / ODbL，注意 OFF 的 ODbL 传染性）；**无任何购买/交易端点**。
+
+---
+
+## 5. 合规与边界（公益项目重点）
+
+- **数据源许可要分清**：OFF 是 **ODbL**（衍生数据库需同样开放+署名），USDA 是 **CC0**（最宽松）。混用时要按最严格许可对外标注，避免许可冲突。
+- 爬取守 robots.txt / 服务条款，礼貌限速，标明 User-Agent 身份。
+- 只采**客观参数**；营销文案/评测原文不照搬（链接来源即可）。
+- 无个人数据(PII)，只处理商品信息。
+- 站点显著声明：**仅提供信息、不提供购买、不构成消费建议**；价格为官方指导价历史快照。
+- 提供权利方**纠错/下架**联系渠道。
+
+---
+
+## 6. 里程碑（仍不写代码，仅规划，供确认）
+
+| 阶段 | 目标 | 关键产出 |
+|------|------|----------|
+| **M0 工程地基** | 仓库骨架 | Go API 骨架 + Python 采集骨架 + PostgreSQL + Docker Compose + CI + 数据契约文档 |
+| **M1 数据模型** | 食品 schema | 主表/食品字段/MSRP/辅助实体 的迁移与字典 |
+| **M2 种子数据** | 有真实数据 | 导入 Open Food Facts dump(食品子集) + USDA 营养补全 |
+| **M3 MVP API (Go)** | 可查询 | 条码/ID/搜索/营养/MSRP + OpenAPI 文档 + 限流缓存 |
+| **M4 采集管线 (Python)** | 自动更新 | 1~2 个 adapter(OFF API / GS1) + ETL + 去重 + 质量评分 + 调度 |
+| **M5 开放与规模化** | 上线 | 搜索引擎 + CDN + API Key + 众包纠错后台 + 开发者文档站 + 开放数据许可 |
+
+---
+
+## 7. 待你确认/补充
+
+1. **价格范围**：确认只收「官方指导价 (MSRP)」、不碰实时电商价？（建议是）
+2. **OFF 的 ODbL 许可**：可接受（意味着我们对外的数据库也要用 ODbL 并署名 OFF）？还是更想用 CC0 来源(USDA)为主以保持宽松？
+3. **种子数据**：同意先导入 Open Food Facts 食品 dump 作为启动数据吗？
+4. **Go Web 框架偏好**：Gin / Echo / Chi / 标准库 net/http，有偏好吗？（无偏好我默认 Chi 或标准库，轻量）
+5. **地域范围**：首批面向中国市场商品，还是中外都收？（影响优先用 GS1-China 还是 OFF 全球库）
+
+> 你确认后，我把它定为 v1.0 规划，并据此拆成可执行的工程任务清单（仍按你的节奏，需要我动手写代码时再开始）。
@@ -0,0 +1,107 @@
+# 商品档案公益 API 系统 — 规划方案 (v1.0 定稿)
+
+> 公益网站/服务：采集全网商品信息，提供商品参数查询 API。**只收集 + 只提供信息，不涉及任何购买行为。**
+
+---
+
+## 1. 已锁定的决策
+
+| # | 决策 | 结论 |
+|---|------|------|
+| 1 | 品类 | 首批 **食品快消** |
+| 2 | 价格 | 只收 **官方标准零售价 (MSRP)**，静态字段，带来源/时间/地区/币种 + 免责说明；**不收实时电商价、不提供购买入口** |
+| 3 | 技术栈 | **Go**(对外API/核心服务) + **Python**(采集/ETL/爬虫)，经 PostgreSQL + Redis/队列解耦 |
+| 4 | 种子数据 | ✅ **先导入 Open Food Facts 食品 dump**，最快拥有真实数据 |
+| 5 | 数据许可 | 因采用 OFF → 对外数据库用 **ODbL** 并署名来源；CC0 来源(USDA)可自由混入 |
+
+### 1.1 我先用的默认值（如不同意请指出，否则按此执行）
+- **Go Web 框架**：`chi` + 标准库 `net/http`（轻量、稳定、易维护）。
+- **地域范围**：先用 OFF **全球食品库**起步，后续接 **GS1-China** 补强中国市场数据。
+- **数据库迁移工具**：Go 侧用 `golang-migrate`（纯 SQL 迁移，两端共享同一套 schema）。
+- **部署**：初期 Docker Compose 一键起全套（Postgres/Redis/Go API/Python worker）。
+
+---
+
+## 2. 目标架构（定稿）
+
+```
+ 数据源(OFF dump / OFF API / USDA / GS1)
+        │
+        ▼  Python: 采集 adapters → ETL(清洗/归一/去重/质量评分)
+        │
+   ┌────▼─────────┐   图片   ┌──────────┐
+   │ PostgreSQL   │◀───────▶│  S3/MinIO │
+   │ (商品档案主库)│         └──────────┘
+   └────▲─────────┘
+        │  只读 (+Redis缓存/限流)
+        ▼  Go: 公开 REST API + OpenAPI 文档
+   各种软件 / 开发者
+```
+
+- **解耦契约**：两端通过共享 PostgreSQL schema + 一份《数据契约文档》协作，互不直接调用。
+- **Go 端只读主库**（或读副本）；**Python 端负责写入**。
+
+---
+
+## 3. 仓库结构（计划，写代码时落地）
+
+```
+goods/
+├── README.md
+├── docker-compose.yml              # postgres + redis + minio + api + worker
+├── docs/
+│   ├── data-contract.md            # 两端共享的字段契约
+│   └── openapi.yaml                # API 契约
+├── migrations/                     # 共享 SQL 迁移 (golang-migrate)
+├── api/                            # Go: 对外只读 API
+│   ├── cmd/server/main.go
+│   ├── internal/{handler,store,model,middleware}/
+│   └── go.mod
+└── ingestion/                      # Python: 采集 + ETL
+    ├── pyproject.toml
+    ├── adapters/{openfoodfacts,usda,gs1}.py
+    ├── etl/{normalize,dedup,quality}.py
+    └── jobs/{seed_off_dump,scheduler}.py
+```
+
+## 4. 数据模型 & API 契约
+（沿用 v0.2：`product` 主表 + `food` 食品字段 + `msrp` 价格 + 辅助实体；API 以 `GET /products/barcode/{gtin}` 为核心，全只读、无交易端点。详见 v0.2 附件。）
+
+---
+
+## 5. 可执行任务拆分（按里程碑，写代码时逐项落地）
+
+**M0 — 工程地基**
+- [ ] 初始化 Go module (`api/`) + Python 项目 (`ingestion/`)
+- [ ] `docker-compose.yml`：Postgres + Redis + MinIO
+- [ ] CI（Go: build/vet/test；Python: ruff/pytest）
+- [ ] `docs/data-contract.md` 初版
+
+**M1 — 数据模型**
+- [ ] `migrations/`：product / food / msrp / brand / manufacturer / category / source / attribute_definition / merge_log
+- [ ] JSONB + GIN 索引；gtin 唯一索引
+
+**M2 — 种子数据 (Python)**
+- [ ] 下载 OFF 食品 dump（CSV）
+- [ ] `seed_off_dump`：字段映射 → 入库（含营养/成分/过敏原/图片URL）
+- [ ] USDA(CC0) 营养补全（可选）
+
+**M3 — MVP API (Go)**
+- [ ] 路由 + handler：barcode / id / search / nutriments / msrp / brands / categories / sources
+- [ ] 统一响应、分页、`fields=` 裁剪、错误处理
+- [ ] Redis 缓存 + IP 限流；`/healthz` + OpenAPI 文档
+
+**M4 — 采集管线 (Python)**
+- [ ] adapter：OFF API（增量更新）+ GS1（条码补全）
+- [ ] ETL：清洗/单位归一/去重合并/质量评分/溯源
+- [ ] 调度（定时增量更新）
+
+**M5 — 开放与规模化**
+- [ ] 搜索引擎（PG 全文 → OpenSearch）、CDN 缓存
+- [ ] 免费 API Key（防滥用+统计）、众包纠错后台
+- [ ] 开发者文档站 + 开放数据许可声明 + 站点"不提供购买"声明
+
+---
+
+## 6. 下一步
+规划已定稿。**你说先不写代码，所以我暂停在这里**。等你说"开始"，我就从 **M0 工程地基** 动手，搭好骨架后开 PR 给你看。也可以先只做某个里程碑（比如先 M0+M1 把骨架和数据模型立起来）。
@@ -1,9 +0,0 @@
-"""OpenGoods (天工·商品标签) ingestion package.
-
-Collects public product information from open data sources (e.g. Open Food
-Facts) and normalizes it into the OpenGoods database. This package only
-collects and processes product facts; it performs no purchase or commerce
-actions.
-"""
-
-__version__ = "0.1.0"
@@ -1,6 +0,0 @@
-"""Source adapters.
-
-Each open data source (Open Food Facts, USDA FoodData Central, GS1, ...) gets
-its own adapter that fetches raw records and yields them for the ETL layer.
-Adapters must respect each source's robots.txt, rate limits and license.
-"""
@@ -1,17 +0,0 @@
-"""Base adapter protocol shared by all source adapters."""
-
-from __future__ import annotations
-
-from collections.abc import Iterator
-from typing import Protocol
-
-
-class SourceAdapter(Protocol):
-    """A source adapter fetches raw product records from one data source."""
-
-    #: Stable identifier of the source, e.g. "openfoodfacts".
-    source_name: str
-
-    def fetch(self) -> Iterator[dict]:
-        """Yield raw product records as dictionaries."""
-        ...
@@ -1 +0,0 @@
-"""ETL: clean, normalize, dedup and score raw records before loading."""
@@ -1 +0,0 @@
-"""Jobs: seed import and scheduled incremental ingestion."""
@@ -1,97 +0,0 @@
-"""Unit normalization for OpenGoods.
-
-Product parameters arrive in many units (g/kg/ml/L, kcal/kJ, ...). To make
-values comparable and searchable we store both the original value and a
-normalized value expressed in a canonical unit per dimension.
-
-This module is intentionally dependency-free and pure so it is easy to test.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from decimal import Decimal
-
-# Conversion factor maps each unit to its canonical unit within a dimension.
-# canonical_value = value * factor
-_FACTORS: dict[str, tuple[str, str, Decimal]] = {
-    # mass -> g
-    "mg": ("mass", "g", Decimal("0.001")),
-    "g": ("mass", "g", Decimal("1")),
-    "kg": ("mass", "g", Decimal("1000")),
-    # volume -> ml
-    "ml": ("volume", "ml", Decimal("1")),
-    "cl": ("volume", "ml", Decimal("10")),
-    "l": ("volume", "ml", Decimal("1000")),
-    # energy -> kJ
-    "kj": ("energy", "kJ", Decimal("1")),
-    "kcal": ("energy", "kJ", Decimal("4.184")),
-}
-
-# Alias map normalizes common spellings/locales to a canonical unit code.
-_ALIASES: dict[str, str] = {
-    "kgs": "kg",
-    "千克": "kg",
-    "公斤": "kg",
-    "克": "g",
-    "毫升": "ml",
-    "升": "l",
-    "L": "l",
-    "litre": "l",
-    "liter": "l",
-    "kj": "kj",
-    "kJ": "kj",
-    "千焦": "kj",
-    "千卡": "kcal",
-    "大卡": "kcal",
-}
-
-
-class UnitError(ValueError):
-    """Raised when a unit cannot be recognized."""
-
-
-@dataclass(frozen=True)
-class Normalized:
-    """Result of normalizing a (value, unit) pair to its canonical unit."""
-
-    value: Decimal
-    unit: str
-    dimension: str
-    canonical_value: Decimal
-    canonical_unit: str
-
-
-def canonical_unit_code(unit: str) -> str:
-    """Resolve a raw unit string to a known canonical unit code."""
-    cleaned = unit.strip()
-    cleaned = _ALIASES.get(cleaned, cleaned).lower()
-    if cleaned not in _FACTORS:
-        raise UnitError(f"unknown unit: {unit!r}")
-    return cleaned
-
-
-def normalize(value: Decimal | float | int | str, unit: str) -> Normalized:
-    """Normalize a value+unit to its canonical unit within its dimension."""
-    code = canonical_unit_code(unit)
-    dimension, canonical, factor = _FACTORS[code]
-    dec = value if isinstance(value, Decimal) else Decimal(str(value))
-    return Normalized(
-        value=dec,
-        unit=code,
-        dimension=dimension,
-        canonical_value=dec * factor,
-        canonical_unit=canonical,
-    )
-
-
-def kcal_to_kj(kcal: Decimal | float | int | str) -> Decimal:
-    """Convert energy in kcal to kJ (1 kcal = 4.184 kJ)."""
-    dec = kcal if isinstance(kcal, Decimal) else Decimal(str(kcal))
-    return dec * Decimal("4.184")
-
-
-def kj_to_kcal(kj: Decimal | float | int | str) -> Decimal:
-    """Convert energy in kJ to kcal."""
-    dec = kj if isinstance(kj, Decimal) else Decimal(str(kj))
-    return dec / Decimal("4.184")
@@ -1,31 +0,0 @@
-[project]
-name = "opengoods-ingestion"
-version = "0.1.0"
-description = "OpenGoods (天工·商品标签) ingestion & ETL: collect product data and load it into the OpenGoods database."
-requires-python = ">=3.11"
-dependencies = [
-    "httpx>=0.27",
-]
-
-[project.optional-dependencies]
-dev = [
-    "ruff>=0.6",
-    "pytest>=8.0",
-]
-
-[build-system]
-requires = ["setuptools>=68"]
-build-backend = "setuptools.build_meta"
-
-[tool.setuptools.packages.find]
-include = ["opengoods*"]
-
-[tool.ruff]
-line-length = 100
-target-version = "py311"
-
-[tool.ruff.lint]
-select = ["E", "F", "I", "UP", "B"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
@@ -1,47 +0,0 @@
-from decimal import Decimal
-
-import pytest
-
-from opengoods.units import (
-    UnitError,
-    canonical_unit_code,
-    kcal_to_kj,
-    kj_to_kcal,
-    normalize,
-)
-
-
-def test_normalize_mass_kg_to_g():
-    result = normalize("1.5", "kg")
-    assert result.dimension == "mass"
-    assert result.canonical_unit == "g"
-    assert result.canonical_value == Decimal("1500.0")
-
-
-def test_normalize_volume_litre_alias():
-    result = normalize(2, "升")
-    assert result.dimension == "volume"
-    assert result.canonical_value == Decimal("2000")
-    assert result.canonical_unit == "ml"
-
-
-def test_normalize_energy_kcal_to_kj():
-    result = normalize("539", "kcal")
-    assert result.dimension == "energy"
-    assert result.canonical_unit == "kJ"
-    assert result.canonical_value == Decimal("539") * Decimal("4.184")
-
-
-def test_canonical_unit_code_alias():
-    assert canonical_unit_code("公斤") == "kg"
-    assert canonical_unit_code(" G ") == "g"
-
-
-def test_unknown_unit_raises():
-    with pytest.raises(UnitError):
-        normalize(1, "parsec")
-
-
-def test_energy_roundtrip():
-    assert kcal_to_kj(1) == Decimal("4.184")
-    assert kj_to_kcal(Decimal("4.184")) == Decimal("1")
@@ -1,3 +0,0 @@
-# Database migrations (golang-migrate)
-
-SQL migrations live here from milestone M1. Format: `NNNN_description.up.sql` / `.down.sql`.
				`@@ -1 +0,0 @@`
				`"""ETL: clean, normalize, dedup and score raw records before loading."""`
				`@@ -1 +0,0 @@`
				`"""Jobs: seed import and scheduled incremental ingestion."""`