B2B2B 酒店分销平台系统架构文档

版本: v1.0
适用场景: 一人公司 + AI 搭档，技术驱动，几万块启动资金，Demo 驱动融资
目标读者: 创始人/技术负责人、投资人
编写日期: 2025-01

目录

• 1. 项目概述
• 2. 整体系统架构
• 3. 技术栈选型及理由
• 4. 模块间调用关系图
• 5. 数据流图
• 6. 模块详细设计
• 6.1 酒店房型基库
• 6.2 匹配管理
• 6.3 查价引擎
• 6.4 订单管理
• 6.5 销售管理
• 6.6 价格管理
• 6.7 结算管理
• 6.8 库存管理
• 6.9 风控体系
• 6.10 数据智能
• 6.11 API 网关
• 6.12 管理后台
• 6. 缓存架构
• 6.1 三级缓存架构
• 6.2 缓存粒度设计
• 6.3 缓存失效策略（Tag 清理 + Pub/Sub）
• 6.4 热点数据分层 TTL
• 6.5 防击穿与防雪崩
• 6.6 多实例一致性
• 7. MVP 范围定义
• 8. 成本估算
• 9. 开发路线图
• 10. 风险与对策
• 11. 补充能力模块
• 11.1 缓存策略
• 11.2 消息队列设计
• 11.3 分库分表策略
• 11.4 多租户架构
• 12. AI Agent 智能运营层
• 12.1 决策支持引擎（Insight Engine）
• 12.2 自主执行权限管理
• 12.3 供应商自动接入流水线
• 12.4 工单系统（Ticket System）
• 12.5 结构化知识库
• 12.6 财务感知与预警
• 12.7 指标采集与全链路 Trace

1. 项目概述

1.1 什么是 B2B2B 酒店分销

B2B2B 酒店分销平台连接三方：酒店/批发商（供应商） → 本平台 → OTA/旅行社/代理商（采购方）。

核心价值： - 聚合供应商：统一接入多个酒店批发商和直签酒店 - 标准化数据：异构房型、价格、库存统一映射 - 智能分发：根据渠道需求匹配最优价格和可用性 - 自动化运营：订单、结算、对账全流程自动化

1.2 核心业务流程

代理商查价 → 平台聚合多供应商报价 → 代理商下单 → 平台向供应商下单 
→ 供应商确认/拒绝 → 订单履约 → 对账结算 → 佣金结算

1.3 关键成功指标

2. 整体系统架构

