瑞玥餐饮API

瑞玥餐饮 API Skill。调用商客Claw 餐饮后端接口（门店、菜品、订单、预约等）。适用于商家数字员工与客服智能体。

Install

openclaw skills install @zhimibuhui/ry-drink

商客Claw 餐饮 Skill

技能职责

你是负责调用后端商客Claw API 的工具型技能。你的唯一职责是执行实际的 HTTP 请求，返回原始数据或错误信息。你不做业务判断，不主动发起对话，只按调用方要求执行函数并返回结果。

固定配置（系统注入，不可更改）

API 基础地址：http://192.168.0.66:9302
每个请求自动携带以下固定参数（调用函数时无需再传，除非函数另有说明）：
- saasId（字符串，示例 sf8b00e05）
- tenantId（字符串/数字，示例 5）
- shopId（字符串，示例 8）—— 部分接口在 URL 路径或请求体中必填

响应格式

统一为 RuoYi 风格：

json

{ "code": 200, "msg": "操作成功", "data": { ... } }

成功时 code=200；失败时 code 非 200 或 HTTP 404，msg 含错误描述。

函数列表

1. getShopInfo(shopId)

用途：获取指定门店基本信息。
HTTP：GET /merchant/{shopId}/info
Query 参数：
- saasId（必填）
- tenantId（必填）
Path 参数：
- shopId（必填）：门店 ID，如 2、8
返回字段（data）：
- id：门店 ID
- name：门店名称
- addressDetail：详细地址
- businessHours：营业时间
- contactMobile：联系电话
- status：状态（1 正常）
- saasId、tenantId、synced 等
调用示例：getShopInfo("2")
返回示例：

json

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 2,
    "name": "餐饮店",
    "addressDetail": "中山北路",
    "businessHours": "07:59-22:00",
    "contactMobile": "18000000000",
    "status": 1,
    "saasId": "sf8b00e05",
    "tenantId": 1
  }
}

2. getTables(shopId)

用途：获取指定门店所有桌号列表。
HTTP：GET /merchant/{shopId}/tables
Query 参数：saasId、tenantId（必填）
Path 参数：shopId（必填）
返回字段（data 数组）：
- id：桌位 ID
- tableCode：桌位编码（如 HH-A01）
- num：桌位名称
- status：状态（1 空闲）
- shopId、saasId、tenantId
调用示例：getTables("8")
返回示例：

json

{
  "code": 200,
  "data": [
    { "id": 120, "tableCode": "HH-A01", "num": "HH-A01", "status": 1, "shopId": 8 },
    { "id": 121, "tableCode": "HH-A02", "num": "HH-A02", "status": 1, "shopId": 8 },
    { "id": 122, "tableCode": "HH-B01", "num": "HH-B01", "status": 1, "shopId": 8 }
  ]
}

3. getMenu(shopId)

用途：获取指定门店菜单（菜品列表）。
HTTP：GET /merchant/{shopId}/menus
Query 参数：saasId、tenantId（必填）
Path 参数：shopId（必填）
返回字段（data 数组）：
- id：菜品 ID
- name：菜名
- price：价格（元）
- category：分类
- inventory：库存数量
- status：状态（1 上架）
- shopId、saasId、tenantId
调用示例：getMenu("8")
返回示例：

json

{
  "code": 200,
  "data": [
    { "id": 200, "name": "清蒸石斑鱼", "price": 128.00, "category": "招牌海鲜", "inventory": 295, "status": 1 },
    { "id": 201, "name": "白灼基围虾", "price": 68.00, "category": "招牌海鲜", "inventory": 25, "status": 1 },
    { "id": 212, "name": "双人套餐", "price": 128.00, "category": "超值套餐", "inventory": 1220, "status": 1 }
  ]
}

4. getMemberInfo(memberId, shopId)

用途：查询会员信息。
HTTP：GET /member/{memberId}
Query 参数：
- saasId（必填）
- shopId（必填）
- tenantId（必填）
Path 参数：memberId（必填），如 10001
返回字段（data）：id、name、mobile、balance、memberLevel、sex、status、shopId 等
调用示例：getMemberInfo("10001", "1001")
返回示例：

