goods/docs/planning/history/v0.1-initial-plan.md

商品档案公益 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 核心实体

// 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。