B2B2B 酒店分销平台 - API 接口设计汇总

从总纲文档各章节提取的所有 API 接口定义

酒店房型基库
匹配管理
查价引擎
订单管理
销售管理
价格管理
结算管理
库存管理
风控体系
数据智能
API 网关
动态定价规则
价格一致性监控
促销活动管理
汇率自动换算
拆单/并单
改单/取消规则
担保/预付
订单超时自动取消
多语言内容管理
图片管理
政策管理
评价系统
对账差异自动处理
供应商评级体系
代理商分层权益
消息通知中心
审计日志
多租户隔离
AI 决策支持引擎
自主执行权限管理
供应商自动接入流水线
工单系统
结构化知识库
财务感知与预警
指标采集与全链路 Trace

酒店房型基库

接口设计

# 酒店管理 API
GET    /api/v1/hotels                    # 酒店列表（分页+筛选+搜索）
GET    /api/v1/hotels/:id                # 酒店详情
POST   /api/v1/hotels                    # 创建酒店
PUT    /api/v1/hotels/:id                # 更新酒店
DELETE /api/v1/hotels/:id                # 下架酒店
GET    /api/v1/hotels/:id/room-types     # 酒店的房型列表
POST   /api/v1/hotels/batch              # 批量操作

# 房型管理 API
GET    /api/v1/room-types/:id            # 房型详情
POST   /api/v1/room-types                # 创建房型
PUT    /api/v1/room-types/:id            # 更新房型
DELETE /api/v1/room-types/:id            # 删除房型

# 供应商数据同步 API
POST   /api/v1/sync/suppliers/:code/hotels      # 触发供应商酒店数据同步
GET    /api/v1/sync/suppliers/:code/status       # 查看同步状态
POST   /api/v1/sync/suppliers/:code/hotels/diff # 查看数据差异

# 搜索 API（对接 ES）
GET    /api/v1/search/hotels?city=XXX&check_in=YYYY-MM-DD&check_out=YYYY-MM-DD&adults=2

匹配管理

接口设计

# 匹配操作 API
POST   /api/v1/match/hotels                    # 触发酒店匹配任务
POST   /api/v1/match/room-types                # 触发房型匹配任务
GET    /api/v1/match/tasks                     # 匹配任务列表
GET    /api/v1/match/tasks/:id                 # 匹配任务详情+进度
GET    /api/v1/match/pending                   # 待人工审核的匹配列表
POST   /api/v1/match/pending/:id/confirm       # 确认匹配
POST   /api/v1/match/pending/:id/reject        # 拒绝匹配

# 映射查询 API
GET    /api/v1/mappings/hotel?supplier=XXX&supplier_hotel_id=YYY
GET    /api/v1/mappings/hotel/:platform_hotel_id/suppliers  # 反向查映射
GET    /api/v1/mappings/room-type?supplier=XXX&supplier_room_code=YYY

查价引擎

接口设计

# 查价 API（核心接口）
POST   /api/v2/prices/search
# 请求体:
{
  "hotel_id": "HPT-001234",
  "check_in": "2025-03-01",
  "check_out": "2025-03-03",
  "adults": 2,
  "children": 0,
  "room_count": 1,
  "currency": "CNY",
  "guest_country": "CN",
  "rate_plan_codes": [],           # 可选: 指定价格计划
  "supplier_codes": [],            # 可选: 指定供应商
  "client_reference": "req-xxx"    # 代理商请求号
}

# 响应体:
{
  "request_id": "plat-xxx",
  "hotel_id": "HPT-001234",
  "hotel_name": "Shanghai Marriott Hotel",
  "check_in": "2025-03-01",
  "check_out": "2025-03-03",
  "nights": 2,
  "currency": "CNY",
  "options": [
    {
      "option_id": "OPT-001",
      "supplier_code": "HOTELBEDS",
      "room_type_code": "DBL",
      "room_type_name": "豪华大床房",
      "meal_plan": "BB",
      "rate_plan_code": "BAR",
      "gross_price": 1200.00,       # 售价(含佣金)
      "net_price": 1000.00,         # 净价
      "commission": 200.00,         # 佣金
      "currency": "CNY",
      "available_rooms": 5,
      "cancellation_policy": {
        "type": "non_refundable"
      },
      "supplier_ref": "HB-123456",  # 供应商侧报价引用号
      "valid_until": "2025-01-20T10:00:00Z"  # 报价有效期
    }
  ],
  "meta": {
    "total_options": 3,
    "search_time_ms": 850,
    "suppliers_queried": ["HOTELBEDS", "EXPEDIA", "BEDSONLINE"],
    "cache_hit": false
  }
}

