vghoost360/jumbo

Jumbo API

🛒 Jumbo.com杂货平台的综合REST API和现代Web仪表板

通过无头Chromium自动化认证，管理购物篮、清单（lijstjes）、订单历史、商店收据，并提供基于SKU或EAN条码的产品详情查询（含OpenFoodFacts fallback功能）。

🚀 快速开始

bash
docker compose up -d

• Web仪表板: http://localhost:8000
• API文档: http://localhost:8000/docs%EF%BC%88%E4%BA%A4%E4%BA%92%E5%BC%8FSwagger UI）
• 完整API指南: API_README.md

✨ 核心功能

🛒 购物篮管理

• 查看当前购物篮及产品详情
• 通过SKU添加/移除产品
• 更新商品数量
• 实时价格计算
• 支持促销价

📝 购物清单

• 访问所有购物清单
• 查看收藏清单和自定义清单
• 显示产品图片、价格及详情
• 商品数量跟踪

📦 订单管理

• 查看在线订单历史
• 详细订单信息（含配送日期）
• 商品级详情（图片、定价）
• 跟踪订单状态、替换商品及缺货商品
• 支持送货上门和到店自提订单

🧾 商店收据

• 查看店内及在线收据历史
• 详细收据 breakdown（含增值税汇总）
• 产品匹配与信息补充
• loyalty积分跟踪（Jumbo Extra's）
• 支付方式信息
• 商店位置详情

🔍 产品搜索与查询

• 通过SKU搜索产品
• 智能条码查询（EAN码）: 含OpenFoodFacts fallback
• EAN相似匹配算法: 未找到精确条码时自动匹配最佳产品
  • 最多查询8个候选产品
  • 基于EAN前缀相似度评分（0-100）
  • 颜色编码置信度（绿色≥90%，黄色<90%）
  • 显示扫描条码与匹配产品EAN
• Jumbo未找到条码时: 自动查询OpenFoodFacts并按产品名称搜索
• 全面产品信息：营养数据、过敏原、多图、定价、品牌、库存状态等

🔐 认证与自动重登录

• Selenium-based浏览器自动登录
• 重启后Cookie持久化
• 会话过期时自动重认证
• 仪表板设置页的凭证管理
• 从仪表板直接保存凭证
• 支持环境变量配置（适用于homelab部署）

🎨 现代Web仪表板

• 深色主题、响应式UI
• 实时购物篮更新
• 交互式产品卡片（带图片）
• 详情模态框
• 提示通知
• 命令历史跟踪
• 完整设置页（含凭证管理）

⚙️ 产品匹配引擎

• 智能收据产品信息补充
• 可配置置信度阈值
• 价格、重量、名称匹配
• 缓存优化性能
• 手动清除缓存
• OpenFoodFacts集成（未知条码）

📚 文档

交互式API探索器

访问 http://localhost:8000/docs 获取完整Swagger/OpenAPI文档：

• 直接在浏览器中测试所有端点
• 查看请求/响应 schema
• 测试认证流程
• 无需编写代码

全面API参考

查看 API_README.md：

• 完整端点文档
• 认证指南
• Python/JavaScript/cURL代码示例
• 架构概述
• 故障排除提示

🔐 认证设置

API支持三种持久化认证方式：

方式1：Web仪表板（最简单）

1. 打开 http://localhost:8000
2. 进入 设置 标签页
3. 在“登录凭证”部分输入账号密码
4. 点击“保存凭证”
5. 凭证将安全存储用于自动重认证

方式2：环境变量（Homelab推荐）

通过Portainer或docker-compose设置环境变量：

yaml
environment:
  - JUMBO_USERNAME=your-email@example.com
  - JUMBO_PASSWORD=your-password

方式3：手动登录

通过Web仪表板登录一次：

• 点击头部“登录”按钮
• 输入凭证
• 凭证自动保存用于后续会话

工作原理:

• 会话Cookie保存至 /app/data/session-cookies.json
• 凭证保存至 /app/data/credentials.json（或使用环境变量）
• Cookie过期时触发自动重认证
• 无需手动干预即可无缝运行

🔧 设置与配置

Web仪表板设置

通过设置面板配置：

🔐 登录凭证

• 保存/更新Jumbo.com凭证
• 查看凭证状态
• 删除已保存凭证

📦 条码查询

