实时业务状态接口契约（Realtime Status API）¶

文档编号：DOC-OPS-KB-03 / KB-RTS 版本：V1.0 创建日期：2026-08-13 维护人：听云（WCL） / WDE 保密级别：🟢 可公开发布（仅契约描述，不含真实端点 URL/Token） 关联文档：业务知识库索引、DIP1-API OpenAPI 规格、DIP1-P2 一线操作系统设计、CPT-D 客户跟踪设计

一、文档定位¶

本文件定义 AI 客服系统调用实时业务状态接口的契约规范——AI 在回答涉及客户订单、师傅状态、报价计算、工单状态等实时信息的问题时，须通过 Function Calling 调用本文件定义的接口，禁止凭知识库静态内容回答。

使用方式： - 作为 AI 客服系统 Function Calling 的工具定义清单 - 作为 WDE（听码）开发客服 API 端点的契约依据 - 作为 WCL（听云）监控 API 健康状态的清单参考

与 DIP1-API 的关系： - 本文件复用 DIP1 已有的 65 端点中的客户/订单/师傅/报价查询接口 - 本文件新增 AI 客服专用聚合接口（如 GET /api/v1/ai/customer/overview） - 接口实现由 WDE 负责，接口契约由 WCL + WDE 共同维护

二、AI 客服接口总览¶

2.1 接口分类¶

类别	接口数	用途	调用频率
客户身份识别	2	通过手机号/客户 ID 识别客户	高
订单状态查询	3	查询客户当前/历史订单及阶段	极高
报价计算	2	实时报价 + 报价历史	高
师傅状态查询	2	师傅位置/接单状态	中
工单管理	3	AI 工单创建/查询/更新	高
AI 专用聚合	3	客户全貌/订单全貌/工单全貌	极高
总计	15	—	—

2.2 通用规范¶

项	规范
Base URL	`https://api.weavely.hk/api/v1`（生产）/ `https://staging.api.weavely.hk/api/v1`（预发）
认证	Bearer Token（JWT），AI 客服使用专用 service account
请求格式	`application/json; charset=utf-8`
响应格式	`{ "code": 0, "data": {...}, "message": "success" }`
错误码	0=成功 / 4xx=客户端错误 / 5xx=服务端错误
限流	AI 客服 service account：1000 req/min（可调）
超时	5s（订单查询）/ 10s（报价计算）/ 15s（AI 聚合接口）
幂等性	所有 GET 接口天然幂等；POST/PUT 接口支持 `Idempotency-Key`

2.3 AI 客服 service account 权限矩阵¶

资源	读	写	说明
客户信息（CPL）	✅	❌	可查客户基本信息+标签，不可改
订单（CPT）	✅	⚠️	可查可创建工单，不可改订单核心字段
师傅信息（WPL）	✅	❌	可查师傅状态，不可改
报价（QSV）	✅	✅	可查可创建报价（不落库的预算）
工单（Ticket）	✅	✅	可查可创建可更新（受限字段）
系统配置	❌	❌	禁止访问

三、客户身份识别接口¶

3.1 `GET /ai/customer/identify` — 按手机号识别客户¶

用途：AI 客服在客户首次咨询时识别身份

请求参数：

参数	类型	必填	说明
phone	string	✅	客户手机号（+852XXXXXXXX）

响应 data：

{
  "customer_id": "CST-2026-00001",
  "name_masked": "陈**",
  "nickname": "陈生",
  "preferred_language": "yue-HK",
  "trust_badges": ["repeat_customer", "nps_promoter"],
  "lifetime_value": "high",
  "is_vip": false,
  "open_tickets_count": 1,
  "active_orders_count": 2
}

AI 消费规则： - 命中客户 → AI 使用 nickname 称呼，避免使用真实姓名 - 未命中 → AI 引导客户提供订单号或注册手机号 - open_tickets_count > 0 → AI 主动告知"您有 N 个进行中工单" - is_vip = true → AI 切换至 VIP 服务模式（响应优先级提升）

3.2 `GET /ai/customer/overview/{customer_id}` — 客户全貌聚合¶

用途：AI 客服在处理复杂咨询时一次性获取客户全貌

响应 data：

{
  "customer": { "...": "见 3.1" },
  "active_orders": [
    {
      "order_id": "ORD-2026-08-0001",
      "stage": "L4",
      "stage_name": "已派单",
      "service_category": "C01",
      "service_category_name": "家具",
      "product": "双人床安装",
      "scheduled_at": "2026-08-14 14:00",
      "worker": { "worker_id": "WKR-001", "name_masked": "李**", "rating": 4.8, "level": "gold" }
    }
  ],
  "history_orders_summary": { "total": 12, "last_30d": 2, "completed": 11, "cancelled": 1 },
  "open_tickets": [ { "ticket_id": "T-20260813-01", "subject": "师傅迟到", "status": "in_progress" } ],
  "nps_history": [ { "order_id": "ORD-...", "score": 9, "created_at": "2026-07-15" } ]
}

