sophhub 0.4.71 → 0.4.72

package/skills/hotel-booking/src/scripts/hotel_booking.py

@@ -0,0 +1,963 @@
+#!/usr/bin/env python3
+"""
+国内酒店查询与预订脚本：关键词检索、起价列表、房型详情、预订校验、创建订单、支付、
+订单状态查询、取消订单、部分退订。
+
+入住人信息从环境变量读取（与 flight-booking 同名，用户需提前配置）。
+对外契约见 llmops-backend 仓库的 doc/hotel-api.md，本脚本按该契约调用。
+"""
+
+import argparse
+import json
+import os
+import sys
+import time
+from datetime import datetime
+
+import requests
+
+# API 配置（网关，Bearer API_KEY 鉴权）。
+# 默认线上网关；联调时用 SOPH_GATEWAY_BASE_URL 覆盖（例如指向测试环境的网关地址）。
+GATEWAY_BASE_URL = os.environ.get(
+    "SOPH_GATEWAY_BASE_URL", "https://www.sophnet.com/api"
+).rstrip("/")
+HOTEL_BASE = f"{GATEWAY_BASE_URL}/open-apis/hotel"
+
+
+def _resolve_api_key() -> str:
+    key = os.environ.get("SOPH_API_KEY", "").strip()
+    if key:
+        return key
+    openclaw_path = os.path.expanduser("~/.openclaw/openclaw.json")
+    try:
+        with open(openclaw_path, "r", encoding="utf-8") as f:
+            cfg = json.load(f)
+        key = cfg.get("models", {}).get("providers", {}).get("sophnet", {}).get("apiKey", "")
+        if key:
+            return key
+    except (OSError, json.JSONDecodeError):
+        pass
+    raise RuntimeError("未找到 SOPH_API_KEY：请设置环境变量 SOPH_API_KEY ")
+
+
+API_KEY = _resolve_api_key()
+
+# 入住人信息（与 flight-booking 复用同一组环境变量，用户配置一次即可）
+ENV_GUEST_NAME = "PASSENGER_NAME"
+ENV_GUEST_MOBILE = "PASSENGER_MOBILE"
+ENV_GUEST_CREDENTIAL_NO = "PASSENGER_CREDENTIAL_NO"
+
+# 本期只做国内酒店，统一走"在途"ID 体系
+ORIGIN_TYPE_INHOUSE = 80
+
+DATA_DIR = os.path.join(os.path.expanduser("~"), ".openclaw", "hotel-booking")
+os.makedirs(DATA_DIR, exist_ok=True)
+LAST_SEARCH_FILE = os.path.join(DATA_DIR, ".last_search.json")
+LAST_DETAIL_FILE = os.path.join(DATA_DIR, ".last_detail.json")
+ORDERS_CACHE_FILE = os.path.join(DATA_DIR, ".orders_cache.json")
+PASSENGERS_FILE = os.path.join(DATA_DIR, ".passengers.json")
+
+# 供应商 orderShowStatus → 中文（网关原值透传，这里只做展示翻译）
+SHOW_STATUS_ZH = {
+    "WAIT_PAYMENT": "待支付",
+    "ISSUING": "确认中",
+    "ISSUED": "已确认",
+    "CANCELED": "已取消",
+    "REFUNDING": "退订中",
+    "REFUNDED": "已退订",
+    "PART_REFUND_CHANGE": "部分退订",
+}
+
+# 网关错误码 → 给用户的话术。40101 不保证幂等，写操作绝不允许自动重试。
+ERROR_HINT = {
+    40101: "上游酒店服务异常（未拿到响应）。写操作请勿自动重试，先查订单状态再人工决定。",
+    40105: "请求参数不合法，按提示补齐字段后重试。",
+    40108: "酒店支付/退订能力暂未开放。",
+    40109: "价格已变化，需按最新报价重新确认后才能下单。",
+    40110: "该房型暂无可售库存，换房型或换日期。",
+}
+
+
+# ---------- 基础 API 工具 ----------
+
+def _headers() -> dict:
+    return {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {API_KEY}",
+    }
+
+
+def _extract_ota(body: dict) -> dict:
+    """从网关响应 {status, message, result} 中提取 OTA 层 {code, msg, data}"""
+    result = body.get("result")
+    if result is None:
+        return {"code": str(body.get("status", "-1")), "msg": body.get("message", "unknown")}
+    return result
+
+
+def _post(path: str, data: dict | None = None) -> dict:
+    resp = requests.post(f"{HOTEL_BASE}{path}", headers=_headers(), json=data or {}, timeout=60)
+    return _extract_ota(resp.json())
+
+
+def _get(path: str) -> dict:
+    resp = requests.get(f"{HOTEL_BASE}{path}", headers=_headers(), timeout=60)
+    return _extract_ota(resp.json())
+
+
+def _fail(status: int | str | None, message: str | None, extra: dict | None = None) -> int:
+    """统一的失败输出：给 Agent 的 JSON，含错误码话术。"""
+    payload = {
+        "ok": False,
+        "status": status,
+        "message": message,
+        "hint": ERROR_HINT.get(status),
+    }
+    if extra:
+        payload.update(extra)
+    print(json.dumps(payload, ensure_ascii=False))
+    return 1
+
+
+# ---------- 纯函数（可单测，不触网） ----------
+
+def _text(value) -> str | None:
+    """只接受非空字符串（数字会被转成字符串）；其它类型视为无值。"""
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        value = str(value)
+    if isinstance(value, str):
+        value = value.strip()
+        return value or None
+    return None
+
+
+def to_number(value) -> float | None:
+    """价格/库存字段可能是数字或字符串；解析不出来返回 None（不猜 0）。"""
+    text = _text(value)
+    if text is None:
+        return None
+    try:
+        return float(text)
+    except ValueError:
+        return None
+
+
+def nights_between(check_in: str, check_out: str) -> int | None:
+    """入住晚数；日期非法或离店不晚于入住时返回 None。"""
+    try:
+        d1 = datetime.strptime((check_in or "").strip(), "%Y-%m-%d")
+        d2 = datetime.strptime((check_out or "").strip(), "%Y-%m-%d")
+    except ValueError:
+        return None
+    nights = (d2 - d1).days
+    return nights if nights > 0 else None
+
+
+def plan_total(night_rates, rooms: int = 1, expected_nights: int | None = None) -> float | None:
+    """逐晚价合计 × 房间数，与网关的比价口径一致。
+
+    逐晚价缺失、解析不出来、或条数与入住晚数不符时返回 None —— 缺一晚就少算一晚的钱，
+    绝不能按剩下的凑。
+    """
+    if not isinstance(night_rates, list) or not night_rates:
+        return None
+    if expected_nights is not None and len(night_rates) != expected_nights:
+        return None
+    per_night = 0.0
+    for item in night_rates:
+        price = to_number((item or {}).get("price"))
+        if price is None:
+            return None
+        per_night += price
+    return round(per_night * max(int(rooms or 1), 1), 2)
+
+
+def flatten_plans(detail: dict, expected_nights: int | None = None) -> list[dict]:
+    """把详情响应的 rooms[] × ratePlans[] 摊平成"一行一个价格计划"。
+
+    必须房型 + 价格计划成对取：实测同一个 ratePlanId 会出现在不同房型下且价格不同，
+    只按 ratePlanId 索引会拿到别的房型的价。
+    """
+    rows: list[dict] = []
+    for room in (detail or {}).get("rooms") or []:
+        if not isinstance(room, dict):
+            continue
+        room_id = _text(room.get("originRoomId")) or _text(room.get("roomId"))
+        for plan in room.get("ratePlans") or []:
+            if not isinstance(plan, dict):
+                continue
+            night_rates = plan.get("nightRates") or []
+            cancel_rule = plan.get("cancelRule") or {}
+            rows.append({
+                "originRoomId": room_id,
+                "roomName": _text(room.get("name")),
+                "bedType": _text(plan.get("bedType")) or _text(plan.get("bedInfo")),
+                "ratePlanId": _text(plan.get("ratePlanId")),
+                "price": to_number(plan.get("price")),
+                "stock": to_number(plan.get("stock")),
+                "nightTotal": plan_total(night_rates, 1, expected_nights),
+                "productType": _text(plan.get("productType")) or "UNKNOWN",
+                "breakfast": _text((night_rates[0] or {}).get("breakFastDes")) if night_rates else None,
+                "cancelRule": _text(cancel_rule.get("showDescription")),
+                "shoppingCode": _text(plan.get("shoppingCode")),
+                "nightRates": night_rates,
+            })
+    return rows
+
+
+def build_create_payload(
+    *,
+    city_id: str | None,
+    origin_hotel_id: str,
+    origin_room_id: str,
+    rate_plan_id: str,
+    shopping_code: str,
+    check_in: str,
+    check_out: str,
+    rooms: int,
+    total_amount: float,
+    earliest_arrival_time: str,
+    latest_arrival_time: str,
+    guests: list[dict],
+    contacter_name: str,
+    contacter_mobile: str,
+) -> dict:
+    """组装创单报文。无值的字段直接不下发（网关会点名字段报 40105）。"""
+    payload = {
+        "cityId": city_id,
+        "shoppingCode": shopping_code,
+        "originHotelId": origin_hotel_id,
+        "originRoomId": origin_room_id,
+        "ratePlanId": rate_plan_id,
+        "originType": ORIGIN_TYPE_INHOUSE,
+        "checkInDate": check_in,
+        "checkOutDate": check_out,
+        "numberOfRooms": rooms,
+        "totalAmount": total_amount,
+        "earliestArrivalTime": earliest_arrival_time,
+        "latestArrivalTime": latest_arrival_time,
+        "customers": guests,
+        "contacterName": contacter_name,
+        "contacterMobile": contacter_mobile,
+    }
+    return {k: v for k, v in payload.items() if v not in (None, "")}
+
+
+def build_partial_refund(room_no: int, check_in: str, check_out: str, reason: str | None) -> dict:
+    """组装部分退订报文。退订日期必须连续，且只允许同房间号同日期段。"""
+    payload = {"partialRefunds": [{
+        "roomNos": [room_no],
+        "checkInDate": check_in,
+        "checkOutDate": check_out,
+    }]}
+    if reason:
+        payload["reason"] = reason
+    return payload
+
+
+def show_status_zh(value: str | None) -> str:
+    text = _text(value)
+    if not text:
+        return "-"
+    return SHOW_STATUS_ZH.get(text.upper(), text)
+
+
+# ---------- 展示辅助 ----------
+
+def _display_width(text: str) -> int:
+    """中文按 2 列宽计算，保证表格在终端里对齐。"""
+    import unicodedata
+    return sum(2 if unicodedata.east_asian_width(ch) in ("W", "F") else 1 for ch in str(text))
+
+
+def _pad(text, width: int, align: str = "left") -> str:
+    text = "" if text is None else str(text)
+    gap = max(width - _display_width(text), 0)
+    if align == "right":
+        return " " * gap + text
+    return text + " " * gap
+
+
+def _truncate(text, width: int) -> str:
+    text = "" if text is None else str(text)
+    if _display_width(text) <= width:
+        return text
+    out = ""
+    for ch in text:
+        if _display_width(out + ch) > width - 1:
+            break
+        out += ch
+    return out + "…"
+
+
+def _print_table(headers: list[str], rows: list[list], aligns: list[str] | None = None) -> None:
+    aligns = aligns or ["left"] * len(headers)
+    cells = [[_truncate(c, 40) for c in row] for row in rows]
+    widths = []
+    for i, header in enumerate(headers):
+        widths.append(max([_display_width(header)] + [_display_width(r[i]) for r in cells]))
+    print("  ".join(_pad(h, widths[i]) for i, h in enumerate(headers)))
+    print("  ".join("-" * w for w in widths))
+    for row in cells:
+        print("  ".join(_pad(c, widths[i], aligns[i]) for i, c in enumerate(row)))
+
+
+# ---------- 本地缓存 ----------
+
+def _read_json(path: str, default):
+    if os.path.isfile(path):
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except (OSError, json.JSONDecodeError):
+            pass
+    return default
+
+
+def _write_json(path: str, data) -> None:
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+    except OSError:
+        pass  # 缓存写失败只影响后续步骤的免参便利，不影响本次结果
+
+
+def _cached_city_id(explicit, detail_cache: dict, search_cache: dict):
+    """cityId 取值：显式入参 > 最近一次缓存（检索缓存 / 详情缓存，谁新用谁）。
+
+    下单全程必须透传 cityId，而首次 hotel-detail 时详情缓存还是空的，
+    只能从关键词检索缓存里取；如果这次检索比上次详情更新，说明用户换了城市，
+    也必须用新的（旧 cityId 会让列表/详情查不到酒店）。
+    """
+    if explicit:
+        return explicit
+    candidates = [c for c in (detail_cache, search_cache) if (c or {}).get("cityId")]
+    if not candidates:
+        return None
+    newest = max(candidates, key=lambda c: str(c.get("createdAt") or ""))
+    return newest.get("cityId")
+
+
+def _select_plan(room_id: str | None, rate_plan_id: str | None):
+    """从最近一次 hotel-detail 的缓存里选价格计划，返回 (plan, error)。"""
+    cache = _read_json(LAST_DETAIL_FILE, {}) or {}
+    plans = cache.get("plans") or []
+    if not plans:
+        return None, "没有可用的房型报价缓存，请先执行 hotel-detail"
+    matched = [
+        p for p in plans
+        if (not room_id or p.get("originRoomId") == room_id)
+        and (not rate_plan_id or p.get("ratePlanId") == rate_plan_id)
+    ]
+    if not matched:
+        return None, f"缓存里没有房型 {room_id} + 价格计划 {rate_plan_id}，请重新执行 hotel-detail"
+    return matched[0], None
+
+
+# ---------- 一、关键词 / 地标检索 ----------
+
+def cmd_search_city(args: argparse.Namespace) -> int:
+    payload = {"keyword": args.keyword}
+    if args.city_id:
+        payload["cityId"] = args.city_id
+    if args.city_name:
+        payload["cityName"] = args.city_name
+    if args.page_no:
+        payload["pageNo"] = args.page_no
+    if args.page_size:
+        payload["pageSize"] = args.page_size
+
+    res = _post("/search/keyword", payload)
+    if res.get("code") != "0":
+        return _fail(res.get("code"), res.get("msg"))
+
+    data = res.get("data") or {}
+    hits = (data.get("currentCityList") or []) + (data.get("otherCityList") or [])
+    if not hits:
+        _write_json(LAST_SEARCH_FILE, {"keyword": args.keyword, "hotels": [], "cityId": None})
+        print(f"关键词「{args.keyword}」没有匹配到城市或酒店，换个说法再试。")
+        return 0
+
+    rows = []
+    hotels = []
+    cities: dict[str, str] = {}
+    for i, hit in enumerate(hits, 1):
+        city_id = _text(hit.get("cityId"))
+        city_name = _text(hit.get("cityName")) or ""
+        hotel_id = _text(hit.get("id"))
+        rows.append([i, city_name, city_id, hit.get("name"), hit.get("address")])
+        if city_id:
+            cities.setdefault(city_id, city_name)
+        if hotel_id:
+            hotels.append({
+                "originHotelId": hotel_id,
+                "name": _text(hit.get("name")),
+                "cityId": city_id,
+                "cityName": city_name,
+                "address": _text(hit.get("address")),
+            })
+
+    _print_table(["#", "城市", "cityId", "酒店 / 地点", "地址"], rows)
+    print()
+    if len(cities) == 1:
+        city_id, city_name = next(iter(cities.items()))
+        print(f"候选城市：{city_name}  cityId={city_id}（下单全程必须透传这个 cityId）")
+        picked_city = city_id
+    else:
+        print("候选城市（多个，请让用户确认后把 cityId 传进来）：")
+        for city_id, city_name in cities.items():
+            print(f"  {city_name}  cityId={city_id}")
+        picked_city = None
+
+    _write_json(LAST_SEARCH_FILE, {
+        "keyword": args.keyword,
+        "cityId": picked_city,
+        "cityName": cities.get(picked_city) if picked_city else None,
+        "hotels": hotels,
+        "createdAt": time.strftime("%Y-%m-%d %H:%M:%S"),
+    })
+    print()
+    print(f"共 {len(hits)} 条命中，已保存 {len(hotels)} 个带酒店 ID 的候选。"
+          "下一步：search-hotel --check-in <日期> --check-out <日期>")
+    return 0
+
+
+# ---------- 二、起价列表 ----------
+
+def cmd_search_hotel(args: argparse.Namespace) -> int:
+    cache = _read_json(LAST_SEARCH_FILE, {}) or {}
+    hotel_ids = [s.strip() for s in (args.hotel_ids or "").split(",") if s.strip()]
+    if not hotel_ids:
+        hotel_ids = [h.get("originHotelId") for h in (cache.get("hotels") or []) if h.get("originHotelId")]
+
+    payload = {"checkInDate": args.check_in, "checkOutDate": args.check_out,
+               "originType": ORIGIN_TYPE_INHOUSE}
+    if hotel_ids:
+        payload["originHotelIds"] = hotel_ids[:100]
+        mode = f"ID 列表模式（{len(payload['originHotelIds'])} 个酒店）"
+    else:
+        city_id = args.city_id or cache.get("cityId")
+        if not city_id:
+            return _fail(None, "缺少酒店 ID 与 cityId：请先执行 search-city，或用 --hotel-ids 指定酒店 ID")
+        payload["cityId"] = city_id
+        mode = f"条件搜索模式（cityId={city_id}）"
+        print("提示：条件搜索在测试环境实测返回空数组，拿不到起价属正常，改为 ID 列表模式更稳。")
+    if args.page_index:
+        payload["pageIndex"] = args.page_index
+    if args.page_size:
+        payload["pageSize"] = args.page_size
+
+    print(f"查询方式：{mode}　入住 {args.check_in} → 离店 {args.check_out}")
+    res = _post("/search/list", payload)
+    if res.get("code") != "0":
+        return _fail(res.get("code"), res.get("msg"))
+
+    items = res.get("data") or []
+    if not isinstance(items, list) or not items:
+        print("没有返回任何酒店（起价为空）。")
+        print("用途说明：该接口返回的是**起价**，用于筛酒店；房型与逐晚价请用 hotel-detail。")
+        return 0
+
+    rows = []
+    for i, item in enumerate(items, 1):
+        rows.append([i, item.get("name"), _text(item.get("originHotelId")),
+                     item.get("lowestPrice"), item.get("address")])
+    _print_table(["#", "酒店", "originHotelId", "起价", "地址"], rows, aligns=["left", "left", "left", "right", "left"])
+    print()
+    print(f"共 {len(items)} 家酒店（起价非最终价）。下一步：hotel-detail --origin-hotel-id <ID> "
+          f"--check-in {args.check_in} --check-out {args.check_out}")
+    return 0
+
+
+# ---------- 三、房型与价格计划详情 ----------
+
+def cmd_hotel_detail(args: argparse.Namespace) -> int:
+    last = _read_json(LAST_DETAIL_FILE, {}) or {}
+    search = _read_json(LAST_SEARCH_FILE, {}) or {}
+    check_in = args.check_in or last.get("checkInDate")
+    check_out = args.check_out or last.get("checkOutDate")
+    if not check_in or not check_out:
+        return _fail(None, "需要 --check-in 与 --check-out（yyyy-MM-dd）")
+    nights = nights_between(check_in, check_out)
+    if not nights:
+        return _fail(None, f"入住/离店日期不合法：{check_in} → {check_out}（离店必须晚于入住）")
+
+    payload = {"originHotelId": args.origin_hotel_id, "originType": ORIGIN_TYPE_INHOUSE,
+               "checkInDate": check_in, "checkOutDate": check_out}
+    city_id = _cached_city_id(args.city_id, last, search)
+    if city_id:
+        payload["cityId"] = city_id
+
+    res = _post("/search/detail", payload)
+    if res.get("code") != "0":
+        return _fail(res.get("code"), res.get("msg"))
+
+    data = res.get("data") or {}
+    plans = flatten_plans(data, expected_nights=nights)
+    if not plans:
+        return _fail(None, "详情里没有可售房型/价格计划")
+
+    rows = []
+    for i, plan in enumerate(plans, 1):
+        rows.append([
+            i, plan["roomName"], plan["bedType"], plan["originRoomId"], plan["ratePlanId"],
+            plan["price"], plan["nightTotal"], plan["stock"],
+            plan["breakfast"] or "-", plan["cancelRule"] or "-", plan["productType"],
+        ])
+    print(f"{data.get('name') or ''}　{check_in} → {check_out}（{nights} 晚）　起价 {data.get('lowestPrice')}")
+    print()
+    _print_table(
+        ["#", "房型", "床型", "originRoomId", "ratePlanId", "每晚", f"{nights}晚合计", "库存", "早餐", "取消规则", "价格类型"],
+        rows,
+        aligns=["left", "left", "left", "left", "left", "right", "right", "right", "left", "left", "left"],
+    )
+
+    _write_json(LAST_DETAIL_FILE, {
+        "originHotelId": _text(data.get("originHotelId")) or args.origin_hotel_id,
+        "hotelName": data.get("name"),
+        "cityId": city_id,
+        "checkInDate": check_in,
+        "checkOutDate": check_out,
+        "nights": nights,
+        "plans": plans,
+        "createdAt": time.strftime("%Y-%m-%d %H:%M:%S"),
+    })
+    print()
+    print("已保存本次报价。下单前请把**最新总价**展示给用户确认，然后执行：")
+    print("  create-order --room-id <originRoomId> --rate-plan-id <ratePlanId> [--rooms N]")
+    return 0
+
+
+# ---------- 四、预订校验 ----------
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    plan, err = _select_plan(args.room_id, args.rate_plan_id)
+    if err:
+        return _fail(None, err)
+    cache = _read_json(LAST_DETAIL_FILE, {}) or {}
+    payload = {
+        "shoppingCode": plan.get("shoppingCode"),
+        "customerNum": args.customer_num,
+        "checkInDate": cache.get("checkInDate"),
+        "checkOutDate": cache.get("checkOutDate"),
+        "numberOfRooms": args.rooms,
+        "totalAmount": plan.get("nightTotal"),
+        "originHotelId": cache.get("originHotelId"),
+        "originRoomId": plan.get("originRoomId"),
+        "ratePlanId": plan.get("ratePlanId"),
+        "originType": ORIGIN_TYPE_INHOUSE,
+        "earliestArrivalTime": f"{cache.get('checkInDate')} 14:00:00",
+        "latestArrivalTime": f"{cache.get('checkInDate')} 23:59:00",
+    }
+    res = _post("/search/validate", payload)
+    if res.get("code") != "0":
+        return _fail(res.get("code"), res.get("msg"))
+    print(json.dumps({"ok": True, "message": "报价码仍有效（价格与库存以 hotel-detail 为准）",
+                      "data": res.get("data")}, ensure_ascii=False))
+    return 0
+
+
+# ---------- 五、创建订单 ----------
+
+def _guests_from_env(rooms: int, credential_type: str):
+    name = os.environ.get(ENV_GUEST_NAME, "").strip()
+    mobile = os.environ.get(ENV_GUEST_MOBILE, "").strip()
+    credential_no = os.environ.get(ENV_GUEST_CREDENTIAL_NO, "").strip()
+    missing = []
+    if not name:
+        missing.append(ENV_GUEST_NAME)
+    if not mobile:
+        missing.append(ENV_GUEST_MOBILE)
+    if not credential_no:
+        missing.append(ENV_GUEST_CREDENTIAL_NO)
+    if missing:
+        return None, missing, name, mobile
+    guests = [{
+        "name": name,
+        "mobile": mobile,
+        "credentialType": credential_type,
+        "credentialNo": credential_no,
+        "roomNo": room_no,
+    } for room_no in range(1, rooms + 1)]
+    return guests, [], name, mobile
+
+
+def _expire_time_text(expire_time) -> str:
+    """上游 expireTime 是毫秒时间戳，转成本地可读时间。"""
+    try:
+        return datetime.fromtimestamp(int(expire_time) / 1000).strftime("%Y-%m-%d %H:%M:%S")
+    except (TypeError, ValueError, OSError, OverflowError):
+        return str(expire_time)
+
+
+def cmd_create_order(args: argparse.Namespace) -> int:
+    plan, err = _select_plan(args.room_id, args.rate_plan_id)
+    if err:
+        return _fail(None, err)
+    cache = _read_json(LAST_DETAIL_FILE, {}) or {}
+    check_in = cache.get("checkInDate")
+    check_out = cache.get("checkOutDate")
+    nights = cache.get("nights") or nights_between(check_in, check_out)
+    if not (check_in and check_out and nights):
+        return _fail(None, "缺少入住/离店日期缓存，请重新执行 hotel-detail")
+
+    rooms = max(int(args.rooms or 1), 1)
+    total = plan_total(plan.get("nightRates"), rooms, nights)
+    if total is None:
+        return _fail(None, "缓存的逐晚价不完整或晚数对不上，请重新执行 hotel-detail 后再下单")
+
+    guests, missing, guest_name, guest_mobile = _guests_from_env(rooms, args.credential_type)
+    if missing:
+        return _fail(None, "创建订单前请设置以下环境变量", {"missing": missing})
+
+    payload = build_create_payload(
+        city_id=cache.get("cityId"),
+        origin_hotel_id=cache.get("originHotelId"),
+        origin_room_id=plan.get("originRoomId"),
+        rate_plan_id=plan.get("ratePlanId"),
+        shopping_code=plan.get("shoppingCode"),
+        check_in=check_in,
+        check_out=check_out,
+        rooms=rooms,
+        total_amount=total,
+        earliest_arrival_time=args.earliest_arrival_time or f"{check_in} 14:00:00",
+        latest_arrival_time=args.latest_arrival_time or f"{check_in} 23:59:00",
+        guests=guests,
+        contacter_name=args.contacter_name or guest_name,
+        contacter_mobile=args.contacter_mobile or guest_mobile,
+    )
+
+    print("即将提交的订单：")
+    print(f"  酒店：{cache.get('hotelName')}（originHotelId={cache.get('originHotelId')}）")
+    print(f"  房型：{plan.get('roomName')} / {plan.get('bedType')}（originRoomId={plan.get('originRoomId')}）")
+    print(f"  入住：{check_in} → {check_out}（{nights} 晚 × {rooms} 间）")
+    print(f"  价格计划：{plan.get('ratePlanId')}　取消规则：{plan.get('cancelRule') or '-'}")
+    print(f"  应付金额：¥{total}")
+    print(f"  入住人：{guest_name}　联系人：{payload.get('contacterName')}")
+    print()
+
+    res = _post("/order/create", payload)
+    if res.get("code") != "0":
+        return _fail(res.get("code"), res.get("msg"))
+
+    data = res.get("data") or {}
+    order_no = _text(data.get("orderNo"))
+    if not order_no:
+        return _fail(None, f"创单响应里没有订单号：{json.dumps(data, ensure_ascii=False)}")
+
+    print(f"创单成功　订单号：{order_no}")
+    print(f"  应付金额：¥{total}")
+    print(f"  超时自动取消时间：{_expire_time_text(data.get('expireTime'))}")
+
+    cache_orders = _read_json(ORDERS_CACHE_FILE, {}) or {}
+    cache_orders[order_no] = {
+        "orderNo": order_no,
+        "showStatus": "WAIT_PAYMENT",
+        "totalAmount": total,
+        "hotelName": cache.get("hotelName"),
+        "roomName": plan.get("roomName"),
+        "checkInDate": check_in,
+        "checkOutDate": check_out,
+        "rooms": rooms,
+        "expireTime": _expire_time_text(data.get("expireTime")),
+        "updatedAt": time.strftime("%Y-%m-%d %H:%M:%S"),
+    }
+    _write_json(ORDERS_CACHE_FILE, cache_orders)
+
+    print()
+    print("重要：请先把订单号、入住信息与金额展示给用户确认，用户明确表示要支付后再执行：")
+    print(f"  pay-order --order-no {order_no}")
+    return 0
+
+
+# ---------- 六、支付 ----------
+
+def cmd_pay_order(args: argparse.Namespace) -> int:
+    detail = _get(f"/order/{args.order_no}")
+    if detail.get("code") != "0":
+        return _fail(detail.get("code"), detail.get("msg"))
+    data = detail.get("data") or {}
+    amount = args.pay_amount if args.pay_amount is not None else to_number(data.get("totalAmount"))
+    if amount is None:
+        return _fail(None, "拿不到应付金额，请用 --pay-amount 指定")
+
+    payload = {
+        "orderNo": args.order_no,
+        "paymentMethod": "BP_ACCOUNT",
+        "payAmount": amount,
+        "paymentTotalPrice": amount,
+        "paymentTradeId": f"HB-{int(time.time() * 1000)}",
+    }
+    print(f"订单 {args.order_no}　应付 ¥{amount}　支付方式：企业账户（BP_ACCOUNT）")
+    res = _post("/order/pay", payload)
+    if res.get("code") != "0":
+        return _fail(res.get("code"), res.get("msg"))
+
+    print(f"支付已受理　{json.dumps(res.get('data'), ensure_ascii=False)}")
+    print("注意：code=0 只代表**受理**，不代表已确认。请用 order-status 轮询确认终态：")
+    print(f"  order-status --order-no {args.order_no}")
+    return 0
+
+
+# ---------- 七、订单状态 ----------
+
+def _print_order_summary(order_no: str, data: dict) -> None:
+    print(f"订单号：{order_no}")
+    print(f"  订单状态：{show_status_zh(data.get('showStatus'))}（{data.get('showStatus') or '-'}）")
+    print(f"  本地状态：{data.get('status') or '-'}")
+    print(f"  酒店 / 房型：{data.get('hotelName') or '-'} / {data.get('roomName') or '-'}")
+    print(f"  入住：{data.get('checkInDate') or '-'} → {data.get('checkOutDate') or '-'}"
+          f"（{data.get('nightCount') or '-'} 晚 × {data.get('roomCount') or '-'} 间）")
+    print(f"  订单总额：¥{data.get('totalAmount')}　违约金：¥{data.get('penaltyAmount')}")
+    print(f"  确认号：{data.get('confirmNo') or '-'}")
+    if data.get("cancelReason"):
+        print(f"  取消原因：{data.get('cancelReason')}")
+    if data.get("failReason"):
+        print(f"  失败原因：{data.get('failReason')}")
+    print(f"  超时自动取消时间：{_expire_time_text(data.get('expireTime')) if data.get('expireTime') else '-'}")
+
+
+def cmd_order_status(args: argparse.Namespace) -> int:
+    res = _get(f"/order/{args.order_no}")
+    if res.get("code") != "0":
+        return _fail(res.get("code"), res.get("msg"))
+    data = res.get("data") or {}
+    if not data:
+        print(json.dumps({"ok": False, "message": f"本地没有订单 {args.order_no}"}, ensure_ascii=False))
+        return 1
+    _print_order_summary(args.order_no, data)
+
+    cache_orders = _read_json(ORDERS_CACHE_FILE, {}) or {}
+    record = cache_orders.get(args.order_no) or {"orderNo": args.order_no}
+    record.update({
+        "showStatus": data.get("showStatus"),
+        "status": data.get("status"),
+        "totalAmount": data.get("totalAmount"),
+        "confirmNo": data.get("confirmNo"),
+        "updatedAt": time.strftime("%Y-%m-%d %H:%M:%S"),
+    })
+    cache_orders[args.order_no] = record
+    _write_json(ORDERS_CACHE_FILE, cache_orders)
+    return 0
+
+
+# ---------- 八、取消订单 ----------
+
+def cmd_cancel_order(args: argparse.Namespace) -> int:
+    res = _post(f"/order/{args.order_no}/cancel")
+    if res.get("code") != "0":
+        return _fail(res.get("code"), res.get("msg"))
+    print(f"已提交取消　{json.dumps(res.get('data'), ensure_ascii=False)}")
+    print("未支付订单取消后即释放冻结额度；已支付订单请用 order-status 确认最终状态。")
+    return 0
+
+
+# ---------- 九、部分退订 ----------
+
+def first_refund_order_no(data) -> str | None:
+    """从退订响应里取退单号。
+
+    整单退订 `data` 是对象、部分退订 `data` 是**数组**（dev8 实测），两种形态都要认；
+    取不到就返回 None（调用方据此提示用户，绝不能当成整单取消）。
+    注意字符串 `"null"`（供应商在"未确认订单等价取消"时会这么回）也要当成没有退单号。
+    """
+    def _normalize(value) -> str | None:
+        text = _text(value)
+        if text is None or text.lower() == "null":
+            return None
+        return text
+
+    if isinstance(data, dict):
+        return _normalize(data.get("refundOrderNo"))
+    if isinstance(data, list):
+        for item in data:
+            if isinstance(item, dict):
+                found = _normalize(item.get("refundOrderNo"))
+                if found:
+                    return found
+    return None
+
+
+def cmd_refund_part(args: argparse.Namespace) -> int:
+    nights = nights_between(args.check_in, args.check_out)
+    if not nights:
+        return _fail(None, f"退订日期不合法：{args.check_in} → {args.check_out}（需连续且离店晚于入住）")
+
+    detail = _get(f"/order/{args.order_no}")
+    if detail.get("code") != "0":
+        return _fail(detail.get("code"), detail.get("msg"))
+    order = detail.get("data") or {}
+    print(f"订单 {args.order_no}　当前状态：{show_status_zh(order.get('showStatus'))}")
+    print(f"  拟退：房间 {args.room_no}　{args.check_in} → {args.check_out}（{nights} 晚）")
+    print(f"  订单总额：¥{order.get('totalAmount')}　已扣款：¥{order.get('deductedAmount')}")
+
+    if args.dry_run:
+        print()
+        print("（dry-run：未提交退订。实际退款金额以供应商生成的退单为准，受理后由轮询回填。）")
+        print("确认没问题后去掉 --dry-run 再执行一次。")
+        return 0
+
+    payload = build_partial_refund(args.room_no, args.check_in, args.check_out, args.reason)
+    res = _post(f"/order/{args.order_no}/refund", payload)
+    if res.get("code") != "0":
+        return _fail(res.get("code"), res.get("msg"))
+
+    refund_no = first_refund_order_no(res.get("data"))
+    if not refund_no:
+        print(json.dumps({
+            "ok": False,
+            "message": "退订响应里没有退单号，请立刻人工核对（不要重复提交）",
+            "data": res.get("data"),
+        }, ensure_ascii=False))
+        return 1
+    print(f"退订已受理　退单号：{refund_no}（上游先 AUDITING，等放款后入账）")
+    print("入账时刻取决于供应商放款，请间隔一段时间用 order-status 复查；"
+          "同一订单要发起下一笔退订，必须等上一笔入账完成。")
+    return 0
+
+
+# ---------- 十、本地订单缓存 / 入住人管理 ----------
+
+def cmd_list_orders(args: argparse.Namespace) -> int:
+    cache = _read_json(ORDERS_CACHE_FILE, {}) or {}
+    if not cache:
+        print("本地还没有订单记录。")
+        return 0
+    rows = []
+    for order_no, item in cache.items():
+        rows.append([
+            order_no, show_status_zh(item.get("showStatus")), item.get("hotelName"),
+            item.get("roomName"), f"{item.get('checkInDate') or '-'} → {item.get('checkOutDate') or '-'}",
+            item.get("totalAmount"),
+        ])
+    _print_table(["订单号", "状态", "酒店", "房型", "入住 → 离店", "金额"],
+                 rows, aligns=["left", "left", "left", "left", "left", "right"])
+    return 0
+
+
+def _load_passengers() -> list:
+    return _read_json(PASSENGERS_FILE, []) or []
+
+
+def cmd_save_passenger(args: argparse.Namespace) -> int:
+    name = os.environ.get(ENV_GUEST_NAME, "").strip()
+    mobile = os.environ.get(ENV_GUEST_MOBILE, "").strip()
+    credential_no = os.environ.get(ENV_GUEST_CREDENTIAL_NO, "").strip()
+    if not (name and mobile and credential_no):
+        return _fail(None, f"请先设置环境变量 {ENV_GUEST_NAME} / {ENV_GUEST_MOBILE} / {ENV_GUEST_CREDENTIAL_NO}")
+    passengers = _load_passengers()
+    record = {"name": name, "mobile": mobile, "credentialNo": credential_no,
+              "savedAt": time.strftime("%Y-%m-%d %H:%M:%S")}
+    for i, item in enumerate(passengers):
+        if item.get("credentialNo") == credential_no:
+            passengers[i] = record
+            break
+    else:
+        passengers.append(record)
+    _write_json(PASSENGERS_FILE, passengers)
+    print(json.dumps({"ok": True, "saved": {"name": name, "mobile": mobile}}, ensure_ascii=False))
+    return 0
+
+
+def cmd_list_passengers(args: argparse.Namespace) -> int:
+    passengers = _load_passengers()
+    if not passengers:
+        print("还没有保存过入住人身份。")
+        return 0
+    # 手机号与证件号打码，避免把身份信息原样摊在会话里
+    rows = []
+    for item in passengers:
+        mobile = str(item.get("mobile") or "")
+        masked = mobile[:3] + "*" * max(len(mobile) - 7, 0) + mobile[-4:] if len(mobile) >= 7 else mobile
+        rows.append([item.get("name"), masked, item.get("savedAt")])
+    _print_table(["姓名", "手机号", "保存时间"], rows)
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="酒店查询与预订")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_city = sub.add_parser("search-city", help="关键词 / 地标 / 酒店名检索，返回候选城市与酒店 ID")
+    p_city.add_argument("--keyword", required=True, help="城市名、地标、商圈或酒店名，如 外滩")
+    p_city.add_argument("--city-id", default=None, help="可选，在途城市 ID（如 10801）")
+    p_city.add_argument("--city-name", default=None, help="可选，城市名（与 --city-id 同时给）")
+    p_city.add_argument("--page-no", type=int, default=None)
+    p_city.add_argument("--page-size", type=int, default=None)
+    p_city.set_defaults(func=cmd_search_city)
+
+    p_hotel = sub.add_parser("search-hotel", help="按酒店 ID 或 cityId 查起价列表")
+    p_hotel.add_argument("--check-in", required=True, help="入住日期 YYYY-MM-DD")
+    p_hotel.add_argument("--check-out", required=True, help="离店日期 YYYY-MM-DD")
+    p_hotel.add_argument("--hotel-ids", default=None, help="可选，逗号分隔的酒店 ID；默认用 search-city 的候选")
+    p_hotel.add_argument("--city-id", default=None, help="可选，条件搜索用（测试环境实测返空，仅作兜底）")
+    p_hotel.add_argument("--page-index", type=int, default=None)
+    p_hotel.add_argument("--page-size", type=int, default=None)
+    p_hotel.set_defaults(func=cmd_search_hotel)
+
+    p_detail = sub.add_parser("hotel-detail", help="查房型与价格计划（含逐晚价、库存、取消规则）")
+    p_detail.add_argument("--origin-hotel-id", required=True, help="在途酒店 ID")
+    p_detail.add_argument("--check-in", default=None, help="入住日期，默认沿用上次")
+    p_detail.add_argument("--check-out", default=None, help="离店日期，默认沿用上次")
+    p_detail.add_argument("--city-id", default=None, help="可选，会话城市 ID")
+    p_detail.set_defaults(func=cmd_hotel_detail)
+
+    p_validate = sub.add_parser("validate", help="预订校验（报价码是否仍有效）")
+    p_validate.add_argument("--room-id", default=None, help="房型 ID，默认取缓存里的第一行")
+    p_validate.add_argument("--rate-plan-id", default=None, help="价格计划 ID")
+    p_validate.add_argument("--rooms", type=int, default=1, help="房间数，默认 1")
+    p_validate.add_argument("--customer-num", type=int, default=1, help="入住人数，默认 1")
+    p_validate.set_defaults(func=cmd_validate)
+
+    p_create = sub.add_parser("create-order", help="创建订单（房间与日期取缓存；入住人取环境变量）")
+    p_create.add_argument("--room-id", default=None, help="房型 ID，默认取缓存里的第一行")
+    p_create.add_argument("--rate-plan-id", default=None, help="价格计划 ID")
+    p_create.add_argument("--rooms", type=int, default=1, help="房间数，默认 1")
+    p_create.add_argument("--credential-type", default="IDENTITY", help="证件类型，默认 IDENTITY")
+    p_create.add_argument("--contacter-name", default=None, help="联系人姓名，默认同入住人")
+    p_create.add_argument("--contacter-mobile", default=None, help="联系人手机号，默认同入住人")
+    p_create.add_argument("--earliest-arrival-time", default=None, help="最早到店时间，默认入住日 14:00:00")
+    p_create.add_argument("--latest-arrival-time", default=None, help="最晚到店时间，默认入住日 23:59:00")
+    p_create.set_defaults(func=cmd_create_order)
+
+    p_pay = sub.add_parser("pay-order", help="支付订单（企业账户）")
+    p_pay.add_argument("--order-no", required=True, help="订单号")
+    p_pay.add_argument("--pay-amount", type=float, default=None, help="可选，默认取订单详情的订单总额")
+    p_pay.set_defaults(func=cmd_pay_order)
+
+    p_status = sub.add_parser("order-status", help="查询订单状态与详情")
+    p_status.add_argument("--order-no", required=True, help="订单号")
+    p_status.set_defaults(func=cmd_order_status)
+
+    p_cancel = sub.add_parser("cancel-order", help="取消订单（未支付取消 / 已支付退订由网关按状态自动选择）")
+    p_cancel.add_argument("--order-no", required=True, help="订单号")
+    p_cancel.set_defaults(func=cmd_cancel_order)
+
+    p_refund = sub.add_parser("refund-part", help="部分退订（需先 --dry-run 展示，再经用户确认）")
+    p_refund.add_argument("--order-no", required=True, help="订单号")
+    p_refund.add_argument("--room-no", type=int, required=True, help="房间号，从 1 开始")
+    p_refund.add_argument("--check-in", required=True, help="退订起始日期 YYYY-MM-DD")
+    p_refund.add_argument("--check-out", required=True, help="退订结束日期 YYYY-MM-DD")
+    p_refund.add_argument("--reason", default=None, help="可选，退订原因")
+    p_refund.add_argument("--dry-run", action="store_true", default=False, help="只展示订单与退款信息，不提交")
+    p_refund.set_defaults(func=cmd_refund_part)
+
+    p_list = sub.add_parser("list-orders", help="列出本地缓存的历史订单摘要")
+    p_list.set_defaults(func=cmd_list_orders)
+
+    p_save_pax = sub.add_parser("save-passenger", help="把当前环境变量中的入住人身份保存到本地文件")
+    p_save_pax.set_defaults(func=cmd_save_passenger)
+
+    p_list_pax = sub.add_parser("list-passengers", help="列出已保存的入住人身份（手机号打码）")
+    p_list_pax.set_defaults(func=cmd_list_passengers)
+
+    args = parser.parse_args()
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())