人员数据接口.md 28 KB
人员数据接口
本文引用的文件
- PersonBasicInfoController.java
- PersonGroupController.java
- IntimacyController.java
- ResidentPopulationController.java
- DataProfileController.java
- personApi.ts
- dpApi.ts
- types/query.ts
- types/dto.ts
目录
简介
本文面向后端人员和画像相关接口的使用者，重点说明以下能力：
- 人员基本信息、人员分组、亲密度配置、常住人口和人口统计。
- 人员数据画像中的通话统计、最常联系人、交易统计、最常交易对象、银行卡信息和趋势统计。
- 每个接口的 HTTP 方法、URL、请求参数、响应字段、分页格式。
- 人员实体与通话、交易、轨迹、治理树等业务数据的关联查询思路。
- 敏感字段的安全处理方式和前端展示建议。
- 常见问题的排查方法，包括人员不存在、分组为空、亲密度数据缺失等。
项目结构定位
人员数据接口主要分布在后端 ai-server 模块的 com.zsjz.ai.module.person.controller 包中，并由前端 ai-electron/frontend/src/person/api 调用：
- 后端控制器：
- 人员基本信息：
PersonBasicInfoController - 人员分组：
PersonGroupController - 亲密度配置：
IntimacyController - 常住人口：
ResidentPopulationController - 数据画像：
DataProfileController
- 人员基本信息：
前端 API：
personApi.ts：封装人员基本信息、分组、亲密度等接口。dpApi.ts：封装数据画像接口。types/query.ts、types/dto.ts：定义查询条件和响应类型。graph TB subgraph "前端" PersonAPI["personApi.ts"] DpAPI["dpApi.ts"] TypesQ["types/query.ts"] TypesDTO["types/dto.ts"] end subgraph "后端控制器" PbiCtrl["PersonBasicInfoController<br/>/pbi"] PgCtrl["PersonGroupController<br/>/pg"] IntCtrl["IntimacyController<br/>/intimacy"] RpCtrl["ResidentPopulationController<br/>/rp"] DpCtrl["DataProfileController<br/>/dp"] end PersonAPI --> PbiCtrl PersonAPI --> PgCtrl PersonAPI --> IntCtrl DpAPI --> DpCtrl TypesQ --> DpAPI TypesDTO --> DpAPI
图表来源
- PersonBasicInfoController.java:8-62
- PersonGroupController.java:8-84
- IntimacyController.java:17-39
- ResidentPopulationController.java:8-13
- DataProfileController.java:24-190
- personApi.ts
- dpApi.ts
- types/query.ts
- types/dto.ts
章节来源
- PersonBasicInfoController.java:8-62
- PersonGroupController.java:8-84
- IntimacyController.java:17-39
- ResidentPopulationController.java:8-13
- DataProfileController.java:24-190
- personApi.ts
- dpApi.ts
- types/query.ts
- types/dto.ts
核心控制器总览
| 控制器 | 基础路径 | 职责 | 关键能力 |
|---|---|---|---|
| 人员基本信息控制器 | /pbi |
管理 PersonBasicInfo |
创建、删除、更新、查询人员列表、排序 |
| 人员分组控制器 | /pg |
管理 PersonGroup 及人员分组关系 |
分组增删改查、添加人员、移除人员、设置主成员 |
| 亲密度控制器 | /intimacy |
管理亲密度配置 | 获取亲密度列表、批量修改亲密度 |
| 常住人口控制器 | /rp |
常住人口相关服务入口 | 当前代码未暴露具体接口方法，需以实际新增方法为准 |
| 数据画像控制器 | /dp |
人员画像统计分析 | 通话统计、最常联系 TOP10、通话站点、通话记录汇总、运营商手机号；交易统计、最常交易 TOP10、交易记录汇总、对方名称分页、银行卡信息、月度年度趋势、亲密度汇总 |
章节来源
- PersonBasicInfoController.java:8-62
- PersonGroupController.java:8-84
- IntimacyController.java:17-39
- ResidentPopulationController.java:8-13
- DataProfileController.java:24-190
统一响应与分页格式
统一响应
所有接口统一返回 Result<T> 包装结构，成功时携带业务数据，失败时通过状态码和消息描述错误。常见语义如下：
- 成功：业务数据位于响应体的数据字段中。
- 失败：包含错误码、错误消息、是否成功标志。
- 空数据：部分接口可能返回空列表或空对象，而不是抛出异常。
由于本文聚焦接口契约，不直接输出后端 Result 类源码，调用方应基于前端类型定义和实际响应体判断业务结果。
分页格式
分页接口通常返回 MyBatis-Plus 的 Page<T> 结构，典型字段包括：
records：当前页数据列表。total：总记录数。current：当前页码。size：每页数量。pages：总页数。
分页请求一般由 Query 或具体查询 DTO 传入页码、每页数量、过滤条件。
章节来源
- DataProfileController.java:24-190
接口定义
人员基本信息接口
创建人员信息
- HTTP 方法：
POST - URL：
/pbi/create - 请求体：
PersonBasicInfoDTO - 响应：
Result<Void> - 用途：新增或覆盖人员基本信息。
章节来源
- PersonBasicInfoController.java:17-26
删除人员信息
- HTTP 方法：
GET - URL：
/pbi/delete - 请求参数：
personName - 响应：
Result<Void> - 用途：根据姓名删除人员基本信息。
章节来源
- PersonBasicInfoController.java:28-35
更新人员信息
- HTTP 方法：
POST - URL：
/pbi/update - 请求体：
PersonBasicInfoDTO - 响应：
Result<Void> - 用途：更新已有人员信息。
章节来源
- PersonBasicInfoController.java:37-44
查询人员列表
- HTTP 方法：
GET - URL：
/pbi/getPersons - 请求参数：无
- 响应：
Result<List<PersonBasicInfo>> - 用途：返回全部人员基本信息列表。
章节来源
- PersonBasicInfoController.java:46-50
人员排序
- HTTP 方法：
POST - URL：
/pbi/personOrder - 请求体：
List<PersonBasicInfo> - 响应：
Result<Void> - 用途：按前端传入顺序保存人员排序。
章节来源
- PersonBasicInfoController.java:52-57
人员分组接口
获取分组列表
- HTTP 方法：
GET - URL：
/pg/list - 请求参数：无
- 响应：
Result<List<PersonGroup>> - 用途：返回系统内所有分组。
章节来源
- PersonGroupController.java:17-21
创建分组
- HTTP 方法：
POST - URL：
/pg/create - 请求体：
PersonGroup - 响应：
Result<Void> - 用途：新增分组。
章节来源
- PersonGroupController.java:23-30
更新分组
- HTTP 方法：
POST - URL：
/pg/update - 请求体：
PersonGroup - 响应：
Result<Void> - 用途：修改分组信息。
章节来源
- PersonGroupController.java:32-39
删除分组
- HTTP 方法：
POST - URL：
/pg/delete - 请求体：
DeletePersonGroupDTO，包含id - 响应：
Result<Void> - 用途：删除指定分组。
章节来源
- PersonGroupController.java:41-49
添加人员到分组
- HTTP 方法：
POST - URL：
/pg/addPerson - 请求体：
AddPersonGroupDTO - 响应：
Result<Void> - 用途：将人员加入某个分组。
章节来源
- PersonGroupController.java:51-58
从分组移除人员
- HTTP 方法：
GET - URL：
/pg/remPerson - 请求参数：
relId - 响应：
Result<Void> - 用途：根据关系 ID 移除分组中的人员。
章节来源
- PersonGroupController.java:60-65
设置主成员
- HTTP 方法：
GET - URL：
/pg/changeMain - 请求参数：
relId、groupId - 响应：
Result<Void> - 用途：调整分组中的人员主成员关系。
章节来源
- PersonGroupController.java:67-71
亲密度接口
获取亲密度列表
- HTTP 方法：
GET - URL：
/intimacy/list - 请求参数：无
- 响应：
Result<List<Intimacy>> - 用途：返回亲密度规则或配置项。
章节来源
- IntimacyController.java:25-31
批量修改亲密度
- HTTP 方法：
POST - URL：
/intimacy/modify - 请求体：
List<Intimacy> - 响应：
Result<Void> - 用途：批量更新亲密度配置。
章节来源
- IntimacyController.java:33-38
常住人口接口
当前 ResidentPopulationController 仅声明基础路径 /rp 并注入服务，但未暴露具体接口方法。若后续扩展，新增方法会继承该基础路径。
章节来源
- ResidentPopulationController.java:8-13
数据画像接口
通话数据统计
- HTTP 方法：
GET - URL：
/dp/callStat - 请求参数：
personName - 响应：
Result<CallDataProfileStatDTO> - 用途：根据人员姓名统计号码分布、通话次数、日期范围、主叫被叫占比等。
章节来源
- DataProfileController.java:38-48
最常联系 TOP10
- HTTP 方法：
POST - URL：
/dp/callOftenTop10 - 请求体：
CallOftenTop10Query - 响应：
Result<Page<CallOftenTop10DTO>> - 用途：查询与指定人员通话频率最高的前 10 个联系人或号码。
章节来源
- DataProfileController.java:50-59
通话站点统计
- HTTP 方法：
POST - URL：
/dp/callStatStation - 请求体：
CallStatStationQuery - 响应：
Result<List<CallStatStationDTO>> - 用途：统计通话基站位置，辅助分析活动轨迹。
章节来源
- DataProfileController.java:61-70
通话记录汇总（分页）
- HTTP 方法：
POST - URL：
/dp/getCallRecordSummary - 请求体：
CallRecordSummaryQuery - 响应：
Result<Page<CallRecordSummaryDTO>> - 用途：分页查询通话记录汇总。
章节来源
- DataProfileController.java:72-79
获取运营商手机号信息
- HTTP 方法：
POST - URL：
/dp/getCallOperPhoneInfo - 请求体：
CallOperPhoneInfoQuery - 响应：
Result<List<CallOpenInfo>> - 用途：查询人员手机号码及其运营商信息。
章节来源
- DataProfileController.java:81-88
交易数据统计
- HTTP 方法：
GET - URL：
/dp/transStat - 请求参数：
personName - 响应：
Result<TransDataProfileStatDTO> - 用途：根据人员姓名统计银行分布、卡号数量、交易总额、余额等。
章节来源
- DataProfileController.java:98-107
最常交易 TOP10（分页）
- HTTP 方法：
POST - URL：
/dp/transOfPersons - 请求体：
TransOftenTop10Query - 响应：
Result<Page<TransOftenTop10DTO>> - 用途：查询与指定人员交易频率最高的前 10 个账户或交易对象。
章节来源
- DataProfileController.java:109-118
交易记录汇总（分页）
- HTTP 方法：
POST - URL：
/dp/getTransRecordSummary - 请求体：
TransRecordSummaryQuery - 响应：
Result<Page<TransRecordSummaryDTO>> - 用途：分页查询交易记录汇总，支持金额、次数、卡号等筛选。
章节来源
- DataProfileController.java:120-128
交易对方名称分页
- HTTP 方法：
GET - URL：
/dp/getTransOtherName - 请求参数：
Query，包含页码、每页数量、人员姓名、对方名称等 - 响应：
Result<Page<String>> - 用途：分页查询去重后的交易对方名称。
章节来源
- DataProfileController.java:130-137
获取银行卡交易详细信息
- HTTP 方法：
POST - URL：
/dp/getTransBankCardInfo - 请求体：
TransBankCardInfoQuery - 响应：
Result<List<TransBankCardInfoDTO>> - 用途：查询银行卡收支汇总、净额、余额、开户销户时间等。
章节来源
- DataProfileController.java:139-147
按月统计交易金额趋势
- HTTP 方法：
POST - URL：
/dp/transAmountTrendYM - 请求体：
TransTrendQuery - 响应：
Result<List<TransTrendDTO>> - 用途：按月份统计交易金额变化趋势。
章节来源
- DataProfileController.java:149-157
按年统计交易金额趋势
- HTTP 方法：
POST - URL：
/dp/transAmountTrendY - 请求体：
TransTrendQuery - 响应：
Result<List<TransTrendDTO>> - 用途：按年度统计交易金额变化趋势。
章节来源
- DataProfileController.java:159-167
亲密度汇总
- HTTP 方法：
GET - URL：
/dp/intimacySummary - 请求参数：
personName - 响应：
Result<List<IntimacyDTO>> - 用途：返回某人员的亲密度汇总数据。
章节来源
- DataProfileController.java:173-180
实体关联与查询方式
人员数据并非孤立存在，而是围绕“人员”这一主体，与通话、交易、轨迹、治理树等数据形成关联：
erDiagram
PERSON {
string person_name PK
string phone
string card_no
string id_card
string group_id
timestamp created_at
timestamp updated_at
}
PERSON_GROUP {
long id PK
string name
string description
}
CALL_RECORD {
long id PK
string caller
string callee
string person_name
timestamp call_time
string base_station
}
TRANSACTION {
long id PK
string person_name
string bank_card
string other_name
decimal amount
string trans_type
timestamp trans_time
}
TRAJECTORY {
long id PK
string person_name
string location
timestamp time
}
GOVERN_TREE {
long id PK
string person_name
string node_label
string relation_type
}
PERSON ||--o{ PERSON_GROUP : "属于"
PERSON ||--o{ CALL_RECORD : "发起或接听"
PERSON ||--o{ TRANSACTION : "参与"
PERSON ||--o{ TRAJECTORY : "出现于"
PERSON ||--o{ GOVERN_TREE : "构成节点"
- 人员与分组：通过
PersonGroup将人员归类，支持主成员标记和关系 ID 管理。 - 人员与通话：通过
personName、caller、callee等字段关联通话记录，用于统计最常联系人、通话站点、通话汇总。 - 人员与交易：通过
personName、bank_card、other_name关联交易数据，用于交易统计、最常交易对象、银行卡详情、趋势分析。 - 人员与轨迹：通过
personName关联轨迹数据，结合基站、地点和时间分析活动范围。 人员与治理树：通过
personName和关系类型构建治理树，用于案件分析和关系图谱。sequenceDiagram participant Client as "调用方" participant DataProfile as "DataProfileController" participant Service as "DataProfileService" participant CallModel as "通话模型" participant TransModel as "交易模型" Client->>DataProfile: GET /dp/callStat?personName=张三 DataProfile->>Service: callInfoStat(personName) Service->>CallModel: 查询通话统计 CallModel-->>Service: 通话统计结果 Service-->>DataProfile: CallDataProfileStatDTO DataProfile-->>Client: Result<CallDataProfileStatDTO> Client->>DataProfile: POST /dp/transOfPersons DataProfile->>Service: transOfPersons(query) Service->>TransModel: 查询交易统计 TransModel-->>Service: 分页交易 TOP10 Service-->>DataProfile: Page<TransOftenTop10DTO> DataProfile-->>Client: Result<Page<TransOftenTop10DTO>>
图表来源
- DataProfileController.java:38-180
章节来源
- DataProfileController.java:38-180
敏感字段与安全处理
人员数据中包含姓名、电话、身份证号、银行卡号、地址等敏感信息，安全处理建议如下：
后端脱敏策略
- 对身份证号、银行卡号进行掩码处理，例如保留前几位和后几位。
- 对手机号进行中间位替换。
- 对详细地址进行模糊化或分段显示。
- 避免在日志中输出完整敏感字段。
前端展示策略
- 使用统一的敏感字段渲染组件，避免直接打印原始值。
- 对需要查看明细的场景增加权限校验和操作留痕。
- 对列表页默认脱敏，详情页按需解密或二次确认。
接口层控制
- 非必要的接口不应返回完整敏感字段。
- 不同角色返回不同粒度的数据。
- 对外部系统对接时，优先使用标识符而非明文敏感值。
前端敏感字段处理可参考通用工具逻辑，并在人员画像页面中对电话、卡号、身份证等字段做脱敏展示。
章节来源
- types/dto.ts
curl 示例：查询某人员及其关系
以下为常用 curl 示例，请根据实际服务地址替换 BASE_URL，并准备正确的登录态或鉴权头。
查询人员基本信息列表
curl --location --request GET "BASE_URL/pbi/getPersons"
查询某人员通话统计
curl --location --request GET "BASE_URL/dp/callStat?personName=张三"
查询最常联系 TOP10
curl --location --request POST "BASE_URL/dp/callOftenTop10" \
--header "Content-Type: application/json" \
--data '{"personName":"张三","startTime":"","endTime":"","page":1,"size":10}'
查询交易统计
curl --location --request GET "BASE_URL/dp/transStat?personName=张三"
查询最常交易 TOP10
curl --location --request POST "BASE_URL/dp/transOfPersons" \
--header "Content-Type: application/json" \
--data '{"personName":"张三","startTime":"","endTime":"","page":1,"size":10}'
查询交易对方名称分页
curl --location --request GET "BASE_URL/dp/getTransOtherName?page=1&size=10&personName=张三&otherName="
查询亲密度汇总
curl --location --request GET "BASE_URL/dp/intimacySummary?personName=张三"
注意：以上请求体中的字段名来源于前端类型定义与服务端查询 DTO 的对应关系。若实际字段存在差异，请以服务端实现和前端类型为准。
章节来源
- personApi.ts
- dpApi.ts
- types/query.ts
- DataProfileController.java:38-180
常见问题排查
人员不存在
- 现象：通话统计、交易统计、亲密度汇总返回空数据或空列表。
- 排查步骤：
- 先调用
/pbi/getPersons确认该人员是否存在。 - 检查
personName是否与系统中存储的姓名完全一致。 - 若存在但画像为空，再分别调用通话、交易、亲密度接口确认数据来源。
- 检查是否因数据清洗或案件数据源未接入导致缺失。
- 先调用
章节来源
- PersonBasicInfoController.java:46-50
- DataProfileController.java:38-180
分组为空
- 现象：分组列表为空，或人员无法加入分组。
- 排查步骤：
- 调用
/pg/list确认是否存在分组。 - 若没有分组，先调用
/pg/create创建分组。 - 调用
/pg/addPerson将人员加入分组，注意请求体是否为AddPersonGroupDTO。 - 若仍失败，检查
relId是否正确，必要时通过/pg/remPerson和/pg/changeMain调整关系。
- 调用
章节来源
- PersonGroupController.java:17-71
亲密度数据缺失
- 现象：亲密度列表为空，或
/dp/intimacySummary返回空列表。 - 排查步骤：
- 调用
/intimacy/list确认亲密度配置是否存在。 - 若配置缺失，调用
/intimacy/modify批量写入亲密度规则。 - 若配置存在但汇总为空，检查该人员是否有通话或交易数据作为亲密度计算依据。
- 检查前端是否对空数据做了默认处理。
- 调用
章节来源
- IntimacyController.java:25-38
- DataProfileController.java:173-180
数据画像分页为空
- 现象：最常联系 TOP10、最常交易 TOP10、通话记录汇总、交易记录汇总返回空分页。
- 排查步骤：
- 检查请求中的
personName、时间范围、交易类型、金额等过滤条件。 - 逐步缩小条件，先查全量再叠加筛选。
- 确认分页参数
page、size是否合法。 - 检查底层数据是否已入库，是否存在数据源未同步问题。
- 检查请求中的
章节来源
- DataProfileController.java:50-167
性能与使用建议
- 分页优先：TOP10 和汇总接口已提供分页，避免一次性拉取大量数据。
- 缓存利用：部分接口注释中包含缓存键提示，实际缓存行为以后端实现为准，建议对热点人员画像适当缓存。
- 批量操作：亲密度修改使用批量接口，减少多次网络往返。
- 参数精简：画像查询尽量只传必要字段，避免宽泛条件导致大数据扫描。
- 脱敏输出：对包含敏感字段的响应，在前端做统一脱敏展示，降低泄露风险。
[本节为通用建议，不直接分析具体源码]
结论
人员数据接口以“人员”为中心，向上提供基本信息、分组管理和亲密度配置，向下支撑通话、交易、轨迹、治理树等多维业务数据的画像分析。调用方应重点关注：
- 接口基础路径和请求体结构。
- 分页接口的
Page响应结构。 - 人员不存在、分组为空、亲密度缺失等常见场景。
- 敏感字段的后端脱敏与前端安全展示。
在实际集成时，建议先验证人员存在性和分组有效性，再调用画像接口，并对分页、缓存、脱敏做系统化设计。
[本节为总结性内容，不直接分析具体源码]