🚀 Hackathon AI峰会2025-Glovo订购API

一种专门的模拟API，用于使用MCP（模型上下文协议）构建glovo食品订购代理

一个生产就绪的REST API，包含真实的食品、杂货和零售SKU数据，以支持 Glovo订购代理 挑战。使用FastAPI、SQLite和Docker构建，用于即时黑客马拉松部署。

⚡ 快速开始：参见 QUICKSTART.md 2分钟入门指南！

🎯 目的与挑战

Glovo订购挑战

视觉: *“想象一下，在一个世界里，点餐就像和朋友聊天一样自然。没有无休止地滚动菜单，没有来回点击——只需说出你想要什么，在对话中完善它，然后下订单。”*

此API作为黑客马拉松参与者的后端基础：

构建Glovo AI 这有助于用户自然地计划和下订单
建议个性化订单 基于历史和简单聊天上下文
允许自然精炼: *“把披萨换成寿司”*, *“将其设为3而不是2”*
完成结账 通过模拟API集成
添加语音接口 （语音转文本/文本转语音）作为额外功能

✨ 特性

🏪 多店铺数据：餐厅、超市、电子产品、药店共有20家门店
📦 丰富的产品目录：80多种产品，包含详细的元数据（饮食标签、成分、卡路里）
👥 用户群体：4个行为细分市场中的150名匿名用户（食品爱好者、科技爱好者、零售购物者、偶尔使用的用户）
📊 历史订单：2954个具有标准化数据结构的实际订单
🐳 Docker就绪：一个在本地启动的命令
✅ 经过全面测试：100%通过单元和集成测试的测试套件
📖 自动生成的文档：交互式Swagger/ReDoc API文档，位于 /docs 和 /redoc

🚀 快速开始

先决条件

Docker&Docker编写 （推荐）-
或Python 3.9+ （用于地方发展）

选项1:Docker（推荐）🐳

最快的开始方式！一个命令，你就可以破解了：

# Clone the repository
git clone https://github.com/your-username/Hackathon-AI-Summit-2025.git
cd Hackathon-AI-Summit-2025

# Start with Docker Compose
docker-compose up --build -d

# API is now running at http://localhost:8000

验证它是否正常工作：

# Check health
curl http://localhost:8000/health

# Expected response:
{
    "status": "healthy",
    "database": "sqlite",
    "data_stats": {
        "stores": 20,
        "products": 80,
        "users": 150,
        "orders": 2954,
        "order_items": 8371
    }
}

# View logs
docker-compose logs -f

# Stop when done
docker-compose down

方案2：地方发展

非常适合开发和调试：

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start the development server (with hot-reload)
python -m uvicorn main:app --reload --port 8000

# API available at http://localhost:8000

🎉 你准备好了

运行后，探索API：

交互式文档: Swagger文档
备选文档: ReDoc文档
健康检查: 健康检查
根信息: 根

📚 API文档

基本URL

http://localhost:8000

已实现的端点

🏠 根与健康

GET / -API信息和功能列表
GET /health -使用数据库统计信息进行健康检查

例子：

curl http://localhost:8000/health

🏪 商店

GET /api/stores -列出所有商店

- 查询参数： cuisine （按菜肴类型过滤）， limit （最多50个）

例子：

# Get all stores
curl "http://localhost:8000/api/stores?limit=20"

# Filter by cuisine
curl "http://localhost:8000/api/stores?cuisine=italian&limit=10"

🍕 产品

GET /api/products -列出带有筛选功能的产品

- 查询参数： store_id, category, dietary, limit （最多50个）

例子：

# Get all products
curl "http://localhost:8000/api/products?limit=20"

# Filter by store and dietary preferences
curl "http://localhost:8000/api/products?store_id=1&dietary=vegetarian&limit=10"

# Filter by category
curl "http://localhost:8000/api/products?category=pizza&limit=10"

👤 用户

GET /api/users -列出所有用户（仅匿名数据）

- 查询参数： limit （最多50个）

