代理商务平台-POC
人工智能结账与MCP和ACP支持的集成
______________________________________________________________________
🎯 快速入门（5分钟）
1.启动后端
cd backend
pip install -r requirements.txt
python scripts/seed_products.py
uvicorn app.main:app --reload2.启动前端
# Ensure Node.js 18+
cd frontend/simulator
npm install
npm run dev3.打开演示
http://localhost:5173演示流程：
- 类型：“我想买Air Max鞋”
- 点击：“加入购物车”
- 类型：“俄勒冈州波特兰市主街123号，邮编97220”
- 点击：“完成购买”
- 请参阅：订单已确认！ ✅
______________________________________________________________________
📊 包含什么
✅ 完整的后端API（双重集成路径）
路径1:MCP端点 （基于简化工具的API）
- 单端点 -
POST /mcp对于所有操作 - 6工具 -搜索产品、获取产品详情、创建结账、添加发货地址、完成采购、获取订单状态
- 用例 -自定义UI、演示、快速原型制作
路径2:ACP REST端点 （OpenAI标准）
- 5+REST端点 -
/acp/v1/*遵循OpenAI ACP规范 - 完整协议 -结账会话、支付令牌、订单、产品提要
- 用例 -ChatGPT集成，生产AI代理
共享后端
- 6内部服务 -产品、库存、结账、发货、付款、订单
- 4数据库模型 -SQLAlchemy ORM与SQLite
- 47测试 -56%的覆盖率（产品服务：97%）
- 10样品产品 -准备演示
✅ ChatGPT模拟器用户界面
- 反应18 -现代前端
- ChatGPT风格接口 -黑暗主题，对话式用户体验
- MCP集成 -使用简化的MCP端点（PATH 1）
- 完整的采购流程 -搜索→ Cart → 结账→ Order
- 调试面板 -实时显示API调用
- 订单确认 -漂亮的成功屏幕
✅ 综合文档
- 体系结构规范 -完整的技术文档
- 商业案例 -投资回报率分析和建议
- 演示指南 -多种展示方式
- 决策日志 -记录所有架构决策
______________________________________________________________________
🏗️ 建筑
两条整合路径
AI Agents / Clients (ChatGPT, Claude, Custom UIs...)
│
├─────────────────┬─────────────────┐
│ │ │
PATH 1: MCP PATH 2: ACP REST
(Simplified) (OpenAI Standard)
│ │
POST /mcp /acp/v1/*
6 tools 5+ endpoints
│ │
└────────┬────────┘
↓
Protocol Gateway Layer (Translation & Orchestration)
↓
Internal Services Layer (Protocol-Agnostic)
• Product • Inventory • Checkout • Shipping • Payment • Order
↓
Data Layer (SQLite + Stripe)关键模式： 双通道API（MCP+ACP REST）→ 网关→ 服务
| 路径 | 最适合 | POC使用 |
|---|---|---|
| MCP端点 | 自定义UI、演示、快速原型制作 | ✅ 前端模拟器 |
| ACP休息 | ChatGPT集成、生产代理 | 测试脚本 |
______________________________________________________________________
📚 文档
基础阅读
- 建筑.md -完整的技术架构
- 高管\_ SUMMARY.md -商业案例和投资回报率
- docs/TEST_GUIDE.md -测试指南和覆盖目标
- docs/DECISION_LOG.md -架构决策
______________________________________________________________________
🎬 演示选项
选项1：视觉用户界面（推荐）
# Start servers (see Quick Start above)
open http://localhost:5173使用： 路径1（MCP端点）\ 具有完整购买流程的ChatGPT风格界面
选项2:Python脚本-MCP路径
cd backend
python scripts/test_mcp_flow.py使用： 路径1（MCP端点）\ 使用简化的基于工具的API显示完整流程
选项3:Python脚本-ACP REST路径
cd backend
python scripts/test_purchase_flow.py使用： 路径2（ACP-REST）\ 使用OpenAI ACP标准端点显示完整流程
选项4：API文档
open http://localhost:8000/docs用于测试MCP和ACP终点的交互式Swagger UI
______________________________________________________________________
🧪 测试
cd backend
# Run all tests
pytest
# Run with coverage
pytest --cov=app --cov-report=html
# View coverage report
open htmlcov/index.html当前覆盖范围： 总体56%，产品服务：97%
______________________________________________________________________
🎯 项目状态
| 组件 | 状态 | 覆盖范围 |
|---|---|---|
| 后端API | ✅ 完成 | 56% |
| 前端UI | ✅ 完成 | 不适用 |
| 采购流程 | ✅ 工作中 | E2E已验证 |
| 文档 | ✅ 完成 | 20+份文档 |
| 演示脚本 | ✅ 就绪 | 3个选项 |
总体而言： ✅ 演示就绪POC
______________________________________________________________________
🚀 技术栈
后端：
- Python 3.11+/FastAPI
- SQLAlchemy（ORM）
- SQLite（数据库）
- Stripe SDK（支付）
- pytest（测试）
前端：
- React 18/Vite
- TailwindCSS
- 状态（State）
- Axios（API客户端）
______________________________________________________________________
📋 后续步骤
达到90%的测试覆盖率
- 为剩余服务添加约70个测试
- 遵循模式
tests/test_services/test_product_service.py - 预计：8-10小时
用于生产
- 集成真正的Stripe API
- 生产级MCP服务器部署
- 企业CRM/ERP集成
- Kubernetes/容器编排
- AI平台认证
看 高管\_ SUMMARY.md 完整的生产路线图。
______________________________________________________________________
🤝 贡献
看 贡献.md 发展指南。
______________________________________________________________________
📝 许可证
MIT许可证-有关详细信息，请参阅许可证文件
______________________________________________________________________
📧 支持
- 架构问题： 看 建筑.md
- 商业案例： 看 高管\_ SUMMARY.md
- 测试： 看 docs/TEST_GUIDE.md
______________________________________________________________________
状态： ✅ 演示就绪POC\ 新闻报道： 56%（产品服务：97%）