zsjz-ai/.qoder/repowiki/zh/content/API 接口参考/通话数据接口.md

通话数据接口

本文引用的文件

• CallRecordController.java
• CallNightController.java
• CallContinuousController.java
• CallSensitiveController.java
• CallRecordService.java
• CallNightService.java
• CallContinuousService.java
• CallSensitiveService.java
• CallRecordMapper.java
• CallNightMapper.java
• CallContinuousMapper.java
• CallSensitiveMapper.java
• CallRecordQuery.java
• CallNightQuery.java
• CallContinuousQuery.java
• CallSensitiveQuery.java
• CallRecord.java
• CallNightDTO.java
• CallContinuousDTO.java
• CallSensitiveDTO.java

目录

1. 文档目标与适用范围
2. 接口总览
3. 调用模型与通用规则
4. 通话记录查询接口
5. 夜间通话统计接口
6. 连续通话统计接口
7. 敏感通话统计接口
8. 调查场景中的用途
9. 与人员、轨迹、治理树的关联关系
10. 典型查询示例
11. 分页、排序与性能说明
12. 常见问题排查
13. 架构图

文档目标与适用范围

本文面向后端接口使用者、前端对接人员和调查分析人员，说明以下四类通话数据接口的请求参数、响应字段、分页方式及在调查工作中的使用方式：

• 通话记录查询
• 夜间通话统计
• 连续通话统计
• 敏感通话统计

这些接口统一通过控制器暴露 HTTP 端点，服务层负责动态表名、默认查询条件和业务预处理，数据访问层通过 MyBatis Mapper 执行数据库查询。

接口总览

模块	控制器	基础路径	主要接口	返回类型
通话记录	CallRecordController	/cr	POST /cr/getCallRecord	分页通话记录
夜间通话	CallNightController	/call/night	POST /call/night/statFirstCallNight	分页夜间汇总
夜间通话	CallNightController	/call/night	POST /call/night/statSecondCallNight	夜间明细汇总
连续通话	CallContinuousController	/call/continuous	POST /call/continuous/statFirstCallContinuous	分页连续汇总
连续通话	CallContinuousController	/call/continuous	POST /call/continuous/statSecondCallContinuous	分页详细连续汇总
敏感通话	CallSensitiveController	/call/sensitive	POST /call/sensitive/statFirstCallSensitive	分页敏感汇总
敏感通话	CallSensitiveController	/call/sensitive	POST /call/sensitive/statSecondCallSensitive	分页敏感明细

所有接口均使用 POST 方法，请求体为 JSON，统一由后端封装为 Result 对象返回。

章节来源

• CallRecordController.java:1-38
• CallNightController.java:1-53
• CallContinuousController.java:1-51
• CallSensitiveController.java:1-52

调用模型与通用规则

统一返回结构

后端控制器将业务结果包装为 Result，其中包含成功标志、数据和错误信息。调用方应优先判断整体是否成功，再读取具体数据字段。

统一查询基类

查询参数类继承通用 Query 基类，因此通常支持以下通用分页字段：

• page：页码
• limit：每页条数

实际分页实现依赖各 Controller 和服务层构造的 MyBatis-Plus Page 对象。

动态表名

所有通话相关查询都会通过 GovernConfService.getCallTableName() 设置动态表名。这意味着：

• 表名不是固定写死在接口中；
• 实际数据可能来自不同案件或不同数据源；
• 如果配置缺失或表名无效，可能出现空结果或数据库异常。

默认人员范围

夜间通话、连续通话和敏感通话的服务层会在未提供人员姓名列表时，自动填充系统已知人员姓名集合。这样可以在不指定具体人员的情况下进行全局扫描。

flowchart TD
    Client["调用方"] --> Controller["通话数据控制器"]
    Controller --> Service["通话数据服务层"]
    Service --> Config["治理配置服务<br/>获取通话表名"]
    Service --> Person["人员基本信息服务<br/>获取人员姓名列表"]
    Service --> Mapper["MyBatis Mapper"]
    Mapper --> Database["通话数据表"]

