# 治理与其他业务接口

<cite>
**本文引用的文件**   
- [GovernController.java](file://ai-server/src/main/java/com/zsjz/ai/module/govern/controller/GovernController.java)
- [GovernTreeController.java](file://ai-server/src/main/java/com/zsjz/ai/module/govern/controller/GovernTreeController.java)
- [GovernService.java](file://ai-server/src/main/java/com/zsjz/ai/module/govern/serivce/GovernService.java)
- [GovernTreeService.java](file://ai-server/src/main/java/com/zsjz/ai/module/govern/serivce/GovernTreeService.java)
- [GovernConfService.java](file://ai-server/src/main/java/com/zsjz/ai/module/govern/serivce/GovernConfService.java)
- [SearchController.java](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/SearchController.java)
- [TimeSeriesController.java](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/TimeSeriesController.java)
- [SpecialDateController.java](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/SpecialDateController.java)
- [DmController.java](file://ai-server/src/main/java/com/zsjz/ai/module/dm/controller/DmController.java)
- [SearchQueryService.java](file://ai-server/src/main/java/com/zsjz/ai/module/search/service/SearchQueryService.java)
- [TimeSeriesService.java](file://ai-server/src/main/java/com/zsjz/ai/module/otg/service/TimeSeriesService.java)
- [SpecialDateService.java](file://ai-server/src/main/java/com/zsjz/ai/module/otg/service/SpecialDateService.java)
- [DmService.java](file://ai-server/src/main/java/com/zsjz/ai/module/dm/service/DmService.java)
- [GovernTreeQuery.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/govern/query/GovernTreeQuery.java)
- [SearchDTO.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/otg/dto/SearchDTO.java)
- [SearchQuery.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/otg/query/SearchQuery.java)
- [TimeSeriesQuery.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/otg/query/TimeSeriesQuery.java)
- [SpecialDateRecord.java](file://ai-server/src/main/java/com/zsjz/ai/common/model/otg/entity/SpecialDateRecord.java)
</cite>

## 目录

1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细接口说明](#详细接口说明)
6. [依赖关系分析](#依赖关系分析)
7. [性能与并发特性](#性能与并发特性)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)

## 引言

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

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

## 项目结构

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

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

```mermaid
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](file://ai-server/src/main/java/com/zsjz/ai/module/govern/controller/GovernController.java#L1-L72)
- [GovernTreeController.java:1-122](file://ai-server/src/main/java/com/zsjz/ai/module/govern/controller/GovernTreeController.java#L1-L122)
- [SearchController.java:1-26](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/SearchController.java#L1-L26)
- [TimeSeriesController.java:1-37](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/TimeSeriesController.java#L1-L37)
- [SpecialDateController.java:1-44](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/SpecialDateController.java#L1-L44)
- [DmController.java:1-179](file://ai-server/src/main/java/com/zsjz/ai/module/dm/controller/DmController.java#L1-L179)

**章节来源**
- [GovernController.java:1-72](file://ai-server/src/main/java/com/zsjz/ai/module/govern/controller/GovernController.java#L1-L72)
- [GovernTreeController.java:1-122](file://ai-server/src/main/java/com/zsjz/ai/module/govern/controller/GovernTreeController.java#L1-L122)
- [SearchController.java:1-26](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/SearchController.java#L1-L26)
- [TimeSeriesController.java:1-37](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/TimeSeriesController.java#L1-L37)
- [SpecialDateController.java:1-44](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/SpecialDateController.java#L1-L44)
- [DmController.java:1-179](file://ai-server/src/main/java/com/zsjz/ai/module/dm/controller/DmController.java#L1-L179)

## 核心组件

### 治理控制器

`GovernController` 暴露三类能力：

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

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

**章节来源**
- [GovernController.java:1-72](file://ai-server/src/main/java/com/zsjz/ai/module/govern/controller/GovernController.java#L1-L72)
- [GovernService.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/govern/serivce/GovernService.java#L1-L200)

### 治理树控制器

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

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

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

**章节来源**
- [GovernTreeController.java:1-122](file://ai-server/src/main/java/com/zsjz/ai/module/govern/controller/GovernTreeController.java#L1-L122)
- [GovernTreeService.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/govern/serivce/GovernTreeService.java#L1-L200)

### 搜索服务

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

**章节来源**
- [SearchController.java:1-26](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/SearchController.java#L1-L26)
- [SearchQueryService.java:1-108](file://ai-server/src/main/java/com/zsjz/ai/module/search/service/SearchQueryService.java#L1-L108)

### 时序服务

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

**章节来源**
- [TimeSeriesController.java:1-37](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/TimeSeriesController.java#L1-L37)
- [TimeSeriesService.java:1-94](file://ai-server/src/main/java/com/zsjz/ai/module/otg/service/TimeSeriesService.java#L1-L94)

### 特殊日期服务

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

**章节来源**
- [SpecialDateController.java:1-44](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/SpecialDateController.java#L1-L44)
- [SpecialDateService.java:1-118](file://ai-server/src/main/java/com/zsjz/ai/module/otg/service/SpecialDateService.java#L1-L118)

### 数据建模服务

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

**章节来源**
- [DmController.java:1-179](file://ai-server/src/main/java/com/zsjz/ai/module/dm/controller/DmController.java#L1-L179)
- [DmService.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/dm/service/DmService.java#L1-L200)

## 架构总览

```mermaid
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](file://ai-server/src/main/java/com/zsjz/ai/module/govern/controller/GovernController.java#L24-L72)
- [GovernService.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/govern/serivce/GovernService.java#L1-L200)

## 详细接口说明

### 治理任务接口

#### 启动治理计算任务

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

典型调用示例：

```text
GET /govern/calcTask?taskProcess=66
```

注意事项：

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

**章节来源**
- [GovernController.java:24-72](file://ai-server/src/main/java/com/zsjz/ai/module/govern/controller/GovernController.java#L24-L72)
- [GovernService.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/govern/serivce/GovernService.java#L1-L200)

### 治理树接口

#### 获取治理树结构

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

作用：

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

典型调用示例：

```text
GET /gt/tree
```

#### 治理树表格分页

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

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

典型调用示例：

```json
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` |

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

典型调用示例：

```json
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](file://ai-server/src/main/java/com/zsjz/ai/module/govern/controller/GovernTreeController.java#L18-L122)
- [GovernTreeService.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/govern/serivce/GovernTreeService.java#L1-L200)
- [GovernTreeQuery.java:1-47](file://ai-server/src/main/java/com/zsjz/ai/common/model/govern/query/GovernTreeQuery.java#L1-L47)

### 搜索接口

#### 搜索关键词列表

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

`SearchDTO` 字段说明：

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

典型调用示例：

```text
GET /search/list?keyword=转账
```

行为约定：

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

**章节来源**
- [SearchController.java:1-26](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/SearchController.java#L1-L26)
- [SearchQueryService.java:1-108](file://ai-server/src/main/java/com/zsjz/ai/module/search/service/SearchQueryService.java#L1-L108)
- [SearchDTO.java:1-21](file://ai-server/src/main/java/com/zsjz/ai/common/model/otg/dto/SearchDTO.java#L1-L21)

### 时间序列接口

#### 获取时间序列列表

| 项目 | 说明 |
|---|---|
| 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` | 日期 | 结束日期 |

典型调用示例：

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

**章节来源**
- [TimeSeriesController.java:1-37](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/TimeSeriesController.java#L1-L37)
- [TimeSeriesService.java:1-94](file://ai-server/src/main/java/com/zsjz/ai/module/otg/service/TimeSeriesService.java#L1-L94)
- [TimeSeriesQuery.java:1-48](file://ai-server/src/main/java/com/zsjz/ai/common/model/otg/query/TimeSeriesQuery.java#L1-L48)

### 特殊日期接口

#### 列出特殊日期记录

| 项目 | 说明 |
|---|---|
| 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` | 字符串 | 临时日期 |

典型调用示例：

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

**章节来源**
- [SpecialDateController.java:1-44](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/SpecialDateController.java#L1-L44)
- [SpecialDateService.java:1-118](file://ai-server/src/main/java/com/zsjz/ai/module/otg/service/SpecialDateService.java#L1-L118)
- [SpecialDateRecord.java:1-30](file://ai-server/src/main/java/com/zsjz/ai/common/model/otg/entity/SpecialDateRecord.java#L1-L30)

### 数据建模接口

#### 预处理文件

| 项目 | 说明 |
|---|---|
| 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>` |

典型调用示例：

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

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

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

**章节来源**
- [DmController.java:1-179](file://ai-server/src/main/java/com/zsjz/ai/module/dm/controller/DmController.java#L1-L179)
- [DmService.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/dm/service/DmService.java#L1-L200)

## 依赖关系分析

```mermaid
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](file://ai-server/src/main/java/com/zsjz/ai/module/govern/controller/GovernController.java#L1-L72)
- [GovernTreeController.java:1-122](file://ai-server/src/main/java/com/zsjz/ai/module/govern/controller/GovernTreeController.java#L1-L122)
- [GovernService.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/govern/serivce/GovernService.java#L1-L200)
- [GovernTreeService.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/govern/serivce/GovernTreeService.java#L1-L200)
- [GovernConfService.java:1-113](file://ai-server/src/main/java/com/zsjz/ai/module/govern/serivce/GovernConfService.java#L1-L113)
- [SearchController.java:1-26](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/SearchController.java#L1-L26)
- [SearchQueryService.java:1-108](file://ai-server/src/main/java/com/zsjz/ai/module/search/service/SearchQueryService.java#L1-L108)
- [TimeSeriesController.java:1-37](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/TimeSeriesController.java#L1-L37)
- [TimeSeriesService.java:1-94](file://ai-server/src/main/java/com/zsjz/ai/module/otg/service/TimeSeriesService.java#L1-L94)
- [SpecialDateController.java:1-44](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/SpecialDateController.java#L1-L44)
- [SpecialDateService.java:1-118](file://ai-server/src/main/java/com/zsjz/ai/module/otg/service/SpecialDateService.java#L1-L118)
- [DmController.java:1-179](file://ai-server/src/main/java/com/zsjz/ai/module/dm/controller/DmController.java#L1-L179)
- [DmService.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/dm/service/DmService.java#L1-L200)

## 性能与并发特性

### 治理任务并发模型

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

### 文件预处理并发

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

### 搜索结果上限

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

### 时间序列默认跳转方向

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

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

## 故障排查指南

### 治理树结构异常

**现象：**

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

**排查要点：**

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

**相关实现线索：**

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

**章节来源**
- [GovernTreeService.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/govern/serivce/GovernTreeService.java#L1-L200)
- [GovernService.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/govern/serivce/GovernService.java#L1-L200)
- [GovernConfService.java:1-113](file://ai-server/src/main/java/com/zsjz/ai/module/govern/serivce/GovernConfService.java#L1-L113)

### 搜索结果为空

**现象：**

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

**排查要点：**

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

**章节来源**
- [SearchController.java:1-26](file://ai-server/src/main/java/com/zsjz/ai/module/otg/controller/SearchController.java#L1-L26)
- [SearchQueryService.java:1-108](file://ai-server/src/main/java/com/zsjz/ai/module/search/service/SearchQueryService.java#L1-L108)

### 时序数据不完整

**现象：**

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

**排查要点：**

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

**章节来源**
- [TimeSeriesService.java:1-94](file://ai-server/src/main/java/com/zsjz/ai/module/otg/service/TimeSeriesService.java#L1-L94)
- [GovernConfService.java:1-113](file://ai-server/src/main/java/com/zsjz/ai/module/govern/serivce/GovernConfService.java#L1-L113)

### 特殊日期修改或删除失败

**现象：**

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

**排查要点：**

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

**章节来源**
- [SpecialDateService.java:1-118](file://ai-server/src/main/java/com/zsjz/ai/module/otg/service/SpecialDateService.java#L1-L118)

### 数据建模配置错误

**现象：**

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

**排查要点：**

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

**章节来源**
- [DmController.java:1-179](file://ai-server/src/main/java/com/zsjz/ai/module/dm/controller/DmController.java#L1-L179)
- [DmService.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/dm/service/DmService.java#L1-L200)
- [GovernConfService.java:1-113](file://ai-server/src/main/java/com/zsjz/ai/module/govern/serivce/GovernConfService.java#L1-L113)

## 结论

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

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

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

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