zsjz-ai/.qoder/repowiki/zh/content/业务数据模块/轨迹模块 track.md

轨迹模块 track

本文引用的文件

• case_table.sql
• aasd.sql
• TrackAnalysisTool.java
• TrackToolSpecs.java
• TrackCellTowerService.java
• TrackEnLocalService.java
• TrackMeetService.java
• TrackTogetherLiveService.java
• TrackTogetherTravelService.java
• TrackExpressInfoService.java

目录

1. 引言
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖关系分析
7. 性能与优化建议
8. 故障排查指南
9. 结论
10. 附录：查询示例与可视化对接

引言

轨迹模块 track 是案件数据分析中用于还原目标人员时间线与空间活动的重要维度。它管理快递、旅馆住宿、同行（同航班、同火车、同大巴）、同住、同城、基站、火车票等轨迹类调查数据，并通过“谁在什么时间出现在哪里、和谁在一起”来支撑案件串并、行踪追踪和关联挖掘。

该模块的轨迹数据主要来源于多源清洗入库表，以及通话记录衍生的基站位置信息；对外暴露的分析能力集中在 Agent 工具层，以只读方式提供基站汇总、昼夜活动、碰面、同住、同行、快递聚合等查询入口。

项目结构

轨迹模块在后端代码中的组织方式采用“领域包 + 分层职责”的结构：

• 实体与查询对象位于 common/model/track/entity 与 common/model/track/query。
• Mapper XML 位于 resources/mappers/track。
• Service 位于 module/track/service，封装按人员、时间、地点、来源系统的聚合与过滤逻辑。

• Agent 工具位于 module/agent/tools/TrackAnalysisTool，将业务方法包装为可被大模型调用的只读工具。

  graph TB
  subgraph "Agent 工具层"
      Tool["TrackAnalysisTool<br/>轨迹与分析工具集"]
  end
  
  subgraph "业务服务层"
      S1["TrackCellTowerService<br/>基站轨迹"]
      S2["TrackEnLocalService<br/>境外本地昼夜活动"]
      S3["TrackMeetService<br/>轨迹碰面"]
      S4["TrackTogetherLiveService<br/>同住分析"]
      S5["TrackTogetherTravelService<br/>同行旅行"]
      S6["TrackExpressInfoService<br/>快递聚合"]
  end
  
  subgraph "持久化映射层"
      M1["TrackCellTowerMapper"]
      M2["TrackEnLocalMapper"]
      M3["TrackMeetMapper"]
      M4["TrackTogetherTravelMapper"]
      M5["HotelStayInfoMapper"]
      M6["TogetherLiveMapper"]
      M7["ExpressInfoMapper"]
  end
  
  subgraph "数据库表"
      T1["call_record / call_record_all<br/>通话及基站位置"]
      T2["hotel_stay_info<br/>旅馆住宿"]
      T3["together_live_info<br/>同住服务"]
      T4["together_flight_info<br/>同航班"]
      T5["together_train_info<br/>同火车"]
      T6["flight_ticket_info<br/>民航订票"]
      T7["flight_departure_info<br/>民航离港"]
      T8["train_ticket_info<br/>铁路订票"]
      T9["track_car_ticket_info<br/>汽车票务"]
      T10["express_info<br/>快递收件信息"]
      T11["resident_population_info<br/>户籍人口"]
  end
  
  Tool --> S1
  Tool --> S2
  Tool --> S3
  Tool --> S4
  Tool --> S5
  Tool --> S6
  
  S1 --> M1
  S2 --> M2
  S3 --> M3
  S4 --> M4
  S4 --> M5
  S4 --> M6
  S5 --> M4
  S6 --> M7
  
  M1 --> T1
  M2 --> T1
  M3 --> T1
  M4 --> T4
  M4 --> T5
  M4 --> T6
  M4 --> T7
  M4 --> T8
  M4 --> T9
  M5 --> T2
  M6 --> T3
  M7 --> T10
  

图示来源

• TrackAnalysisTool.java:1-200
• TrackCellTowerService.java:1-56
• TrackEnLocalService.java:1-74
• TrackMeetService.java:1-80
• TrackTogetherLiveService.java:1-200
• TrackTogetherTravelService.java:1-200
• TrackExpressInfoService.java:1-164
• case_table.sql:248-531