# 批量查价 API（多酒店）
POST   /api/v2/prices/batch-search

# 报价验证 API（下单前验证报价是否仍有效）
POST   /api/v2/prices/verify

订单管理

接口设计

# 订单 API
POST   /api/v2/orders                     # 创建订单（下单）
GET    /api/v2/orders/:order_no           # 查询订单详情
GET    /api/v2/orders                     # 订单列表（分页+筛选）
PUT    /api/v2/orders/:order_no/cancel    # 取消订单
PUT    /api/v2/orders/:order_no/modify    # 修改订单
POST   /api/v2/orders/:order_no/remarks   # 添加备注

# 供应商回调 API
POST   /api/v2/callbacks/supplier/:code/orders  # 供应商订单状态回调
# Webhook 签名验证 + 幂等处理

# 代理商回调 API
POST   /api/v2/callbacks/agent/:code/orders/:order_no  # 通知代理商

# 创建订单请求体:
{
  "hotel_id": "HPT-001234",
  "option_id": "OPT-001",           # 查价返回的报价ID
  "check_in": "2025-03-01",
  "check_out": "2025-03-03",
  "adults": 2,
  "children": 0,
  "room_count": 1,
  "guest": {
    "name": "张三",
    "email": "zhangsan@example.com",
    "phone": "+8613800138000",
    "special_requests": "高楼层，不吸烟"
  },
  "client_reference": "AGENT-ORD-001",
  "reference_price": 1200.00         # 代理商看到的报价(防篡改校验)
}

销售管理

API 接口

GET    /api/v1/agents/:code/channels                  # 代理商的渠道列表
POST   /api/v1/agents/:code/channels                  # 创建渠道
GET    /api/v1/channels/:id                           # 渠道详情
PUT    /api/v1/channels/:id                           # 更新渠道配置
PUT    /api/v1/channels/:id/status                    # 启用/禁用渠道
DELETE /api/v1/channels/:id                           # 删除渠道
GET    /api/v1/channels/:id/statistics                # 渠道统计信息

业务逻辑

代理商创建多个渠道，每个渠道绑定不同的业务场景
每个渠道独立配置：
定价规则：关联不同 pricing_strategy_id，实现不同渠道不同加价
可见供应商：通过 allowed_suppliers 限制该渠道可查询的供应商
请求配额：rate_limit（每分钟）和 daily_limit（每日），超限返回 429
结算方式：independent_settlement = true 时该渠道独立结算
API 请求携带 X-Channel-Id 头标识当前渠道
查价引擎根据渠道 ID 过滤供应商和定价规则
渠道级别的统计独立计算（订单量、GMV、利润等）

价格管理

接口设计

# 加价策略 API
GET    /api/v1/markup/rules                  # 加价规则列表
POST   /api/v1/markup/rules                  # 创建加价规则
PUT    /api/v1/markup/rules/:id              # 更新加价规则
DELETE /api/v1/markup/rules/:id              # 删除加价规则
POST   /api/v1/markup/simulate               # 加价模拟计算
# 请求: { "net_price": 100, "agent_code": "AGT-001", "hotel_id": 123 }
# 响应: { "net_price": 100, "gross_price": 118, "applied_rules": [...], "currency": "CNY" }

# 汇率 API
GET    /api/v1/currencies                     # 币种列表+当前汇率
GET    /api/v1/currencies/:code/history       # 汇率历史
POST   /api/v1/currencies/:code/rate          # 手动更新汇率
POST   /api/v1/currencies/sync                # 同步外部汇率

