治理与其他业务接口

本文引用的文件

GovernController.java
GovernTreeController.java
GovernService.java
GovernTreeService.java
GovernConfService.java
SearchController.java
TimeSeriesController.java
SpecialDateController.java
DmController.java
SearchQueryService.java
TimeSeriesService.java
SpecialDateService.java
DmService.java
GovernTreeQuery.java
SearchDTO.java
SearchQuery.java
TimeSeriesQuery.java
SpecialDateRecord.java

引言

本文面向治理、搜索、时序、特殊日期和数据建模等跨模块业务接口，整理后端控制器与服务层职责，明确各接口的 HTTP 方法、URL、请求参数、响应结构、分页约定和错误行为。文档还解释：

治理树在调查组织关系建模中的作用；
otg 模块中搜索与时间序列的使用场景；
dm 数据建模接口如何辅助外部表、清洗流程与治理计算；
常见异常现象的根因定位方法。

项目结构

本项目的后端以 Spring Boot 为主，相关控制器位于 module 下的不同业务包中：

模块	主要职责	对应控制器
govern	数据治理任务调度、治理树查询、治理配置读写	`GovernController`、`GovernTreeController`
otg	搜索、时间序列、特殊日期等业务能力	`SearchController`、`TimeSeriesController`、`SpecialDateController`
dm	数据建模、文件预览、清洗、外部表与治理配置同步	`DmController`

graph TB
    Client["前端或外部调用方"] --> GovernCtrl["GovernController<br/>治理任务与 SSE"]
    Client --> GovernTreeCtrl["GovernTreeController<br/>治理树与关联分页"]
    Client --> SearchCtrl["SearchController<br/>全文检索"]
    Client --> TimeSeriesCtrl["TimeSeriesController<br/>时间序列"]
    Client --> SpecialDateCtrl["SpecialDateController<br/>特殊日期"]
    Client --> DmCtrl["DmController<br/>数据建模与清洗"]

    GovernCtrl --> GovernSvc["GovernService"]
    GovernTreeCtrl --> GovernTreeSvc["GovernTreeService"]
    SearchCtrl --> SearchSvc["SearchQueryService"]
    TimeSeriesCtrl --> TimeSeriesSvc["TimeSeriesService"]
    SpecialDateCtrl --> SpecialDateSvc["SpecialDateService"]
    DmCtrl --> DmSvc["DmService"]

图示来源

GovernController.java:1-72
GovernTreeController.java:1-122
SearchController.java:1-26
TimeSeriesController.java:1-37
SpecialDateController.java:1-44
DmController.java:1-179

章节来源

GovernController.java:1-72
GovernTreeController.java:1-122
SearchController.java:1-26
TimeSeriesController.java:1-37
SpecialDateController.java:1-44
DmController.java:1-179

核心组件

治理控制器

GovernController 暴露三类能力：

SSE 连接建立：GET /govern/sse；
SSE 控制通道：GET /govern/sse/put；
启动治理计算任务：GET /govern/calcTask。

治理任务由异步线程执行，通过 SSE 推送进度。任务执行前会校验案件上下文，并通过进程内集合防止同一案件重复触发。

章节来源

GovernController.java:1-72
GovernService.java:1-200

治理树控制器

GovernTreeController 提供治理树结构查询及多类关联数据的分页查询，包括：

治理树节点；
交易人员、银行卡；
通话人员、通话对方号码；
开户使用本人、开户使用对方信息。

所有分页接口返回统一包装结构，包含 list 和 total 两类键值，用于前端表格分页渲染。

章节来源

GovernTreeController.java:1-122
GovernTreeService.java:1-200

搜索服务

SearchController 仅暴露一个列表接口，实际检索逻辑在 SearchQueryService 中完成，底层使用 Elasticsearch 进行全文检索，并按时间降序返回最多 500 条结果。

章节来源

SearchController.java:1-26
SearchQueryService.java:1-108

时序服务

TimeSeriesController 提供时间序列列表、详情和跳转查询。时间序列数据通常用于按时间维度展示交易、通话等行为变化。

