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