AI 消费规则： - 一次性获取所有相关信息，避免多次 API 调用 - AI 基于全貌生成"上下文感知"回复（如"陈生，您明天下午 2 点李师傅会为您装床..."）

四、订单状态查询接口¶

4.1 `GET /ai/order/{order_id}` — 查询单个订单详情¶

响应 data：

{
  "order_id": "ORD-2026-08-0001",
  "customer_id": "CST-2026-00001",
  "stage": "L4",
  "stage_name": "已派单",
  "stage_progress": 50,
  "service_category": "C01",
  "service_category_name": "家具",
  "product": "双人床安装",
  "address_masked": "港島 灣仔 **樓 **室",
  "scheduled_at": "2026-08-14 14:00",
  "quote": { "final_price": 580, "cap_price": 650, "currency": "HKD" },
  "worker": { "worker_id": "WKR-001", "name_masked": "李**", "phone_masked": "****1234", "rating": 4.8, "level": "gold", "eta_minutes": 25 },
  "anomalies": [],
  "next_action": "师傅将在 25 分钟内到达",
  "created_at": "2026-08-12 10:30",
  "updated_at": "2026-08-13 09:15"
}

AI 消费规则： - stage 映射到 CPT 8 阶段，AI 须用客户能理解的语言表述（不说"L4"，说"已派单，师傅正在路上"） - anomalies 非空 → AI 主动解释异常并告知处理方案 - worker.eta_minutes 存在 → AI 主动告知预计到达时间

4.2 `GET /ai/customer/{customer_id}/orders` — 查询客户订单列表¶

请求参数：

参数	类型	必填	默认	说明
status	string	❌	all	`active` / `completed` / `cancelled` / `all`
limit	int	❌	20	1-50
offset	int	❌	0	分页偏移

响应 data：{ "orders": [ {...见 4.1} ], "total": 12, "has_more": false }

4.3 `GET /ai/order/{order_id}/timeline` — 查询订单时间线¶

用途：客户问"我的订单走到哪了"时，AI 获取完整时间线

响应 data：

{
  "order_id": "ORD-2026-08-0001",
  "timeline": [
    { "stage": "L1", "stage_name": "线索", "timestamp": "2026-08-12 09:00", "note": "客户通过 App 下单" },
    { "stage": "L2", "stage_name": "报价", "timestamp": "2026-08-12 09:15", "note": "系统自动报价 HK$580" },
    { "stage": "L3", "stage_name": "下单", "timestamp": "2026-08-12 10:30", "note": "客户确认下单" },
    { "stage": "L4", "stage_name": "已派单", "timestamp": "2026-08-12 11:00", "note": "派单给金牌师傅李**" }
  ],
  "current_stage": "L4",
  "next_expected_stage": "L5 上门",
  "next_expected_at": "2026-08-14 14:00"
}

五、报价计算接口¶

5.1 `POST /ai/quote/calculate` — 实时报价计算¶

用途：客户问"装一张床多少钱"时，AI 收集参数后调用本接口实时计算

请求 body：

{
  "service_category": "C01",
  "product": "双人床",
  "building_type": "private",
  "district": "wan_chai",
  "worker_level": "certified",
  "time_slot": "off_peak",
  "floor": 8,
  "has_elevator": true,
  "special_work": []
}

响应 data：

{
  "quote_id": "QT-20260813-0001",
  "base_fee": 400,
  "building_factor": 1.0,
  "district_factor": 1.1,
  "worker_level_factor": 1.0,
  "time_slot_factor": 1.0,
  "floor_extra": 0,
  "special_work_extra": 0,
  "final_price": 440,
  "cap_price": 500,
  "currency": "HKD",
  "breakdown_visible": true,
  "valid_until": "2026-08-13 23:59"
}

AI 消费规则： - AI 必须展示 final_price 与 cap_price，强调"封顶价 HK$500" - AI 应当主动说明各项系数影响（如"湾仔区域加成 1.1"） - AI 应当提示报价有效期（valid_until）

5.2 `GET /ai/quote/history?customer_id={id}` — 查询客户历史报价¶

响应 data：{ "quotes": [ {...见 5.1} ], "total": 8 }

六、师傅状态查询接口¶

6.1 `GET /ai/worker/{worker_id}` — 查询师傅基本信息¶

响应 data：