章节来源

TimeSeriesController.java:1-37
TimeSeriesService.java:1-94

特殊日期服务

SpecialDateController 管理特殊日期记录，支持公历与农历，并可生成前后间隔区间，用于时间轴上的标记。

章节来源

SpecialDateController.java:1-44
SpecialDateService.java:1-118

数据建模服务

DmController 是数据建模与清洗入口，覆盖文件预处理、Web 上传、原始数据预览、清洗任务、批次清理、文件列表、删除、提取数据计算以及治理配置读写。

章节来源

DmController.java:1-179
DmService.java:1-200

架构总览

sequenceDiagram
    participant FE as "前端"
    participant Ctrl as "GovernController"
    participant Svc as "GovernService"
    participant SSE as "SseService"
    participant DB as "数据源"

    FE->>Ctrl: GET /govern/calcTask
    Ctrl->>Ctrl: 校验案件上下文
    Ctrl->>Svc: tryStartGovern(caseId)
    alt 已有同案件任务
        Svc-->>Ctrl: 失败
        Ctrl-->>FE: 业务异常
    else 允许启动
        Svc-->>Ctrl: 成功
        Ctrl->>Svc: calcTask(taskProcess, caseId, userId)
        Note over Svc,DB: 异步执行治理流水线
        Svc->>SSE: 推送进度消息
        Svc->>DB: 写入治理树与中间表
        SSE-->>FE: 实时进度
    end

图示来源

GovernController.java:24-72
GovernService.java:1-200

详细接口说明

治理任务接口

启动治理计算任务

项目	说明
HTTP 方法	GET
URL	`/govern/calcTask`
路径参数	无
查询参数	`taskProcess`，可选，整数，表示任务进度基准
请求体	无
成功响应	`Result<Void>`
失败响应	抛出业务异常，常见原因包括未打开案件、同案件任务已在运行

典型调用示例：

GET /govern/calcTask?taskProcess=66

注意事项：

必须在已打开案件的上下文中调用；
同一案件同时只能运行一条治理流水线；
治理任务由独立线程执行，SSE 进度需要显式绑定用户 ID。

章节来源

GovernController.java:24-72
GovernService.java:1-200

治理树接口

获取治理树结构

项目	说明
HTTP 方法	GET
URL	`/gt/tree`
请求参数	无
响应字段	`Result<List<GovernTree>>`，包含层级节点

作用：

返回机构、银行、运营商等组织的层级树；
节点含 id、父节点 pid、类型、中文表名和数据量等信息；
AI 动态表节点会使用负数 id，并额外下发字符串形式的模板 id，避免前端 JSON 数字精度丢失。

典型调用示例：

GET /gt/tree

治理树表格分页

项目	说明
HTTP 方法	POST
URL	`/gt/treeTablePage`
请求体	`GovernTreeQuery`
响应字段	`Result<Map<String,Object>>`，包含 `pages`、`head`、`detail`

GovernTreeQuery 支持通用分页字段、排序字段、表名、节点 id，以及自定义条件 SQL。

典型调用示例：

POST /gt/treeTablePage
{
  "page": 1,
  "limit": 20,
  "tableName": "trans_record_all",
  "orderKey": "createTime",
  "hasAsc": true
}

治理树关联的交易人员分页

项目	说明
HTTP 方法	POST
URL	`/gt/getTreeTransPersonPage`
请求体	`GovernTreeQuery`
响应字段	`Result<Map<String,Object>>`，包含 `pages`、`head`

过滤条件包括人员名称、卡号、金额、借贷类型、摘要等。若选择“未知对象”，系统会从已知人员卡号集合中排除，再查交易记录。

典型调用示例：

POST /gt/getTreeTransPersonPage
{
  "personName": "张三",
  "money": 1000,
  "moneySymbol": 1,
  "debitCreditFlag": "借"
}

治理树关联的交易银行卡分页

项目	说明
HTTP 方法	POST
URL	`/gt/getTreeTransBankPage`
请求体	`GovernTreeQuery`
响应字段	`Result<Map<String,Object>>`，包含 `pages`、`head`