章节来源

• TrackAnalysisTool.java:1-200
• case_table.sql:248-531

核心组件

轨迹模块的核心由以下六类业务能力组成：

组件	职责	主要输入	主要输出	关键规则
基站轨迹	基于通话记录统计人员在基站下的出现频次、首末时间、经纬度	人员姓名、基站名称、LAC/CID、日期范围	基站汇总、通联明细	表名来自治理配置；未传人员时取案件全部人员
境外本地昼夜活动	将基站通话按白天、夜间时段分组统计	人员、昼夜阈值、小时阈值	昼夜活动汇总、通话明细	默认白天截止 8 点、夜间起点 20 点
轨迹碰面	自关联通话记录，判断两人在同一基站和时间窗口内是否碰面	人员、基站、时间窗口分钟数	碰面汇总、碰面明细	默认 30 分钟时间窗口
同住分析	合并旅馆住宿与同住服务，推导同住人及同住次数	人员、同住次数阈值	按人员分组的同住关系	同住判定含“同酒店+时间交集”和“同行+24 小时”逻辑
同行旅行	合并同航班、同火车、铁路订票、民航订票、民航离港、汽车票务	人员、时间范围	同行关系、出行时间线	按车次/航班号+时间匹配多人
快递聚合	按收件人和地址聚合快递记录，区分收件与寄件	人员电话、地址关键词	地址聚合页、快递明细	使用人员电话缓存去重并按地址聚合

这些组件共同回答三类问题：

1. 目标人员在何时何地出现过。
2. 目标人员与哪些人在时空上存在关联。
3. 不同系统数据能否拼成一条完整的时间线和空间轨迹。

章节来源

• TrackAnalysisTool.java:1-200
• TrackToolSpecs.java:1-200

架构总览

轨迹模块的数据流分为四层：

1. Agent 工具层：通过 TrackAnalysisTool 暴露只读工具，限定参数结构，避免直接 SQL 注入风险。
2. Service 业务层：实现跨表聚合、人员范围处理、时间窗口计算、去重与分页。
3. Mapper 映射层：负责具体 SQL 执行，包括动态表名、排序、分页和统计。

4. 数据库层：存放各轨迹类型原始表，以及与通话、人员基础信息的关联。

   sequenceDiagram
   participant Agent as "Agent 或前端"
   participant Tool as "TrackAnalysisTool"
   participant Service as "Track*Service"
   participant Mapper as "Track*Mapper"
   participant DB as "轨迹相关表"
   
   Agent->>Tool: 调用轨迹分析工具
   Tool->>Tool: 校验参数、解析日期、设置时间窗口
   Tool->>Service: 调用对应业务方法
   Service->>Service: 确定人员范围、表名、过滤条件
   Service->>Mapper: 执行统计或明细查询
   Mapper->>DB: 执行 SQL
   DB-->>Mapper: 返回结果
   Mapper-->>Service: DTO 或实体列表
   Service-->>Tool: 聚合、去重、分页结果
   Tool-->>Agent: 表格结果或产物文件
   

图示来源

• TrackAnalysisTool.java:1-200
• TrackCellTowerService.java:1-56
• TrackExpressInfoService.java:1-164

详细组件分析

基站轨迹与境外本地昼夜活动

基站轨迹是轨迹模块中最接近“时空坐标”的数据。通话记录中包含基站区域编号、小区编号、基站名称、经度和纬度；服务层据此统计每个人员在每个基站的通话次数、首次和末次通话时间。

境外本地昼夜活动是在基站轨迹基础上增加“白天/夜间”时段划分，用于发现异常作息或高频活动地点。

flowchart TD
    Start(["进入基站轨迹查询"]) --> SetTable["设置通话记录表名"]
    SetTable --> SetPersons{"是否传入人员列表？"}
    SetPersons -->|否| LoadAllPersons["加载案件全部人员姓名"]
    SetPersons -->|是| UseInputPersons["使用输入人员列表"]
    LoadAllPersons --> QueryBase["执行基站汇总或明细 SQL"]
    UseInputPersons --> QueryBase
    QueryBase --> Result["返回基站汇总或明细分页结果"]

图示来源

