lixu
54175238ad
新增 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>
217 lines
12 KiB
Markdown
217 lines
12 KiB
Markdown
# 商品档案公益 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。
|