图示来源

• CallRecordService.java:1-39
• CallNightService.java:1-61
• CallContinuousService.java:1-58
• CallSensitiveService.java:1-58

章节来源

• CallRecordService.java:24-38
• CallNightService.java:33-60
• CallContinuousService.java:33-57
• CallSensitiveService.java:33-57

通话记录查询接口

接口定义

• HTTP 方法：POST
• URL：/cr/getCallRecord
• 请求体：CallRecordQuery
• 返回：分页的 CallRecord

请求参数

字段	类型	必填	含义
id	Long	否	单条通话记录主键
ids	List<Long>	否	多条通话记录主键列表
fileId	Long	否	关联文件标识
sheetId	Long	否	关联工作表标识
personPhones	List<String>	否	本方号码列表
operatorId	String	否	运营商
personPhoneArea	String	否	本方号码归属地
personCertNo	String	否	本方证件号码
personRegionId	String	否	本方基站大区号
personCellId	String	否	本方基站小区号
duration	Integer	否	通话时长
callDirection	String	否	主被叫标识
callType	String	否	通话类型
otherName	String	否	对方户名
otherPhones	List<String>	否	对方号码列表
otherPhone	String	否	单个对方号码
startTime	String	否	开始时间
endTime	String	否	结束时间
symbol	String	否	比较符号，默认值为“ge”
page	Long	否	页码
limit	Long	否	每页大小

特殊处理逻辑

• 比较符号为空时，默认使用“ge”。
• 如果对方号码列表中包含“未知号码”，会清空列表并改为按单个“未知号码”过滤。
• 表名由治理配置服务动态注入。

响应字段

字段	类型	含义
personName	String	本方姓名
personPhone	String	本方号码
operatorId	String	运营商
personPhoneArea	String	本方号码归属地
personCertNo	String	本方证件号码
personRegionId	String	本方基站大区号
personCellId	String	本方基站小区号
personStationName	String	本方基站名称
personStationLongitude	String	本方基站经度
personStationLatitude	String	本方基站纬度
callDateTime	LocalDateTime	通话日期时间
callDate	LocalDate	通话日期
callTime	LocalTime	通话时间
duration	Integer	通话时长
callDirection	String	主被叫标识
callType	String	通话类型
otherName	String	对方户名
otherPhone	String	对方号码
otherPhoneArea	String	对方号码归属地
otherCertNo	String	对方证件号码
remark	String	备注
personLibId	String	关联人卡库
callLocal	String	本地通话标识

章节来源

• CallRecordController.java:22-37
• CallRecordService.java:24-38
• CallRecordQuery.java:10-92
• CallRecord.java:28-198

夜间通话统计接口

第一层：按时间段汇总

• HTTP 方法：POST
• URL：/call/night/statFirstCallNight
• 请求体：CallNightQuery
• 返回：分页的 CallNightDTO

该接口用于按时间段汇总夜间通话次数，适合先做宏观分析，例如查看某人在哪些夜间时段频繁通话。

请求参数

字段	类型	必填	含义
nightStart	Integer	否	夜间起始小时
nightEnd	Integer	否	夜间结束小时
monthVal	Integer	否	月份阈值
otherName	String	否	对方姓名
otherPhone	String	否	对方号码
personNames	List<String>	否	人员姓名列表；为空时自动填充全部人员
page	Long	否	页码
limit	Long	否	每页大小

响应字段

字段	类型	含义
time	String	时间段标识，如“22:00-23:00”
otherName	String	对方姓名
personName	String	本方姓名
otherPhone	String	对方号码集合
callCount	Integer	通话总次数
totalMonthCount	Integer	跨越的月份总数
startHour	String	起始小时
endHour	String	结束小时
ids	String	关联标识集合

第二层：夜间通话详情

• HTTP 方法：POST
• URL：/call/night/statSecondCallNight
• 请求体：CallNightQuery
• 返回：List<CallNightDTO>

该接口不再分页，返回更详细的夜间通话统计信息，适合在第一层筛选后进一步展开。