# 价格合规 API
GET    /api/v1/compliance/rules               # 合规规则列表
POST   /api/v1/compliance/check               # 价格合规检查
# 请求: { "supplier_code": "HOTELBEDS", "hotel_id": 123, "gross_price": 150, "net_price": 140 }
# 响应: { "compliant": true/false, "violations": [...], "suggestion": 160 }

# 特殊日期 API
GET    /api/v1/special-dates                  # 特殊日期列表
POST   /api/v1/special-dates                  # 创建
PUT    /api/v1/special-dates/:id              # 更新

结算管理

接口设计

# 结算 API
GET    /api/v1/settlements/bills                 # 结算单列表
POST   /api/v1/settlements/bills/generate        # 手动生成结算单
GET    /api/v1/settlements/bills/:id             # 结算单详情+明细
PUT    /api/v1/settlements/bills/:id/approve     # 审批结算单
PUT    /api/v1/settlements/bills/:id/cancel      # 取消结算单

# 对账 API
GET    /api/v1/settlements/reconciliation        # 对账结果列表
POST   /api/v1/settlements/reconciliation/run    # 触发对账
GET    /api/v1/settlements/reconciliation/disputes  # 争议列表

# 发票 API
GET    /api/v1/settlements/invoices              # 发票列表
POST   /api/v1/settlements/invoices              # 创建发票申请
PUT    /api/v1/settlements/invoices/:id/status   # 更新发票状态

# 付款 API
GET    /api/v1/settlements/payments              # 付款列表
POST   /api/v1/settlements/payments              # 记录付款
PUT    /api/v1/settlements/payments/:id/confirm  # 确认付款

# 财务报表 API
GET    /api/v1/settlements/reports/profit        # 利润报表
GET    /api/v1/settlements/reports/receivables   # 应收账龄分析
GET    /api/v1/settlements/reports/payables      # 应付账龄分析

库存管理

接口设计

# 库存管理 API (内部)
POST   /api/v1/inventory/hold                 # 预占库存
# 请求: { "order_id": 123, "supplier_code": "HB", "hotel_id": "X", "room_code": "DBL", "date": "2025-03-01", "count": 1 }
DELETE /api/v1/inventory/hold/:order_id       # 释放库存
GET    /api/v1/inventory/status               # 查询库存状态
POST   /api/v1/inventory/sync/:supplier_code  # 触发库存同步

# 关停房 API (管理后台)
GET    /api/v1/stop-sells                     # 关停房列表
POST   /api/v1/stop-sells                     # 创建关停房
DELETE /api/v1/stop-sells/:id                 # 删除关停房

# 配额管理 API
GET    /api/v1/inventory/allocations          # 配额列表
POST   /api/v1/inventory/allocations          # 创建配额
PUT    /api/v1/inventory/allocations/:id      # 更新配额

风控体系

接口设计

# 风控内部 API (被其他模块调用)
POST   /api/v1/risk/check-price              # 价格风控检查
# 请求: { "net_price": 100, "gross_price": 80, "hotel_id": 123 }
# 响应: { "passed": false, "reason": "售价低于采购价", "severity": "high" }

POST   /api/v1/risk/check-credit             # 信用额度检查
# 请求: { "agent_code": "AGT-001", "amount": 5000 }
# 响应: { "passed": true, "remaining_credit": 15000, "usage_rate": 0.25 }

POST   /api/v1/risk/check-traffic            # 流量风控检查
# 请求: { "ip": "1.2.3.4", "agent_code": "AGT-001", "endpoint": "/prices/search" }
# 响应: { "passed": true, "remaining_quota": 450 }

POST   /api/v1/risk/hold-credit              # 冻结信用额度
POST   /api/v1/risk/release-credit           # 释放信用额度

