分贝通酒店预定助手 (fb-hotel-skill)

技能描述

分贝通酒店预定助手，实时查询搜索酒店、展示酒店列表、查询酒店房型、展示房型产品和报价、预定酒店、查看订单、取消订单、查看酒店基础信息和酒店评论信息。

---

🔐 鉴权流程（必须先完成）

重要：使用任何功能前，用户必须先完成鉴权流程。鉴权成功后获得的 identity_code（access-token）会自动保存在 ~/.fbt-auth.json 文件中，新会话会自动沿用。

鉴权步骤

步骤 1：发送验证码

用户回复: 分贝通登录
AI: 请输入您的手机号以接收验证码（例如：13800138000）

用户输入: 13800138000
AI: ✅ 验证码已发送到 138****8000，请在5分钟内输入验证码

API调用：

from scripts.fb_hotel_api import send_verification_code

result = send_verification_code("13800138000")
# 成功响应: {"code": 0, "msg": "success", "data": true}

步骤 2：验证并获取 identity_code

用户输入: 1234
AI: 🎉 认证成功！身份编码已保存到 ~/.fbt-auth.json，有效期90天
    现在可以使用分贝通企业接口了

API调用：

from scripts.fb_hotel_api import verify_and_get_token

success, result = verify_and_get_token("13800138000", "1234")
if success:
    access_token = result  # fbsk-xxx
    # token 已自动保存到 ~/.fbt-auth.json
else:
    print(f"验证失败: {result}")

步骤 3：自动注入（后续调用）

后续所有 API 调用会自动从 ~/.fbt-auth.json 读取 token：

from scripts.fb_hotel_api import FbHotelApi

# 无需传入 token，自动从文件读取
api = FbHotelApi()
result = api.search_hotel_list(city_name="北京市", keywords="国贸")

Token 存储管理

| 文件 | 路径 | 说明 | |-----|------|------| | 鉴权文件 | ~/.fbt-auth.json | 保存 identity_code 和手机号 |

文件格式：

{
  "identity_code": "fbsk-2db251f6c8d74ce69ae3dcb82ed1055b",
  "mobile": "138****8000",
  "created_at": "2026-03-25T09:48:00",
  "updated_at": "2026-03-25T09:48:00"
}

API 函数

from scripts.fb_hotel_api import (
    save_auth_token,    # 保存 token
    load_auth_token,    # 读取 token
    get_auth_info,      # 获取完整认证信息
    clear_auth_token    # 清除认证信息
)

# 保存 token
save_auth_token("fbsk-xxx", "13800138000")

# 读取 token
token = load_auth_token()

# 获取完整信息
info = get_auth_info()  # {"identity_code": "...", "mobile": "..."}

# 清除认证
clear_auth_token()

接口鉴权说明

| skill_type | 接口名称 | 需要认证 | |------------|---------|---------| | getMobileCaptcha | 获取手机号验证码 | ❌ 否 | | getIdentityCode | 获取身份编码 | ❌ 否 | | searchHotelList | 搜索酒店列表 | ✅ 是 | | queryHotelPrice | 查询酒店价格详情 | ✅ 是 | | queryHotelDetail | 查询酒店扩展详情 | ✅ 是 | | queryHotelComment | 查询酒店评论 | ✅ 是 | | createOrder | 酒店下单 | ✅ 是 | | cancelOrder | 取消订单 | ✅ 是 | | queryOrder | 查询订单 | ✅ 是 |

---

⚠️ 【重要约束】

• 必须调用 scripts/fb_hotel_api.py 中的函数获取数据
• 禁止自行编造酒店信息、价格或评论
• 接口返回什么数据就展示什么，不要修改
• 首次使用必须先完成分贝通企业认证

---

对接信息

环境配置

| 环境 | 域名 | |-----|------| | FAT 测试环境 | https://app-gate.fenbeitong.com | | 线上环境 | https://app-gate.fenbeitong.com |

统一接口入口

所有接口统一使用同一入口：

POST /business/hotel/open/push/skill/access

通过 skill_type 参数区分不同操作。

请求格式

Headers:

Content-Type: application/json
access-token: fbsk-xxx  （认证类接口除外）

Body:

{
    "skill_type": "searchHotelList",
    // 其他参数...
}

---

核心接口列表

一、认证类接口

1. 获取手机号验证码

skill_type: getMobileCaptcha

请求示例：

curl --location 'https://app-gate.fenbeitong.com/business/hotel/open/push/skill/access' \
--header 'Content-Type: application/json' \
--data '{
    "skill_type":"getMobileCaptcha",
    "mobile":"18301187051"
}'

响应示例：

{
    "request_id": "nQabT9pHt5u5m0mA",
    "code": 0,
    "msg": "success",
    "data": true
}

