# 轨迹数据接口

<cite>
**本文引用的文件**   
- [TrackTogetherTravelController.java](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackTogetherTravelController.java)
- [TrackTogetherLiveController.java](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackTogetherLiveController.java)
- [TrackMeetController.java](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackMeetController.java)
- [TrackEnLocalController.java](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackEnLocalController.java)
- [TrackCellTowerController.java](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackCellTowerController.java)
- [ExpressInfoController.java](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/ExpressInfoController.java)
- [Query.java](file://ai-server/src/main/java/com/zsjz/ai/common/base/Query.java)
- [Result.java](file://ai-server/src/main/java/com/zsjz/ai/common/config/Result.java)
- [TrackTogetherTravelQuery.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/query/TrackTogetherTravelQuery.java)
- [TrackTogetherLiveQuery.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/query/TrackTogetherLiveQuery.java)
- [TogetherLiveDetailQuery.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/query/TogetherLiveDetailQuery.java)
- [TrackMeetQuery.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/query/TrackMeetQuery.java)
- [TrackEnLocalQuery.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/query/TrackEnLocalQuery.java)
- [TrackCellTowerQuery.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/query/TrackCellTowerQuery.java)
- [ExpressInfoQuery.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/query/ExpressInfoQuery.java)
- [TravelTimelineDTO.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TravelTimelineDTO.java)
- [TravelRecordDTO.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TravelRecordDTO.java)
- [TrackPersonTogetherLiveDTO.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TrackPersonTogetherLiveDTO.java)
- [TogetherLiveDTO.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TogetherLiveDTO.java)
- [HotelStayInfo.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/entity/HotelStayInfo.java)
- [TogetherLiveInfo.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/entity/TogetherLiveInfo.java)
- [TrackMeetSummeryDTO.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TrackMeetSummeryDTO.java)
- [TrackMeetDTO.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TrackMeetDTO.java)
- [TrackEnLocalDTO.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TrackEnLocalDTO.java)
- [TrackCellTowerDTO.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TrackCellTowerDTO.java)
- [TrackCellTowerSecondDTO.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TrackCellTowerSecondDTO.java)
- [ExpressDTO.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/ExpressDTO.java)
- [ExpressInfo.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/entity/ExpressInfo.java)
</cite>

## 目录
1. [文档目标与适用范围](#文档目标与适用范围)
2. [系统边界与调用约定](#系统边界与调用约定)
3. [控制器总览](#控制器总览)
4. [通用查询与分页模型](#通用查询与分页模型)
5. [同行轨迹接口](#同行轨迹接口)
6. [同住轨迹接口](#同住轨迹接口)
7. [见面轨迹接口](#见面轨迹接口)
8. [本地活动轨迹接口](#本地活动轨迹接口)
9. [基站轨迹接口](#基站轨迹接口)
10. [快递信息接口](#快递信息接口)
11. [人员关联与时空调查支持](#人员关联与时空调查支持)
12. [按人员或时间范围查询示例](#按人员或时间范围查询示例)
13. [错误码与响应结构](#错误码与响应结构)
14. [数据缺失、坐标无效、时间异常排查指南](#数据缺失坐标无效时间异常排查指南)
15. [性能与使用建议](#性能与使用建议)
16. [结论](#结论)

## 文档目标与适用范围
本文件面向后端接口使用者、前端开发者和数据分析人员，说明轨迹数据接口的用途、参数、返回结构、分页方式和常见排错方法。覆盖以下六类轨迹能力：
- 同行：统计两人或多人的出行同行关系。
- 同住：统计旅馆住宿和同住服务中的同住关系。
- 见面：基于基站区域和时间窗口分析人员碰面。
- 同城/本地活动：统计境外人员在本地活动轨迹。
- 基站：按基站、LAC、CID 统计通信轨迹。
- 快递：按收件人、寄件人、地址等维度统计快递收发轨迹。

这些接口主要服务于人员关联分析和时空调查：通过“谁在什么时间出现在哪里”“谁和谁在一起”两条线索，串联人员、通话、交易和治理树等业务对象，形成可追溯的时空证据链。

## 系统边界与调用约定
- 所有轨迹控制器均位于 `com.zsjz.ai.module.track.controller` 包下。
- 请求统一使用 `POST`，请求体为 JSON。
- 返回值统一封装在 `Result<T>` 中。
- 分页接口返回 MyBatis-Plus 的 `Page<T>` 类型；非分页接口返回列表、映射或具体 DTO。
- 查询条件大多继承自通用基类 `Query`，因此分页、排序、日期范围等字段可复用。

```mermaid
graph TB
    Client["客户端"] --> Gateway["网关或业务入口"]
    Gateway --> TogetherTravel["同行控制器<br/>/track/togetherTravel"]
    Gateway --> TogetherLive["同住控制器<br/>/track/togetherLive"]
    Gateway --> Meet["见面控制器<br/>/track/meet"]
    Gateway --> EnLocal["本地活动控制器<br/>/track/enLocal"]
    Gateway --> CellTower["基站控制器<br/>/track/cellTower"]
    Gateway --> Express["快递控制器<br/>/expressInfo"]
```

**图表来源**
- [TrackTogetherTravelController.java:1-48](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackTogetherTravelController.java#L1-L48)
- [TrackTogetherLiveController.java:1-70](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackTogetherLiveController.java#L1-L70)
- [TrackMeetController.java:1-50](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackMeetController.java#L1-L50)
- [TrackEnLocalController.java:1-46](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackEnLocalController.java#L1-L46)
- [TrackCellTowerController.java:1-49](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackCellTowerController.java#L1-L49)
- [ExpressInfoController.java:1-49](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/ExpressInfoController.java#L1-L49)

## 控制器总览

| 控制器 | 基础路径 | 主要职责 | 是否分页 |
|---|---|---|---|
| 同行轨迹控制器 | `/track/togetherTravel` | 统计同行旅行时间线、二次记录、三次同行 | 否 |
| 同住轨迹控制器 | `/track/togetherLive` | 首次同住统计、二次同住详情、旅馆住宿详情、同住服务详情 | 是（详情接口） |
| 见面轨迹控制器 | `/track/meet` | 首次碰面汇总、二次碰面明细 | 否 |
| 本地活动轨迹控制器 | `/track/enLocal` | 首次本地活动分组统计、二次明细 | 是（二次明细） |
| 基站轨迹控制器 | `/track/cellTower` | 首次基站轨迹统计、二次基站轨迹统计 | 是 |
| 快递信息控制器 | `/expressInfo` | 一级聚合统计、二级明细统计 | 是 |

**章节来源**
- [TrackTogetherTravelController.java:1-48](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackTogetherTravelController.java#L1-L48)
- [TrackTogetherLiveController.java:1-70](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackTogetherLiveController.java#L1-L70)
- [TrackMeetController.java:1-50](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackMeetController.java#L1-L50)
- [TrackEnLocalController.java:1-46](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackEnLocalController.java#L1-L46)
- [TrackCellTowerController.java:1-49](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackCellTowerController.java#L1-L49)
- [ExpressInfoController.java:1-49](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/ExpressInfoController.java#L1-L49)

## 通用查询与分页模型
所有轨迹查询条件大多继承 `Query`，因此以下字段通常可用：

| 字段 | 类型 | 含义 | 默认值或说明 |
|---|---|---|---|
| `page` | `long` | 当前页码 | 默认 `1` |
| `limit` | `long` | 每页条数 | 默认 `20` |
| `startDate` | `LocalDate` | 开始日期 | 用于按日期范围过滤 |
| `endDate` | `LocalDate` | 结束日期 | 用于按日期范围过滤 |
| `orderKey` | `String` | 排序字段 | 仅写入，不参与序列化 |
| `sort` | `String` | 排序方式 | 默认升序 |
| `tableName` | `String` | 表名 | 不参与 JSON 序列化 |
| `personName` | `String` | 本方姓名 | 常用于以被调查对象为中心筛选 |
| `personNames` | `List<String>` | 本方姓名列表 | 多人员筛选 |
| `keyword` | `String` | 关键词搜索 | 仅写入，不参与序列化 |

**章节来源**
- [Query.java:1-86](file://ai-server/src/main/java/com/zsjz/ai/common/base/Query.java#L1-L86)

## 同行轨迹接口

### 统计同行时间线
- **HTTP 方法**：`POST`
- **URL**：`/track/togetherTravel/statTogetherTravel`
- **请求体**：`TrackTogetherTravelQuery`
- **返回**：`Result<List<TravelTimelineDTO>>`

#### 请求字段
| 字段 | 类型 | 必填 | 含义 |
|---|---|---:|---|
| `personCertNos` | `List<String>` | 否 | 多人身份证号集合 |
| `personCertNo` | `String` | 否 | 单人身份证号 |
| `ids` | `List<String>` | 否 | 数据 ID 列表 |
| `type` | `String` | 否 | 同行类型标识 |
| `id` | `String` | 否 | 单条数据 ID |

#### 返回字段
| 字段 | 类型 | 含义 |
|---|---|---|
| `personName` | `String` | 被调查对象姓名 |
| `companionName` | `String` | 同行人姓名 |
| `count` | `Integer` | 同行次数 |
| `idList` | `List<String>` | 关联详细记录的 ID 列表 |

#### 适用场景
- 快速查看两名人员之间的同行频率。
- 通过 `idList` 进一步拉取同行明细，用于时间线可视化。

**章节来源**
- [TrackTogetherTravelController.java:1-48](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackTogetherTravelController.java#L1-L48)
- [TrackTogetherTravelQuery.java:1-27](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/query/TrackTogetherTravelQuery.java#L1-L27)
- [TravelTimelineDTO.java:1-56](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TravelTimelineDTO.java#L1-L56)

### 统计二次同行记录
- **HTTP 方法**：`POST`
- **URL**：`/track/togetherTravel/statSecondTogetherTravel`
- **请求体**：`TrackTogetherTravelQuery`
- **返回**：`Result<List<TravelRecordDTO>>`

#### 返回字段
| 字段 | 类型 | 含义 |
|---|---|---|
| `tripDate` | `String` | 出行日期 |
| `data` | `List<TravelDataDTO>` | 该日期的出行数据列表 |

#### 适用场景
- 从时间线切换到按日期展开的具体出行记录。
- 结合人员、通话、交易数据做交叉验证。

**章节来源**
- [TrackTogetherTravelController.java:1-48](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackTogetherTravelController.java#L1-L48)
- [TravelRecordDTO.java:1-26](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TravelRecordDTO.java#L1-L26)

### 统计三次同行
- **HTTP 方法**：`POST`
- **URL**：`/track/togetherTravel/statThreeTogetherTravel`
- **请求体**：`TrackTogetherTravelQuery`
- **返回**：`Result<Object>`

该接口返回泛型对象，主要用于更复杂的三人或多人员同行分析。调用方应根据实际业务上下文解析返回结构。

**章节来源**
- [TrackTogetherTravelController.java:1-48](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackTogetherTravelController.java#L1-L48)

## 同住轨迹接口

### 首次同住统计
- **HTTP 方法**：`POST`
- **URL**：`/track/togetherLive/statFirstTrackTogetherLive`
- **请求体**：`TrackTogetherLiveQuery`
- **返回**：`Result<List<TrackPersonTogetherLiveDTO>>`

#### 请求字段
| 字段 | 类型 | 必填 | 含义 |
|---|---|---:|---|
| `search` | `List<String>` | 否 | 调查对象姓名或身份证号模糊匹配 |
| `ids` | `List<String>` | 否 | 数据 ID 列表 |
| `togHotel` | `String` | 否 | 同住酒店名称 |
| `outCount` | `Integer` | 否 | 同住次数阈值 |
| `outCountSymbol` | `SymbolEnum` | 否 | 比较符号：大于等于或小于等于 |
| `timeGap` | `Integer` | 否 | 同住时间窗口，单位分钟 |
| `personName` | `String` | 否 | 被调查对象名称 |
| `liveWithName` | `String` | 否 | 同住人名称 |
| `liveWithCertNo` | `String` | 否 | 同住人身份证号 |
| `suspectedTogether` | `Integer` | 否 | 疑似同住标记 |
| `hotelName` | `String` | 否 | 旅店名称精确过滤 |
| `hasTogether` | `Integer` | 否 | 同住判定标记 |

#### 返回结构
外层为被调查对象维度的统计结果，内部包含同住人列表。常用字段包括：
- `personCertNo`
- `personName`
- `photograph`
- `list`：`TogetherLiveDTO` 列表

`TogetherLiveDTO` 关键字段：
- `personName`
- `personCertNo`
- `liveWithName`
- `liveWithCertNo`
- `liveCount`
- `hotelName`
- `hasTogether`
- `inDateTime`

其中 `hasTogether` 表示确定同住或疑似同住状态。

**章节来源**
- [TrackTogetherLiveController.java:1-70](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackTogetherLiveController.java#L1-L70)
- [TrackTogetherLiveQuery.java:1-75](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/query/TrackTogetherLiveQuery.java#L1-L75)
- [TrackPersonTogetherLiveDTO.java:1-43](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TrackPersonTogetherLiveDTO.java#L1-L43)
- [TogetherLiveDTO.java:1-118](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TogetherLiveDTO.java#L1-L118)

### 二次同住统计
- **HTTP 方法**：`POST`
- **URL**：`/track/togetherLive/statSecondTrackTogetherLive`
- **请求体**：`TrackTogetherLiveQuery`
- **返回**：`Result<Page<TogetherLiveDTO>>`

返回分页的同住关系视图，适合在前端表格中展示并支持翻页。

**章节来源**
- [TrackTogetherLiveController.java:1-70](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackTogetherLiveController.java#L1-L70)
- [TogetherLiveDTO.java:1-118](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TogetherLiveDTO.java#L1-L118)

### 旅馆住宿详情
- **HTTP 方法**：`POST`
- **URL**：`/track/togetherLive/hotelStayInfoDetail`
- **请求体**：`TogetherLiveDetailQuery`
- **返回**：`Result<Page<HotelStayInfo>>`

#### 请求字段
| 字段 | 类型 | 必填 | 含义 |
|---|---|---:|---|
| `hotelName` | `String` | 否 | 酒店名称 |
| `personName` | `String` | 否 | 被调查对象名称 |
| `personCertNo` | `String` | 否 | 被调查对象身份证号 |
| `liveWithName` | `String` | 否 | 同住人名称 |
| `liveWithCertNo` | `String` | 否 | 同住人身份证号 |
| `search` | `String` | 否 | 旅店名称模糊查询 |
| `inStartTime` | `LocalDateTime` | 否 | 入住开始时间 |
| `inEndTime` | `LocalDateTime` | 否 | 入住结束时间 |
| `outStartTime` | `LocalDateTime` | 否 | 退房开始时间 |
| `outEndTime` | `LocalDateTime` | 否 | 退房结束时间 |
| `timeGap` | `Integer` | 否 | 疑似同住时间窗口，单位小时 |
| `hasTogether` | `Integer` | 否 | 疑似同住标记 |

#### 返回实体字段
`HotelStayInfo` 关键字段：
- `personName`
- `personCertNo`
- `personCertName`
- `gender`
- `addressCity`
- `addressDetail`
- `hotelName`
- `hotelAddress`
- `roomNo`
- `inDateTime`
- `outDateTime`

**章节来源**
- [TrackTogetherLiveController.java:1-70](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackTogetherLiveController.java#L1-L70)
- [TogetherLiveDetailQuery.java:1-91](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/query/TogetherLiveDetailQuery.java#L1-L91)
- [HotelStayInfo.java:1-111](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/entity/HotelStayInfo.java#L1-L111)

### 同住服务详情
- **HTTP 方法**：`POST`
- **URL**：`/track/togetherLive/togetherLiveInfoDetail`
- **请求体**：`TogetherLiveDetailQuery`
- **返回**：`Result<Page<TogetherLiveInfo>>`

#### 返回实体字段
`TogetherLiveInfo` 关键字段：
- `queryName`
- `togetherCertNo`
- `queryCertType`
- `queryGender`
- `queryAge`
- `queryEthnicity`
- `queryOrigin`
- `hotelName`
- `roomNo`
- `inDateTime`
- `outDateTime`
- `coType`
- `stayCount`
- `remark`
- `queryCertNo`

**章节来源**
- [TrackTogetherLiveController.java:1-70](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackTogetherLiveController.java#L1-L70)
- [TogetherLiveInfo.java:1-136](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/entity/TogetherLiveInfo.java#L1-L136)

## 见面轨迹接口

### 首次轨迹碰面统计
- **HTTP 方法**：`POST`
- **URL**：`/track/meet/statFirstTrackMeet`
- **请求体**：`TrackMeetQuery`
- **返回**：`Result<List<TrackMeetSummeryDTO>>`

#### 请求字段
| 字段 | 类型 | 必填 | 含义 |
|---|---|---:|---|
| `timeInterval` | `Integer` | 否 | 碰面时间窗口，单位分钟 |
| `lac` | `String` | 否 | 基站区域 ID |
| `cid` | `String` | 否 | 基站小区 ID |
| `persona` | `String` | 否 | 人员 A |
| `personb` | `String` | 否 | 人员 B |

#### 返回字段
| 字段 | 类型 | 含义 |
|---|---|---|
| `persona` | `String` | 人员 A |
| `personb` | `String` | 人员 B |
| `meetCount` | `Integer` | 碰面次数 |
| `meets` | `List<TrackMeetDTO>` | 碰面明细列表 |

**章节来源**
- [TrackMeetController.java:1-50](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackMeetController.java#L1-L50)
- [TrackMeetQuery.java:1-35](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/query/TrackMeetQuery.java#L1-L35)
- [TrackMeetSummeryDTO.java:1-13](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TrackMeetSummeryDTO.java#L1-L13)

### 二次轨迹碰面详情
- **HTTP 方法**：`POST`
- **URL**：`/track/meet/statSecondTrackMeet`
- **请求体**：`TrackMeetQuery`
- **返回**：`Result<List<TrackMeetDTO>>`

#### 返回字段
| 字段 | 类型 | 含义 |
|---|---|---|
| `persona` | `String` | 人员 A |
| `personb` | `String` | 人员 B |
| `lac` | `String` | 基站区域 ID |
| `cid` | `String` | 基站小区 ID |
| `stationName` | `String` | 基站名称 |
| `meetCount` | `Integer` | 碰面次数 |
| `meetDateTime` | `LocalDateTime` | 碰面时间 |
| `meetId` | `String` | 碰面记录 ID |
| `gapMinutes` | `String` | 间隔分钟数 |

**章节来源**
- [TrackMeetController.java:1-50](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackMeetController.java#L1-L50)
- [TrackMeetDTO.java:1-18](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TrackMeetDTO.java#L1-L18)

## 本地活动轨迹接口

### 首次本地活动统计
- **HTTP 方法**：`POST`
- **URL**：`/track/enLocal/statFirstTrackEnLocal`
- **请求体**：`TrackEnLocalQuery`
- **返回**：`Result<Map<String, List<TrackEnLocalDTO>>>`

#### 请求字段
| 字段 | 类型 | 必填 | 含义 |
|---|---|---:|---|
| `dayNightTotal` | `Integer` | 否 | 昼夜活动总次数阈值 |
| `morningTime` | `Integer` | 否 | 白天时段阈值 |
| `nightTime` | `Integer` | 否 | 夜晚时段阈值 |
| `nightTimeStr` | `String` | 否 | 夜晚时段字符串表达 |
| `morningTimeStr` | `String` | 否 | 白天时段字符串表达 |
| `personRegionId` | `String` | 否 | 人员区域标识 |
| `personCellId` | `String` | 否 | 人员小区标识 |
| `personStationName` | `String` | 否 | 基站名称 |
| `nightTempFlag` | `Integer` | 否 | 夜间临时标志 |

#### 返回结构
返回以人员姓名为键的映射，值为该人员在本地活动的轨迹列表。轨迹项包含：
- `personName`
- `personRegionId`
- `personCellId`
- `personStationName`
- `dayNightTotal`

**章节来源**
- [TrackEnLocalController.java:1-46](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackEnLocalController.java#L1-L46)
- [TrackEnLocalQuery.java:1-41](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/query/TrackEnLocalQuery.java#L1-L41)
- [TrackEnLocalDTO.java:1-37](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TrackEnLocalDTO.java#L1-L37)

### 二次本地活动明细
- **HTTP 方法**：`POST`
- **URL**：`/track/enLocal/statSecondTrackEnLocal`
- **请求体**：`TrackEnLocalQuery`
- **返回**：`Result<Page<CallRecord>>`

该接口返回分页的通话记录实体，适用于将本地活动轨迹与通话行为联合分析。

**章节来源**
- [TrackEnLocalController.java:1-46](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackEnLocalController.java#L1-L46)

## 基站轨迹接口

### 首次基站轨迹统计
- **HTTP 方法**：`POST`
- **URL**：`/track/cellTower/statFirstTrackCellTower`
- **请求体**：`TrackCellTowerQuery`
- **返回**：`Result<Page<TrackCellTowerDTO>>`

#### 请求字段
| 字段 | 类型 | 必填 | 含义 |
|---|---|---:|---|
| `personStationName` | `String` | 否 | 基站名称模糊匹配 |
| `personRegionId` | `String` | 否 | LAC |
| `personCellId` | `String` | 否 | CID |
| `otherPhone` | `String` | 否 | 对方号码模糊匹配 |

#### 返回字段
| 字段 | 类型 | 含义 |
|---|---|---|
| `personStationName` | `String` | 基站名称 |
| `personStationLongitude` | `String` | 基站经度 |
| `personStationLatitude` | `String` | 基站纬度 |
| `personName` | `String` | 通信人姓名 |
| `callCount` | `Integer` | 通信次数 |
| `personRegionId` | `String` | LAC |
| `personCellId` | `String` | CID |
| `startDate` | `LocalDate` | 最早通信日期 |
| `endDate` | `LocalDate` | 最晚通信日期 |

**章节来源**
- [TrackCellTowerController.java:1-49](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackCellTowerController.java#L1-L49)
- [TrackCellTowerQuery.java:1-33](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/query/TrackCellTowerQuery.java#L1-L33)
- [TrackCellTowerDTO.java:1-66](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TrackCellTowerDTO.java#L1-L66)

### 二次基站轨迹统计
- **HTTP 方法**：`POST`
- **URL**：`/track/cellTower/statSecondTrackCellTower`
- **请求体**：`TrackCellTowerQuery`
- **返回**：`Result<Page<TrackCellTowerSecondDTO>>`

#### 返回字段
| 字段 | 类型 | 含义 |
|---|---|---|
| `personStationName` | `String` | 基站名称 |
| `personName` | `String` | 通信人姓名 |
| `callCount` | `Integer` | 通信次数 |
| `personPhone` | `String` | 本人电话 |
| `otherPhone` | `String` | 对方电话 |
| `otherName` | `String` | 对方姓名 |

**章节来源**
- [TrackCellTowerController.java:1-49](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackCellTowerController.java#L1-L49)
- [TrackCellTowerSecondDTO.java:1-30](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TrackCellTowerSecondDTO.java#L1-L30)

## 快递信息接口

### 一级快递信息统计
- **HTTP 方法**：`POST`
- **URL**：`/expressInfo/statFirstExpressInfo`
- **请求体**：`ExpressInfoQuery`
- **返回**：`Result<Page<ExpressDTO>>`

#### 请求字段
| 字段 | 类型 | 必填 | 含义 |
|---|---|---:|---|
| `ids` | `List<String>` | 否 | 快递 ID 列表 |
| `location` | `String` | 否 | 地理位置模糊匹配 |
| `recipientName` | `String` | 否 | 收件人姓名模糊匹配 |
| `senderName` | `String` | 否 | 寄件人姓名模糊匹配 |
| `departurePlace` | `String` | 否 | 出发地模糊匹配 |
| `destinationPlace` | `String` | 否 | 目的地模糊匹配 |
| `personPhones` | `List<String>` | 否 | 人员电话号码列表 |

#### 返回字段
| 字段 | 类型 | 含义 |
|---|---|---|
| `ids` | `Set<String>` | 相关快递 ID 集合 |
| `sendIds` | `Set<String>` | 发件 ID 集合 |
| `rcpId` | `Set<String>` | 收件 ID 集合 |
| `personName` | `String` | 被调查对象姓名 |
| `location` | `String` | 快递收发地点 |
| `recipientCount` | `Integer` | 收快递次数 |
| `senderCount` | `Integer` | 发快递次数 |

注意：`recipientCount` 和 `senderCount` 会根据对应 ID 集合大小计算，空集合时返回 `0`。

**章节来源**
- [ExpressInfoController.java:1-49](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/ExpressInfoController.java#L1-L49)
- [ExpressInfoQuery.java:1-48](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/query/ExpressInfoQuery.java#L1-L48)
- [ExpressDTO.java:1-125](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/ExpressDTO.java#L1-L125)

### 二级快递信息明细
- **HTTP 方法**：`POST`
- **URL**：`/expressInfo/statSecondExpressInfo`
- **请求体**：`ExpressInfoQuery`
- **返回**：`Result<Page<ExpressInfo>>`

#### 返回实体字段
| 字段 | 类型 | 含义 |
|---|---|---|
| `recipientName` | `String` | 收件人姓名 |
| `recipientCurrentAddress` | `String` | 收件人现住址 |
| `recipientPhone` | `String` | 收件人联系电话 |
| `senderName` | `String` | 寄件人姓名 |
| `senderPhone` | `String` | 寄件人电话 |
| `sendDate` | `LocalDateTime` | 寄件日期 |
| `senderCurrentAddress` | `String` | 寄件人现住址 |
| `waybillNumber` | `String` | 运单号 |
| `departurePlace` | `String` | 始发地名称 |
| `destinationPlace` | `String` | 目的地名称 |
| `recipientCompany` | `String` | 收件单位名称 |
| `expressCompanyCode` | `String` | 快递公司编号 |
| `goodsName` | `String` | 物品名称 |

**章节来源**
- [ExpressInfoController.java:1-49](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/ExpressInfoController.java#L1-L49)
- [ExpressInfo.java:1-122](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/entity/ExpressInfo.java#L1-L122)

## 人员关联与时空调查支持

### 与人员的关系
轨迹数据以人员为核心维度。多数查询都支持通过姓名、身份证号、电话号码或基站定位对象进行筛选。典型关联路径：
- 通过人员姓名或身份证号查同行、同住、见面。
- 通过人员电话号码查基站轨迹和快递信息。
- 通过人员位置特征查本地活动轨迹。

### 与通话的关系
- 本地活动轨迹的二次明细直接返回通话记录实体，便于将“某人在某基站活动”与“某人在某时间段打电话”结合分析。
- 基站轨迹提供对方号码和对方姓名，可与通话记录、联系人关系相互印证。

### 与交易的关系
- 快递信息中的寄件人、收件人、地址、运单号可作为资金流向、账户归属、收货地址分析的补充证据。
- 同住和同行发现的高频接触对象，常与共同交易、频繁转账存在强关联。

### 与治理树的关系
- 轨迹发现的人员关系可作为治理树扩展边：同行、同住、见面、同城、基站重叠、快递收发均可作为间接关系。
- 时空调查中，先通过轨迹锁定“关键人物+关键地点+关键时间”，再沿治理树向上溯源组织关系、向下追踪执行节点。

```mermaid
graph TB
    Person["人员"] --> TrackTogether["同行"]
    Person --> TrackTogetherLive["同住"]
    Person --> TrackMeet["见面"]
    Person --> TrackEnLocal["本地活动"]
    Person --> TrackCellTower["基站"]
    Person --> Express["快递"]
    TrackCellTower --> Call["通话"]
    Express --> Transaction["交易"]
    TrackTogetherLive --> GovernanceTree["治理树"]
    TrackMeet --> GovernanceTree
    TrackEnLocal --> GovernanceTree
    TrackCellTower --> GovernanceTree
    Express --> GovernanceTree
```

[本图为概念关系图，不直接映射具体源码文件]

## 按人员或时间范围查询示例

### 示例一：按人员查同行时间线
- **目的**：查看指定人员与其他人员的同行频率。
- **接口**：`POST /track/togetherTravel/statTogetherTravel`
- **建议请求体**：
  - 使用 `personCertNo` 或 `personCertNos` 指定人员。
  - 可结合 `type` 或 `id` 缩小数据来源。
- **期望返回**：多条同行关系，每条包含双方姓名、同行次数、ID 列表。

### 示例二：按时间范围查基站轨迹
- **目的**：查看某人员在某段时间内的基站活动。
- **接口**：`POST /track/cellTower/statFirstTrackCellTower`
- **建议请求体**：
  - 使用 `personName` 或 `personNames` 指定人员。
  - 使用 `startDate`、`endDate` 限定日期范围。
  - 使用 `personStationName`、`personRegionId`、`personCellId` 限定基站。
- **期望返回**：分页的基站统计，包含通信次数、时间区间、经纬度等。

### 示例三：按人员和酒店查同住详情
- **目的**：确认某人是否与特定对象在指定酒店同住。
- **接口**：`POST /track/togetherLive/hotelStayInfoDetail`
- **建议请求体**：
  - 使用 `personName`、`personCertNo` 指定被调查对象。
  - 使用 `liveWithName`、`liveWithCertNo` 指定同住人。
  - 使用 `hotelName`、`inStartTime`、`inEndTime` 限定酒店和时间。
- **期望返回**：分页旅馆住宿记录，包含入住退房时间、房间号、酒店地址等。

### 示例四：按基站和人员查见面明细
- **目的**：查看两人在同一基站区域的碰面记录。
- **接口**：`POST /track/meet/statSecondTrackMeet`
- **建议请求体**：
  - 使用 `persona`、`personb` 指定两人。
  - 使用 `lac`、`cid` 指定基站区域。
  - 使用 `timeInterval` 设置碰面时间窗口。
- **期望返回**：碰面明细列表，包含基站、碰面时间、间隔分钟数等。

### 示例五：按人员电话查快递明细
- **目的**：查找某人员相关的快递收发记录。
- **接口**：`POST /expressInfo/statSecondExpressInfo`
- **建议请求体**：
  - 使用 `recipientName`、`senderName`、`personPhones` 指定人员。
  - 使用 `location`、`departurePlace`、`destinationPlace` 辅助定位地址。
- **期望返回**：分页快递明细，包含运单号、地址、寄收件人、商品信息等。

**章节来源**
- [TrackTogetherTravelController.java:1-48](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackTogetherTravelController.java#L1-L48)
- [TrackCellTowerController.java:1-49](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackCellTowerController.java#L1-L49)
- [TrackTogetherLiveController.java:1-70](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackTogetherLiveController.java#L1-L70)
- [TrackMeetController.java:1-50](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackMeetController.java#L1-L50)
- [ExpressInfoController.java:1-49](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/ExpressInfoController.java#L1-L49)
- [Query.java:1-86](file://ai-server/src/main/java/com/zsjz/ai/common/base/Query.java#L1-L86)

## 错误码与响应结构

所有接口返回统一结构 `Result<T>`，包含以下字段：

| 字段 | 类型 | 含义 |
|---|---|---|
| `code` | `int` | 状态码 |
| `message` | `String` | 状态描述 |
| `data` | `T` | 业务数据 |

常用状态码：
- `200`：成功。
- `400`：未知失败或明确失败。

当接口正常完成时，`code` 通常为 `200`，`data` 为业务数据；异常情况应检查 `code` 和 `message`。

```mermaid
flowchart TD
    Start["发起轨迹请求"] --> Send["发送 POST 请求"]
    Send --> Response["接收 Result 响应"]
    Response --> CheckCode{"code 是否为 200"}
    CheckCode -->|是| UseData["读取 data 字段"]
    CheckCode -->|否| HandleError["根据 message 处理错误"]
    UseData --> End["完成"]
    HandleError --> End
```

**图表来源**
- [Result.java:1-114](file://ai-server/src/main/java/com/zsjz/ai/common/config/Result.java#L1-L114)

**章节来源**
- [Result.java:1-114](file://ai-server/src/main/java/com/zsjz/ai/common/config/Result.java#L1-L114)

## 数据缺失、坐标无效、时间异常排查指南

### 数据缺失
**现象**：接口返回空列表或分页结果为空。

**排查步骤**：
1. 检查是否传入了正确的 `personName`、`personCertNo`、`personPhones` 或 `ids`。
2. 检查分页参数 `page`、`limit` 是否过大导致无数据。
3. 检查业务侧过滤条件，如 `hotelName`、`location`、`personStationName` 是否过于严格。
4. 对聚合接口，确认上游清洗数据或源表是否已入库。

**涉及接口**：
- 同行、同住、见面、本地活动、基站、快递等全部轨迹接口。

### 坐标无效
**现象**：基站轨迹返回的经纬度为空、不可用或地图显示异常。

**排查步骤**：
1. 确认基站数据是否包含 `personStationLongitude`、`personStationLatitude`。
2. 若坐标为空，优先检查基站字典、基站转换服务或底层基站数据源。
3. 若坐标存在但明显异常，需结合 LAC、CID、基站名称校验基站库准确性。
4. 对于本地活动轨迹，还需确认 `personRegionId`、`personCellId` 是否正确。

**涉及接口**：
- 基站轨迹接口。
- 本地活动轨迹接口。

**章节来源**
- [TrackCellTowerDTO.java:1-66](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TrackCellTowerDTO.java#L1-L66)
- [TrackEnLocalDTO.java:1-37](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TrackEnLocalDTO.java#L1-L37)

### 时间范围异常
**现象**：时间过滤无效、返回数据不在预期范围内，或出现跨年、跨月异常。

**排查步骤**：
1. 检查 `startDate`、`endDate` 是否传入，且格式为日期类型。
2. 同住详情接口还区分入住时间与退房时间，应同时检查 `inStartTime`、`inEndTime`、`outStartTime`、`outEndTime`。
3. 检查 `timeGap`、`timeInterval` 的单位：同住详情为小时，见面为分钟。
4. 对本地活动轨迹，检查白天、夜晚时段配置 `morningTime`、`nightTime`、`nightTempFlag` 是否符合业务语义。
5. 若接口返回空，尝试放宽时间范围，确认是否为数据本身不在该时间段。

**涉及接口**：
- 同住详情接口。
- 见面接口。
- 本地活动接口。
- 通用分页查询基类。

**章节来源**
- [TogetherLiveDetailQuery.java:1-91](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/query/TogetherLiveDetailQuery.java#L1-L91)
- [TrackMeetQuery.java:1-35](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/query/TrackMeetQuery.java#L1-L35)
- [TrackEnLocalQuery.java:1-41](file://api-server/src/main/java/com/zsjz/ai/common/model/track/query/TrackEnLocalQuery.java#L1-L41)
- [Query.java:1-86](file://ai-server/src/main/java/com/zsjz/ai/common/base/Query.java#L1-L86)

### 同住关系判断异常
**现象**：同住统计中出现大量疑似同住，或与旅馆住宿明细不一致。

**排查步骤**：
1. 检查 `hasTogether`、`suspectedTogether` 是否被设置为疑似同住。
2. 检查 `timeGap` 是否过小或过大，影响疑似同住判定。
3. 对比 `statFirstTrackTogetherLive` 与 `hotelStayInfoDetail`、`togetherLiveInfoDetail` 的结果。
4. 确认数据来源是否来自旅馆住宿表或同住服务表。

**章节来源**
- [TrackTogetherLiveController.java:1-70](file://ai-server/src/main/java/com/zsjz/ai/module/track/controller/TrackTogetherLiveController.java#L1-L70)
- [TogetherLiveDTO.java:1-118](file://ai-server/src/main/java/com/zsjz/ai/common/model/track/dto/TogetherLiveDTO.java#L1-L118)

## 性能与使用建议
- 优先使用一级聚合接口获取概览，再用二级明细接口加载具体记录。
- 分页查询时合理设置 `limit`，避免单次返回过多数据。
- 对基站、同住、快递等可能产生大结果的接口，务必使用人员、时间、地址等条件缩小范围。
- 对同行、见面等关系型分析，建议先通过身份证号或姓名锁定目标人员，再进行多人员组合分析。
- 对于地图展示，应先校验基站经纬度，避免无效坐标导致渲染异常。
- 对时间敏感的分析，应统一时间单位，避免把分钟和小时混用。

[本节为通用建议，不直接分析具体源码文件]

## 结论
轨迹数据接口围绕“人—时间—地点—关系”构建，既支持高层聚合统计，也支持明细数据查询。通过同行、同住、见面、本地活动、基站、快递六类轨迹，系统能够支撑人员关联分析与时空调查，并与通话、交易、治理树形成互补证据链。使用时应重点关注人员标识、时间范围、基站定位和分页控制，并在数据缺失、坐标无效、时间异常时按排查清单逐步定位问题。