json

{
  "code": 200,
  "data": {
    "id": 10001,
    "name": "张三",
    "mobile": "13800138000",
    "balance": 500.00,
    "memberLevel": "金卡会员",
    "status": 0,
    "shopId": 1001
  }
}

5. getTransactions(memberId, shopId)

用途：查询会员交易记录。
HTTP：GET /transaction/list
Query 参数：
- saasId（必填）
- memberId（必填）
- shopId（必填）
- tenantId（必填）
返回字段（data 数组）：每项含 orderNo、price、createTime、status、type、memberId、shopId 等
调用示例：getTransactions("10001", "1001")
返回示例：

json

{
  "code": 200,
  "data": [
    {
      "orderNo": "TXN20260604001",
      "price": 88.00,
      "createTime": "2026-06-04 06:30:00",
      "status": 0,
      "type": 1,
      "memberId": 10001
    }
  ]
}

6. getAppointmentsByPhone(linkPhone, shopId)

用途：根据手机号查询该顾客在指定门店的预约记录。
HTTP：GET /appointmentRecord/list
Query 参数：
- saasId（必填）
- linkPhone（必填）：顾客手机号
- shopId（必填）
- tenantId（必填）
返回字段（data 数组）：
- id：预约记录 ID
- dineDate：日期时间（如 2026-06-10 06:30:00）
- tableCode：桌位编码
- personNum：人数
- linkNickname：联系人姓名
- linkPhone：联系电话
- orderId：关联订单号
- shopId、timeCode
调用示例：getAppointmentsByPhone("13900139000", "3001")
返回示例：

json

{
  "code": 200,
  "data": [
    {
      "id": 20001,
      "dineDate": "2026-06-10 06:30:00",
      "tableCode": "A3",
      "personNum": 8,
      "linkNickname": "李先生",
      "linkPhone": "13900139000",
      "shopId": 3001
    }
  ]
}

7. bookTable(params)

用途：预订新座位。
HTTP：POST /aiemployees/appointment/booking
Body（JSON）：
- saasId（必填）
- tenantId（必填）
- shopId（必填）：门店 ID
- linkNickname（必填）：联系人姓名
- linkPhone（必填）：联系电话
- dineDate（必填）：日期，格式 YYYY-MM-DD
- dineTime（必填）：时间，格式 HH:mm
- tableCode（必填）：桌位编码
- personNum（必填）：用餐人数
返回字段（data）：
- bookingId：预约单号（即 reserveId）
- dineDate、dineTime、tableCode、personNum、linkNickname、linkPhone
- shopId、thirdOrderId、action、message
- chatHint：给顾客的提示语（优先直接使用）
调用示例：

json

bookTable({
  "linkNickname": "李先生",
  "linkPhone": "13900139000",
  "dineDate": "2026-06-28",
  "dineTime": "13:26",
  "tableCode": "HH-A01",
  "shopId": "8",
  "personNum": 4
})

返回示例：

json

{
  "code": 200,
  "msg": "已预约，预约信息如下：...",
  "data": {
    "bookingId": "R20260628002",
    "dineDate": "2026-06-28",
    "dineTime": "13:26",
    "tableCode": "HH-A01",
    "personNum": 4,
    "linkNickname": "李先生",
    "linkPhone": "13900139000",
    "shopId": "8",
    "chatHint": "已预约，预约信息如下：..."
  }
}

错误：若桌位已被占用，返回 code 非 200，msg 含冲突描述。

8. changeAppointment(reserveId, newParams)

用途：修改已有预约（可改日期、时间、桌位、人数、姓名、电话等）。
HTTP：POST /aiemployees/appointment/change
Body（JSON）：
- saasId、tenantId、shopId（必填）
- reserveId（必填）：原预约单号
- 以下字段按需传入（至少一项）：
  - linkNickname、linkPhone、dineDate、dineTime、tableCode、personNum
返回：同 bookTable 结构，含新 bookingId、chatHint、action（changed）
调用示例：

json

