本文引用的文件
时序与特殊日期模块 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
图表来源
章节来源
/otg/timeSeries 下的列表、详情和跳转接口。/sdc 下的列表、创建、更新、删除接口。/search/list,委托给搜索服务做关键词检索。章节来源
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: 成功响应
图表来源
时序控制器提供三类操作:
时序查询支持以下维度:
hasLocal=Y 要求 ext8、ext9 非空,用于区分是否包含本地数据。人员名称、时间范围、滚动方向、目标 ID 或时间轴 ID。
flowchart TD
Start(["进入列表接口"]) --> ParseTime["解析起止日期为时间戳"]
ParseTime --> FlattenTypes["扁平化 types"]
FlattenTypes --> BuildQuery["构建查询参数"]
BuildQuery --> Execute["执行 selectTimeSeriesList"]
Execute --> Limit["限制最多 20 条"]
Limit --> Return(["返回结果"])
图表来源
章节来源
详情接口会:
跳转接口则通过 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: 成功响应
图表来源
章节来源
特殊日期是用于标注“某天不是普通工作日”的日历概念,至少包括:
数据模型分为两层:
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 : "业务通过日期范围间接关联"
图表来源
章节来源
特殊日期控制器暴露的基础操作如下:
| 方法 | 路径 | 用途 | 主要行为 |
|---|---|---|---|
| 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(["完成"])
图表来源
章节来源
特殊日期表被其他模块通过日期范围 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["亲密关系查询"]
图表来源
章节来源
搜索控制器只暴露 /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: 成功响应
图表来源
章节来源
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
图表来源
章节来源
time_series_info 是聚合型表,通常由上游同步任务批量写入。personName 和 otherName。seriesDateTime 范围查询,应增加时间索引。当前列表查询限制 20 条,能缓解全表扫描压力,但大表仍建议加索引。
flowchart TD
Start(["评估时序写入与查询模式"]) --> Analyze["分析高频查询条件"]
Analyze --> AddIndex["为 seriesDateTime 或 personName+seriesDateTime 添加索引"]
AddIndex --> BatchWrite["使用批量写入 time_series_info"]
BatchWrite --> Monitor["监控慢查询与表增长"]
Monitor --> Tune["调整分页大小、索引和同步策略"]
图表来源
seriesDateTime 作为时间轴主键字段,避免业务表各自使用时间字段导致无法对齐。tableNameEn 区分数据来源,配合 personName、otherName 做主体关联。ext1~ext9 保留扩展字段,但不要无节制扩展;优先保持可读性和稳定性。special_date 的 startDate、endDate 做时间语义判断,而不是在业务代码里硬编码节假日规则。special_date,确保节假日、工作日和自定义事件日能被一致识别。章节来源
步骤:
/sdc 中新增一个特殊日期,例如“春节假期”,选择公历或农历,并可设置前后间隔。startDate 到 endDate 区间。special_date 的日期范围过滤,即可得到节假日或工作日对应的行为数据。相关实现位置:
步骤:
/sdc/create 中标记某个自定义事件日,例如“系统封网演练”。/otg/timeSeries/list 拉取该人物或该表类型的时序趋势。special_date.name 输出告警原因,例如“封网期间交易量下降超阈值”。相关实现位置:
步骤:
/otg/timeSeries/jump,传入该记录的 ID 和时间轴 ID。相关实现位置:
现象:调用 /sdc/update 报缺少日期记录 ID。
原因:请求体未传 ID,而代码对包装类型做了安全判空,并抛出业务异常。
处理:
id。相关实现位置:
现象:调用 /sdc/delete 报缺少日期记录 ID。
原因:同上,对包装类型 ID 做了空值检查。
处理:
相关实现位置:
现象:调用 /otg/timeSeries/detailTimeSeries 报未找到表信息。
原因:请求中的表名没有对应的 MyBatis-Plus 表元信息。
处理:
tableNameEn 与实际表名一致。相关实现位置:
现象:特殊日期写入主库而非从库。 原因:批量保存不走 Mapper 代理,需要在外层方法上切从库数据源。 处理:
create 和 update 方法上的从库注解生效。相关实现位置:
章节来源
otg 模块以 time_series_info 和 special_date 为核心,把时间维度从业务表中抽象出来:
special_date 复用时间语义,避免在各处重复实现节假日规则。在实际使用中,应重点把握: