crm-backend-matt/.scratch/a4-doc-fields/endpoint-response-survey.md

# A4 响应字段缺口返回类型普查

依据 `.scratch/customer-e2e/defs_a4.py` 与两份 specimens JSON 静态计算；缺口定义为未取得 `response.data` 的端点。源码命中范围为 `crm-customer` 与 `crm-rule` 的 `src/main/java`。

## 汇总

- A4 定义端点总数：57
- 已有 E2E `response.data`、生成器可展开字段表：28
- 当前缺口：29

| 返回形态 | 端点数 |
| --- | ---: |
| List<T> | 2 |
| PageResult<T> | 1 |
| 内联结构 | 4 |
| 单个 DTO | 5 |
| 原始标量 | 1 |
| 空响应 | 14 |
| 非标准响应 | 2 |

## 各类代表端点

- List<T>：`GET /api/customer/company-lookup`（`defs_a4.py:146`）；`GET /api/customer/transfer/{id}/assignable`（`defs_a4.py:340`）
- PageResult<T>：`POST /api/customer/page`（`defs_a4.py:110`）
- 内联结构：`POST /api/customer/claim-batch`（`defs_a4.py:183`）；`POST /api/customer/assign-batch`（`defs_a4.py:191`）
- 单个 DTO：`POST /api/customer`（`defs_a4.py:26`）；`PUT /api/customer/{id}`（`defs_a4.py:67`）
- 原始标量：`POST /api/customer/contact`（`defs_a4.py:253`）
- 空响应：`POST /api/customer/claim`（`defs_a4.py:179`）；`POST /api/customer/assign`（`defs_a4.py:187`）
- 非标准响应：`GET /api/customer/import/template`（`defs_a4.py:365`）；`GET /api/customer/ping`（`defs_a4.py:370`）

## Java 类型名直查结果

- 可按 `resp` 中类型名唯一命中 `.java` 文件：7 条。
- 找不到同名 `.java` 文件：1 条。
- 同名文件歧义：0 条。

### 未命中类型

- `GET /api/customer/company-lookup` — `CompanyCandidate`；`resp`：List<CompanyCandidate>（V1 stub 恒 []）

## 逐端点清单

### 01. 新增客户

- 对账键：`POST /api/customer`（`defs_a4.py:26`）
- 返回描述：`CustomerSaveResultDTO 双形态：needConfirm=true + similarHits[]（未落库，待确认）；或直接返回新客户 id（string）`
- 分类：单个 DTO；候选类型：`CustomerSaveResultDTO`
- 源码命中：`crm-customer/src/main/java/com/crm/customer/domain/dto/CustomerSaveResultDTO.java`

### 02. 编辑客户

- 对账键：`PUT /api/customer/{id}`（`defs_a4.py:67`）
- 返回描述：`CustomerSaveResultDTO（同新增；命中相似时 needConfirm=true）`
- 分类：单个 DTO；候选类型：`CustomerSaveResultDTO`
- 源码命中：`crm-customer/src/main/java/com/crm/customer/domain/dto/CustomerSaveResultDTO.java`

### 03. 客户分页

- 对账键：`POST /api/customer/page`（`defs_a4.py:110`）
- 返回描述：`PageResult<CustomerDetailDTO>（content/total，ID 序列化为 string）`
- 分类：PageResult<T>；候选类型：`CustomerDetailDTO`
- 源码命中：`crm-customer/src/main/java/com/crm/customer/domain/dto/CustomerDetailDTO.java`

### 04. 工商信息查询

- 对账键：`GET /api/customer/company-lookup`（`defs_a4.py:146`）
- 返回描述：`List<CompanyCandidate>（V1 stub 恒 []）`
- 分类：List<T>；候选类型：`CompanyCandidate`
- 源码命中：无

### 05. 领取客户

- 对账键：`POST /api/customer/claim`（`defs_a4.py:179`）
- 返回描述：`null（Result<Void>，data=null 非失败）`
- 分类：空响应

### 06. 批量领取

- 对账键：`POST /api/customer/claim-batch`（`defs_a4.py:183`）
- 返回描述：`BatchResult{successCount,failures:[{id,reason}]}`
- 分类：内联结构；候选类型：`BatchResult`
- 源码命中：无

### 07. 分配客户

- 对账键：`POST /api/customer/assign`（`defs_a4.py:187`）
- 返回描述：`null`
- 分类：空响应

### 08. 批量分配

- 对账键：`POST /api/customer/assign-batch`（`defs_a4.py:191`）
- 返回描述：`BatchResult{successCount,failures}`
- 分类：内联结构；候选类型：`BatchResult`
- 源码命中：无

### 09. 抛公海

- 对账键：`POST /api/customer/release-pool`（`defs_a4.py:195`）
- 返回描述：`null`
- 分类：空响应

### 10. 批量抛公海

- 对账键：`POST /api/customer/release-pool-batch`（`defs_a4.py:199`）
- 返回描述：`BatchResult{successCount,failures}`
- 分类：内联结构；候选类型：`BatchResult`
- 源码命中：无

### 11. 归档客户

- 对账键：`POST /api/customer/archive`（`defs_a4.py:203`）
- 返回描述：`null`
- 分类：空响应

### 12. 批量归档

- 对账键：`POST /api/customer/archive-batch`（`defs_a4.py:207`）
- 返回描述：`BatchResult{successCount,failures}`
- 分类：内联结构；候选类型：`BatchResult`
- 源码命中：无

### 13. 恢复客户

- 对账键：`POST /api/customer/restore`（`defs_a4.py:211`）
- 返回描述：`null`
- 分类：空响应

### 14. 添加团队成员

- 对账键：`POST /api/customer/{id}/members`（`defs_a4.py:223`）
- 返回描述：`null`
- 分类：空响应

### 15. 移除团队成员

- 对账键：`DELETE /api/customer/{id}/members/{memberUserId}`（`defs_a4.py:227`）
- 返回描述：`null`
- 分类：空响应

### 16. 新增联系人

- 对账键：`POST /api/customer/contact`（`defs_a4.py:253`）
- 返回描述：`新联系人 id（string）`
- 分类：原始标量

### 17. 编辑联系人

- 对账键：`PUT /api/customer/contact/{id}`（`defs_a4.py:267`）
- 返回描述：`null`
- 分类：空响应

### 18. 删除联系人

- 对账键：`DELETE /api/customer/contact/{id}`（`defs_a4.py:277`）
- 返回描述：`null`
- 分类：空响应

### 19. 联系人详情

- 对账键：`GET /api/customer/contact/{id}`（`defs_a4.py:280`）
- 返回描述：`ContactDTO（含 customerName/customerNo 仅出参字段）`
- 分类：单个 DTO；候选类型：`ContactDTO`
- 源码命中：`crm-customer/src/main/java/com/crm/customer/domain/dto/ContactDTO.java`

### 20. 关注客户

- 对账键：`POST /api/customer/{id}/focus`（`defs_a4.py:298`）
- 返回描述：`null`
- 分类：空响应

### 21. 取消关注客户

- 对账键：`POST /api/customer/{id}/unfocus`（`defs_a4.py:301`）
- 返回描述：`null`
- 分类：空响应

### 22. 标记重点客户

- 对账键：`POST /api/customer/{id}/star`（`defs_a4.py:304`）
- 返回描述：`null`
- 分类：空响应

### 23. 取消重点标记

- 对账键：`POST /api/customer/{id}/unstar`（`defs_a4.py:307`）
- 返回描述：`null`
- 分类：空响应

### 24. 批量关注客户

- 对账键：`POST /api/customer/focus-batch`（`defs_a4.py:310`）
- 返回描述：`null`
- 分类：空响应

### 25. 发起交接

- 对账键：`POST /api/customer/transfer/initiate`（`defs_a4.py:319`）
- 返回描述：`TransferDetailDTO（交接单头：transferNo/status/totalCount/assignedCount…）`
- 分类：单个 DTO；候选类型：`TransferDetailDTO`
- 源码命中：`crm-customer/src/main/java/com/crm/customer/domain/dto/TransferDetailDTO.java`

### 26. 可分配销售列表

- 对账键：`GET /api/customer/transfer/{id}/assignable`（`defs_a4.py:340`）
- 返回描述：`List<AssignableUserDTO>（userId/userName/deptName；当前因 D-07 不可达）`
- 分类：List<T>；候选类型：`AssignableUserDTO`
- 源码命中：`crm-customer/src/main/java/com/crm/customer/domain/dto/AssignableUserDTO.java`

### 27. 上传导入文件并预校验

- 对账键：`POST /api/customer/import/upload`（`defs_a4.py:345`）
- 返回描述：`ImportPreviewDTO（taskId + totalCount/insertCount/updateCount/failCount/suspectCount + 行级明细）`
- 分类：单个 DTO；候选类型：`ImportPreviewDTO`
- 源码命中：`crm-customer/src/main/java/com/crm/customer/domain/dto/ImportPreviewDTO.java`

### 28. 下载导入模板

- 对账键：`GET /api/customer/import/template`（`defs_a4.py:365`）
- 返回描述：`非信封：二进制文件流（Content-Disposition: attachment; filename*=UTF-8''…xlsx）；失败时标准 JSON 信封`
- 分类：非标准响应

### 29. 健康探针

- 对账键：`GET /api/customer/ping`（`defs_a4.py:370`）
- 返回描述：`文字说明：标准 JSON 信封，data 为固定探针文案`
- 分类：非标准响应