# 风控管理 API (管理后台)
GET    /api/v1/risk/rules                    # 风控规则列表
POST   /api/v1/risk/rules                    # 创建规则
PUT    /api/v1/risk/rules/:id                # 更新规则
GET    /api/v1/risk/events                   # 风控事件列表
GET    /api/v1/risk/alerts                   # 告警列表
PUT    /api/v1/risk/alerts/:id/acknowledge   # 确认告警
GET    /api/v1/risk/blacklist                # 黑名单管理
POST   /api/v1/risk/blacklist                # 添加黑名单

数据智能

接口设计

# BI API
GET    /api/v1/analytics/dashboard             # 看板概览数据
# 响应: { "today": { "orders": 150, "gmv": 285000, "profit": 42000 }, ... }

GET    /api/v1/analytics/trends               # 趋势数据
# 参数: metric=orders/gmv/profit, period=7d/30d/90d, granularity=day/week

GET    /api/v1/analytics/hotels/top            # 热门酒店排行
GET    /api/v1/analytics/suppliers/ranking     # 供应商排行

# 评分 API
GET    /api/v1/analytics/suppliers/:code/score # 供应商评分详情
GET    /api/v1/analytics/agents/:code/score    # 代理商评分详情

# 预测 API
GET    /api/v1/analytics/forecast?hotel_id=123&date_from=2025-03-01&date_to=2025-03-31

# 报表 API
GET    /api/v1/reports                        # 报表列表
POST   /api/v1/reports/generate               # 手动生成报表
GET    /api/v1/reports/:id/download           # 下载报表

API 网关

接口设计

API 网关本身提供的管理接口：

# API Key 管理
POST   /api/v1/admin/api-keys                 # 创建 API Key
GET    /api/v1/admin/api-keys                 # 列表
PUT    /api/v1/admin/api-keys/:id/status      # 启用/禁用
POST   /api/v1/admin/api-keys/:id/rotate      # 轮换密钥

# 限流管理
GET    /api/v1/admin/rate-limits              # 限流规则列表
POST   /api/v1/admin/rate-limits              # 创建规则
PUT    /api/v1/admin/rate-limits/:id          # 更新规则

# 日志查询
GET    /api/v1/admin/logs/requests            # 请求日志查询

# 健康检查
GET    /health                                # 健康检查
GET    /ready                                 # 就绪检查
GET    /metrics                               # Prometheus 指标

AI 决策支持引擎

API 接口

方法	路径	说明
GET	/api/insights/rules	获取所有规则
POST	/api/insights/rules	创建规则
GET	/api/insights/events	获取事件列表
POST	/api/insights/events/{id}/feedback	提交反馈

业务逻辑

系统每小时触发一次全量扫描任务，逐条检查 insight_rules 中 enabled=true 的规则。从指标存储中拉取对应 metric_source 的数据，与 condition 中定义的阈值/趋势做比对。触发后生成 insight_events 记录，通过飞书机器人推送消息。用户在飞书中回复"执行"或"忽略"后，系统回调更新 user_feedback 和 status 字段，同时记录决策偏好用于优化后续建议策略。

自主执行权限管理

API 接口

方法	路径	说明
GET	/api/permissions/policies	获取权限策略列表
PUT	/api/permissions/policies/{id}	更新权限策略
GET	/api/permissions/execution-log	获取执行日志

业务逻辑

AI Agent 在执行任何操作前，先查询 permission_policy 匹配 action_category + action_name，获得对应的权限级别。L1 操作直接执行并记录日志；L2 操作先执行，完成后通过飞书通知；L3 操作发送审批请求，等待人工确认。conditions 字段支持时间窗口、环境等额外条件，例如 L2 操作在非工作时间自动升级为 L3。

供应商自动接入流水线

API 接口

方法	路径	说明
POST	/api/suppliers/onboarding	创建供应商接入任务
PUT	/api/suppliers/onboarding/{id}/advance	推进到下一阶段
GET	/api/suppliers/onboarding/{id}/test-results	获取测试结果

业务逻辑

创建 supplier_onboarding 记录后，状态机驱动整个流程。每个阶段有对应的自动化任务：adapter_dev 阶段根据 API 文档自动生成适配器骨架代码；mock_test 阶段运行 Mock 测试用例；integration_test 阶段对接真实供应商沙箱环境；staging 阶段小流量灰度验证；全部通过后进入 production。任何阶段失败进入 failed 状态，记录 notes 供人工排查。

