xinyouhe/yunke
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
yunke/docs/superpowers/specs/2026-08-01-yunke-data-dictionary.md
T
浅念 cd8d36fd00 docs: initial design spec, data dictionary, implementation plan 
Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-01 10:53:28 +08:00

10 KiB
Raw Permalink Blame History

云客 CRM 数据字典（全系统扫描结果）

  • 日期：2026-08-01
  • 来源：登录云客 CRM（crm2.yunkecn.com）实地抓包，覆盖全部模块
  • 状态标记：✅ 已确认字段 ｜ ⏳ 接口已找到，字段待 Phase 0 ｜ 🔭 仅知入口

本文档是设计文档的配套数据字典，列出系统中所有数据实体及其接口、字段、规模、抓取优先级。

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. 限速/反爬阈值：高频请求风控观察
Reference in New Issue View Git Blame Copy Permalink