坚锋 Topcentral — 开放API体系 & AI Agent集成平台设计规范 v1.0

**日期**: 2026-05-27 | **状态**: Phase 1 实施基线 | **核心**: 做聚合者，不做孤岛

---

一、平台愿景：坚锋 = 聚合式AI Agent管理平台

我们不是在"做一个商城"。我们是在"做一个聚合多个AI Agent能力的行业中枢平台"。

                   外部AI Agent平台
     DeepSeek Agent  Kimi Agent  千问 Agent  豆包 Agent  ChatGPT Agent
          │               │           │           │            │
          └───────────────┼───────────┼───────────┼────────────┘
                          ▼
              ┌────────────────────────────────┐
              │   坚锋 AI Agent 聚合管理平台       │
              │                                  │
              │  自有Agent     外部Agent适配器     │
              │  (客服/销售     (MCP协议桥接器)     │
              │   /选品/报价)                      │
              │                                  │
              │  统一核心系统 (正在构建)             │
              │  CRM │ Mall │ 积分 │ 审批 │ 绩效   │
              │                                  │
              │  AIGC GEO  │ SEO  │ 企业微信      │
              │  线索管道   │ 流量管道│ 双向入口    │
              └────────────────────────────────┘
                    │           │           │
                    ▼           ▼           ▼
              外部SaaS      外部SaaS     外部Agent
              (ERP/金蝶)   (电子签章)   (碳计算/物流)

---

二、六种接口协议规范

2.1 REST API — 主力接口 (Phase 1 ✅ 已就绪)

  • **框架**: FastAPI + OpenAPI 3.0
  • **格式**: JSON
  • **版本化**: /api/v1/mall/ (后续v2 = /api/v2/mall/)
  • **认证**: Bearer JWT Token
  • **文档**: /api/v1/mall/docs (Swagger UI 自动生成)
  • **分页**: page, page_size, 响应含 total/pages
  • **错误**: 统一格式 `{"detail": "错误信息", "code": "ERROR_CODE"}`
  • **审计**: 所有写操作记录到 BizProcessLog

    • **Phase 1 已实现的端点**: 16个 (品牌/系列/牌号CRUD+搜索+微信登录+四分类验证+会员档案+客户分级)

    2.2 Webhook — 事件推送 (Phase 1 ⚡ 现在就做)

  • **方向**: 坚锋平台 → 外部系统 (单向推送)
  • **协议**: HTTPS POST
  • **格式**: JSON + HMAC-SHA256 签名
  • **Header**: `X-Topcentral-Signature`, `X-Topcentral-Timestamp`, `X-Topcentral-Idempotency-Key`
  • **重试**: 失败自动3次 (10s, 60s, 300s)
  • **注册**: Web后台配置回调URL

    • **20个事件类型**（覆盖全部6大业务线的关键状态变更）:

  • `order.created / paid / shipped / signed_receipt / completed`
  • `inquiry.submitted / quoted`
  • `sample.submitted / shipped / 7day_followup`
  • `payment.receipt_uploaded / confirmed`
  • `complaint.created / resolved`
  • `npd.submitted / completed`
  • `lead.from_geo / from_seo`
  • `delivery.daily_update`
  • `contract.signed`

    • 2.3 MCP — AI Agent互操作标准 (Phase 1 预留骨架)

    MCP = AI Agent的"行业标准插头"，Anthropic主导，已成AI Agent互操作事实标准。

    **MCP Server提供三大类能力**:

  • **Tools (工具)**: product_search, stock_check, order_status, customer_grade_query, carbon_credit_query, price_inquiry, sample_request
  • **Resources (资源)**: product_catalog, certifications/{code}, docs/msds, docs/tds
  • **Prompts (提示模板)**: material_recommendation, quotation_generation, carbon_report_generation

    • **对外暴露方式**:

  • 方式A (HTTP端点, Phase 1可实施): `POST /api/v1/mall/mcp/tools/product_search`
  • 方式B (MCP SDK, AI Agent原生对接)

    • 2.4 WebSocket (Phase 2)

  • 实时推送: 个人通知 / 销售通知 / 在线客服IM

    • 2.5 gRPC (Phase 3+)

  • Agent间高性能调用 (Agent数>20时)

    • 2.6 GraphQL (按需)

  • 外部SaaS自定义字段组合查询

    • ---

    三、集成适配器架构

    每个外部系统 = 一个Adapter，遵循统一接口

    class ERPAdapter(ExternalServiceAdapter):       # 金蝶/用友
class ESignatureAdapter(ExternalServiceAdapter): # 法大大/e签宝
class GeoSeoAdapter(ExternalServiceAdapter):    # AIGC GEO/SEO线索管道
class LogisticsAdapter(ExternalServiceAdapter): # 菜鸟/顺丰/跨越
class PaymentAdapter(ExternalServiceAdapter):   # 支付宝+微信支付
class CarbonCreditAdapter(ExternalServiceAdapter): # 碳积分交易平台

    ---

    四、AI Agent互操作生态

    4.1 坚锋→外部AI (调用外部AI能力)

    已有8个AIGC平台API Key → 统一包装成适配器，Agent无需关心用哪个平台

    4.2 外部AI→坚锋 (外部AI调用坚锋数据)

    通过MCP协议 → 外部DeepSeek/Kimi Agent可查询坚锋产品/库存/订单

    4.3 AIGC GEO + SEO → CRM线索管道

    已在GEO/SEO站部署 → 检测用户行为 → 触发CrmGeoSeoLead → 推送到销售企微

    ---

    五、坚锋商标体系（已录入）

    再生塑料品牌:
  PlasCircles™️ 帕塑 = PCR Topcircle™️ 淘塑™️ + PIR (工业再生)

其他品牌:
  TcycleGP®  /  TcycleEP®  /  TcycleSP®  /  TcycleElast®  /  TcycleAM®
  Topcentral™️  /  坚锋®