治理树关联的通话人员分页

项目	说明
HTTP 方法	POST
URL	`/gt/getTreeCallPersonPage`
请求体	`GovernTreeQuery`
响应字段	`Result<Map<String,Object>>`，包含 `pages`、`head`

治理树关联的通话对方号码分页

项目	说明
HTTP 方法	POST
URL	`/gt/getTreeCallOperPage`
请求体	`GovernTreeQuery`
响应字段	`Result<Map<String,Object>>`，包含 `pages`、`head`

治理树关联的开户使用本人信息分页

项目	说明
HTTP 方法	POST
URL	`/gt/getTreeCallPersonUseOpenInfoPage`
请求体	`GovernTreeQuery`
响应字段	`Result<Map<String,Object>>`，包含 `pages`、`head`

治理树关联的开户使用对方信息分页

项目	说明
HTTP 方法	POST
URL	`/gt/getTreeCallOperUseOpenInfoPage`
请求体	`GovernTreeQuery`
响应字段	`Result<Map<String,Object>>`，包含 `pages`、`head`

章节来源

GovernTreeController.java:18-122
GovernTreeService.java:1-200
GovernTreeQuery.java:1-47

搜索接口

搜索关键词列表

项目	说明
HTTP 方法	GET
URL	`/search/list`
查询参数	`keyword`，可选
响应字段	`Result<List<SearchDTO>>`

SearchDTO 字段说明：

字段	类型	含义
`id`	字符串	行标识
`sheetId`	字符串	工作表标识
`fileId`	字符串	文件标识
`dateTime`	时间戳	文档时间
`content`	字符串	内容片段，可能包含高亮标签
`tableName`	字符串	所属表
`fileName`	字符串	文件名
`sheetName`	字符串	工作表名

典型调用示例：

GET /search/list?keyword=转账

行为约定：

空关键词返回空列表；
没有案件上下文时跳过检索，返回空列表；
最大返回 500 条；
内容按时间降序；
内容中包含 <em class="search-highlight"> 高亮片段。

章节来源

SearchController.java:1-26
SearchQueryService.java:1-108
SearchDTO.java:1-21

时间序列接口

获取时间序列列表

项目	说明
HTTP 方法	POST
URL	`/otg/timeSeries/list`
请求体	`TimeSeriesQuery`
响应字段	`Result<List<TimeSeries>>`

时间序列详情

项目	说明
HTTP 方法	POST
URL	`/otg/timeSeries/detailTimeSeries`
请求体	`TimeSeriesQuery`
响应字段	`Result<Map<String,Object>>`，包含 `head` 和 `dt`

时间序列跳转

项目	说明
HTTP 方法	POST
URL	`/otg/timeSeries/jump`
请求体	`TimeSeriesQuery`
响应字段	`Result<List<TimeSeries>>`

TimeSeriesQuery 关键字段：

字段	类型	含义
`hasLocal`	字符串	是否包含本地数据，Y 或 N
`tableNameEn`	字符串	中文表名
`types`	数组	时序类型
`id`	长整型	源数据 id
`rowId`	长整型	当前时间轴位置
`rowIdSymbol`	枚举	滚动方向
`startDate`	日期	起始日期
`endDate`	日期	结束日期

典型调用示例：

POST /otg/timeSeries/list
{
  "id": 1001,
  "types": ["CALL_RECORD", "TRANS_RECORD"],
  "startDate": "2026-01-01",
  "endDate": "2026-10-28"
}

章节来源

TimeSeriesController.java:1-37
TimeSeriesService.java:1-94
TimeSeriesQuery.java:1-48

特殊日期接口

列出特殊日期记录

项目	说明
HTTP 方法	GET
URL	`/sdc/list`
响应字段	`Result<List<SpecialDateRecord>>`

创建特殊日期记录

项目	说明
HTTP 方法	POST
URL	`/sdc/create`
请求体	`SpecialDateRecord`
响应字段	`Result<Void>`

