# 商品档案公益 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。