章节来源

• CallNightController.java:26-52
• CallNightService.java:33-60
• CallNightQuery.java:8-16
• CallNightDTO.java:10-56

连续通话统计接口

第一层：按本人号码与对方姓名汇总

• HTTP 方法：POST
• URL：/call/continuous/statFirstCallContinuous
• 请求体：CallContinuousQuery
• 返回：分页的 CallContinuousDTO

该接口用于识别长期持续联系的对象，适合发现稳定联系人。

请求参数

字段	类型	必填	含义
monthVal	Integer	否	连续月份阈值
otherName	String	否	对方姓名
otherPhone	String	否	对方号码
personNames	List<String>	否	人员姓名列表；为空时自动填充全部人员
page	Long	否	页码
limit	Long	否	每页大小

响应字段

字段	类型	含义
personName	String	本方姓名
personPhone	String	本方手机号
otherPhone	String	合并后的对方手机号
otherPhones	String	对方号码集合
otherName	String	对方姓名
pairContMonthCount	Integer	持续月份
pairTotalCalls	Integer	通话总次数
continuousStartMonth	String	连续通话开始月份
continuousEndMonth	String	连续通话结束月份

第二层：按本人号码、对方姓名与对方号码细化

• HTTP 方法：POST
• URL：/call/continuous/statSecondCallContinuous
• 请求体：CallContinuousQuery
• 返回：分页的 CallContinuousDTO

该层级进一步区分具体对方号码，适合从“稳定联系人”下钻到具体号码组合。

章节来源

• CallContinuousController.java:25-50
• CallContinuousService.java:33-57
• CallContinuousQuery.java:8-24
• CallContinuousDTO.java:4-36

敏感通话统计接口

第一层：按对方姓名与对方号码汇总

• HTTP 方法：POST
• URL：/call/sensitive/statFirstCallSensitive
• 请求体：CallSensitiveQuery
• 返回：分页的 CallSensitiveDTO

该接口用于发现高风险或重点关注的通话对象。

请求参数

字段	类型	必填	含义
otherPhone	String	否	对方号码
otherName	String	否	对方姓名
personNames	List<String>	否	人员姓名列表；为空时自动填充全部人员
page	Long	否	页码
limit	Long	否	每页大小

响应字段

字段	类型	含义
personName	String	本方姓名
otherName	String	对方姓名
otherPhone	String	对方号码
callCount	Integer	通话次数

第二层：敏感通话明细

• HTTP 方法：POST
• URL：/call/sensitive/statSecondCallSensitive
• 请求体：CallSensitiveQuery
• 返回：分页的 CallRecord

该接口直接返回敏感通话的具体记录，便于结合时间、地点、主被叫方向等字段进行核查。

章节来源

• CallSensitiveController.java:25-51
• CallSensitiveService.java:33-57
• CallSensitiveQuery.java:8-22
• CallSensitiveDTO.java:8-29
• CallRecord.java:28-198

调查场景中的用途

通话记录查询

适用于原始数据核对、证据调取、线索交叉验证。可基于号码、时间范围、主被叫方向、通话类型、基站信息等条件检索。

典型用途：

• 根据案件时间范围拉取目标号码的完整通话清单。
• 根据对方号码反查与本方号码的通话情况。
• 结合基站信息辅助定位通话发生区域。

夜间通话

适用于分析作息异常、隐蔽联络、非工作时间活动。

典型用途：

• 查找在深夜或凌晨频繁通话的人员。
• 按时间段观察夜间通话趋势。
• 锁定夜间高频联系人。

连续通话

适用于发现长期稳定联系关系。

典型用途：

• 找出跨月持续通话的对象。
• 分析联系持续时间跨度。
• 从稳定联系人进一步定位具体号码组合。

敏感通话

适用于风险预警和重点对象筛查。

典型用途：

• 快速发现高风险联系人。
• 对敏感联系人进行通话频次统计。
• 下钻查看具体敏感通话明细。