{
  "worker_id": "WKR-001",
  "name_masked": "李**",
  "nickname": "李师傅",
  "level": "gold",
  "rating": 4.8,
  "completed_orders_30d": 45,
  "skills": ["C01-床", "C01-沙发", "C02-吊灯"],
  "current_status": "on_the_way",
  "current_order_id": "ORD-2026-08-0001",
  "eta_minutes": 25
}

AI 消费规则： - AI 始终使用 nickname 称呼师傅，禁止透露师傅真实姓名/手机号 - 客户索要师傅联系方式 → AI 引导通过 App 内匿名通话功能

6.2 `GET /ai/worker/{worker_id}/location` — 查询师傅实时位置¶

用途：客户问"师傅到哪里了"时调用

响应 data：

{
  "worker_id": "WKR-001",
  "current_district": "wan_chai",
  "distance_km": 2.3,
  "eta_minutes": 25,
  "last_updated_at": "2026-08-13 13:45",
  "status": "on_the_way"
}

安全约束： - 仅在师傅 current_status = on_the_way 且 current_order_id 属于该客户时返回精确位置 - 其他情况返回模糊位置（如"师傅目前在港岛区"）

七、工单管理接口¶

7.1 `POST /ai/ticket` — 创建工单¶

请求 body：

{
  "customer_id": "CST-2026-00001",
  "order_id": "ORD-2026-08-0001",
  "category": "complaint",
  "subject": "师傅迟到",
  "description": "客户反馈师傅比约定时间晚到 30 分钟",
  "priority": "P2",
  "source": "ai_chat",
  "ai_confidence": 0.85,
  "ai_summary": "客户情绪较激动，需要安抚+具体到达时间"
}

响应 data：

{
  "ticket_id": "T-20260813-01",
  "status": "open",
  "assigned_to": "WCL-AI",
  "sla_response_deadline": "2026-08-13 17:00",
  "sla_resolution_deadline": "2026-08-15 17:00"
}

AI 消费规则： - AI 创建工单时必须附 ai_confidence 与 ai_summary，便于人工兜底客服快速接手 - ai_confidence < 0.7 → AI 主动升级人工

7.2 `GET /ai/ticket/{ticket_id}` — 查询工单状态¶

响应 data：

{
  "ticket_id": "T-20260813-01",
  "status": "in_progress",
  "assigned_to": "WCL-Human-002",
  "category": "complaint",
  "subject": "师傅迟到",
  "priority": "P2",
  "created_at": "2026-08-13 14:00",
  "updated_at": "2026-08-13 14:30",
  "sla_response_deadline": "2026-08-13 17:00",
  "sla_resolution_deadline": "2026-08-15 17:00",
  "sla_response_breach": false,
  "sla_resolution_breach": false,
  "history": [
    { "action": "created", "actor": "WCL-AI", "timestamp": "2026-08-13 14:00", "note": "AI 创建工单" },
    { "action": "assigned", "actor": "WCL-AI", "timestamp": "2026-08-13 14:05", "note": "自动转人工（AI 置信度 0.65）" }
  ]
}

7.3 `PATCH /ai/ticket/{ticket_id}` — 更新工单¶

可更新字段：status / priority / assigned_to / note

AI 权限：仅可更新 status 为 pending_customer / waiting_internal / resolved；其他字段变更需人工客服操作。

八、AI 专用聚合接口¶

本节接口为 AI 客服专用，一次性返回多个域的信息，避免 AI 多次调用造成延迟。

8.1 `GET /ai/context/customer+order?phone={phone}` — 客户+订单聚合¶

用途：AI 客服接入咨询时一次性获取客户身份 + 进行中订单 + 工单

响应 data：

{
  "customer": { "...": "见 3.1" },
  "active_orders": [ { "...": "见 4.1" } ],
  "open_tickets": [ { "...": "见 7.2" } ],
  "suggested_actions": [
    "确认身份后主动告知订单进度",
    "如有工单则同步工单状态"
  ]
}

8.2 `GET /ai/context/order+worker?order_id={id}` — 订单+师傅聚合¶

响应 data：

{
  "order": { "...": "见 4.1" },
  "worker": { "...": "见 6.1" },
  "worker_location": { "...": "见 6.2" },
  "timeline": { "...": "见 4.3" },
  "anomalies": []
}

8.3 `GET /ai/context/ticket+order?ticket_id={id}` — 工单+订单聚合¶

响应 data：

{
  "ticket": { "...": "见 7.2" },
  "order": { "...": "见 4.1" },
  "customer": { "...": "见 3.1" },
  "sla_status": { "response_breach": false, "resolution_breach": false, "response_remaining_minutes": 180 }
}

九、接口健康监控¶

9.1 WCL 监控指标¶

指标	阈值	告警
接口可用性	≥ 99.5%	< 99.5% 告警
平均响应时间	≤ 500ms（简单）/ 2s（聚合）	超阈值告警
错误率（5xx）	≤ 0.5%	> 0.5% 告警
AI 调用成功率	≥ 99%	< 99% 告警
限流触发次数	≤ 10次/天	超阈值告警（需扩容）

9.2 接口降级策略¶

当接口异常时，AI 客服按以下策略降级：

异常类型	降级策略
单个接口超时	AI 改用静态知识库回答 + 提示"实时数据暂不可用"
客户身份接口失败	AI 引导客户手动提供订单号
订单接口失败	AI 创建工单转人工处理
报价接口失败	AI 提供区间参考价（基于 business-knowledge.md） + 引导下单查看精准报价
全部接口不可用	AI 主动告知"系统临时维护中" + 创建 P0 工单 + 升级人工

十、修订记录¶

版本	日期	修订人	修订内容
V1.0	2026-08-13	DT	初始化实时业务状态接口契约；定义 15 个 AI 客服专用接口（客户识别 2 + 订单 3 + 报价 2 + 师傅 2 + 工单 3 + 聚合 3）；定义 AI service account 权限矩阵；定义接口降级策略与健康监控指标

本文件为 AI 客服系统的实时业务状态接口契约。接口实现由听码 WDE 负责，契约维护由听云 WCL + WDE 共同承担。对齐 DIP1-API OpenAPI 规格 V2.0。

实时业务状态接口契约（Realtime Status API）¶

一、文档定位¶

二、AI 客服接口总览¶

2.1 接口分类¶

2.2 通用规范¶

2.3 AI 客服 service account 权限矩阵¶

三、客户身份识别接口¶

3.1 GET /ai/customer/identify — 按手机号识别客户¶

3.2 GET /ai/customer/overview/{customer_id} — 客户全貌聚合¶

四、订单状态查询接口¶

4.1 GET /ai/order/{order_id} — 查询单个订单详情¶

4.2 GET /ai/customer/{customer_id}/orders — 查询客户订单列表¶

4.3 GET /ai/order/{order_id}/timeline — 查询订单时间线¶

五、报价计算接口¶

5.1 POST /ai/quote/calculate — 实时报价计算¶

5.2 GET /ai/quote/history?customer_id={id} — 查询客户历史报价¶

六、师傅状态查询接口¶

6.1 GET /ai/worker/{worker_id} — 查询师傅基本信息¶

6.2 GET /ai/worker/{worker_id}/location — 查询师傅实时位置¶

七、工单管理接口¶

7.1 POST /ai/ticket — 创建工单¶

7.2 GET /ai/ticket/{ticket_id} — 查询工单状态¶

7.3 PATCH /ai/ticket/{ticket_id} — 更新工单¶

八、AI 专用聚合接口¶

8.1 GET /ai/context/customer+order?phone={phone} — 客户+订单聚合¶

8.2 GET /ai/context/order+worker?order_id={id} — 订单+师傅聚合¶

8.3 GET /ai/context/ticket+order?ticket_id={id} — 工单+订单聚合¶

九、接口健康监控¶

9.1 WCL 监控指标¶

9.2 接口降级策略¶

十、修订记录¶

3.1 `GET /ai/customer/identify` — 按手机号识别客户¶

3.2 `GET /ai/customer/overview/{customer_id}` — 客户全貌聚合¶

4.1 `GET /ai/order/{order_id}` — 查询单个订单详情¶

4.2 `GET /ai/customer/{customer_id}/orders` — 查询客户订单列表¶

4.3 `GET /ai/order/{order_id}/timeline` — 查询订单时间线¶

5.1 `POST /ai/quote/calculate` — 实时报价计算¶

5.2 `GET /ai/quote/history?customer_id={id}` — 查询客户历史报价¶

6.1 `GET /ai/worker/{worker_id}` — 查询师傅基本信息¶

6.2 `GET /ai/worker/{worker_id}/location` — 查询师傅实时位置¶

7.1 `POST /ai/ticket` — 创建工单¶

7.2 `GET /ai/ticket/{ticket_id}` — 查询工单状态¶

7.3 `PATCH /ai/ticket/{ticket_id}` — 更新工单¶

8.1 `GET /ai/context/customer+order?phone={phone}` — 客户+订单聚合¶

8.2 `GET /ai/context/order+worker?order_id={id}` — 订单+师傅聚合¶

8.3 `GET /ai/context/ticket+order?ticket_id={id}` — 工单+订单聚合¶