交易数据接口

本文引用的文件

TransFundFlowController.java
TransFastFundFlowController.java
TransFixedDepositController.java
TransFinancialController.java
CashKeyController.java
TransRecordController.java

引言

本文面向使用后端交易数据的开发者、分析师和调查人员，整理交易相关控制器的对外 API。重点覆盖：

资金流水
快速流水
固定存款
金融关键词统计
现金关键字配置
以及后续扩展的大额、频率、连续、卡持、敏感等交易分析接口

每个接口均说明 HTTP 方法、URL、请求体结构、主要返回字段、分页方式、排序方式和常见错误处理思路，并补充交易数据与人员、账户、交易对手、治理树之间的关系说明。

项目结构与控制器总览

交易类接口集中在 com.zsjz.ai.module.trans.controller 包下，采用 Spring REST 风格，统一通过 POST 或 GET 暴露，并以统一结果对象包装返回。

graph TB
    subgraph "交易控制器层"
        TF["TransFundFlowController<br/>资金流向"]
        TFF["TransFastFundFlowController<br/>快速流水"]
        TFD["TransFixedDepositController<br/>固定存款"]
        TFT["TransFinancialController<br/>金融分析"]
        CK["CashKeyController<br/>现金关键字配置"]
        TR["TransRecordController<br/>交易记录"]
    end

    subgraph "服务层与模型"
        SVC["Service 业务逻辑"]
        DTO["DTO/Query 请求与响应对象"]
    end

    TF --> SVC
    TFF --> SVC
    TFD --> SVC
    TFT --> SVC
    CK --> SVC
    TR --> SVC

    SVC --> DTO

图示来源

TransFundFlowController.java:1-60
TransFastFundFlowController.java:1-35
TransFixedDepositController.java:1-55
TransFinancialController.java:1-36
CashKeyController.java:1-58
TransRecordController.java

章节来源

TransFundFlowController.java:1-60
TransFastFundFlowController.java:1-35
TransFixedDepositController.java:1-55
TransFinancialController.java:1-36
CashKeyController.java:1-58
TransRecordController.java

核心业务关系说明

交易数据在系统中通常围绕以下实体展开：

人员：交易发起方或受益方的自然人或单位主体。
账户：银行账户、卡号、电子钱包账号等资金载体。
交易对手：交易的另一方，可能是账户、人员或机构。
治理树：组织、案件、任务或调查对象的层级结构，用于权限、范围和数据归属划分。

典型关系如下：