与人员、轨迹、治理树的关联关系

与人员

• 通话记录包含本方姓名、本方号码、本方证件号码、对方姓名、对方号码等信息。
• 夜间通话、连续通话、敏感通话在查询时可传入人员姓名列表；若为空，服务层会从人员基本信息服务中获取全部人员。
• 敏感通话和连续通话的第一层结果都带有本方姓名和对方姓名，便于与人员档案关联。

与轨迹

• 通话记录包含本方基站大区号、小区号、基站名称、经度、纬度等字段。
• 这些字段可与基站轨迹、位置轨迹联合分析，辅助还原通话发生时的大致位置。
• 夜间通话和连续通话虽然以汇总为主，但其底层仍来源于通话记录，可通过明细接口或原始通话记录接口联动轨迹数据。

与治理树

• 通话数据表名通过治理配置服务动态获取，说明通话数据属于治理体系下的数据资源。

• 治理树或治理配置决定当前查询使用哪张通话数据表，从而把通话数据纳入案件、数据源或组织维度的治理边界。

  graph TB
  CallRecord["通话记录"] --> Person["人员档案"]
  CallRecord --> Track["轨迹数据"]
  CallRecord --> Governance["治理配置<br/>治理树与数据表映射"]
  NightCall["夜间通话"] --> CallRecord
  ContinuousCall["连续通话"] --> CallRecord
  SensitiveCall["敏感通话"] --> CallRecord
  

图示来源

• CallRecord.java:28-198
• CallNightService.java:33-60
• CallContinuousService.java:33-57
• CallSensitiveService.java:33-57

典型查询示例

示例一：查询某人某段时间内的通话记录

• 接口：POST /cr/getCallRecord
• 建议参数：
  • personPhones：目标本方号码
  • startTime：开始时间
  • endTime：结束时间
  • page：1
  • limit：100

适用场景：案件时间范围内拉取目标号码通话清单。

示例二：查询夜间通话汇总

• 接口：POST /call/night/statFirstCallNight
• 建议参数：
  • nightStart：22
  • nightEnd：6
  • personNames：目标人员姓名列表
  • page：1
  • limit：50

适用场景：分析目标人员在夜间的时间段分布。

示例三：查看连续通话的长期联系人

• 接口：POST /call/continuous/statFirstCallContinuous
• 建议参数：
  • monthVal：大于等于期望的连续月数
  • personNames：目标人员姓名列表

适用场景：识别稳定联系人。

示例四：查看敏感通话明细

• 接口：POST /call/sensitive/statSecondCallSensitive
• 建议参数：
  • otherPhone：可疑对方号码
  • personNames：目标人员姓名列表
  • page：1
  • limit：200

适用场景：对敏感联系人进行逐条核查。

分页、排序与性能说明

分页

• 通话记录、夜间通话、连续通话、敏感通话的分页接口均通过 MyBatis-Plus Page 传递页码和每页大小。
• 第一层汇总接口通常返回分页结果，适合列表展示。
• 夜间通话第二层详情接口返回普通列表，不分页。
• 敏感通话第二层明细接口返回分页通话记录，适合大数据量明细浏览。

排序

• 当前控制器和服务层没有显式设置默认排序字段。
• 最终排序行为取决于对应 Mapper 的 SQL 实现。
• 如需稳定排序，建议在调用前确认后端 SQL 是否已按时间、通话次数或其他关键字段排序。

性能特征

• 通话记录 Mapper 提供流式查询能力，适合大数据量导出或遍历。
• 其他分析接口多为聚合查询，受数据量和分组维度影响较大。
• 建议：
  • 尽量缩小时间范围。
  • 先使用第一层汇总接口筛选，再进入第二层明细。
  • 控制每页大小，避免单次返回过多数据。

章节来源

• CallRecordMapper.java:33-91
• CallNightController.java:35-52
• CallContinuousController.java:33-50
• CallSensitiveController.java:33-51

常见问题排查

问题一：返回结果为空

可能原因：