GET /api/users/{user_id} -获取用户资料（饮食偏好、最喜欢的菜肴）
GET /api/users/{user_id}/orders -使用标准化数据获取用户的订单历史记录

- 查询参数： limit （默认值10）

例子：

# Get user profile
curl "http://localhost:8000/api/users/1"

# Get user's order history
curl "http://localhost:8000/api/users/1/orders?limit=5"

🛒 物零碎

GET /api/carts/{session_id} -获取当前购物车内容
POST /api/carts/{session_id}/add -将商品添加到购物车

- 身体参数： product_id （必填）， quantity （默认值1）

例子：

# Add product to cart
curl -X POST "http://localhost:8000/api/carts/session123/add?product_id=1&quantity=2"

# View cart
curl "http://localhost:8000/api/carts/session123"

常用查询参数

limit -要返回的最大项目数（默认值：50）
cuisine -按菜肴类型过滤商店（例如。， italian, chinese, mexican)
category -按类别过滤产品（例如。， pizza, burger, sushi)
dietary -通过饮食标签过滤产品（例如。， vegetarian, vegan, gluten-free)
store_id -按店铺ID筛选产品

🤖 MCP集成

什么是MCP？

模型上下文协议（MCP）使AI模型能够安全地与外部数据源和工具连接。此API提供数据以在上面构建工具。

🏗️ 建筑

Hackathon-AI-Summit-2025/
├── main.py                      # FastAPI application entry point
├── api/
│   ├── database.py             # SQLite database management
│   └── mock_data.py            # CSV data processing
├── data/                       # CSV data files
│   ├── stores.csv             # 20 stores
│   ├── products.csv           # 80+ products
│   ├── users.csv              # 150 anonymized users
│   └── orders.csv             # 2,954 orders
├── scripts/
│   └── generate_mock_data.py  # Data generation script
├── tests/                      # Comprehensive test suite
│   ├── unit/                  # Unit tests
│   ├── integration/           # Integration tests
│   └── conftest.py            # Test fixtures
├── Dockerfile                  # Docker image definition
├── docker-compose.yml         # Docker Compose configuration
├── requirements.txt           # Python dependencies
└── README.md                  # This file

数据库模式

标准化SQLite数据库：

stores -店铺信息（名称、美食、类型、评级、配送信息）
products -产品目录（名称、价格、类别、饮食标签、成分）
users -匿名用户资料（饮食偏好、最喜欢的菜肴、订单历史）
orders -订单记录（user_id、total_amount、状态、日期）
order_items -标准化订单项（order_id、product_id、数量、price_at_order）
carts -基于会话的购物车（Session_id，商品JSON，总计）

所有表都有适当的索引用于快速查询。

🎨 数据场景

API包括多个预先配置的订餐场景：

多餐厅送餐：披萨店、汉堡店、寿司店、咖啡店
杂货店：新鲜农产品、乳制品、肉类、食品储藏室用品，附有详细的营养信息
美食：高档餐厅，提供葡萄酒搭配和餐饮服务
快速休闲的：快速服务，可定制碗、沙拉，并打造自己的选择
国际美食：正宗的意大利、中国、墨西哥、印度菜
关注健康：有机、纯素、酮、无麸质选项，成分清单齐全

🧪 测试与开发

运行测试

API提供了一个全面的测试套件（100%通过！）：

# Activate virtual environment first
source venv/bin/activate

# Run all tests
pytest tests/ -v

# Run specific test categories
pytest tests/unit/ -v              # Unit tests only
pytest tests/integration/ -v       # Integration tests only
pytest -m api -v                   # API endpoint tests
pytest -m database -v              # Database tests

# Interactive test runner (recommended)
python run_tests.py

测试覆盖范围：

✅ API终点：测试所有端点（根、健康、商店、产品、用户、购物车、订单）
✅ 数据库操作：SQLite初始化、数据加载、查询、规范化
✅ 模拟数据处理：CSV解析、JSON处理、数据验证
✅ 整合：完成从发现到结账的用户工作流程
✅ 隐私：确保在任何端点中都没有暴露PII