erDiagram
  PERSON ||--o{ ACCOUNT : "拥有或关联"
  ACCOUNT ||--o{ TRANSACTION : "发生交易"
  PERSON ||--o{ TRANSACTION : "作为交易一方"
  TRANSACTION ||--o{ COUNTERPARTY : "对应交易对手"
  GOVERN_TREE ||--o{ TRANSACTION : "数据归属或权限范围"

该关系有助于理解不同接口的查询维度：

按账户查询：适合追踪资金进出路径、对手账户分布、快转和资金流向。
按人员查询：适合刻画人员资金画像、高频交易对手、敏感交易特征。
结合治理树：可限定某个案件、组织或调查范围内的交易数据。

图示来源

TransFundFlowController.java:1-60
TransFastFundFlowController.java:1-35
TransFixedDepositController.java:1-55
TransFinancialController.java:1-36

接口总表

资金流向接口

基础信息
- 控制器：TransFundFlowController
- 根路径：/trans/fundsFlow
- 认证与鉴权：由系统统一拦截器或网关控制；调用前需具备相应案件或数据源权限。

序号	方法	URL	请求体类型	主要用途	主要返回字段	分页	排序
1	POST	`/trans/fundsFlow/getTransFundFlowPage`	`TransRecordQuery`	分页查询资金流向数据	资金流向列表、总数、当前页、每页条数	支持	通常依赖 Query 中的排序字段
2	POST	`/trans/fundsFlow/graph`	`TransFlowGraphQuery`	资金流向图分析	树形节点、节点关系、汇总金额	不适用	不适用
3	POST	`/trans/fundsFlow/trace`	`TransFlowGraphQuery`	资金流向追溯分析	追溯链、上游下游账户、关键中转节点	不适用	不适用

请求参数要点
- 资金流向分页接口使用 TransRecordQuery，通常包含账户、人员、时间范围、金额范围、交易对手、治理范围等筛选条件。
- 图和追溯接口使用 TransFlowGraphQuery，通常以账户或人员为起点，限制深度、时间范围和金额阈值。
响应字段要点
- 分页接口返回 MyBatis-Plus 的 Page 对象，包含列表、总数、页码、每页大小等。
- 图和追溯接口返回 TransFlowDTO，用于展示资金流动拓扑。

章节来源

TransFundFlowController.java:1-60

快速流水接口

基础信息
- 控制器：TransFastFundFlowController
- 根路径：/trans/fastFundFlow
- 业务含义：快速资金流转，常用于识别快进快出、分散转入集中转出等可疑行为。

序号	方法	URL	请求体类型	主要用途	主要返回字段	分页	排序
1	POST	`/trans/fastFundFlow/statFirstTransFastFundFlow`	`TransFastFundFlowQuery`	统计首次资金快转流水	银行统计、交易明细、首笔快转标识	不适用	不适用

请求参数要点
- 通常包含人员卡号、时间范围、金额阈值、快转判定规则等。
- 适用于对指定人员在指定时间内的快转行为进行定位。
响应字段要点
- 返回 TransFastFundFlowDTO，包含银行维度的统计信息和具体交易明细。

章节来源

TransFastFundFlowController.java:1-35

固定存款接口

基础信息
- 控制器：TransFixedDepositController
- 根路径：/trans/fixedDeposit
- 业务含义：定期存款属于中长期资金沉淀，常用于识别资金存放、资产固化、规避短期监控等行为。

序号	方法	URL	请求体类型	主要用途	主要返回字段	分页	排序
1	POST	`/trans/fixedDeposit/statFirstTransFixedDeposit`	`TransFixedDepositQuery`	统计首层定期存款汇总	人员姓名、账户、收入总额、支出总额	否	否
2	POST	`/trans/fixedDeposit/statSecondTransFixedDepositList`	`TransFixedDepositQuery`	统计第二层定期存款明细	明细列表、账户变动明细	是	是

请求参数要点
- 通常包含人员姓名、日期范围、账户、治理范围、分页和排序字段。
- 第一层接口侧重人员汇总；第二层接口侧重账户级明细。
响应字段要点
- 第一层返回 List<TransPersonFixedDepositDTO>。
- 第二层返回 Page<TransPersonFixedDepositDetailDTO>，包含分页字段。

章节来源

TransFixedDepositController.java:1-55

金融分析接口

基础信息
- 控制器：TransFinancialController
- 根路径：/trans/financial
- 业务含义：根据金融关键词或分类对交易进行统计，辅助发现特定金融行为模式。

序号	方法	URL	请求体类型	主要用途	主要返回字段	分页	排序
1	POST	`/trans/financial/statFirstTransFinancial`	`TransFinancialQuery`	统计首笔交易金融数据	金融统计项、金额、频次、账户或人员聚合	是	是

请求参数要点
- 通常包含分页参数、金融关键词、账户、人员、时间范围、治理范围等。
响应字段要点
- 返回 Page<TransFinancialDTO>，适合前端表格分页展示。

章节来源

TransFinancialController.java:1-36

现金关键字配置接口

基础信息
- 控制器：CashKeyController
- 根路径：/trans/cashKey
- 业务含义：管理“现金”相关的关键词配置，用于后续现金交易识别、清洗或分析。

序号	方法	URL	请求体类型	主要用途	主要返回字段	分页	排序
1	GET	`/trans/cashKey/list`	无	获取所有现金关键字	现金关键字列表	否	否
2	POST	`/trans/cashKey/createOrUpdate`	`TransCashKey`	创建或更新现金关键字	布尔值，表示是否成功	否	否
3	GET	`/trans/cashKey/delete`	`id` 查询参数	根据 ID 删除现金关键字	布尔值，表示是否成功	否	否

请求参数要点
- 创建或更新接口传入 TransCashKey 实体，通常包含 ID、关键字内容、启用状态等。
- 删除接口通过 URL 查询参数 id 指定要删除的记录。
响应字段要点
- 列表返回 List<TransCashKey>。
- 写操作返回 Boolean，表示保存或删除是否成功。

章节来源

CashKeyController.java:1-58

其他交易分析接口（扩展说明）

以下控制器在当前仓库中已存在，但本文未逐行展开其源码。实际使用时应参考对应 Controller、Service、DTO 和 Mapper 定义确认具体字段和行为：

大额交易：TransBigController、TransBigService、TransBigQuery、TransBigDTO
频率交易：TransFrequencyController、TransFrequencyService、TransFrequencyQuery、TransFrequencyDTO
连续交易：TransContinuousController、TransContinuousService、TransContinuousQuery、TransContinuousDTO
卡持交易：TransCardHoldController、TransCardHoldService
敏感交易：TransSensitiveController、TransSensitiveService、TransSensitiveDTO
交易记录：TransRecordController、TransRecordService、TransRecordQuery、TransRecord

这些接口通常遵循相同约定：

查询接口多使用 POST + JSON 请求体。
列表接口多返回 Page<T>。
写操作多返回 Result<Boolean> 或 Result<Void>。
分页字段通常为 current、size、total、pages、records。
排序字段通常在 Query 对象中提供，如 sortField、orderDirection。

章节来源

TransRecordController.java

按账户查询交易示例

以资金流向分页接口为例，说明如何按账户查询交易。

HTTP 方法：POST
URL：/trans/fundsFlow/getTransFundFlowPage

请求体示例

{
"account": "示例账户",
"startTime": "2025-01-01 00:00:00",
"endTime": "2025-12-31 23:59:59",
"minAmount": 0,
"maxAmount": 1000000,
"current": 1,
"size": 20
}

主要字段说明
- account：账户或卡号，用于限定交易主体。
- startTime、endTime：时间范围，必须满足时间格式要求。
- minAmount、maxAmount：金额范围，用于过滤小额或异常大额交易。
- current、size：分页参数。

响应示例

{
"code": 200,
"message": "success",
"data": {
"records": [],
"total": 0,
"current": 1,
"size": 20
}
}

注意事项
- 如果时间范围过长或数据量过大，建议先缩小时间窗口或增加金额、对手、治理范围等筛选条件。
- 若需要进一步分析资金去向，可继续调用 /trans/fundsFlow/graph 或 /trans/fundsFlow/trace。

章节来源

TransFundFlowController.java:1-60

按人员查询交易示例

以快速流水接口为例，说明如何按人员查询资金快转行为。

HTTP 方法：POST
URL：/trans/fastFundFlow/statFirstTransFastFundFlow

请求体示例

{
"personId": "示例人员ID",
"cardNo": "示例卡号",
"startTime": "2025-06-01 00:00:00",
"endTime": "2025-06-30 23:59:59",
"thresholdAmount": 50000
}

主要字段说明
- personId：人员标识。
- cardNo：人员关联的银行卡号。
- startTime、endTime：快转行为观察窗口。
- thresholdAmount：快转金额阈值，用于判断是否构成快速流转。

响应示例

{
"code": 200,
"message": "success",
"data": {
"bankStats": [],
"transactionDetails": []
}
}

调查意义
- 快速流水常用于识别“快进快出”“分散转入、集中转出”等可疑资金行为。
- 结合人员画像和交易对手网络，可进一步判断是否存在洗钱、转移资产或规避监管行为。

章节来源

TransFastFundFlowController.java:1-35

分页、排序与通用响应

分页约定

分页接口通常返回 Page<T>，字段包括：
- records：当前页数据列表。
- total：符合条件的总记录数。
- current：当前页码。
- size：每页条数。
- pages：总页数。
推荐分页策略：
- 默认 current=1、size=20。
- 大数据量场景建议 size≤100。
- 前端应根据 total 计算总页数并禁用无效页码。

排序约定

排序参数通常位于 Query 对象中，例如：
- sortField：排序字段名。
- orderDirection：升序或降序。
常见排序字段：
- 交易时间：按最近交易优先。
- 金额：按金额绝对值或净额排序。
- 账户或人员：按主体名称或编号排序。

通用响应结构

大多数接口返回统一包装对象，典型结构如下：

{
  "code": 200,
  "message": "success",
  "data": {}
}

code：业务状态码。
message：提示信息。
data：业务数据，可能是列表、分页对象、树形结构或布尔值。

章节来源

TransFundFlowController.java:1-60
TransFixedDepositController.java:1-55
TransFinancialController.java:1-36
CashKeyController.java:1-58

错误码与排查指南

常见错误场景

错误类型	可能原因	排查建议
请求参数缺失	未传必要字段，如账户、人员、时间范围	检查 JSON 字段名是否与接口定义一致
时间格式错误	时间字符串不符合服务端解析格式	使用标准日期时间格式，避免时区歧义
金额格式错误	金额字段为空、非数字或负数	校验最小值、最大值和数值类型
时间范围过长	查询跨度太大导致性能问题	缩短时间范围，分批次查询
数据量过大	未分页或分页 size 过大	调整 `current`、`size`，增加更多筛选条件
权限不足	当前用户无权访问该案件或数据源	检查登录身份、案件归属、数据源权限
配置缺失	现金关键字、金融关键词未配置	调用配置接口查看或新增关键字

排查流程

flowchart TD
    Start["收到接口错误"] --> CheckParam["检查请求参数是否完整"]
    CheckParam --> ParamValid{"参数是否合法"}
    ParamValid -->|否| FixParam["修正字段名、类型或必填项"]
    ParamValid -->|是| CheckTime["检查时间范围和时间格式"]
    CheckTime --> TimeValid{"时间是否有效"}
    TimeValid -->|否| FixTime["修正时间格式或缩短时间范围"]
    TimeValid -->|是| CheckAmount["检查金额范围和格式"]
    CheckAmount --> AmountValid{"金额是否有效"}
    AmountValid -->|否| FixAmount["修正金额字段"]
    AmountValid -->|是| CheckDataSize["检查数据量和分页设置"]
    CheckDataSize --> SizeValid{"是否合理分页"}
    SizeValid -->|否| AdjustPage["调整 current 和 size"]
    SizeValid -->|是| CheckPermission["检查用户权限和数据源"]
    CheckPermission --> PermValid{"是否有权限"}
    PermValid -->|否| FixAuth["检查登录、案件和数据源权限"]
    PermValid -->|是| LogCheck["查看后端日志和服务端错误"]
    FixParam --> End["重新调用"]
    FixTime --> End
    FixAmount --> End
    AdjustPage --> End
    FixAuth --> End
    LogCheck --> End

图示来源

TransFundFlowController.java:1-60
TransFastFundFlowController.java:1-35
TransFixedDepositController.java:1-55
TransFinancialController.java:1-36
CashKeyController.java:1-58

章节来源

TransFundFlowController.java:1-60
TransFastFundFlowController.java:1-35
TransFixedDepositController.java:1-55
TransFinancialController.java:1-36
CashKeyController.java:1-58

高频、大额、敏感交易在调查中的作用

高频交易

典型表现
- 同一账户在短时间内频繁转账。
- 同一人员与多个交易对手反复发生交易。
调查价值
- 识别经营性账户异常、洗钱通道、资金池归集。
- 结合频率分析接口可发现异常活跃账户和人员。

大额交易

典型表现
- 单笔或累计金额超过阈值。
- 短时间内出现多笔接近阈值的大额交易。
调查价值
- 识别大额资产转移、逃避监管、套现或非法资金结算。
- 大额接口通常配合金额阈值、时间窗口和对手分析。

敏感交易

典型表现
- 涉及敏感关键词、敏感地区、敏感对手或敏感时间。
- 与现金、地下钱庄、虚拟货币、跨境资金等相关联。

调查价值

敏感接口可用于标记高风险交易线索。

常与高频、大额、快速流水组合使用，形成风险画像。

flowchart TD
Raw["原始交易数据"] --> HighFreq["高频交易分析"]
Raw --> BigAmt["大额交易分析"]
Raw --> Sensitive["敏感交易分析"]
HighFreq --> RiskProfile["风险画像"]
BigAmt --> RiskProfile
Sensitive --> RiskProfile
RiskProfile --> Investigation["调查分析与取证"]

[本图为概念性流程图，不直接映射具体源码文件]

章节来源

TransFastFundFlowController.java:1-35
TransFinancialController.java:1-36

结论

交易数据接口体系以账户、人员、交易对手和治理范围为基本查询维度，提供资金流向、快速流水、固定存款、金融分析、现金关键字配置等能力。实际使用中应：

优先明确查询目标：是按账户追踪资金路径，还是按人员刻画资金行为。
严格控制时间范围和金额范围，避免一次性拉取过多数据。
合理使用分页和排序，保证前端展示和后端性能。
将高频、大额、敏感交易结合分析，构建更完整的调查线索。
遇到问题时，从参数、时间、金额、分页、权限、配置和日志六个方向逐步排查。

交易数据接口.md 23 KB

Geschiedenis Ruwe

交易数据接口

目录

引言

项目结构与控制器总览

核心业务关系说明

接口总表

资金流向接口

快速流水接口

固定存款接口

金融分析接口

现金关键字配置接口

其他交易分析接口（扩展说明）

按账户查询交易示例

按人员查询交易示例

分页、排序与通用响应

分页约定

排序约定

通用响应结构

错误码与排查指南

常见错误场景

排查流程

高频、大额、敏感交易在调查中的作用

高频交易

大额交易

敏感交易

结论

交易数据接口.md 23 KB Geschiedenis Ruwe

交易数据接口

目录

引言

项目结构与控制器总览

核心业务关系说明

接口总表

资金流向接口

快速流水接口

固定存款接口

金融分析接口

现金关键字配置接口

其他交易分析接口（扩展说明）

按账户查询交易示例

按人员查询交易示例

分页、排序与通用响应

分页约定

排序约定

通用响应结构

错误码与排查指南

常见错误场景

排查流程

高频、大额、敏感交易在调查中的作用

高频交易

大额交易

敏感交易

结论

交易数据接口.md 23 KB

Geschiedenis Ruwe