2. 获取身份编码

skill_type: getIdentityCode

请求示例：

curl --location 'https://app-gate.fenbeitong.com/business/hotel/open/push/skill/access' \
--header 'Content-Type: application/json' \
--data '{
    "skill_type":"getIdentityCode",
    "mobile":"18301187051",
    "captcha":"1234"
}'

响应示例：

{
    "request_id": "oKXv9eCYuFIXoxRn",
    "code": 0,
    "msg": "success",
    "data": {
        "identity_code": "fbsk-2db251f6c8d74ce69ae3dcb82ed1055b"
    }
}

---

二、酒店查询接口

1. 搜索酒店列表

skill_type: searchHotelList

请求参数： | 参数 | 类型 | 必填 | 说明 | |-----|------|-----|------| | city_name | string | 是 | 城市名称（如"北京市"） | | keywords | string | 否 | 关键词（用户输入原样传递） | | hotel_name | string | 否 | 酒店名称 | | page_index | int | 否 | 页码，默认1 | | page_size | int | 否 | 每页数量，默认5 |

请求示例：

curl --location 'https://app-gate.fenbeitong.com/business/hotel/open/push/skill/access' \
--header 'access-token: fbsk-2db251f6c8d74ce69ae3dcb82ed1055b' \
--header 'Content-Type: application/json' \
--data '{
    "skill_type":"searchHotelList",
    "city_name":"北京市",
    "keywords":"预订北京国贸附近1公里的酒店",
    "page_index":1,
    "page_size":5
}'

响应字段： | 字段 | 说明 | |-----|------| | hotel_id | 酒店ID | | name | 酒店名称 | | star_level_name | 星级类型（高档型、豪华型等） | | address | 地址 | | district_name | 区域 | | business_zone_name | 商圈 | | score | 评分 | | min_price | 最低价 | | main_logo | 酒店图片 |

2. 查询酒店价格详情

skill_type: queryHotelPrice

请求参数： | 参数 | 类型 | 必填 | 说明 | |-----|------|-----|------| | hotel_id | string | 是 | 酒店ID | | check_in_date | string | 是 | 入住日期 yyyy-MM-dd | | check_out_date | string | 是 | 退房日期 yyyy-MM-dd | | payment_type | string | 否 | 支付方式 PP=预付 SP=现付 | | nation_type | int | 否 | 1=国内 2=国际 |

请求示例：

curl --location 'https://app-gate.fenbeitong.com/business/hotel/open/push/skill/access' \
--header 'access-token: fbsk-2db251f6c8d74ce69ae3dcb82ed1055b' \
--header 'Content-Type: application/json' \
--data '{
    "skill_type":"queryHotelPrice",
    "nation_type":1,
    "payment_type":"PP",
    "hotel_id":"5a39df2fbbfdc4732360eaa9",
    "check_in_date":"2026-03-27",
    "check_out_date":"2026-03-28"
}'

响应字段： | 字段 | 说明 | |-----|------| | hotel | 酒店基本信息 | | rooms[] | 房型列表 | | rooms[].room_id | 房型ID | | rooms[].room_name | 房型名称 | | rooms[].bed_type | 床型 | | rooms[].window_type | 窗户类型 | | rooms[].area | 面积 | | rooms[].status | 是否可预订 | | rooms[].plan_list[] | 产品列表 | | plan_list[].plan_id | 产品ID | | plan_list[].plan_name | 产品名称 | | plan_list[].breakfast | 早餐 | | plan_list[].cancel_type | 取消政策类型 | | plan_list[].cancel_rule | 取消政策详情 | | plan_list[].total_price | 总价 | | plan_list[].status | 是否可预订 |

3. 查询酒店扩展详情

skill_type: queryHotelDetail

请求参数： | 参数 | 类型 | 必填 | 说明 | |-----|------|-----|------| | hotel_id | string | 是 | 酒店ID |

4. 查询酒店评论

skill_type: queryHotelComment

请求参数： | 参数 | 类型 | 必填 | 说明 | |-----|------|-----|------| | hotel_id | string | 是 | 酒店ID | | page_index | int | 否 | 页码 | | page_size | int | 否 | 每页数量 |

请求示例：

curl --location 'https://app-gate.fenbeitong.com/business/hotel/open/push/skill/access' \
--header 'access-token: fbsk-2db251f6c8d74ce69ae3dcb82ed1055b' \
--header 'Content-Type: application/json' \
--data '{
    "skill_type":"queryHotelComment",
    "hotel_id":"8502475",
    "page_size":5
}'

---

三、订单接口

1. 酒店下单

skill_type: createOrder