更新特殊日期记录

项目	说明
HTTP 方法	POST
URL	`/sdc/update`
请求体	`SpecialDateRecord`
响应字段	`Result<Void>`

删除特殊日期记录

项目	说明
HTTP 方法	GET
URL	`/sdc/delete`
查询参数	`id`，长整型
响应字段	`Result<Void>`

SpecialDateRecord 关键字段：

字段	类型	含义
`id`	长整型	记录 id
`name`	字符串	名称
`flag`	整数	内置或用户添加
`type`	整数	0 公历，1 农历
`gap`	整数	前后间隔天数
`spDate`	字符串	临时日期

典型调用示例：

POST /sdc/create
{
  "name": "春节",
  "type": 1,
  "gap": 1,
  "spDate": "01-01"
}

章节来源

SpecialDateController.java:1-44
SpecialDateService.java:1-118
SpecialDateRecord.java:1-30

数据建模接口

预处理文件

项目	说明
HTTP 方法	POST
URL	`/dm/preFile`
请求体	`PrepareProcessFileDTO`
响应字段	`Result<List<FileInfo>>`

上传文件并预处理

项目	说明
HTTP 方法	POST
URL	`/dm/preFileUpload`
内容类型	`multipart/form-data`
表单字段	`file`
查询参数	`batchId`、`reClean`
响应字段	`Result<FileInfo>`

预览原始数据

项目	说明
HTTP 方法	POST
URL	`/dm/rawPreview`
请求体	`RawPreviewQuery`
响应字段	`Result<RawPreviewDTO>`

执行清洗任务

项目	说明
HTTP 方法	POST
URL	`/dm/doClean`
请求体	`DoCleanDTO`
响应字段	`Result<Void>`

取消清洗任务

项目	说明
HTTP 方法	GET
URL	`/dm/cancelClean`
查询参数	`batchId`
响应字段	`Result<Void>`

清理上传批次

项目	说明
HTTP 方法	GET
URL	`/dm/clearUploadBatch`
查询参数	`batchId`
响应字段	`Result<Void>`

获取文件列表

项目	说明
HTTP 方法	POST
URL	`/dm/getFiles`
请求体	`FileInfoQuery`
响应字段	`Result<List<FileInfo>>`

删除文件

项目	说明
HTTP 方法	POST
URL	`/dm/deletedFiles`
请求体	`DeletedFilesDTO`
响应字段	`Result<Void>`

计算提取数据

项目	说明
HTTP 方法	GET
URL	`/dm/calcData`
查询参数	`batchId`
响应字段	`Result<CalcDataDTO>`

获取治理配置列表

项目	说明
HTTP 方法	GET
URL	`/dm/getGovernConfList`
响应字段	`Result<List<GovernConf>>`

保存或更新治理配置

项目	说明
HTTP 方法	POST
URL	`/dm/saveGovernCon`
请求体	`List<GovernConf>`
响应字段	`Result<Void>`

典型调用示例：

POST /dm/preFileUpload
Content-Type: multipart/form-data

file: <Excel 或 CSV 文件>
batchId: 1700000000000000001
reClean: 1

POST /dm/rawPreview
{
  "sheetId": "sheet_1",
  "headerRowIndex": 0,
  "headers": [],
  "limit": 2000
}

章节来源

DmController.java:1-179
DmService.java:1-200

依赖关系分析

