旺小宝来访分页查询

> CRITICAL —— 跑命令前 MUST 先用 Read tool 读取 ../wangxiaobao-shared/SKILL.md（一份共享文档讲清安装 / 登录 / 选项目 / 错误码 / 输出协议等所有 xiaobao-cli 命令通用的前置约定）。

跑 xiaobao-cli visit list 查当前激活项目的来访记录。

执行前必读

• 必须有有效 token：先调 xiaobao-cli auth whoami；未登录就走 auth login --no-wait split-flow（见 wangxiaobao-shared）
• 必须有激活项目：命令内部自动读，缺失返回 NO_ACTIVE_PROJECT
• 数据权限隔离：跟客户接口一样，按当前用户授权可见顾问范围过滤
• LocalDateTime 格式：yyyy-MM-dd HH:mm:ss（空格分隔），CLI 自动转
• 不要写文件、出报告

快速索引：意图 → 工具

核心约束

1. 客户名 vs 客户 ID —— 优先 ID，更准更快

用户说"李女士最近几次来访"——优先走两步：

1. 调 xiaobao-cli customer list { customerName: "李女士" } 反查到 --customer-id
2. 调 xiaobao-cli visit list { customerId: } 拿来访历史

直接传 --customer-name 也能用（后端 JOIN customer_profile 模糊匹配），但：

• 同名客户可能有多个（重名 "李女士"），结果混在一起不好辨认
• JOIN 慢于纯 visit 表查询

2. 时间窗：用户没明确说就推断

3. 分页：page 从 1 开始；size 上限 500

跟其他接口一样。

4. 响应字段重点

{
  "code": "0",
  "data": {
    "page": 1, "size": 10, "total": 23,
    "content": [
      {
        "visitId":   "...",
        "customerId": "1685535452481236993",      // = wang_id，可传回 customers 查
        "visitTime": "2023-07-30 14:01:03",
        "visitCount": 1,                           // 第几次到访
        "visitTimer": 1439184,                     // 来访总秒数
        "audioCount": 3,                           // 关联录音条数（= audios.length）
        "audios": [                                // ★ 录音详情列表，按 startTime 升序
          {
            "audioId":   9001,
            "fileId":    "abc",
            "startTime": "2023-07-30 14:01:15",
            "endTime":   "2023-07-30 14:08:42",
            "duration":  447,                      // 秒
            "fileSize":  3145728,
            "hasValid":  1,                        // 0 无效 / 1 有效
            "status":    4,                        // 0 转存中/1 转文本/2 待分析/3 分析中/4 完成
            "userId":    270078834689187840,
            "fileUrl":   "https://oss.../abc?sign=..."  // 18000 秒过期
          }
        ],
        "userId": 270078834689187840,
        "userName": "兰鸿建",                       // 实际接待顾问
        "belongUserId":   ...,
        "belongUserName": "兰鸿建",                // 客户归属顾问（可能跟接待不同）
        "userInfo": { /* 顾问详情 */ },
        "pankeStatus": "已完成",                    // 盘客状态
        "isPankeCompleted": 1,
        "requireSpeechTotal": 8, "requireSpeechHit": 5,
        "salesSpeechTotal":   12, "salesSpeechHit": 9
      }
    ]
  }
}

CLI 又包一层 → resp.data.data.content。

requireSpeechHitDetail / salesSpeechHitDetail 是 JSON 文本，默认不展示给用户

（除非用户明确问"具体哪条话术命中了"）。

5. 接待 vs 归属：解释差异

• userId / userName = 实际接待（这次来访是谁陪同的）
• belongUserId / belongUserName = 客户归属（客户档案里登记的归属销售）

正常情况两者一致；不一致时可能是：

• 销售 A 不在岗，同事 B 帮忙接待 A 的客户
• 客户重新分配过

用户问"张三接待了几个"——按 userId == 张三；问"张三名下客户来访"——按 belongUserId == 张三

（但本 命令当前不支持按 belongUserId 过滤，需先用 customers 反查再 customerId 过滤）。

使用场景示例

场景 1：今天到访列表

xiaobao-cli visit list --from "2026-05-13 00:00:00" --to "2026-05-14 00:00:00"

渲染：

今天共 18 次到访（按时间倒序）:
1. 屈哥 · 14:01 · 接待:兰鸿建 · 第 1 次 · 12 分 · 录音 3
2. 曹女士 · 13:45 · 接待:陈平 · 第 2 次 · 25 分 · 录音 2
...

场景 2：李女士最近 3 次来访

# step 1: 反查 wang_id
xiaobao-cli customer list --customer-name 李女士 --size 20

# step 2: 假设找到 customerId = 270072120829026305
xiaobao-cli visit list --customer-id 270072120829026305 --page 1 --size 3

场景 3：上周末来访高峰

xiaobao-cli visit list --from "2026-05-10 00:00:00" --to "2026-05-12 00:00:00" --page 1 --size 50

后处理：按 hour 聚合 → 报告"周日下午 14-16 点是峰值"。

场景 4：用客户名直接模糊

# 不知道具体客户 ID，先用名字模糊
xiaobao-cli visit list --customer-name 张 --from "2026-05-01 00:00:00" --size 20

回复："姓张的客户 5 月来访共 8 次，分布在 3 位客户：张先生(133**0692) 来 3 次..."

场景 5：直接看某次到访的录音详情

xiaobao-cli visit list --customer-id 1685535452481236993 --page 1 --size 5

每条 visit 已带 audios[]，不必再调 xiaobao-cli audio list：

屈哥 · 2023-07-30 14:01:03 · 接待:兰鸿建 · 12 分 · 3 条录音：
  1. audioId=9001 · 14:01:15 ~ 14:08:42 · 7 分 · 状态:分析完成
     fileUrl: https://oss.../abc?sign=...
  2. audioId=9002 · 14:09:00 ~ 14:11:30 · 2 分 · 状态:分析完成
  3. audioId=9003 · 14:12:00 ~ 14:15:30 · 3 分 · 状态:分析完成

> 想看某条录音的转录文本还是要单独调 xiaobao-cli audio text，

> audios[] 里只有元数据 + 签名 URL，没有 transcript。

常见错误与排查

• error: 'NO_ACTIVE_PROJECT' — 跑 wangxiaobao-switch-project skill
• 401 / token 过期 — 走 auth login --no-wait --force split-flow 重登
• total: 0 — 时间窗内确实没数据，或当前用户授权范围内没有匹配的接待顾问
• customerName 模糊但没匹到 — 客户名拼写差异（"李女士" vs "李小姐"）；

改用 xiaobao-cli customer list 反查精确 customerId

• 接待顾问跟归属顾问不一致 — 正常业务情况（同事代接待），不是 bug；

必要时跟用户解释