请求参数： | 参数 | 类型 | 必填 | 说明 | |-----|------|-----|------| | nation_type | int | 是 | 1=国内 2=国际 | | payment_type | string | 是 | PP=预付 SP=现付 | | hotel_id | string | 是 | 酒店ID | | check_in_date | string | 是 | 入住日期 | | check_out_date | string | 是 | 退房日期 | | room_id | string | 是 | 房型ID | | plan_id | string | 是 | 产品ID | | total_price | float | 是 | 总价 | | room_count | int | 是 | 房间数 | | contact | object | 是 | 联系人信息 | | guestList1 | array | 是 | 入住人列表（二维数组） |

请求示例：

curl --location 'https://app-gate.fenbeitong.com/business/hotel/open/push/skill/access' \
--header 'access-token: fbsk-2db251f6c8d74ce69ae3dcb82ed1055b' \
--header 'Content-Type: application/json' \
--data '{
    "skill_type":"createOrder",
    "nation_type":1,
    "payment_type":"PP",
    "hotel_id":"5a39df2fbbfdc4732360eaa9",
    "check_in_date":"2026-03-27",
    "check_out_date":"2026-03-28",
    "room_id":"7617d7bbb3a94537a58bb3d33108b429",
    "plan_id":"69c23ae4e37c7d156e3e0c01",
    "total_price":280,
    "room_count":1,
    "contact":{
        "name":"周聪",
        "phone":"18301187051"
    },
    "guestList1":[
        [
            {
                "name":"周聪",
                "phone":"13126525502"
            }
        ]
    ]
}'

重要：guestList1 参数必须为二维数组格式！

2. 取消订单

skill_type: cancelOrder

请求参数： | 参数 | 类型 | 必填 | 说明 | |-----|------|-----|------| | order_id | string | 是 | 订单ID | | cancel_reason | string | 否 | 取消原因 |

请求示例：

curl --location 'https://app-gate.fenbeitong.com/business/hotel/open/push/skill/access' \
--header 'access-token: fbsk-2db251f6c8d74ce69ae3dcb82ed1055b' \
--header 'Content-Type: application/json' \
--data '{
    "skill_type":"cancelOrder",
    "order_id": "69c23b67e37c7d156e3e0c1b",
    "cancel_reason":"取消原因"
}'

3. 查询订单

skill_type: queryOrder

请求参数： | 参数 | 类型 | 必填 | 说明 | |-----|------|-----|------| | order_id | string | 是 | 订单ID |

请求示例：

curl --location 'https://app-gate.fenbeitong.com/business/hotel/open/push/skill/access' \
--header 'access-token: fbsk-2db251f6c8d74ce69ae3dcb82ed1055b' \
--header 'Content-Type: application/json' \
--data '{
    "skill_type":"queryOrder",
    "order_id": "69c23b67e37c7d156e3e0c1b"
}'

---

四、收银台支付

订单创建成功后，通过以下链接引导用户完成支付：

| 类型 | 链接格式 | |-----|---------| | 立即支付 | {域名}/business/hotel/open/push/redirect?orderId={order_id}&type=0&token={access_token} | | 查看订单 | {域名}/business/hotel/open/push/redirect?orderId={order_id}&type=1&token={access_token} |

FAT环境示例：

• 支付：https://app-gate.fenbeitong.com/business/hotel/open/push/redirect?orderId={order_id}&type=0&token=fbsk-xxx
• 订单：https://app-gate.fenbeitong.com/business/hotel/open/push/redirect?orderId={order_id}&type=1&token=fbsk-xxx

---

使用流程

1. 酒店搜索

触发条件：用户输入「酒店搜索/订酒店/找酒店/搜酒店」+ 城市/关键词

步骤：

1. 检查用户认证状态
2. 调用 search_hotel_list() 获取酒店列表
3. 格式化展示酒店列表（表格形式）

展示格式：

🏨 北京国贸附近酒店

| 序号 | 酒店名称 | 星级 | 区域 | 最低价 |
|:---:|---------|:---:|------|---:|
| 1 | 北京建国饭店 | 高档型 | 朝阳区 | ¥572 |
| 2 | 北京共享际5L饭店 | 高档型 | 朝阳区 | ¥712 |

💡 回复序号查看房型价格，如"1"
💡 回复"序号-详情"查看酒店信息和评论，如"1-详情"

2. 查看房型价格

触发条件：用户回复序号（如"1"）

步骤：

1. 获取酒店ID（从之前的搜索结果）
2. 调用 query_hotel_price() 获取房型和产品
3. 过滤 status=false 的房型和产品
4. 展示前5个房型，每个房型展示前5个产品

展示格式：