classDiagram
    class GovernController {
        +sse()
        +ssePut()
        +start(taskProcess)
    }

    class GovernTreeController {
        +getTree()
        +treeTablePage(dto)
        +getTreeTransPersonPage(dto)
        +getTreeTransBankPage(dto)
        +getTreeCallPersonPage(dto)
        +getTreeCallOperPage(dto)
        +getTreeCallPersonUseOpenInfoPage(dto)
        +getTreeCallOperUseOpenInfoPage(dto)
    }

    class GovernService {
        +calcTask(taskProcess, caseId, userId)
        +tryStartGovern(caseId)
        +calcTreeTemplateDataCnt()
    }

    class GovernTreeService {
        +getTree()
        +getTreeTablePage(dto)
        +getTreeTransPersonPage(dto)
    }

    class GovernConfService {
        +saveGovernConfBatch(list)
        +getCallTableName()
        +getTransTableName()
        +useOpenInfo()
        +useDuplicate()
    }

    class SearchController {
        +search(query)
    }

    class SearchQueryService {
        +search(keyword)
    }

    class TimeSeriesController {
        +getTimeSeries(query)
        +detailTimeSeries(query)
        +jumpTimeSeries(query)
    }

    class TimeSeriesService {
        +getTimeSeries(query)
        +detailTimeSeries(query)
        +jumpTimeSeries(query)
    }

    class SpecialDateController {
        +list()
        +create(sdr)
        +update(sdr)
        +delete(id)
    }

    class SpecialDateService {
        +create(sdr)
        +update(sdr)
        +delete(id)
        +listRecord()
    }

    class DmController {
        +preProcessFile(dto)
        +preFileUpload(file,batchId,reClean)
        +rawPreview(query)
        +doClean(dto)
        +cancelClean(batchId)
        +clearUploadBatch(batchId)
        +getFiles(query)
        +deletedFiles(dto)
        +calcData(batchId)
        +getGovernConfList()
        +saveOrUpdate(list)
    }

    class DmService {
        +preProcessFile(dto)
        +preProcessUploadedFile(file,batchId,reClean)
        +rawPreview(query)
        +doClean(dto)
        +calcData(batchId)
    }

    GovernController --> GovernService : "调用"
    GovernTreeController --> GovernTreeService : "调用"
    GovernService --> GovernConfService : "读取表名与开关"
    GovernTreeService --> GovernConfService : "读取表名与开关"
    SearchController --> SearchQueryService : "调用"
    TimeSeriesController --> TimeSeriesService : "调用"
    SpecialDateController --> SpecialDateService : "调用"
    DmController --> DmService : "调用"
    DmController --> GovernConfService : "读取配置"

图示来源

GovernController.java:1-72
GovernTreeController.java:1-122
GovernService.java:1-200
GovernTreeService.java:1-200
GovernConfService.java:1-113
SearchController.java:1-26
SearchQueryService.java:1-108
TimeSeriesController.java:1-37
TimeSeriesService.java:1-94
SpecialDateController.java:1-44
SpecialDateService.java:1-118
DmController.java:1-179
DmService.java:1-200

性能与并发特性

治理任务并发模型

治理任务使用虚拟线程执行器，每个任务一条虚拟线程，避免旧线程池被大案件占满。同一案件通过进程内集合互斥，防止双击或多标签页并发导致共享表被互相清空。

文件预处理并发

文件预处理限制最大并发度，并使用信号量控制并发解析数量，单个任务设置超时，整体处理也受超时保护。

搜索结果上限

全文检索最多返回 500 条结果，默认按时间降序排列。

时间序列默认跳转方向

时间序列跳转默认使用大于方向，未显式传滚动方向时会采用默认符号。

[本节为通用性能说明，不直接分析具体代码行]

故障排查指南

治理树结构异常

现象：

治理树为空；
只有机构节点，没有银行、运营商或子表节点；
AI 模板节点在前端显示异常。

排查要点：

确认已执行治理计算任务，且 dataCount 不为零；
检查治理树构建是否基于有数据的内部表；
检查治理配置是否正确，尤其是通话表和交易表映射；
若存在 AI 动态表，确认模板 id 是否以字符串形式下发。

相关实现线索：

治理树构建会过滤数据量为正的节点；
AI 模板节点 id 为负数，需转换为字符串模板 id；
治理任务会清理治理配置缓存并重新统计。

章节来源

GovernTreeService.java:1-200
GovernService.java:1-200
GovernConfService.java:1-113

搜索结果为空

现象：

调用 /search/list 返回空列表；
关键字能匹配内容但无结果。

排查要点：