工单系统

API 接口

方法	路径	说明
POST	/api/tickets	创建工单
GET	/api/tickets	获取工单列表
GET	/api/tickets/{id}	获取工单详情
POST	/api/tickets/{id}/diagnose	触发 AI 诊断
PUT	/api/tickets/{id}/resolve	解决工单

业务逻辑

工单可通过人工创建（source=manual）、AI Agent 自动创建（source=agent）或监控系统触发（source=monitor）。创建后自动进入 open 状态，AI 根据工单描述和关联数据执行自动诊断，结果写入 diagnosis 和 suggestion 字段，同时记录 ticket_timeline。P0 工单自动升级通知，P3 工单可异步处理。解决后记录 resolution 和 resolved_at，关闭时记录 closed_at。

结构化知识库

API 接口

方法	路径	说明
GET	/api/knowledge	获取知识列表
POST	/api/knowledge	创建知识条目
PUT	/api/knowledge/{id}	更新知识条目
DELETE	/api/knowledge/{id}	删除知识条目
POST	/api/knowledge/search	全文搜索
POST	/api/knowledge/{id}/reference	添加引用关联

业务逻辑

知识条目支持手动录入（source=manual）和自动沉淀（source=auto_decision/auto_incident/auto_config）。当工单解决或决策执行后，AI 自动提取关键信息生成知识条目，confidence 初始值根据来源可信度设定。每次 AI 查询命中某条知识时，reference_count 自增，并创建 knowledge_references 记录关联上下文。搜索采用 pg_trgm 模糊匹配 + tsvector 全文检索双路召回。

财务感知与预警

API 接口

方法	路径	说明
GET	/api/financial/metrics	获取财务指标
GET	/api/financial/alerts	获取预警列表
GET	/api/financial/dashboard	获取财务仪表盘

业务逻辑

每日定时任务从结算模块拉取前一日财务数据，计算各维度的佣金、供应商贡献、代理商收入等指标，写入 financial_metrics。系统根据预设阈值检测异常（如收入环比下降超过 10%、供应商回款逾期、信用额度接近上限），触发后生成 financial_alerts 记录并通过飞书推送。所有 API 仅提供只读访问，不暴露任何资金操作接口。

指标采集与全链路 Trace

API 接口

方法	路径	说明
GET	/api/traces/{trace_id}	按 Trace ID 查询
GET	/api/traces/by-order/{order_id}	按订单号查询
GET	/api/traces/by-hotel/{hotel_id}	按酒店 ID 查询

业务逻辑

每个请求进入 API 网关时生成 trace_id，在服务间调用链中透传。每个服务处理完请求后写入一条 trace_events 记录，包含 span_id（当前环节）和 parent_span_id（上游环节），形成树状调用链。查询时通过 related_type + related_id 可快速定位某个订单/酒店的所有链路事件。PG 存储最近 30 天热数据，超过 30 天的数据通过定时任务归档到 ClickHouse，查询 API 自动路由到对应存储。

附录 A: 项目目录结构