看 tests/README.md 获取详细的测试文档。

生成新的模拟数据

python scripts/generate_mock_data.py

这将使用新的匿名数据重新生成所有CSV文件：

20家商店（餐馆、超市、电子产品等）
所有类别的80多种产品
4个队列中的150名用户（食品爱好者、技术爱好者、零售购物者、偶尔使用的用户）
2954个现实订单

使用Faker可以生成任意数量的用户/订单。

API健康检查

curl http://localhost:8000/health

# Should return:
{
    "status": "healthy",
    "database": "sqlite",
    "data_stats": {
        "stores": 20,
        "products": 80,
        "users": 150,
        "orders": 2954,
        "order_items": 8371
    }
}

🔧 配置

API使用合理的默认值，并且需要最少的配置：

主机: 0.0.0.0 （可从所有网络接口访问）
端口: 8000
数据库：SQLite(hackathon_data.db)
数据源：CSV文件在 data/ 目录
随机种子: 42 （用于可重复数据生成）
重新加载：在开发模式下启用(python -m uvicorn main:app --reload)

所有配置值都集中在 config/constants.py.

想要定制吗？只需编辑常量：

# config/constants.py
API_PORT = 3000  # Change port
RANDOM_SEED = 33  # Different random seed
DEFAULT_NUM_USERS = 500  # Generate more users
DEFAULT_QUERY_LIMIT = 100  # Higher query limits

看 config/README.md 查看完整的配置文档。

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🆘 故障排除

Docker问题

“无法连接到Docker守护进程”

# Start Docker Desktop or Colima
colima start  # If using Colima on Mac
# OR open Docker Desktop application

“端口8000已在使用中”

# Stop any running instance
docker-compose down

# OR use a different port
docker-compose up -d --build && docker-compose exec glovo-ordering-api echo "Running on alternate port"

“容器不断重新启动”

# Check logs for errors
docker-compose logs glovo-ordering-api

# Rebuild from scratch
docker-compose down
docker-compose up --build

地方发展问题

“找不到模块”错误

# Ensure virtual environment is activated
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Reinstall dependencies
pip install -r requirements.txt

数据库错误

# Delete and regenerate database
rm hackathon_data.db
python -m uvicorn main:app --reload

🆘 支持

📖 文档：查看此README和 tests/README.md
🐛 问题:
🔍 交互式文档: http://localhost:8000/docs（在浏览器中尝试端点！）

🎉 快乐黑客！

准备好打造令人惊叹的glovo订购代理！本API提供：

✅ 生产就绪后端 -没有设置麻烦，只是 docker-compose up\ ✅ 真实数据 -20家门店，80+商品，150用户，2954订单\ ✅ 经过全面测试 -100%通过测试套件以获得信心\ ✅ 有据可查 -交互式API文档+全面自述

专业提示：

从...开始 /docs 以交互方式探索API
结账 tests/integration/test_complete_workflows.py 使用示例
使用健康端点验证一切是否正常工作
审查数据中的用户群体，以构建个性化建议
数据库已标准化-连接 order_items 随着 products 获取丰富的订单数据

把你的黑客马拉松时间集中在构建glovo AI上，而不是后端！ 🚀

Hackathon AI Summit 2025

快速接入

详细介绍

🚀 Hackathon AI峰会2025-Glovo订购API

🎯 目的与挑战

Glovo订购挑战

✨ 特性

🚀 快速开始

先决条件

选项1:Docker（推荐）🐳

方案2：地方发展

🎉 你准备好了

📚 API文档

基本URL

已实现的端点

🏠 根与健康

🏪 商店

🍕 产品

👤 用户

🛒 物零碎

常用查询参数

🤖 MCP集成

什么是MCP？

🏗️ 建筑

数据库模式

🎨 数据场景

🧪 测试与开发

运行测试

生成新的模拟数据

API健康检查

🔧 配置

📄 许可证

🆘 故障排除

Docker问题

地方发展问题

🆘 支持

🎉 快乐黑客！

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP