时序与特殊日期模块 otg.md 33 KB

时序与特殊日期模块 otg

本文引用的文件

  • TimeSeriesController.java
  • SpecialDateController.java
  • SearchController.java
  • TimeSeriesService.java
  • SpecialDateService.java
  • TimeSeriesMapper.java
  • SpecialDateRecordMapper.java
  • SpecialDateMapper.java
  • TimeSeriesMapper.xml
  • SpecialDateRecordMapper.xml
  • SpecialDateMapper.xml
  • TimeSeries.java
  • SpecialDate.java
  • SpecialDateRecord.java
  • TimeSeriesQuery.java
  • SearchQuery.java
  • case_table.sql
  • case_table_1.sql
  • TransSensitiveMapper.xml
  • CallSensitiveMapper.xml
  • IntimacyMapper.xml

目录

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与索引优化
  8. 使用示例
  9. 故障排查指南
  10. 结论

引言

时序与特殊日期模块 otg 为通话、交易、轨迹等案件业务提供统一的时间维度能力。它负责:

  • 维护一个跨表、按时间排序的“时序视图”数据,供前端时间轴、跳转和详情展示。
  • 管理“特殊日期”,包括节假日、工作日、农历节日及自定义事件日,并把用户配置展开成可查询的时间区间。
  • 通过搜索控制器暴露关键词检索入口,便于在业务页面中快速定位记录。

该模块不直接持有通话或交易原始表,而是通过 time_series_info 聚合多类实体,并通过 special_date 提供时间语义标签,从而让行为分析和异常检测可以区分工作日与节假日、识别周期性高峰或异常低谷。

项目结构

otg 模块位于后端服务的 module/otg 下,采用常见的 Controller → Service → Mapper 分层;共享模型放在 common/model/otg;SQL 映射放在 resources/mappers/otg。

graph TB
    subgraph "otg 模块"
        C1["TimeSeriesController"]
        C2["SpecialDateController"]
        C3["SearchController"]
        S1["TimeSeriesService"]
        S2["SpecialDateService"]
        M1["TimeSeriesMapper"]
        M2["SpecialDateRecordMapper"]
        M3["SpecialDateMapper"]
    end

    subgraph "共享模型"
        E1["TimeSeries"]
        E2["SpecialDate"]
        E3["SpecialDateRecord"]
        Q1["TimeSeriesQuery"]
        Q2["SearchQuery"]
    end

    subgraph "数据库"
        DB_TS["time_series_info"]
        DB_SD["special_date"]
        DB_SDR["special_date_reord"]
    end

    C1 --> S1
    C2 --> S2
    C3 -->|"调用"| SearchQueryService
    S1 --> M1
    S2 --> M2
    S2 --> M3
    M1 --> DB_TS
    M2 --> DB_SDR
    M3 --> DB_SD
    E1 --- DB_TS
    E2 --- DB_SD
    E3 --- DB_SDR
    Q1 --> C1
    Q2 --> C3

图表来源

  • TimeSeriesController.java:1-37
  • SpecialDateController.java:1-44
  • SearchController.java:1-26
  • TimeSeriesService.java:1-94
  • SpecialDateService.java:1-118
  • TimeSeriesMapper.java:1-23
  • SpecialDateRecordMapper.java:1-12
  • SpecialDateMapper.java:1-12
  • TimeSeries.java:1-45
  • SpecialDate.java:1-22
  • SpecialDateRecord.java:1-30
  • TimeSeriesQuery.java:1-48
  • SearchQuery.java:1-11

章节来源

  • TimeSeriesController.java:1-37
  • SpecialDateController.java:1-44
  • SearchController.java:1-26
  • TimeSeriesService.java:1-94
  • SpecialDateService.java:1-118
  • TimeSeriesMapper.java:1-23
  • SpecialDateRecordMapper.java:1-12
  • SpecialDateMapper.java:1-12
  • TimeSeries.java:1-45
  • SpecialDate.java:1-22
  • SpecialDateRecord.java:1-30
  • TimeSeriesQuery.java:1-48
  • SearchQuery.java:1-11

