使用说明

代理商务平台-POC

人工智能结账与MCP和ACP支持的集成

🎯 快速入门（5分钟）

1.启动后端

cd backend
pip install -r requirements.txt
python scripts/seed_products.py
uvicorn app.main:app --reload

2.启动前端

# Ensure Node.js 18+
cd frontend/simulator
npm install
npm run dev

3.打开演示

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%）