• TrackCellTowerService.java:1-56
• TrackEnLocalService.java:1-74

关键实现要点：

• 基站轨迹表和通话表名不是硬编码，而是通过治理配置服务获取，便于在不同数据环境切换。
• 若未指定人员，则自动从人员基础信息服务加载案件内人员，保证“不传参也能统计全案”。
• 昼夜活动通过小时阈值构造时间段字符串，并根据夜间起始时间判断是否跨日。

章节来源

• TrackCellTowerService.java:1-56
• TrackEnLocalService.java:1-74
• TrackToolSpecs.java:1-200

轨迹碰面分析

轨迹碰面通过通话记录的自关联，判断两名目标人员在同一基站、同一时间窗口内是否同时出现。这是案件串并中非常重要的隐性关系发现手段。

flowchart TD
    A["输入：人员、基站、时间窗口"] --> B["按基站+时间窗口聚合通话记录"]
    B --> C["两两组合人员对"]
    C --> D{"两人是否在相同基站且时间差小于窗口？"}
    D -->|是| E["计入一次碰面"]
    D -->|否| F["忽略"]
    E --> G["按人员对分组汇总碰面次数"]
    G --> H["返回碰面汇总与明细"]

图示来源

• TrackMeetService.java:1-80
• TrackAnalysisTool.java:1-200

关键点：

• 默认碰面时间窗口为 30 分钟，可通过工具参数调整。
• 汇总阶段按“人员A_人员B”键值合并，避免重复配对。
• 二次查询支持按基站区域下钻查看具体通话记录。

章节来源

• TrackMeetService.java:1-80
• TrackAnalysisTool.java:1-200

同住分析与同行分析

同住分析把两类数据结合：

• 旅馆住宿表：记录某人入住某酒店的时间段。
• 同住服务表：记录查询人与被查询人的同住关系、房间、入住时间段。

服务层会合并这两类数据，按被调查对象分组，再按同住人+是否确认同住进行去重和计数。

同行分析则整合多种交通场景：

• 同航班服务
• 同火车服务
• 铁路订票
• 民航订票
• 民航离港

• 汽车票务

  classDiagram
  class TrackTogetherLiveService {
      +statFirstTrackTogetherLive(query)
      +statSecondTrackTogetherLive(query)
      -fetchTravelTogetherData(persons, query)
      -buildLiveTogetherRecords(persons, query, travelTogetherList, nameToPerson)
  }
  
  class TrackTogetherTravelService {
      +statTogetherTravel(query)
      +statSecondTogetherTravel(query)
  }
  
  class TogetherLiveInfo {
      +queryName
      +queryCertNo
      +hotelName
      +roomNo
      +inDateTime
      +outDateTime
      +coType
      +stayCount
  }
  
  class HotelStayInfo {
      +personName
      +personCertNo
      +hotelName
      +roomNo
      +inDateTime
      +outDateTime
  }
  
  class TravelDataDTO {
      +id
      +personName
      +companionName
      +count
  }
  
  TrackTogetherLiveService --> TogetherLiveInfo : "读取"
  TrackTogetherLiveService --> HotelStayInfo : "读取"
  TrackTogetherTravelService --> TravelDataDTO : "生成"
  

图示来源

• TrackTogetherLiveService.java:1-200
• TrackTogetherTravelService.java:1-200
• case_table.sql:339-531

关键点：

• 同住关系可能来自多个来源，需要按“人员+酒店+同住人+是否确认”去重。
• 同住次数可以按阈值过滤，便于筛选高频同住人。
• 同行分析先按“时间+车次/航班号”分组，再交叉比对多人，形成同行关系。

章节来源

• TrackTogetherLiveService.java:1-200
• TrackTogetherTravelService.java:1-200
• case_table.sql:339-531

快递轨迹聚合

快递数据本身不包含精确地理坐标，但包含收件人、收件电话、寄件人电话、收发地址、运单号和快递公司等信息。服务层将其与人员电话缓存关联，按地址聚合出“某人在某地址收过多少快递、寄过多少快递”，并保留原始记录 ID，便于下钻。