核心组件

  • 时序控制器:对外暴露 /otg/timeSeries 下的列表、详情和跳转接口。
  • 特殊日期控制器:对外暴露 /sdc 下的列表、创建、更新、删除接口。
  • 搜索控制器:对外暴露 /search/list,委托给搜索服务做关键词检索。
  • 时序服务:处理时间范围转换、类型扁平化、动态表头解析、跳转查询。
  • 特殊日期服务:写入特殊日期记录,并批量生成未来多年的时间区间。
  • Mapper 层:声明 DuckDB 从库访问,并提供时序列表、跳转和基础 CRUD。

章节来源

  • TimeSeriesController.java:1-37
  • SpecialDateController.java:1-44
  • SearchController.java:1-26
  • TimeSeriesService.java:1-94
  • SpecialDateService.java:1-118
  • TimeSeriesMapper.java:1-23
  • SpecialDateRecordMapper.java:1-12
  • SpecialDateMapper.java:1-12

架构总览

otg 模块的核心职责是“时间增强”:

  • 对上游业务(通话、交易、轨迹)而言,time_series_info 提供统一的时间轴视图。
  • 对下游分析(敏感交易、亲密关系、通话敏感等)而言,special_date 提供“某日是否属于节假日或自定义事件”的判定条件。

    sequenceDiagram
    participant FE as "前端"
    participant TS as "TimeSeriesController"
    participant SS as "TimeSeriesService"
    participant TM as "TimeSeriesMapper"
    participant DB as "DuckDB<br/>time_series_info"
    
    FE->>TS: POST /otg/timeSeries/list
    TS->>SS: getTimeSeries(query)
    SS->>SS: 转换起止时间、扁平化类型
    SS->>TM: selectTimeSeriesList(...)
    TM->>DB: 带 rowid、时间、人员、扩展字段过滤
    DB-->>TM: 最多 20 条结果
    TM-->>SS: 列表
    SS-->>TS: 列表
    TS-->>FE: 成功响应
    

图表来源

  • TimeSeriesController.java:12-36
  • TimeSeriesService.java:24-53
  • TimeSeriesMapper.java:12-22
  • TimeSeriesMapper.xml:35-77

详细组件分析

时序数据与时序控制器

时序控制器提供三类操作:

  • 列表:根据时间范围、人员、本地标识、类型等返回最近 20 条时序。
  • 详情:根据主键和人员名称查询一条记录,并附带表格列头信息。
  • 跳转:以当前记录为中心,向前后各取若干行,形成时间轴上下文。

时序查询支持以下维度:

  • 本地标识:通过 hasLocal=Y 要求 ext8、ext9 非空,用于区分是否包含本地数据。
  • 中文表名:用于前端展示时匹配表头。
  • 类型集合:由外层把嵌套类型扁平化为字符串列表,再传入 SQL。
  • 人员名称、时间范围、滚动方向、目标 ID 或时间轴 ID。

    flowchart TD
    Start(["进入列表接口"]) --> ParseTime["解析起止日期为时间戳"]
    ParseTime --> FlattenTypes["扁平化 types"]
    FlattenTypes --> BuildQuery["构建查询参数"]
    BuildQuery --> Execute["执行 selectTimeSeriesList"]
    Execute --> Limit["限制最多 20 条"]
    Limit --> Return(["返回结果"])
    

图表来源

  • TimeSeriesService.java:24-53
  • TimeSeriesMapper.xml:35-77

章节来源

  • TimeSeriesController.java:12-36
  • TimeSeriesService.java:24-53
  • TimeSeriesMapper.xml:35-77
  • TimeSeriesQuery.java:12-48

时序详情与跳转