flowchart TB
    subgraph Clients["客户端层"]
        A1["代理商API接入
OTA/旅行社"]
        A2["管理后台Web
运营人员"]
        A3["供应商对接
API/文件"]
    end

    subgraph Gateway["网关层"]
        G1["API Gateway
Kong/Nginx"]
        G2["认证鉴权
JWT + API Key"]
        G3["限流熔断
Sentinel"]
        G4["日志采集
+ 请求追踪"]
    end

    subgraph Services["业务服务层"]
        S1["酒店基库服务
Hotel Service"]
        S2["匹配服务
Mapping Service"]
        S3["查价引擎
Pricing Engine"]
        S4["订单服务
Order Service"]
        S5["销售服务
Sales Service"]
        S6["价格服务
Rate Service"]
        S7["结算服务
Settlement Service"]
        S8["库存服务
Inventory Service"]
        S9["风控服务
Risk Control"]
        S10["数据智能
Data Intelligence"]
    end

    note_left[connection_mode决定服务路由: direct_connect实时查价 direct_procure查本地库存]


    subgraph Middleware["中间件层"]
        MQ["消息队列
RabbitMQ"]
        CACHE["缓存层
Redis Cluster"]
        CONFIG["配置中心
Nacos"]
    end

    subgraph Data["数据层"]
        DB["PostgreSQL
主库 (业务数据)"]
        RO["PostgreSQL
只读副本"]
        CH["ClickHouse
分析库"]
        ES["Elasticsearch
搜索引擎"]
        OBJ["MinIO/OSS
对象存储"]
    end

    subgraph External["外部对接"]
        E1["供应商API
Hotelbeds/Expedia等"]
        E2["支付网关
Stripe/支付宝"]
        E3["通知服务
Email/SMS"]
        E4["汇率API
ExchangeRate"]
    end

    A1 --> G1
    A2 --> G1
    A3 --> G1
    G1 --> G2 --> G3 --> G4
    G1 --> S1
    G1 --> S3
    G1 --> S4
    G1 --> S5
    G3 --> S9

    S1 <--> S2
    S2 --> S3
    S3 <--> S6
    S3 <--> S8
    S4 --> S7
    S4 --> S8
    S5 --> S7
    S6 --> S3
    S8 --> S3

    S1 <--> MQ
    S4 <--> MQ
    S8 <--> MQ

    S1 --> DB
    S2 --> DB
    S3 --> CACHE
    S3 --> DB
    S4 --> DB
    S5 --> DB
    S6 --> DB
    S6 --> CACHE
    S7 --> DB
    S8 --> DB
    S8 --> CACHE

    S10 --> CH
    S10 --> ES
    S1 --> ES

    Services --> External
    class A1,A2,A3,G1,G2,G3,G4,S1,S2,S3,S4,S5,S6,S7,S8,S9,S10,MQ,CACHE,CONFIG,DB,RO,CH,ES,OBJ,E1,E2,E3,E4 process
    classDef process fill:#1a2744,stroke:#58a6ff,stroke-width:1px,color:#c9d1d9
    classDef decision fill:#3a2a1a,stroke:#f0883e,stroke-width:2px,color:#f0883e
    classDef done fill:#1a3a2a,stroke:#3fb950,stroke-width:1px,color:#3fb950
    classDef error fill:#3a1a1a,stroke:#f85149,stroke-width:2px,color:#f85149
    classDef warning fill:#3a2a1a,stroke:#d29922,stroke-width:1px,color:#d29922
    classDef skip fill:#21262d,stroke:#484f58,color:#8b949e

3. 技术栈选型及理由

3.1 核心技术栈

3.2 开发工具链

3.3 基础设施

4. 模块间调用关系图

flowchart LR
    subgraph P0["P0 核心模块"]
        API["API网关"]
        HS["酒店基库"]
        MS["匹配管理"]
        PE["查价引擎"]
        OM["订单管理"]
        AM["管理后台"]
    end

    subgraph P1["P1 增长模块"]
        SM["销售管理"]
        PM["价格管理"]
        BM["库存管理"]
        PAP["进阶定价"]
        ST["结算管理"]
        RC["风控体系"]
    end

    subgraph P2["P2 智能模块"]
        DI["数据智能"]
    end

    API --> PE
    API --> OM
    API --> AM

    HS --> MS
    MS --> PE
    PM --> PE
    PAP["进阶定价"] -.->|"Phase3"| PE
    BM --> PE
    SM -.->|"Phase1"| PE
    RC --> PE
    PE --> OM

    SM --> OM
    SM --> ST
    OM --> ST
    PM --> ST
    BM --> OM

    OM --> DI
    PE --> DI
    SM --> DI
    ST --> DI

    AM --> HS
    AM --> MS
    AM --> SM
    AM --> PM
    AM --> OM
    AM --> ST
    AM --> BM
    AM --> RC
    AM --> DI

    PE -.->|"降级查询"| CACHE["Redis缓存"]
    class API,HS,MS,PE,OM,AM,SM,PM,BM,ST,RC,DI,CACHE,PAP process
    classDef process fill:#1a2744,stroke:#58a6ff,stroke-width:1px,color:#c9d1d9
    classDef decision fill:#3a2a1a,stroke:#f0883e,stroke-width:2px,color:#f0883e
    classDef done fill:#1a3a2a,stroke:#3fb950,stroke-width:1px,color:#3fb950
    classDef error fill:#3a1a1a,stroke:#f85149,stroke-width:2px,color:#f85149
    classDef warning fill:#3a2a1a,stroke:#d29922,stroke-width:1px,color:#d29922
    classDef skip fill:#21262d,stroke:#484f58,color:#8b949e

5. 数据流图

5.1 三阶段业务数据流

查价、试单、下单三条链路均采用三阶段模型，详见各模块设计文档。

5.1.1 查价链路（Search）

flowchart TD
    START(["代理商发起查价请求"]) --> P1_BOX
    subgraph P1["Phase 1: 查价前 Pre-Query"]
        P1_BOX --> GW["Gateway
鉴权+限流"]
        GW --> CB["熔断检查
供应商/代理商"]
        CB --> VIS["可见性过滤
白名单/黑名单"]
        VIS --> CACHE{"L1/L2 缓存
是否有结果?"}
        CACHE -->|"缓存命中"| RET_CACHE["直接返回
回填L1"]
        CACHE -->|"未命中"| MAP["匹配服务
供应商映射解析"]
        MAP --> CH_CFG["渠道配置加载"]
    end

    P1_BOX -->|"熔断/无权限"| BLOCKED(["阻断返回"])

    CH_CFG --> P2_BOX
    subgraph P2["Phase 2: 查价 Query"]
        P2_BOX --> PARA["并发查价
errgroup + 超时"]
        PARA --> DC["直连供应商
调SA实时API"]
        PARA --> DP["直采供应商
查本地库存"]
        DC --> DC_FAIL{"超时/错误?"}
        DC_FAIL -->|"是"| SKIP["跳过该供应商"]
        DC_FAIL -->|"否"| DC_OK["原始报价"]
        DP --> DP_OK["原始报价"]
    end

    DC_OK --> P3_BOX
    DP_OK --> P3_BOX
    SKIP --> P3_BOX

    subgraph P3["Phase 3: 查价后 Post-Query"]
        P3_BOX --> AGG["结果聚合
去重+排序+分页"]
        AGG --> MKUP["Markup 加价"]
        MKUP --> DYN["动态定价调整"]
        DYN --> PROMO["促销匹配"]
        PROMO -> FX["汇率换算"]
        FX --> WR_CACHE["写入L2+L1缓存"]
        WR_CACHE --> LOG_Q["异步写查价日志"]
        LOG_Q --> RETURN(["返回最终报价"])
    end

    class RET_CACHE,RETURN done
    class BLOCKED error
    class START,GW,CB,VIS,CACHE,MAP,CH_CFG,PARA,DC,DP,DC_FAIL,SKIP,DC_OK,DP_OK,AGG,MKUP,DYN,PROMO,FX,WR_CACHE,LOG_Q process
    classDef process fill:#1a2744,stroke:#58a6ff,stroke-width:1px,color:#c9d1d9
    classDef decision fill:#3a2a1a,stroke:#f0883e,stroke-width:2px,color:#f0883e
    classDef done fill:#1a3a2a,stroke:#3fb950,stroke-width:1px,color:#3fb950
    classDef error fill:#3a1a1a,stroke:#f85149,stroke-width:2px,color:#f85149

5.1.2 试单 + 下单链路

flowchart TD
    SEARCH(["查价结果"]) --> V1
    subgraph V1["Verify Phase 1: 试单前"]
        V1 --> V_EXP["报价有效期检查"]
        V_EXP --> V_RISK["风控预检
信用额度"]
        V_RISK --> V_CB["熔断检查"]
    end

    V_CB --> V2
    subgraph V2["Verify Phase 2: 试单"]
        V2 --> V_SUP["供应商实时价格确认"]
        V_SUP --> V_DEV{"价格偏差
超阈值?"}
    end

    V2 --> V3
    subgraph V3["Verify Phase 3: 试单后"]
        V3 --> V_FREEZE["冻结信用额度"]
        V_FREEZE --> V_TOKEN["生成 verify_token"]
        V_TOKEN --> V_DONE(["返回确认价格
+ verify_token"])
    end

    V_DONE --> O1
    subgraph O1["Order Phase 1: 下单前"]
        O1 --> O_TOKEN["verify_token 校验"]
        O_TOKEN --> O_RECHECK["报价二次校验"]
        O_RECHECK --> O_RISK["风控检查
信用+价格异常"]
        O_RISK --> O_INV["库存预检
直采模式"]
    end

    O1 -->|"阻断"| O_BLOCK(["返回错误"])
    O_INV --> O2
    subgraph O2["Order Phase 2: 下单"]
        O2 --> O_CREATE["创建订单 PG事务"]
        O_CREATE --> O_LOCK["库存预占
Redis DECRBY"]
        O_LOCK --> O_CREDIT["信用冻结"]
        O_CREDIT --> O_SUP["调供应商API下单"]
        O_SUP --> O_RESULT{"供应商响应"}
        O_RESULT -->|"确认"| PENDING["PENDING_CONFIRM"]
        O_RESULT -->|"拒绝"| O_REJECT["REJECTED
释放库存+信用"]
    end

    PENDING --> O3
    subgraph O3["Order Phase 3: 下单后"]
        O3 --> O_NOTIFY["通知代理商"]
        O3 --> O_TIMEOUT["设置超时任务"]
        O3 --> O_LOG["写订单日志"]
    end

    PENDING -->|"Webhook确认"| CONFIRMED(["CONFIRMED"])
    PENDING -->|"超时"| EXPIRED(["EXPIRED
自动取消"])

    class V_DONE,CONFIRMED done
    class O_BLOCK,O_REJECT,EXPIRED error
    class SEARCH,V_EXP,V_RISK,V_CB,V_SUP,V_DEV,V_FREEZE,V_TOKEN,O_TOKEN,O_RECHECK,O_RISK,O_INV,O_CREATE,O_LOCK,O_CREDIT,O_SUP,O_RESULT,PENDING,O_NOTIFY,O_TIMEOUT,O_LOG process
    classDef process fill:#1a2744,stroke:#58a6ff,stroke-width:1px,color:#c9d1d9
    classDef decision fill:#3a2a1a,stroke:#f0883e,stroke-width:2px,color:#f0883e
    classDef done fill:#1a3a2a,stroke:#3fb950,stroke-width:1px,color:#3fb950
    classDef error fill:#3a1a1a,stroke:#f85149,stroke-width:2px,color:#f85149

5.2 数据分层

6. 缓存架构

6.1 三级缓存架构

查价系统采用 L1 本地内存 + L2 Redis + DB/远程 API 的三级缓存架构，逐层穿透：

请求 → L1 本地内存（sync.Map + LRU，10万条，30s TTL）
     → L2 Redis（单节点/集群，5min TTL）
     → DB / 远程 API

• L1 本地缓存：基于 sync.Map + LRU 淘汰策略，容量上限 10 万条，默认 TTL 30s。零网络开销，命中响应 < 1ms。
• L2 Redis 缓存：单节点（MVP）→ 集群（生产），默认 TTL 5min。支持 Tag 清理和 Pub/Sub 失效通知。
• L3 数据源：PostgreSQL（直采库存等）或 供应商远程 API（直连查价）。

6.2 缓存粒度设计

查价原始报价缓存

key = price:raw:{supplier_code}:{supplier_hotel_id}:{check_in}:{check_out}

• TTL：60s（直连供应商）/ 30s（直采供应商）
• 内容：仅存储供应商返回的原始报价（净价、房型、餐型等），不含 markup、动态定价、促销
• 设计理由：markup/动态定价/促销规则变更时无需清理原始报价缓存，只在缓存命中后实时计算加价，减少缓存失效频率

聚合结果缓存

key = price:agg:{hotel_id}:{check_in}:{check_out}:{adults}:{channel_code}

• TTL：5min
• 内容：包含 markup + 动态定价 + 促销后的最终价格
• 定位：作为最终兜底缓存，在所有供应商全部超时/失败时仍可返回历史结果（标记"数据可能非实时"）

6.3 缓存失效策略（Tag 清理 + Pub/Sub）

Tag 体系

为不同业务维度定义缓存 Tag，支持按维度批量清理：

Admin CRUD 操作流程

1. 写入 DB：数据持久化
2. 调用 cache.TagDelete(tags...)：批量清除 L2 Redis 中关联该 Tag 的所有缓存 key
3. 发布 Redis Pub/Sub 消息：频道 cache:invalidate:{tag}，通知所有实例
4. 所有 QE 实例订阅该 channel：收到消息后清理 L1 本地缓存中关联 key

消息格式

{"tag": "markup:all", "ts": 1713000000}

6.4 热点数据分层 TTL

6.5 防击穿与防雪崩

singleflight 合并请求

缓存 miss 时使用 singleflight 模式：只放一个请求穿透到下游，其余相同 key 的请求等待结果，避免缓存击穿。

空值缓存

查无结果也缓存（空值标记），TTL = 30s。防止恶意请求或无效查询反复穿透到数据库或供应商 API。

随机 TTL 偏移

所有缓存 TTL 增加 ±10% 随机偏移，避免大量 key 在同一时刻过期导致缓存雪崩。

实际 TTL = 基准 TTL × (0.9 + random() × 0.2)

6.6 多实例一致性

• Redis Pub/Sub 频道：cache:invalidate
• 消息格式：{"tag": "markup:all", "ts": 1713000000}
• 订阅机制：每个 QE 实例启动时自动订阅 cache:invalidate channel
• 收到消息后：根据 tag 匹配本地 L1 缓存 key，执行清理
• 幂等保证：相同 ts 的消息不重复处理，防止重复清理