🏨 汉庭酒店(北京长虹桥店)
📍 农展馆南里12号院5号楼 | ⭐4.8分 | 经济型
📅 入住：2026-03-27 → 退房：2026-03-28

**房型1：测试房型**
床型：2张1.80m大床 | 窗户：有窗 | 面积：22㎡
| 序号 | 价格 | 早餐 | 取消政策 | 取消详情 |
|:---:|---:|:---:|:---:|---|
| 1-1 | ¥1 | 单早 | ✅限时取消 | 3月26日 12:00前免费取消... |

💡 回复"房型序号-产品序号"预订，如"1-1"

3. 创建订单

触发条件：用户回复"房型序号-产品序号"（如"1-1"）

步骤：

1. 收集入住人信息（姓名、手机号）
2. 构建请求参数（注意 guestList1 为二维数组）
3. 调用 create_order() 创建订单
4. 展示订单信息和支付链接

展示格式：

✅ 订单创建成功！

🏨 订单号：69c23b67e37c7d156e3e0c1b
📅 入住：2026-03-27 → 退房：2026-03-28
🛏️ 房型：测试房型
💰 价格：¥280
📋 最晚取消时间：2026-03-26 12:00:00

🔗 [立即支付](https://app-gate.fenbeitong.com/...)
🔗 [查看订单详情](https://app-gate.fenbeitong.com/...)

---

Python API 参考

from scripts.fb_hotel_api import FbHotelApi, send_verification_code, verify_and_get_token

# 初始化（使用默认token或指定token）
api = FbHotelApi(access_token="fbsk-xxx")

# 发送验证码
result = send_verification_code("13800138000")

# 验证并获取token
success, token = verify_and_get_token("13800138000", "1234")

# 搜索酒店
result = api.search_hotel_list(
    city_name="北京市",
    keywords="国贸附近",
    page_size=5
)

# 查询酒店价格
result = api.query_hotel_price(
    hotel_id="5a39df2fbbfdc4732360e860",
    check_in_date="2026-03-27",
    check_out_date="2026-03-28"
)

# 查询酒店扩展详情
result = api.query_hotel_detail(hotel_id="5a39df2fbbfdc4732360e860")

# 查询酒店评论
result = api.query_hotel_comment(hotel_id="8502475", page_size=5)

# 创建订单
result = api.create_order(
    hotel_id="5a39df2fbbfdc4732360eaa9",
    room_id="7617d7bbb3a94537a58bb3d33108b429",
    plan_id="69c23ae4e37c7d156e3e0c01",
    check_in_date="2026-03-27",
    check_out_date="2026-03-28",
    total_price=280,
    contact={"name": "张三", "phone": "13800138000"},
    guest_list=[[{"name": "张三", "phone": "13800138000"}]]
)

# 查询订单
result = api.query_order(order_id="69c23b67e37c7d156e3e0c1b")

# 取消订单
result = api.cancel_order(order_id="69c23b67e37c7d156e3e0c1b", cancel_reason="不想要了")

# 格式化输出
print(api.format_hotel_list(result))
print(api.format_hotel_price(result, "2026-03-27", "2026-03-28"))

---

📝 格式化输出模块

文件位置：scripts/formatter.py

展示配置

| 配置项 | 默认值 | 说明 | |-------|-------|------| | HOTEL_LIST_LIMIT | 5 | 酒店列表展示数量 | | ROOM_LIST_LIMIT | 5 | 房型展示数量 | | PLAN_LIST_LIMIT | 5 | 每个房型展示的产品数量 |

格式化函数

from scripts.formatter import (
    format_hotel_list,      # 酒店列表格式化
    format_hotel_rooms,     # 房型价格格式化
    format_order_result,    # 订单创建结果格式化
    format_trip_plan,       # 行程规划格式化
    format_order_confirmation,  # 订单确认格式化
    format_order_detail_full    # 完整订单详情格式化
)

展示字段规范

酒店列表必须包含：

• 序号、酒店名称、评分、星级、地址、最低价

房型价格必须包含：

• 序号、房型名称、床型、面积、窗户类型
• 价格、早餐、取消政策类型、取消详情

订单详情必须包含：

• 订单号、酒店信息、房型信息
• 床型、面积、窗户、早餐、价格
• 取消政策类型和详情
• [立即支付] 按钮（不是"查看订单详情"）

---

版本历史

| 版本 | 日期 | 变更说明 | |-----|------|---------| | 3.1.0 | 2026-03-25 | 新增格式化输出模块，固化展示逻辑 | | 3.0.0 | 2026-03-25 | 统一接口入口，新增认证流程，重构API | | 2.9.1 | 2026-03-20 | 修复订单创建问题 | | 1.9.1 | 2026-03-15 | 新增酒店评论查询 |