flowchart TD
    A["输入：人员姓名、地址关键词"] --> B["根据人员姓名查人员电话集合"]
    B --> C["按电话集合查快递明细"]
    C --> D["按收件人姓名+地址聚合"]
    D --> E["区分收件记录与寄件记录"]
    E --> F["按收件数或寄件数排序"]
    F --> G["返回地址聚合页"]

图示来源

• TrackExpressInfoService.java:1-164

关键点：

• 聚合键为“人员姓名+地址”，避免同名不同人混淆。
• 使用人员电话缓存提升匹配效率。
• 支持按收件数量、寄件数量排序，也支持按人员默认排序。

章节来源

• TrackExpressInfoService.java:1-164

依赖关系分析

轨迹模块依赖三类外部数据：

1. 人员基础信息：用于补全人员姓名、证件号、照片、排序等元数据。
2. 通话记录：作为基站位置和时间戳的主要来源。

3. 治理配置：决定当前使用哪一张通话表，支持多环境或多库切换。

   graph LR
   Person["PersonBasicInfo<br/>人员基础信息"] --> TrackServices["各 Track*Service"]
   CallTable["call_record / call_record_all<br/>通话与基站"] --> TrackServices
   GovernConf["GovernConfService<br/>治理配置"] --> TrackServices
   TrackServices --> Tools["TrackAnalysisTool<br/>Agent 工具"]
   

图示来源

• TrackCellTowerService.java:1-56
• TrackEnLocalService.java:1-74
• TrackMeetService.java:1-80
• TrackAnalysisTool.java:1-200

潜在耦合点：

• 如果通话表结构变化，所有基站、碰面、昼夜活动接口都会受影响。
• 如果人员基础信息缺失姓名或证件号，同住、同行、快递聚合可能无法正确关联。
• 治理配置指向错误的表名会导致空结果或报错。

章节来源

• TrackCellTowerService.java:1-56
• TrackEnLocalService.java:1-74
• TrackMeetService.java:1-80

性能与优化建议

地理信息查询优化

• 基站经纬度字段可用于地图打点，但不建议在 Java 层做大量地理距离计算；优先在数据库或地理引擎侧完成热点聚合。
• 对基站名称、LAC、CID 建立等值索引，有利于明细查询；经纬度适合范围查询，但需注意数据库是否支持高效的空间索引。
• 对于大规模基站轨迹，建议先按人员+基站聚合，再按需展开明细，避免一次性拉取全量通话。

时间窗口过滤

• 基站轨迹、碰面、同住、同行都应尽量带上起止日期，减少无效扫描。
• 碰面默认 30 分钟窗口适用于一般场景；若数据粒度较粗，可适当放大；若噪声较多，应缩小窗口并结合基站稳定性过滤。
• 昼夜活动的小时阈值应与业务语义一致，避免将正常早班或夜班误判为异常。

轨迹去重

• 同住关系需按“人员+酒店+同住人+是否确认”去重，防止多次导入产生重复。
• 同行关系按“时间+车次/航班号”合并，但要注意不同系统车次号格式不一致导致的匹配失败。
• 快递聚合按“人员+地址”聚合，但同名不同人仍可能误聚合，应优先用证件号或电话辅助区分。

可视化对接建议

• 时间线可视化：使用出行时间线 DTO，按时间顺序展示人员移动过程。
• 地图可视化：使用基站经纬度打点，按颜色区分人员，按大小区分频次。
• 关系图可视化：将同住、同行、碰面、交易、通话作为边，人员作为节点，构建案件关系图谱。
• 热点分析：按基站或地址聚合频次，高亮高频活动点。

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

故障排查指南

现象	可能原因	排查方向
基站轨迹为空	治理配置表名错误、人员姓名为空、时间范围无数据	检查治理配置、人员基础信息、日期范围
同住结果为空	旅馆住宿与同住服务数据未对齐、时间交集不存在	检查酒店名称、房间号、入住时间段
同行关系很少	车次号或航班号不一致、时间精度不匹配	检查各系统时间格式、车次/航班号标准化
快递聚合结果异常	人员电话缓存为空、同名不同人	检查人员电话缓存、改用证件号辅助
碰面结果过多	时间窗口过大、基站定位太宽泛	缩小时间窗口、限定 LAC/CID
工具报参数错误	Agent 传入非数字或非法字段	检查 ToolParam 定义，确保日期和数值类型正确