• OpenFoodFacts Fallback: 条码未找到时自动查询OpenFoodFacts
• EAN相似匹配: 智能算法匹配最佳产品
  • 检查最多8个候选产品
  • 基于EAN前缀匹配位数评分
  • ≥10位匹配 → 90分（高置信度）
  • ≥8位匹配 →70分（中置信度）
  • ≥6位匹配 →50分（低置信度）
• 颜色编码显示置信度
• 透明展示扫描与匹配EAN

🧾 收据产品匹配

• 启用/禁用产品信息补充
• 严格匹配模式
• 置信度阈值滑块

🎯 匹配标准

• 价格匹配
• 重量/体积匹配
• 名称匹配

🗑️ 缓存管理

• 清除产品匹配缓存

🔑 API快速示例

认证

bash
# 登录
curl -X POST http://localhost:8000/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"your@email.com","password":"yourpassword"}'

# 检查认证状态
curl http://localhost:8000/api/auth/status

购物篮操作

bash
# 获取购物篮
curl http://localhost:8000/api/basket

# 添加产品
curl -X POST http://localhost:8000/api/basket/add \
  -H 'Content-Type: application/json' \
  -d '{"sku":"67649PAK","quantity":2}'

# 更新数量
curl -X PATCH http://localhost:8000/api/basket/items/{line_id} \
  -H 'Content-Type: application/json' \
  -d '{"quantity":5}'

# 移除产品
curl -X POST http://localhost:8000/api/basket/remove \
  -H 'Content-Type: application/json' \
  -d '{"line_id":"abc123"}'

购物清单

bash
# 获取所有清单
curl http://localhost:8000/api/lists

# 获取特定清单详情
curl http://localhost:8000/api/lists/{list_id}

订单与收据

bash
# 获取订单和收据
curl "http://localhost:8000/api/orders?limit=10&page=0"

# 获取订单详情
curl http://localhost:8000/api/orders/{order_id}

# 获取收据详情
curl http://localhost:8000/api/receipts/{transaction_id}

产品搜索与条码查询

bash
# 通过SKU搜索
curl "http://localhost:8000/api/products/search?sku=67649PAK"

# 条码查询（含OpenFoodFacts fallback和EAN匹配）
curl -X POST http://localhost:8000/api/products/barcode \
  -H 'Content-Type: application/json' \
  -d '{"barcode":"8718452829408"}'

# 响应示例：
# {
#   "sku": "629680PAK",
#   "title": "Jumbo Cola Regular 6 x 1,5 L",
#   "ean": "8718452829583",
#   "scannedBarcode": "8718452829408",
#   "eanMatchScore": 90,
#   "verified": true,
#   "matchSource": "OpenFoodFacts",
#   "matchedName": "Cola"
# }

设置管理

bash
# 获取所有设置
curl http://localhost:8000/api/settings

# 更新设置
curl -X PUT http://localhost:8000/api/settings \
  -H 'Content-Type: application/json' \
  -d '{"useOpenFoodFactsFallback":true,"confidenceThreshold":50}'

# 保存凭证
curl -X PUT http://localhost:8000/api/settings/credentials \
  -H 'Content-Type: application/json' \
  -d '{"username":"your@email.com","password":"yourpassword"}'

# 移除凭证
curl -X PUT http://localhost:8000/api/settings/credentials \
  -H 'Content-Type: application/json' \
  -d '{"removeCredentials":true}'

# 清除匹配缓存
curl -X POST http://localhost:8000/api/settings/clear-cache

更多示例请查看 API_README.md

🏗️ 项目结构

app/
  main.py              # FastAPI应用与REST端点
  jumbo_client.py      # Jumbo GraphQL客户端 + Selenium认证 + OpenFoodFacts
  templates/
    index.html         # 带设置管理的Web仪表板
  static/
    app.js            # 前端JavaScript
    style.css         # 响应式深色主题
  Dockerfile
  requirements.txt
data/                  # 持久化数据卷
  session-cookies.json # 保存的会话Cookie
  credentials.json     # 加密凭证（可选）
  barcode-cache.json   # 产品条码缓存
  settings.json        # 用户偏好设置
docker-compose.yml
API_README.md          # 完整API文档

🐳 Docker部署

Docker Compose（推荐）

bash
docker-compose up -d

Docker Run