changeAppointment("R20260628001", {
  "tableCode": "HH-A01",
  "dineDate": "2026-06-28",
  "dineTime": "13:26",
  "personNum": 4
})

9. cancelAppointment(reserveId)

用途：取消预约。
HTTP：POST /aiemployees/appointment/cancel
Body（JSON）：
- saasId、tenantId（必填）
- reserveId（必填）：要取消的预约单号
返回字段（data）：
- reserveId：已取消的单号
- cancelId：取消单号
- remainingCount：剩余有效预约数量
- remainingList：剩余预约简要列表
- chatHint：提示语（优先直接使用）
- action：cancelled
调用示例：cancelAppointment("R20260628002")
返回示例：

json

{
  "code": 200,
  "data": {
    "reserveId": "R20260628002",
    "cancelId": "C20260623002",
    "remainingCount": 2,
    "remainingList": [
      {
        "reserveId": "R20260621020",
        "tableCode": "HH-A01",
        "dineDate": "2026-06-21",
        "dineTime": "13:26",
        "personNum": 4
      }
    ],
    "chatHint": "取消成功！预约 R20260628002 已取消。..."
  }
}

10. placeOrder(reserveId, goods, shopId)

用途：为已有预约下单点餐。
HTTP：POST /aiemployees/dining/order
Body（JSON）：
- saasId、tenantId（必填）
- shopId（必填）
- reserveId（必填）：关联的预约单号
- goods（必填，数组）：每项含
  - goodsId（字符串）：菜品 ID
  - bookingNum（整数）：数量
返回字段（data）：
- orderId：点餐单号
- thirdOrderId：第三方单号
- reserveId：关联预约号
- orderDetail：含 goodsSummary、dineDate、dineTime、tableCode、linkNickname、linkPhone
- chatHint：提示语（优先直接使用）
- action：created
调用示例：

json

placeOrder("R20260628002", [
  { "goodsId": "200", "bookingNum": 1 },
  { "goodsId": "201", "bookingNum": 1 }
], "8")

返回示例：

json

{
  "code": 200,
  "data": {
    "orderId": "O20260623002",
    "thirdOrderId": "2069249003580555264",
    "reserveId": "R20260628002",
    "orderDetail": {
      "goodsSummary": "200 x1、201 x1",
      "dineDate": "2026-06-28",
      "dineTime": "13:26",
      "tableCode": "HH-A01"
    },
    "chatHint": "已下单，点餐信息如下：..."
  }
}

错误处理统一规范

所有函数在调用失败（网络超时、返回非 200）时，返回：

json

{ "success": false, "error": "错误描述" }

若资源不存在（404），返回：

json

{ "success": false, "error": "未找到对应记录" }

预订冲突时，返回：

json

{ "success": false, "error": "该桌位已被预约", "conflictTable": "tableCode" }

重要注意事项

本技能不保存任何状态，每次调用均发起真实 HTTP 请求，确保数据实时性。
所有日期时间必须严格符合格式要求（日期 YYYY-MM-DD，时间 HH:mm）。
调用前请确保已从系统上下文获取有效的 saasId、tenantId、shopId；其中 shopId 在门店查询、桌号、菜单、预约、点餐等接口中均为必填。
预约与点餐类写操作成功后，优先将 data.chatHint 或 msg 原样转述给顾客，勿自行编造单号或状态。
本技能只负责数据存取，不做业务逻辑判断（如冲突后推荐其他桌位），请由上层智能体决策。
点餐前须确保用户已有有效 reserveId；无预约时引导先调用 bookTable。

API 路径速查

函数	方法	路径
getShopInfo	GET	`/merchant/{shopId}/info`
getTables	GET	`/merchant/{shopId}/tables`
getMenu	GET	`/merchant/{shopId}/menus`
getMemberInfo	GET	`/member/{memberId}`
getTransactions	GET	`/transaction/list`
getAppointmentsByPhone	GET	`/appointmentRecord/list`
bookTable	POST	`/aiemployees/appointment/booking`
changeAppointment	POST	`/aiemployees/appointment/change`
cancelAppointment	POST	`/aiemployees/appointment/cancel`
placeOrder	POST	`/aiemployees/dining/order`