详情接口会:

  1. 根据请求中的表名获取 MyBatis-Plus 表元信息。
  2. 用主键和可选人员名称查询单条记录。
  3. 从全局缓存读取表头映射,返回列定义和数据。

跳转接口则通过 SQL 先找到目标记录的 rowid,再返回前后固定范围的记录,适合时间轴上下翻页。

sequenceDiagram
    participant FE as "前端"
    participant TS as "TimeSeriesController"
    participant SS as "TimeSeriesService"
    participant TM as "TimeSeriesMapper"
    participant DB as "DuckDB"

    FE->>TS: POST /otg/timeSeries/jump
    TS->>SS: jumpTimeSeries(query)
    SS->>TM: jumpTimeSeries(query)
    TM->>DB: 查找目标 rowid 并返回前后区间
    DB-->>TM: 相邻时序记录
    TM-->>SS: 跳转结果
    SS-->>TS: 跳转结果
    TS-->>FE: 成功响应

图表来源

  • TimeSeriesController.java:28-36
  • TimeSeriesService.java:56-66
  • TimeSeriesMapper.java:15-22
  • TimeSeriesMapper.xml:4-32

章节来源

  • TimeSeriesService.java:68-94
  • TimeSeriesMapper.xml:4-32

特殊日期概念与数据模型

特殊日期是用于标注“某天不是普通工作日”的日历概念,至少包括:

  • 节假日:如国家法定节假日。
  • 工作日:系统内部可用以区分正常工作日与非工作日。
  • 农历节日:通过农历服务将农历日期转换为公历日期。
  • 自定义事件日:例如重大活动、演练、封网等。

