旺小宝来访分页查询
> CRITICAL —— 跑命令前 MUST 先用 Read tool 读取 ../wangxiaobao-shared/SKILL.md（一份共享文档讲清安装 / 登录 / 选项目 / 错误码 / 输出协议等所有 xiaobao-cli 命令通用的前置约定）。
跑 xiaobao-cli visit list 查当前激活项目的来访记录。
执行前必读
- 必须有有效 token：先调
xiaobao-cli auth whoami；未登录就走auth login --no-waitsplit-flow（见 wangxiaobao-shared） - 必须有激活项目：命令内部自动读，缺失返回
NO_ACTIVE_PROJECT - 数据权限隔离：跟客户接口一样，按当前用户授权可见顾问范围过滤
- LocalDateTime 格式：
yyyy-MM-dd HH:mm:ss（空格分隔），CLI 自动转 - 不要写文件、出报告
快速索引：意图 → 工具
| 用户意图 | 命令 | 关键参数 |
|---|---|---|
| 列时间窗内的全部来访 | xiaobao-cli visit list |
--from / --to |
| 看某客户的来访历史 | xiaobao-cli customer list → xiaobao-cli visit list |
--customer-id 反查的 wang_id |
| 按客户名字模糊找来访 | xiaobao-cli visit list |
--customer-name 张 |
| 看某次来访的录音详情 | xiaobao-cli visit list |
直接读返回里的 audios[]（含 fileUrl） |
| 估算总数 | xiaobao-cli visit list |
--page 1 --size 1，只读 total |
核心约束
1. 客户名 vs 客户 ID —— 优先 ID，更准更快
用户说"李女士最近几次来访"——优先走两步：
- 调
xiaobao-cli customer list { customerName: "李女士" }反查到--customer-id - 调
xiaobao-cli visit list { customerId: <wang_id> }拿来访历史
直接传 --customer-name 也能用（后端 JOIN customer_profile 模糊匹配），但：
- 同名客户可能有多个（重名 "李女士"），结果混在一起不好辨认
- JOIN 慢于纯 visit 表查询
2. 时间窗：用户没明确说就推断
| 用户说法 | fromDate / toDate |
|---|---|
| "今天到访" | 今天 00:00:00 / 明天 00:00:00 |
| "本周来访" | 周一 00:00:00 / 今天 23:59:59 |
| "上周末" | 上周六 00:00:00 / 本周一 00:00:00 |
| "5 月份" | 2026-05-01 00:00:00 / 2026-06-01 00:00:00 |
| "最近 3 次" | 不传时间窗，只看 content[] 前 3 条 |
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-projectskill- 401 / token 过期 — 走
auth login --no-wait --forcesplit-flow 重登 total: 0— 时间窗内确实没数据，或当前用户授权范围内没有匹配的接待顾问- customerName 模糊但没匹到 — 客户名拼写差异（"李女士" vs "李小姐"）；
改用xiaobao-cli customer list反查精确 customerId - 接待顾问跟归属顾问不一致 — 正常业务情况（同事代接待），不是 bug；
必要时跟用户解释