bash
docker run -d \
  --name jumbo-api \
  -p 8000:8000 \
  -v jumbo-data:/app/data \
  -e JUMBO_USERNAME=your@email.com \
  -e JUMBO_PASSWORD=yourpassword \
  vghoost360/jumbo:latest

拉取最新版本

bash
docker pull vghoost360/jumbo:latest
# 或特定版本
docker pull vghoost360/jumbo:v2.6.0

卷挂载

容器在 /app/data 使用持久化卷存储：

• 会话Cookie
• 加密凭证
• 产品匹配缓存
• 条码查询缓存
• 用户设置

重要: 挂载此卷以在容器重启时保留认证信息。

🛠️ 技术栈

• 后端: Python 3.11、FastAPI、Uvicorn
• 认证: Selenium（无头Chromium）
• HTTP客户端: httpx（异步）
• 外部API: OpenFoodFacts API集成
• 前端: Vanilla JavaScript、CSS Grid/Flexbox
• 容器: Docker (python:3.11-slim + Chromium)

🔧 配置

环境变量

设置API

通过 /api/settings 或Web仪表板配置行为：

• productMatchingEnabled - 启用/禁用收据信息补充
• strictMatching - 要求更高的匹配置信度
• confidenceThreshold - 最小置信度百分比（0-100）
• usePriceMatching - 匹配算法包含价格
• useWeightMatching - 匹配算法包含重量
• useNameMatching - 匹配算法包含名称相似度
• useOpenFoodFactsFallback - 条码未找到时查询OpenFoodFacts

📊 健康检查

bash
curl http://localhost:8000/api/health

响应:

json
{
  "status": "healthy",
  "timestamp": "2026-02-22T17:43:00Z",
  "authenticated": true
}

🆕 更新日志

v2.6.0（2026-02-22）

新功能:

• 🌐 OpenFoodFacts集成: 条码未找到时自动fallback
  • 查询OpenFoodFacts API获取产品名称
  • 用匹配名称搜索Jumbo目录
  • 设置页可配置开关
• 🎯 EAN相似匹配算法: 智能产品匹配系统
  • 最多检查8个候选产品
  • 基于EAN前缀位数评分（0-100）
  • 模式匹配（如8718452829xxx →10位匹配→90分）
  • 返回扫描条码与匹配产品EAN
  • UI中颜色编码置信度（绿/黄/红）
  • 低置信度匹配（<90%）警告
• 🔐 凭证管理UI: 从设置页直接保存/更新凭证
  • 可视化凭证状态指示器
  • 安全凭证存储
  • 移除凭证选项

Bug修复:

• 🐛 修复阻止按钮点击的JavaScript语法错误
• 🔧 添加缺失的hasProduct变量定义
• 🎨 修复收据渲染中的模板文字错误
• ✅ 解决89+ linting错误
• 🔍 修复EAN匹配结果中的SKU保留问题

改进:

• 📝 增强设置页的凭证管理功能
• 🎯 更智能的条码查询（含EAN匹配）
• 📊 透明的置信度评分系统
• 🎨 修复设置页CSS（输入框重叠）
• 🧹 代码清理与验证
• 📚 全面文档更新

v2.5.1

• 收据产品信息补充
• 订单详情视图
• 购物清单支持
• 产品匹配引擎

🔒 安全说明

• 凭证存储在Docker卷中（不在镜像内）
• .dockerignore 排除构建中的个人数据
• 会话Cookie安全管理
• 日志或版本控制中无凭证
• 生产部署使用环境变量
• OpenFoodFacts查询使用***API访问

🤝 贡献

本项目仅供教育目的，欢迎贡献！

📝 许可

仅供教育使用。Jumbo.com和OpenFoodFacts的服务条款适用于API使用。

🐛 故障排除

按钮无响应

• 硬刷新浏览器（Ctrl+Shift+R）
• 检查浏览器控制台的JavaScript错误
• 验证容器是否运行：docker ps

条码未找到

• 在设置中启用“OpenFoodFacts Fallback”
• 检查产品是否存在于OpenFoodFacts.org
• 尝试按产品名称搜索

认证问题

• 使用设置页保存凭证
• 检查凭证是否正确
• 验证 /app/data/session-cookies.json 中的Cookie
• 查看日志：docker logs jumbo-api

容器无法启动

• 检查端口8000是否可用
• 验证Docker资源是否充足
• 查看日志中的错误信息

更多帮助请查看 API_README.md