# 通话数据接口

<cite>
**本文引用的文件**   
- [CallRecordController.java](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallRecordController.java)
- [CallNightController.java](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallNightController.java)
- [CallContinuousController.java](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallContinuousController.java)
- [CallSensitiveController.java](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallSensitiveController.java)
- [CallRecordService.java](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallRecordService.java)
- [CallNightService.java](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallNightService.java)
- [CallContinuousService.java](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallContinuousService.java)
- [CallSensitiveService.java](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallSensitiveService.java)
- [CallRecordMapper.java](file://ai-server/src/main/java/com/zsjz/ai/module/call/mapper/CallRecordMapper.java)
- [CallNightMapper.java](file://ai-server/src/main/java/com/zsjz/ai/module/call/mapper/CallNightMapper.java)
- [CallContinuousMapper.java](file://ai-server/src/main/java/com/zsjz/ai/module/call/mapper/CallContinuousMapper.java)
- [CallSensitiveMapper.java](file://ai-server/src/main/java/com/zsjz/ai/module/call/mapper/CallSensitiveMapper.java)
- [CallRecordQuery.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/query/CallRecordQuery.java)
- [CallNightQuery.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/query/CallNightQuery.java)
- [CallContinuousQuery.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/query/CallContinuousQuery.java)
- [CallSensitiveQuery.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/query/CallSensitiveQuery.java)
- [CallRecord.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/entity/CallRecord.java)
- [CallNightDTO.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/dto/CallNightDTO.java)
- [CallContinuousDTO.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/dto/CallContinuousDTO.java)
- [CallSensitiveDTO.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/dto/CallSensitiveDTO.java)
</cite>

## 目录
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](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallRecordController.java#L1-L38)
- [CallNightController.java:1-53](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallNightController.java#L1-L53)
- [CallContinuousController.java:1-51](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallContinuousController.java#L1-L51)
- [CallSensitiveController.java:1-52](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallSensitiveController.java#L1-L52)

## 调用模型与通用规则

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

### 统一查询基类
查询参数类继承通用 `Query` 基类，因此通常支持以下通用分页字段：
- `page`：页码
- `limit`：每页条数

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

### 动态表名
所有通话相关查询都会通过 `GovernConfService.getCallTableName()` 设置动态表名。这意味着：
- 表名不是固定写死在接口中；
- 实际数据可能来自不同案件或不同数据源；
- 如果配置缺失或表名无效，可能出现空结果或数据库异常。

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

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

**图示来源**
- [CallRecordService.java:1-39](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallRecordService.java#L1-L39)
- [CallNightService.java:1-61](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallNightService.java#L1-L61)
- [CallContinuousService.java:1-58](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallContinuousService.java#L1-L58)
- [CallSensitiveService.java:1-58](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallSensitiveService.java#L1-L58)

**章节来源**
- [CallRecordService.java:24-38](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallRecordService.java#L24-L38)
- [CallNightService.java:33-60](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallNightService.java#L33-L60)
- [CallContinuousService.java:33-57](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallContinuousService.java#L33-L57)
- [CallSensitiveService.java:33-57](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallSensitiveService.java#L33-L57)

## 通话记录查询接口

### 接口定义
- 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](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallRecordController.java#L22-L37)
- [CallRecordService.java:24-38](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallRecordService.java#L24-L38)
- [CallRecordQuery.java:10-92](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/query/CallRecordQuery.java#L10-L92)
- [CallRecord.java:28-198](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/entity/CallRecord.java#L28-L198)

## 夜间通话统计接口

### 第一层：按时间段汇总
- 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](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallNightController.java#L26-L52)
- [CallNightService.java:33-60](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallNightService.java#L33-L60)
- [CallNightQuery.java:8-16](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/query/CallNightQuery.java#L8-L16)
- [CallNightDTO.java:10-56](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/dto/CallNightDTO.java#L10-L56)

## 连续通话统计接口

### 第一层：按本人号码与对方姓名汇总
- 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](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallContinuousController.java#L25-L50)
- [CallContinuousService.java:33-57](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallContinuousService.java#L33-L57)
- [CallContinuousQuery.java:8-24](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/query/CallContinuousQuery.java#L8-L24)
- [CallContinuousDTO.java:4-36](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/dto/CallContinuousDTO.java#L4-L36)

## 敏感通话统计接口

### 第一层：按对方姓名与对方号码汇总
- 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](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallSensitiveController.java#L25-L51)
- [CallSensitiveService.java:33-57](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallSensitiveService.java#L33-L57)
- [CallSensitiveQuery.java:8-22](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/query/CallSensitiveQuery.java#L8-L22)
- [CallSensitiveDTO.java:8-29](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/dto/CallSensitiveDTO.java#L8-L29)
- [CallRecord.java:28-198](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/entity/CallRecord.java#L28-L198)

## 调查场景中的用途

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

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

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

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

### 连续通话
适用于发现长期稳定联系关系。

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

### 敏感通话
适用于风险预警和重点对象筛查。

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

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

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

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

### 与治理树
- 通话数据表名通过治理配置服务动态获取，说明通话数据属于治理体系下的数据资源。
- 治理树或治理配置决定当前查询使用哪张通话数据表，从而把通话数据纳入案件、数据源或组织维度的治理边界。

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

**图示来源**
- [CallRecord.java:28-198](file://ai-server/src/main/java/com/zsjz/ai/common/model/call/entity/CallRecord.java#L28-L198)
- [CallNightService.java:33-60](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallNightService.java#L33-L60)
- [CallContinuousService.java:33-57](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallContinuousService.java#L33-L57)
- [CallSensitiveService.java:33-57](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallSensitiveService.java#L33-L57)

## 典型查询示例

### 示例一：查询某人某段时间内的通话记录
- 接口：`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](file://ai-server/src/main/java/com/zsjz/ai/module/call/mapper/CallRecordMapper.java#L33-L91)
- [CallNightController.java:35-52](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallNightController.java#L35-L52)
- [CallContinuousController.java:33-50](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallContinuousController.java#L33-L50)
- [CallSensitiveController.java:33-51](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallSensitiveController.java#L33-L51)

## 常见问题排查

### 问题一：返回结果为空
可能原因：
- 时间范围过大但数据表中无匹配记录。
- 号码为空或未正确传入。
- 动态表名未配置或指向错误表。
- 人员姓名列表为空且系统中无可用人员名单。

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

### 问题二：时间范围过大导致查询缓慢
可能原因：
- 全表扫描或大范围聚合。
- 多字段分组统计。

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

### 问题三：对方号码显示为“未知号码”
可能原因：
- 数据清洗或来源侧未解析出对方号码。
- 查询时对方号码列表包含“未知号码”，会被转换为单个“未知号码”过滤。

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

### 问题四：夜间通话或连续通话人员范围太大
可能原因：
- 未传入 `personNames`，服务层自动填充全部人员。

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

### 问题五：敏感通话结果与实际不符
可能原因：
- “敏感”的定义由后端逻辑决定，不一定只依赖号码或姓名。
- 第一层是汇总，第二层才是明细。

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

## 架构图

```mermaid
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](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallRecordController.java#L22-L37)
- [CallNightController.java:26-52](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallNightController.java#L26-L52)
- [CallContinuousController.java:25-50](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallContinuousController.java#L25-L50)
- [CallSensitiveController.java:25-51](file://ai-server/src/main/java/com/zsjz/ai/module/call/controller/CallSensitiveController.java#L25-L51)
- [CallRecordService.java:24-38](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallRecordService.java#L24-L38)
- [CallNightService.java:33-60](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallNightService.java#L33-L60)
- [CallContinuousService.java:33-57](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallContinuousService.java#L33-L57)
- [CallSensitiveService.java:33-57](file://ai-server/src/main/java/com/zsjz/ai/module/call/service/CallSensitiveService.java#L33-L57)
- [CallRecordMapper.java:33-91](file://ai-server/src/main/java/com/zsjz/ai/module/call/mapper/CallRecordMapper.java#L33-L91)
- [CallNightMapper.java:23-40](file://ai-server/src/main/java/com/zsjz/ai/module/call/mapper/CallNightMapper.java#L23-L40)
- [CallContinuousMapper.java:23-39](file://ai-server/src/main/java/com/zsjz/ai/module/call/mapper/CallContinuousMapper.java#L23-L39)
- [CallSensitiveMapper.java:23-40](file://ai-server/src/main/java/com/zsjz/ai/module/call/mapper/CallSensitiveMapper.java#L23-L40)