检查是否传入非空 keyword；
检查是否处于有效案件上下文；
检查 Elasticsearch 中是否存在对应案件的文档；
检查关键词大小写，服务端会统一转为小写；
注意搜索结果最多 500 条。

章节来源

SearchController.java:1-26
SearchQueryService.java:1-108

时序数据不完整

现象：

时间序列列表缺少部分时间段；
详情接口报错；
跳转后数据顺序不符合预期。

排查要点：

检查 TimeSeriesQuery 中的 id、types、时间范围；
检查 detailTimeSeries 中传入的 tableName 是否在系统表映射中存在；
检查是否启用了开户信息或去重配置，导致底层表名变化；
检查跳转方向是否误用。

章节来源

TimeSeriesService.java:1-94
GovernConfService.java:1-113

特殊日期修改或删除失败

现象：

修改特殊日期报业务异常；
删除内置日期失败；
新增农历日期后区间不正确。

排查要点：

修改和删除时必须传入有效的 id；
内置日期不可修改和删除；
农历日期会根据年份展开到前后 20 年；
gap 为空时不生成区间，type 为空时按公历处理。

章节来源

SpecialDateService.java:1-118

数据建模配置错误

现象：

预处理返回空结果；
上传不支持后缀只登记失败状态；
清洗任务无法找到目标表；
治理配置保存时报数据库错误。

排查要点：

确认请求体是否为 application/json，POST 对象入参必须加请求体注解；
仅 csv、xls、xlsx 会被真实上传解析；
不支持后缀会登记失败状态，但仍保留记录；
清洗任务依赖 batchId、文件信息和清洗配置；
治理配置批量保存需要在案件库事务中执行，否则可能读到主库或报关系不存在；
治理计算依赖通话表、交易表的正确映射。

章节来源

DmController.java:1-179
DmService.java:1-200
GovernConfService.java:1-113

结论

治理与其他业务接口围绕“数据建模 → 治理计算 → 可视分析”这条主线展开：

dm 模块负责把外部表、清洗规则、文件元数据和治理配置导入系统；
govern 模块根据配置执行治理计算，输出治理树和关联数据；
otg 模块提供搜索、时间序列和特殊日期能力，帮助前端按人员和时间维度还原调查关系；
治理树是组织关系建模的核心载体，其节点既反映机构层级，也承载各类业务表的数据量与关联查询入口。

调用这些接口时，应重点关注：

是否处于正确的案件上下文；
治理配置是否指向正确的通话表和交易表；
搜索是否命中索引文档；
时序查询是否匹配目标表和类型；
特殊日期是否配置了合法 id、类型和间隔；
数据建模请求是否使用正确的 content-type 和必填字段。

治理与其他业务接口.md 31 KB Vēsture Neapstrādāts

治理与其他业务接口

目录

引言

项目结构

核心组件

治理控制器

治理树控制器

搜索服务

时序服务

特殊日期服务

数据建模服务

架构总览

详细接口说明

治理任务接口

启动治理计算任务

治理树接口

获取治理树结构

治理树表格分页

治理树关联的交易人员分页

治理树关联的交易银行卡分页

治理树关联的通话人员分页

治理树关联的通话对方号码分页

治理树关联的开户使用本人信息分页

治理树关联的开户使用对方信息分页

搜索接口

搜索关键词列表

时间序列接口

获取时间序列列表

时间序列详情

时间序列跳转

特殊日期接口

列出特殊日期记录

创建特殊日期记录

更新特殊日期记录

删除特殊日期记录

数据建模接口

预处理文件

上传文件并预处理

预览原始数据

执行清洗任务

取消清洗任务

清理上传批次

获取文件列表

删除文件

计算提取数据

获取治理配置列表

保存或更新治理配置

依赖关系分析

性能与并发特性

治理任务并发模型

文件预处理并发

搜索结果上限

时间序列默认跳转方向

故障排查指南

治理树结构异常

搜索结果为空

时序数据不完整

特殊日期修改或删除失败

数据建模配置错误

结论

治理与其他业务接口.md 31 KB

Vēsture Neapstrādāts