hotel-distribution-platform/
├── cmd/
│   ├── api/                    # API 服务入口
│   ├── admin/                  # 管理后台后端入口
│   ├── worker/                 # 异步任务 worker
│   └── migrate/                # 数据库迁移工具
├── internal/
│   ├── config/                 # 配置管理
│   ├── middleware/              # Gin 中间件 (鉴权/限流/日志)
│   ├── handler/                # HTTP handlers
│   │   ├── hotel/
│   │   ├── pricing/
│   │   ├── order/
│   │   ├── matching/
│   │   ├── settlement/
│   │   └── admin/
│   ├── service/                # 业务逻辑层
│   │   ├── hotel.go
│   │   ├── matching.go
│   │   ├── pricing_engine.go
│   │   ├── order.go
│   │   ├── inventory.go
│   │   ├── settlement.go
│   │   ├── risk.go
│   │   └── agent.go
│   ├── repository/             # 数据访问层
│   │   ├── postgres/
│   │   └── redis/
│   ├── model/                  # 数据模型
│   ├── supplier/               # 供应商适配器
│   │   ├── adapter.go          # 统一接口
│   │   ├── hotelbeds/
│   │   ├── expedia/
│   │   └── mock/
│   ├── task/                   # 异步任务定义
│   └── pkg/                    # 内部工具包
│       ├── cache/
│       ├── httputil/
│       ├── money/
│       └── validation/
├── api/                        # OpenAPI/Swagger 定义
├── migrations/                 # SQL 迁移文件
├── deployments/                # Docker/Compose 文件
│   ├── docker-compose.yml
│   └── Dockerfile
├── scripts/                    # 运维脚本
├── docs/                       # 文档
├── web/                        # Vue 3 管理后台前端
│   ├── src/
│   │   ├── views/
│   │   ├── components/
│   │   ├── api/
│   │   ├── store/
│   │   └── router/
│   └── package.json
├── go.mod
├── go.sum
├── Makefile
└── README.md

附录 B: 供应商适配器接口设计

// internal/supplier/adapter.go

// SupplierAdapter 供应商统一适配接口
type SupplierAdapter interface {
    // 基本信息
    Name() string
    Code() string

    // 搜索酒店
    SearchHotels(ctx context.Context, req *SearchHotelsRequest) (*SearchHotelsResponse, error)

    // 查价
    SearchRates(ctx context.Context, req *SearchRatesRequest) (*SearchRatesResponse, error)

    // 预订
    CreateBooking(ctx context.Context, req *CreateBookingRequest) (*CreateBookingResponse, error)

    // 取消预订
    CancelBooking(ctx context.Context, req *CancelBookingRequest) (*CancelBookingResponse, error)

    // 查询订单
    GetBooking(ctx context.Context, bookingRef string) (*BookingDetail, error)

    // 库存查询
    CheckAvailability(ctx context.Context, req *CheckAvailabilityRequest) (*CheckAvailabilityResponse, error)

    // 健康检查
    HealthCheck(ctx context.Context) error
}

// 请求/响应结构体定义...

附录 C: 核心配置示例

# config/config.yaml

server:
  port: 8080
  mode: development  # development / production
  read_timeout: 30s
  write_timeout: 60s

database:
  host: localhost
  port: 5432
  user: hotel_platform
  password: ${DB_PASSWORD}
  dbname: hotel_platform
  max_open_conns: 50
  max_idle_conns: 10

redis:
  host: localhost
  port: 6379
    password: ${REDIS_PASSWORD}
  db: 0
  pool_size: 20

pricing:
  cache_ttl: 300s           # 查价缓存 5 分钟
  local_cache_ttl: 60s      # 本地缓存 1 分钟
  supplier_timeout: 3s      # 单供应商查询超时
  max_concurrent: 10        # 最大并发查价数
  default_currency: CNY

inventory:
  hold_ttl: 1800s           # 库存预占 30 分钟
  cleanup_interval: 300s    # 清理间隔 5 分钟
  sync_interval: 600s       # 库存同步间隔 10 分钟

risk:
  credit_check_enabled: true
  price_check_enabled: true
  rate_limit_per_minute: 60  # 默认每分钟限流

log:
  level: info
  format: json
  output: stdout

suppliers:
  hotelbeds:
    enabled: true
    api_key: ${HOTELBEDS_API_KEY}
    api_secret: ${HOTELBEDS_API_SECRET}
    endpoint: https://api.hotelbeds.com
    timeout: 5s
    priority: 10
  expedia:
    enabled: false
    api_key: ${EXPEDIA_API_KEY}
    endpoint: https://api.expediapartners.com
    timeout: 5s
    priority: 5

文档结束
本文档为 B2B2B 酒店分销平台系统架构的完整设计，涵盖 12 个模块的详细设计、技术选型、成本估算和开发路线图。
适用于 Demo 驱动融资场景，后续可根据投资人反馈和实际业务需求迭代优化。