浅念
155 lines
10 KiB
Markdown
155 lines
10 KiB
Markdown
# 云客 CRM 数据字典（全系统扫描结果）
|
||
|
||
- **日期**：2026-08-01
|
||
- **来源**：登录云客 CRM（crm2.yunkecn.com）实地抓包，覆盖全部模块
|
||
- **状态标记**：✅ 已确认字段 ｜ ⏳ 接口已找到，字段待 Phase 0 ｜ 🔭 仅知入口
|
||
|
||
> 本文档是[设计文档](2026-08-01-yunke-data-mirror-design.md)的配套数据字典，列出系统中**所有数据实体**及其接口、字段、规模、抓取优先级。
|
||
|
||
---
|
||
|
||
## 0. 鉴权与接口约定
|
||
|
||
- **鉴权**：自定义请求头 `userid` + `company` + `source:yunkepc` + `channel:4` + 会话 cookie；登录链 `getSecureKey → pcLogin`（账号密码，无验证码，可全自动）
|
||
- **接口前缀**：
|
||
- `/pc/...` — CRM 通用（客户/电话/短信/统计）
|
||
- `/usercenter/...` — 用户/部门
|
||
- `/wechatweb/...` — 微信
|
||
- `/qqweb/WhatsAppUser/...` — WhatsApp
|
||
- **通用响应**：`{success, code:"10000", message, data, traceId}`
|
||
- **媒体存储**：OSS 桶 `yunke-pcfile.oss-cn-beijing.aliyuncs.com`（已由通话录音确认）；头像在 `wx.qlogo.cn` / `mmhead.c2c.wechat.com` / `pc.oss.yunkecn.com`
|
||
|
||
---
|
||
|
||
## 1. 组织与人员
|
||
|
||
| 实体 | 接口 | 状态 | 关键字段 | 规模 |
|
||
|---|---|---|---|---|
|
||
| 部门/分组 department | `POST /usercenter/dept/tree` | ✅ | dept_id, parent_id, name, path | 6 个分组 |
|
||
| 员工 staff | 嵌入账号列表（`userId`+`userName`） | ✅ | user_id, name, phone, sale_phone, dept_id, is_on_job | 与账号同源 |
|
||
| 员工管理(完整) | `/pc/crm_t_portaluser/...` | 🔭 | 姓名/性别/手机/角色/离职 | 设置→部门管理 |
|
||
|
||
---
|
||
|
||
## 2. 微信（prefix `/wechatweb/`）
|
||
|
||
| 实体 | 接口 | 状态 | 关键字段 | 规模 |
|
||
|---|---|---|---|---|
|
||
| 员工微信号+员工 `wxUser/list` | `POST /wechatweb/wxUser/list` | ✅ | wechatId, nickName, alias, phone, userId, userName(员工真名), contactsNum, groupNum, sendNum/receiveNum, isOnJob, dbSize, 在线状态, lastUpdate | **55** |
|
||
| 客户/好友 customer | `POST /wechatweb/wxFriends/friend_list/es` | ✅ | friendWxId, wxId(归属), friendWxNickname/Remark, realName, phone/wechatPhone(完整), gender, region, description, saleName, userId, deptRoute/deptName, friendHeadImageUrl/headImg, lastChatTime, sendNum/receiveNum/messageCount, version, deleteFlag/isBlock/friendState | **8152** |
|
||
| 会话列表 talker | `POST /wechatweb/wxFriends/talkerList` | ✅ | friendWechatId, nickName, remarkName, messageCount, lastChatTime, headUrl, memberCount, analyseResult | 按员工 |
|
||
| **消息** message | `POST /wechatweb/msg/chats` | ✅ | msgSvrId(主键), type/messageType, text, **file/fileTh/fileHd(媒体URL)**, **md5/md5Th/md5Hd**, duration, **transcriptionText(语音转文字)**, imgPath/originalImage/picType, paymsgid, referMsg, talker/oriTalker, wechatId, **roomid(群,空=单聊)**, mine/isSend, timestamp/createTime, version, isDel, name/headUrl | 百万级 |
|
||
| ↳ 参数 | — | ✅ | `wechatId`+`friendId`+`types`+`start/end`(ms 时间范围)；游标 `end`/`hasLast` | — |
|
||
| **群 chatroom** | `POST /wechatweb/chatroom/getChatroomList` | ✅ | chatRoomId(`@chatroom`), chatRoomName, memberCount, **memberIds(分号分隔全部成员wxid)**, headImageUrl, wechatId/wechatNickName(归属), userName/userPhone(群主员工), messageCount/ownMessageCount, lossMembers/addMembers, lastChatTime/updateTime | **1515** |
|
||
| 语音通话 voice_call | `POST /wechatweb/callRecord/queryWeChatVoiceList` | ⏳ | 接口已确认，字段 Phase 0（含录音） | 待测 |
|
||
| 通话统计 | `POST /wechatweb/callRecord/todayStatistics` | 🔭 | 统计聚合 | — |
|
||
|
||
**消息类型码（微信）**：`1`=文字、`-2`=日期分隔符(非真实消息)；图片/语音/视频/文件/转账/红包/引用/系统 各有码（Phase 0 枚举）。
|
||
|
||
---
|
||
|
||
## 3. WhatsApp（prefix `/qqweb/WhatsAppUser/`）
|
||
|
||
| 实体 | 接口 | 状态 | 关键字段 | 规模 |
|
||
|---|---|---|---|---|
|
||
| 员工+账号 `businessSalesList` | `POST /qqweb/WhatsAppUser/businessSalesList` | ✅ | userId, userName(员工真名), uid(`手机号@s.whatsapp.net`), nickName, phone/salePhone/salesBindPhone, contactsNum, groupNum, talkerCount, friendAddNum, isOnJob, lastUpdate | **42** |
|
||
| 客户/联系人 friend | `POST /qqweb/WhatsAppUser/businessFriendList` | ⏳ | 接口已确认，字段 Phase 0 | 待测 |
|
||
| 客户/群信息 | `POST /qqweb/WhatsAppUser/getFriendOrTroopInfo` | ⏳ | 单个客户/群详情 | — |
|
||
| **消息** message | `POST /qqweb/WhatsAppUser/chatRecords` | ✅ | keyId(主键), type/msgType, content, **mediaName(媒体文件名)**, nickName, uid(员工), friendUid(客户), isSend, createTime/dateTime, timezone, companyCode, quotedId/quotedMessage | 百万级 |
|
||
| ↳ 参数 | — | ✅ | `start/end` 时间游标；`hasNext`/`hasLast` | — |
|
||
| 会话统计 | `getBusinessChatOverView` / `getBusinessChatDailyStatistics` / `getBusinessChatDetailList` | 🔭 | 概览/日统计/明细 | — |
|
||
| 语音通话 voice_call | 页面 `waBusiness/wavoicecalllist` | 🔭 | Phase 0 | — |
|
||
|
||
**消息类型码（WhatsApp）**：`0`=文字、`1`=图片/媒体、`-2`=日期符。
|
||
**ID 格式**：`手机号@s.whatsapp.net`。
|
||
**媒体差异**：仅给 `mediaName`（文件名），需专门下载接口（Phase 0）。
|
||
|
||
---
|
||
|
||
## 4. 电话与短信（客户→沟通记录，prefix `/pc/`）
|
||
|
||
| 实体 | 接口 | 状态 | 关键字段 | 规模 |
|
||
|---|---|---|---|---|
|
||
| **电话记录** phone_call | `POST /pc/callLog/list` | ✅ | id, startCallTime, callDuration/callSeconds, ringTime/ringSecond, callStatus(0未接/2接通), incomingCall(0呼出/1呼入), userId/userIdName(员工), departmentId, callNumber, simPhone, simNumber, imei, **recordFile(录音OSS URL)**, isUpload, downloadCount, aiAsr, qcStatus, version, planCustomerName | **6047** |
|
||
| 录音下载 | `/pc/customer/downloadMp3/1`、`/downloadMp3/2` | ✅ | MP3 下载（客户/通话两类） | — |
|
||
| 通话导出 | `/pc/callLog/exportXls` | 🔭 | Excel 导出 | — |
|
||
| **短信记录** sms | `POST /pc/customer/smsLogsList` | ✅ | id, customerPhone, **sms(全文)**/smsSub(预览), sender, direction(0收/1发), userId, senderDepartment/senderDepartmentId, receiveName, createTime, simPhone/simNumber, source | **53** |
|
||
| 现场录音 sales_recording | `/cms/customer/salesRecording` | 🔭 | 工牌/手机设备录音 | 待测 |
|
||
|
||
**录音 URL 形态**（关键，媒体下载用）：
|
||
`https://yunke-pcfile.oss-cn-beijing.aliyuncs.com/callFile/{companyCode}/{userId}/YYYY/MMDD/{callNumber}_{timestamp}.mp3`
|
||
|
||
---
|
||
|
||
## 5. CRM 客户模块（prefix `/pc/newcustomer/`，独立于微信好友）
|
||
|
||
| 实体 | 接口 | 状态 | 备注 |
|
||
|---|---|---|---|
|
||
| CRM 客户 | `POST /pc/newcustomer/customers` | ✅(空) | **本账号 total=0**——该公司未用 CRM 客户，客户全在微信/WhatsApp 好友里 |
|
||
| 客户分组/公海/统计/导出 | `/pc/newcustomer/...` | 🔭 | 接口存在，数据为空 |
|
||
|
||
---
|
||
|
||
## 6. 其他模块数据（来自全系统权限地图 `GET /pc/authority/permissions`）
|
||
|
||
> 权限接口一次返回所有模块/子页/操作 URL，已据此盘点。下列多为**统计/管理/配置**类，非沟通主数据；标注是否建议抓取。
|
||
|
||
### 6.1 微信风控 / 设置（沟通模块下）
|
||
- 微信财务统计、敏感操作统计、敏感词统计/设置、微信登录日志、**好友操作日志**(`/cms/wechat/friendDeletionLog`，含导出)、重复好友、微信验证消息、微信号解绑、聊天标签设置
|
||
- **建议抓**：好友操作日志（好友增删变更，便于追溯）
|
||
|
||
### 6.2 首页统计
|
||
- 数据统计/统计图表/通话/微信/短信/工作量统计/手机统计/打卡统计/自定义报表（均带导出）
|
||
- 多为聚合统计，可后期按需抓
|
||
|
||
### 6.3 AI 分析（`/pc/ai/...`）
|
||
- AI 客户洞察（客户分析/异议/问题/痛点/情绪/沟通关键词）、AI 员工赋能（优秀话术/竞品/战败）、AI 智能质检（敏感词质检/员工情绪/飞单预警/沟通质检）
|
||
- **派生数据**（由聊天/通话经 AI 生成），可后期抓；消息里也有 `analyseResult`/`transcriptionText` 字段
|
||
|
||
### 6.4 微小助 / 营销（`/pc/wxTask/...`、`/cms/wechatAssistantModules/...`）
|
||
- 微信营销任务（发圈/群发好友/群发群/批量加好友/视频号/客户唤醒）、企微任务、抖音/小红书营销、辅助营销（文章库/营销素材/快捷回复/话术库/微信活码）、拓客
|
||
- 多为**任务/素材配置**，非客户沟通数据；按需
|
||
|
||
### 6.5 设备（`/cms/device/...`）
|
||
- 设备统计、**手机截屏**(`/cms/device/phonescreenshot`)、**手机相册**(`/cms/settings/device/albumList`)、插拔卡统计、设备定位/地理围栏、设备管控
|
||
- **含媒体数据**（截屏/相册图片），如需要可抓；默认不在沟通范围
|
||
|
||
### 6.6 设置（`/pc/crm_t_portaluser/...`、`/cms/settings/...`）
|
||
- 部门管理/已离职用户/角色权限、自定义客户字段/标签、业务属性、系统设置（操作日志等）、聊天工作台
|
||
- 配置类，按需
|
||
|
||
---
|
||
|
||
## 7. 规模总览（实测）
|
||
|
||
| 数据 | 规模 |
|
||
|---|---|
|
||
| 微信员工账号 | 55 |
|
||
| WhatsApp 员工账号 | 42 |
|
||
| 微信客户/好友 | 8152 |
|
||
| 微信群 | 1515（含成员列表） |
|
||
| 电话记录 | 6047 |
|
||
| 短信记录 | 53 |
|
||
| 消息量 | 日均 ~2.7 万条（长期百万级 + 多媒体 TB 级） |
|
||
| CRM 客户 | 0（未使用） |
|
||
|
||
---
|
||
|
||
## 8. 抓取优先级建议
|
||
|
||
- **P0 核心（必抓）**：员工/账号（微信+WA）、客户/好友（微信+WA）、群+群成员、消息（单聊+群聊）、电话记录+录音、短信、多媒体（图片/语音/视频/文件/语音通话）
|
||
- **P1 建议**：语音通话（微信+WA）、WhatsApp 联系人明细、好友操作日志、现场录音、会话统计
|
||
- **P2 后期/按需**：AI 分析结果、营销素材/话术、设备截屏/相册、各类统计报表、CRM 客户（空）
|
||
|
||
---
|
||
|
||
## 9. Phase 0 待确认（实现期首批，浏览器抓包）
|
||
|
||
1. **聊天媒体下载**：微信 `file/fileTh/fileHd` 的 URL 形态与鉴权；WhatsApp `mediaName` 的下载接口（OSS 桶已知为 `yunke-pcfile`）
|
||
2. **媒体类型码**：微信/WhatsApp 各渠道 image/voice/video/file/transfer/redpacket/system 的 `type` 枚举
|
||
3. **语音通话字段**：`callRecord/queryWeChatVoiceList`、WhatsApp `wavoicecalllist` 的响应结构 + 录音下载
|
||
4. **WhatsApp 联系人**：`businessFriendList` 完整字段
|
||
5. **登录自动化**：`getSecureKey`/`pcLogin` 请求响应（密码加密方式）
|
||
6. **群成员昵称**：`memberIds` 给的是 wxid，群内显示名/头像是否需另调接口
|
||
7. **限速/反爬阈值**：高频请求风控观察
|