章节来源

• TrackAnalysisTool.java:1-200
• TrackToolSpecs.java:1-200

结论

轨迹模块 track 是一个以“人员—时间—空间—关系”为主线的分析子系统。它并不只是简单列出原始数据，而是围绕基站、住宿、交通、快递等多源数据，提供聚合、去重、关联和可视化的基础能力。

在实际案件中，轨迹数据通常不能单独定案，但能显著增强人员画像、串并分析和行踪还原的可信度。推荐的使用路径是：先按人员和时间范围拉取轨迹，再通过同住、同行、碰面、快递地址找到关联人，最后结合通话、交易进一步验证关系强度。

[本节为总结性内容，不直接分析具体文件]

附录：查询示例与可视化对接

按人员和时间范围查轨迹

适用场景：还原目标人员在某段时间内的活动轮廓。

推荐步骤：

1. 先查基站轨迹汇总，了解高频基站。
2. 对高频基站查通联明细，确认通话号码和活动时段。
3. 如有昼夜异常，查昼夜活动汇总和明细。
4. 如关注异地活动，查境外本地轨迹或交通出行记录。

参考实现入口：

• 基站轨迹汇总：TrackAnalysisTool.statTrackCellTowerSummary
• 基站通联明细：TrackAnalysisTool.statTrackCellTowerDetail
• 昼夜活动汇总：TrackAnalysisTool.statTrackEnLocalSummary
• 昼夜活动明细：TrackAnalysisTool.statTrackEnLocalDetail

章节来源

• TrackAnalysisTool.java:1-200
• TrackCellTowerService.java:1-56
• TrackEnLocalService.java:1-74

同行/同住关系挖掘

适用场景：发现目标人员的密切联系人。

推荐步骤：

1. 查同住汇总，得到高频同住人。
2. 查同住明细，确认是否在同一酒店、同一房间、同一时间段。
3. 查同行汇总，得到同航班、同火车、同大巴记录。
4. 对可疑同行关系查出行详情，核对时间、车次、座位。

参考实现入口：

• 同住汇总：TrackAnalysisTool.stat_together_live_summary
• 同住明细：TrackAnalysisTool.stat_together_live_detail
• 同行汇总：TrackAnalysisTool.stat_together_travel_summary
• 同行详情：TrackAnalysisTool.stat_together_travel_detail

章节来源

• TrackTogetherLiveService.java:1-200
• TrackTogetherTravelService.java:1-200
• TrackAnalysisTool.java:1-200

基站热点分析

适用场景：发现目标人员常驻地、工作地、临时落脚点。

推荐步骤：

1. 不限人员统计全案基站热点，筛选高频基站。
2. 按人员+基站筛选个人热点。
3. 按 LAC/CID 下钻到更细基站单元。
4. 结合昼夜活动判断是否夜间异常停留。

参考实现入口：

• 基站汇总：TrackAnalysisTool.stat_track_cell_tower_summary
• 基站明细：TrackAnalysisTool.stat_track_cell_tower_detail
• 昼夜活动汇总：TrackAnalysisTool.stat_track_en_local_summary

章节来源

• TrackAnalysisTool.java:1-200
• TrackCellTowerService.java:1-56
• TrackEnLocalService.java:1-74

跨系统轨迹合并

适用场景：把住宿、交通、快递、通话基站拼成一条连贯时间线。

推荐步骤：

1. 统一人员标识：优先使用姓名+证件号，必要时用电话辅助。
2. 统一时间格式：注意部分表使用日期、部分使用时间戳。
3. 合并交通出行：同航班、同火车、铁路订票、民航订票、民航离港、汽车票务。
4. 补充住宿和快递地址：用于解释人员为何出现在某地。
5. 用通话基站验证地理位置：确认是否与交通、住宿地点一致。

参考数据结构与表：

• 交通出行：together_flight_info、together_train_info、train_ticket_info、flight_ticket_info、flight_departure_info、track_car_ticket_info
• 住宿：hotel_stay_info、together_live_info
• 快递：express_info
• 基站位置：call_record、call_record_all

章节来源

• case_table.sql:339-531
• TrackTogetherTravelService.java:1-200
• TrackExpressInfoService.java:1-164