• 时间范围过大但数据表中无匹配记录。
• 号码为空或未正确传入。
• 动态表名未配置或指向错误表。
• 人员姓名列表为空且系统中无可用人员名单。

排查建议：

1. 检查 personPhones、otherPhone、otherName 是否为空。
2. 缩小时间范围，先确认是否有任意通话记录。
3. 检查治理配置中通话表名是否正确。
4. 对夜间、连续、敏感接口，确认是否传入了有效人员姓名。

问题二：时间范围过大导致查询缓慢

可能原因：

• 全表扫描或大范围聚合。
• 多字段分组统计。

排查建议：

1. 先按年或月缩小时间范围。
2. 先用汇总接口，再进入明细接口。
3. 增加号码或人员限制，减少分组维度。

问题三：对方号码显示为“未知号码”

可能原因：

• 数据清洗或来源侧未解析出对方号码。
• 查询时对方号码列表包含“未知号码”，会被转换为单个“未知号码”过滤。

排查建议：

1. 使用通话记录接口查看原始 otherPhone 字段。
2. 检查上游数据清洗结果。
3. 明确是否需要保留“未知号码”这一分类。

问题四：夜间通话或连续通话人员范围太大

可能原因：

• 未传入 personNames，服务层自动填充全部人员。

排查建议：

1. 明确传入目标人员姓名列表。
2. 结合案件范围限定人员，避免全量扫描。

问题五：敏感通话结果与实际不符

可能原因：

• “敏感”的定义由后端逻辑决定，不一定只依赖号码或姓名。
• 第一层是汇总，第二层才是明细。

排查建议：

1. 使用第二层接口查看具体通话明细。
2. 结合时间、主被叫方向、通话类型、基站信息进行人工复核。

架构图

classDiagram
    class CallRecordController {
        +getCallRecord(query) Result
    }
    class CallNightController {
        +statFirstCallNight(query) Result
        +statSecondCallNight(query) Result
    }
    class CallContinuousController {
        +statFirstCallContinuous(query) Result
        +statSecondCallContinuous(query) Result
    }
    class CallSensitiveController {
        +statFirstCallSensitive(query) Result
        +statSecondCallSensitive(query) Result
    }

    class CallRecordService {
        +getCallRecord(query) Page
    }
    class CallNightService {
        +statFirstCallNight(query) Page
        +statSecondCallNight(query) List
    }
    class CallContinuousService {
        +statFirstCallContinuous(query) Page
        +statSecondCallContinuous(query) Page
    }
    class CallSensitiveService {
        +statFirstCallSensitive(query) Page
        +statSecondCallSensitive(query) Page
    }

    class CallRecordMapper {
        +selectCallRecordPage(page, query) Page
    }
    class CallNightMapper {
        +statFirstCallNight(page, query) Page
        +statSecondCallNight(query) List
    }
    class CallContinuousMapper {
        +statFirstCallContinuous(page, query) Page
        +statSecondCallContinuous(page, query) Page
    }
    class CallSensitiveMapper {
        +statFirstCallSensitive(page, query) Page
        +statSecondCallSensitive(page, query) Page
    }

    CallRecordController --> CallRecordService : "调用"
    CallNightController --> CallNightService : "调用"
    CallContinuousController --> CallContinuousService : "调用"
    CallSensitiveController --> CallSensitiveService : "调用"

    CallRecordService --> CallRecordMapper : "查询"
    CallNightService --> CallNightMapper : "查询"
    CallContinuousService --> CallContinuousMapper : "查询"
    CallSensitiveService --> CallSensitiveMapper : "查询"

图示来源

• CallRecordController.java:22-37
• CallNightController.java:26-52
• CallContinuousController.java:25-50
• CallSensitiveController.java:25-51
• CallRecordService.java:24-38
• CallNightService.java:33-60
• CallContinuousService.java:33-57
• CallSensitiveService.java:33-57
• CallRecordMapper.java:33-91
• CallNightMapper.java:23-40
• CallContinuousMapper.java:23-39
• CallSensitiveMapper.java:23-40