数据模型分为两层:

  • special_date_reord:用户输入的特殊日期记录,包含名称、标志位、公历或农历标记、前后间隔和目标日期片段。
  • special_date:展开后的时间区间,每条记录对应某个年份内的一段 startDate 到 endDate,并按批次关联到 special_date_reord.id。

    erDiagram
    SPECIAL_DATE_RECORD {
    bigint id PK
    varchar name
    integer flag
    integer type
    integer gap
    varchar spDate
    }
    
    SPECIAL_DATE {
    bigint batchId FK
    varchar name
    date startDate
    date endDate
    }
    
    TIME_SERIES_INFO {
    bigint id PK
    varchar tableNameEn
    varchar tableNameCn
    varchar personName
    varchar otherName
    timestamp seriesDateTime
    varchar ext1
    varchar ext2
    varchar ext3
    varchar ext4
    varchar ext5
    varchar ext6
    varchar ext7
    varchar ext8
    varchar ext9
    }
    
    SPECIAL_DATE ||--o{ SPECIAL_DATE : "batchId"
    SPECIAL_DATE ||--o{ TIME_SERIES_INFO : "业务通过日期范围间接关联"
    

图表来源

  • SpecialDateRecord.java:1-30
  • SpecialDate.java:1-22
  • TimeSeries.java:1-45
  • case_table_1.sql:157-178
  • case_table.sql:534-554

章节来源

  • SpecialDateRecord.java:1-30
  • SpecialDate.java:1-22
  • case_table_1.sql:157-178
  • case_table.sql:534-554

特殊日期控制器的处理管道

特殊日期控制器暴露的基础操作如下:

方法 路径 用途 主要行为
GET /sdc/list 列出所有特殊日期记录 返回 special_date_reord 记录
POST /sdc/create 新增特殊日期 设置标志位、插入记录、展开时间区间
POST /sdc/update 修改特殊日期 校验 ID、删除旧区间、重新展开
GET /sdc/delete 删除特殊日期 校验 ID、删除记录及对应区间
flowchart TD
    Input["接收特殊日期记录"] --> CheckCreate{"是否为新增"}
    CheckCreate -->|是| SetFlag["设置标志位"]
    SetFlag --> InsertRecord["插入特殊日期记录"]
    InsertRecord --> Expand["展开多年时间区间"]
    Expand --> SaveBatch["批量保存 special_date"]
    CheckCreate -->|否| UpdateCheck["校验 ID 是否存在"]
    UpdateCheck --> DeleteOld["删除旧区间"]
    DeleteOld --> Expand
    Expand --> Done(["完成"])

图表来源

  • SpecialDateController.java:16-43
  • SpecialDateService.java:30-118

章节来源

  • SpecialDateController.java:16-43
  • SpecialDateService.java:30-118

特殊日期如何影响行为分析与异常检测

特殊日期表被其他模块通过日期范围 JOIN,从而把“业务日期”打上“是否特殊日期”的语义:

  • 交易敏感分析:通过 transDate BETWEEN startDate AND endDate 判断交易是否发生在特殊日期。
  • 通话敏感分析:通过 callDate BETWEEN startDate AND endDate 判断通话是否发生在特殊日期。
  • 亲密关系分析:也通过 special_date 进行时间维度关联,辅助判断特定时间段内的关系变化。

这意味着,当用户在 otg 中新增一个节假日或自定义事件日后,后续基于这些 Mapper 的分析查询会自动把该日期纳入“特殊时间窗口”。

graph LR
    SD["special_date"] --> TR["交易敏感查询"]
    SD --> CL["通话敏感查询"]
    SD --> IN["亲密关系查询"]

图表来源

  • TransSensitiveMapper.xml:33-34
  • TransSensitiveMapper.xml:77-78
  • CallSensitiveMapper.xml:34-35
  • CallSensitiveMapper.xml:74-75
  • IntimacyMapper.xml:36-37
  • IntimacyMapper.xml:84-85

章节来源

  • TransSensitiveMapper.xml:33-34
  • TransSensitiveMapper.xml:77-78
  • CallSensitiveMapper.xml:34-35
  • CallSensitiveMapper.xml:74-75
  • IntimacyMapper.xml:36-37
  • IntimacyMapper.xml:84-85

搜索控制器

搜索控制器只暴露 /search/list,接收 SearchQuery,然后委托给 SearchQueryService.search(keyword)。该控制器本身不做复杂逻辑,主要用于把关键词搜索入口统一到搜索服务。

sequenceDiagram
    participant FE as "前端"
    participant SC as "SearchController"
    participant SQS as "SearchQueryService"

    FE->>SC: GET /search/list?keyword=...
    SC->>SQS: search(keyword)
    SQS-->>SC: 搜索结果列表
    SC-->>FE: 成功响应

图表来源

  • SearchController.java:12-25
  • SearchQuery.java:1-11

章节来源

  • SearchController.java:12-25
  • SearchQuery.java:1-11

依赖关系分析

  • otg 控制器依赖各自的服务。
  • TimeSeriesService 还依赖治理配置服务和全局缓存,用于动态表头和表映射。
  • SpecialDateService 依赖农历服务和两个 Mapper,负责从库写特殊日期及其展开区间。
  • 所有 Mapper 都标注了从库数据源,表示时序数据和特殊日期数据落在 DuckDB 或案件从库。

    classDiagram
    class TimeSeriesController {
        +getTimeSeries(query)
        +detailTimeSeries(query)
        +jumpTimeSeries(query)
    }
    class SpecialDateController {
        +list()
        +create(sdr)
        +update(sdr)
        +delete(id)
    }
    class SearchController {
        +search(query)
    }
    class TimeSeriesService {
        +getTimeSeries(query)
        +jumpTimeSeries(query)
        +detailTimeSeries(query)
    }
    class SpecialDateService {
        +create(sdr)
        +update(sdr)
        +delete(id)
        +listRecord()
    }
    class TimeSeriesMapper
    class SpecialDateRecordMapper
    class SpecialDateMapper
    
    TimeSeriesController --> TimeSeriesService
    SpecialDateController --> SpecialDateService
    SearchController --> SearchQueryService
    TimeSeriesService --> TimeSeriesMapper
    SpecialDateService --> SpecialDateRecordMapper
    SpecialDateService --> SpecialDateMapper
    

图表来源

  • TimeSeriesController.java:12-36
  • SpecialDateController.java:16-43
  • SearchController.java:12-25
  • TimeSeriesService.java:14-94
  • SpecialDateService.java:22-118
  • TimeSeriesMapper.java:12-22
  • SpecialDateRecordMapper.java:10-11
  • SpecialDateMapper.java:10-11

章节来源

  • TimeSeriesService.java:14-94
  • SpecialDateService.java:22-118
  • TimeSeriesMapper.java:12-22
  • SpecialDateRecordMapper.java:10-11
  • SpecialDateMapper.java:10-11

性能与索引优化

时序数据写入性能

  • time_series_info 是聚合型表,通常由上游同步任务批量写入。
  • 当前代码没有直接提供 otg 自身的批量写入接口;批量写入应集中在数据同步层,避免高频单条插入。
  • 建议:
    • 使用批量插入,而不是逐条插入。
    • 关闭不必要的唯一性校验和触发器。
    • 按时间分片或分区,减少单表膨胀。
    • 在入库前过滤无效时间、重复记录和缺失关键字段。

时间索引优化

  • 当前索引主要覆盖 personName 和 otherName。
  • 如果频繁按 seriesDateTime 范围查询,应增加时间索引。
  • 如果按“人员+时间”组合查询较多,应考虑复合索引。
  • 当前列表查询限制 20 条,能缓解全表扫描压力,但大表仍建议加索引。

    flowchart TD
    Start(["评估时序写入与查询模式"]) --> Analyze["分析高频查询条件"]
    Analyze --> AddIndex["为 seriesDateTime 或 personName+seriesDateTime 添加索引"]
    AddIndex --> BatchWrite["使用批量写入 time_series_info"]
    BatchWrite --> Monitor["监控慢查询与表增长"]
    Monitor --> Tune["调整分页大小、索引和同步策略"]
    

图表来源

  • case_table.sql:534-554
  • TimeSeriesMapper.xml:35-77

与其他模块共享时间上下文的最佳实践

  • 使用统一的 seriesDateTime 作为时间轴主键字段,避免业务表各自使用时间字段导致无法对齐。
  • 使用 tableNameEn 区分数据来源,配合 personName、otherName 做主体关联。
  • 使用 ext1~ext9 保留扩展字段,但不要无节制扩展;优先保持可读性和稳定性。
  • 使用 special_date 的 startDate、endDate 做时间语义判断,而不是在业务代码里硬编码节假日规则。
  • 在分析查询中 JOIN special_date,确保节假日、工作日和自定义事件日能被一致识别。

章节来源

  • TimeSeries.java:1-45
  • TimeSeriesMapper.xml:35-77
  • case_table.sql:534-554
  • TransSensitiveMapper.xml:33-34
  • CallSensitiveMapper.xml:34-35
  • IntimacyMapper.xml:36-37

使用示例

示例一:按工作日或节假日筛选通话或交易

步骤:

  1. 在 /sdc 中新增一个特殊日期,例如“春节假期”,选择公历或农历,并可设置前后间隔。
  2. 服务会把该日期展开为未来多年的 startDate 到 endDate 区间。
  3. 在交易或通话敏感查询中,通过 special_date 的日期范围过滤,即可得到节假日或工作日对应的行为数据。
  4. 对比工作日与节假日的交易量、通话量、活跃人数,发现异常波动。

相关实现位置:

  • 特殊日期增删改查接口:SpecialDateController.java:16-43
  • 特殊日期展开逻辑:SpecialDateService.java:30-118
  • 交易特殊日期 JOIN:TransSensitiveMapper.xml:33-34
  • 通话特殊日期 JOIN:CallSensitiveMapper.xml:34-35

示例二:标记特殊日期并结合时序趋势做异常报警

步骤:

  1. 在 /sdc/create 中标记某个自定义事件日,例如“系统封网演练”。
  2. 通过 /otg/timeSeries/list 拉取该人物或该表类型的时序趋势。
  3. 在分析层比较该事件日前后时序值的变化,若交易量、通话量或活跃度显著偏离历史基线,则触发异常报警。
  4. 结合 special_date.name 输出告警原因,例如“封网期间交易量下降超阈值”。

相关实现位置:

  • 时序列表接口:TimeSeriesController.java:18-22
  • 时序列表处理逻辑:TimeSeriesService.java:24-53
  • 时序 SQL 过滤:TimeSeriesMapper.xml:35-77

示例三:时间轴跳转查看上下文

步骤:

  1. 在前端选中某条时序记录。
  2. 调用 /otg/timeSeries/jump,传入该记录的 ID 和时间轴 ID。
  3. 后端返回目标记录前后若干条记录,形成时间轴上下文。
  4. 前端渲染时间轴,并高亮当前记录。

相关实现位置:

  • 跳转接口:TimeSeriesController.java:28-36
  • 跳转服务:TimeSeriesService.java:56-66
  • 跳转 SQL:TimeSeriesMapper.xml:4-32

故障排查指南

特殊日期修改时报缺少 ID

现象:调用 /sdc/update 报缺少日期记录 ID。 原因:请求体未传 ID,而代码对包装类型做了安全判空,并抛出业务异常。 处理:

  • 前端确保修改时携带 id。
  • 不要修改内置日期,ID 为内置值时会抛业务异常。

相关实现位置:

  • SpecialDateService.java:45-59

特殊日期删除时报缺少 ID

现象:调用 /sdc/delete 报缺少日期记录 ID。 原因:同上,对包装类型 ID 做了空值检查。 处理:

  • 确保删除请求携带有效 ID。
  • 内置日期不可删除。

相关实现位置:

  • SpecialDateService.java:61-72

时序详情报未找到表信息

现象:调用 /otg/timeSeries/detailTimeSeries 报未找到表信息。 原因:请求中的表名没有对应的 MyBatis-Plus 表元信息。 处理:

  • 确认 tableNameEn 与实际表名一致。
  • 确认表已注册到框架的表元信息中。

相关实现位置:

  • TimeSeriesService.java:68-79

特殊日期写入数据源问题

现象:特殊日期写入主库而非从库。 原因:批量保存不走 Mapper 代理,需要在外层方法上切从库数据源。 处理:

  • 确保 create 和 update 方法上的从库注解生效。
  • 注意事务范围,保证失败回滚。

相关实现位置:

  • SpecialDateService.java:30-43
  • SpecialDateRecordMapper.java:10-11
  • SpecialDateMapper.java:10-11

章节来源

  • SpecialDateService.java:30-72
  • TimeSeriesService.java:68-79
  • SpecialDateRecordMapper.java:10-11
  • SpecialDateMapper.java:10-11

结论

otg 模块以 time_series_info 和 special_date 为核心,把时间维度从业务表中抽象出来:

  • 时序表提供统一的时间轴视图,支撑时间轴、跳转、详情和趋势分析。
  • 特殊日期表提供节假日、工作日和自定义事件日的语义,支撑行为分析和异常检测。
  • 控制器暴露清晰的 REST 入口,服务层封装时间转换、数据源切换和批量展开逻辑。
  • 其他模块通过 JOIN special_date 复用时间语义,避免在各处重复实现节假日规则。

在实际使用中,应重点把握:

  • 明确时序表的写入责任边界,尽量批量写入。
  • 为时间范围和人员维度补充合适索引。
  • 使用特殊日期统一管理节假日和自定义事件。
  • 在异常检测中同时考虑时序趋势和特殊日期语义,提高告警的可解释性。