102 lines
4.4 KiB
Markdown
102 lines
4.4 KiB
Markdown
# 全量商机查询接口文档
|
||
|
||
> 提供 CRM 全量商机精简字段清单，包含已归档/已签单商机，不分页。
|
||
|
||
## 基本信息
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 接口路径 | `GET /api/opportunities/all` |
|
||
| 调用方 | 内部系统 / 系统间集成（不面向前端用户） |
|
||
| 请求头鉴权 | `X-Internal-Secret`（内部接口密钥） |
|
||
| 数据范围 | 全量商机（含已归档/已签单），不做数据权限过滤 |
|
||
| 排序 | 按创建时间倒序，创建时间相同按 id 倒序 |
|
||
| 分页 | 无（一次性返回全部） |
|
||
|
||
## 鉴权方式
|
||
|
||
与商机集成更新接口 `PUT /api/opportunities/integration/update`、OMS 退单回调接口保持一致，使用 `unisbase.internal-auth` 配置的密钥校验。
|
||
|
||
- 请求头字段：`X-Internal-Secret`（可通过 `unisbase.internal-auth.header-name` 覆盖）
|
||
- 秘钥值：`unisbase.internal-auth.secret`
|
||
- 校验逻辑：
|
||
- 当 `unisbase.internal-auth.enabled=true` 时强制校验，头信息与配置密钥不一致则返回 `401`（`内部接口鉴权失败`）；
|
||
- 当 `enabled=false` 时跳过鉴权（仅用于本地开发）。
|
||
- 该路径已加入 `unisbase.security.permit-all-urls`，**不需要** `Authorization: Bearer` 登录态。
|
||
|
||
## 请求
|
||
|
||
```
|
||
GET /api/opportunities/all
|
||
X-Internal-Secret: <配置的secret>
|
||
```
|
||
|
||
无查询参数、无请求体。
|
||
|
||
## 响应
|
||
|
||
统一响应结构 `ApiResponse<List<OpportunityFullDTO>>`：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `code` | string | 状态码，`"0"` 表示成功，`"-1"` 表示失败 |
|
||
| `msg` | string | 提示信息，成功为 `success` |
|
||
| `data` | array | 商机列表 |
|
||
|
||
`data` 元素字段：
|
||
|
||
| 字段 | 类型 | 对应库表字段 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `opportunityCode` | string | `crm_opportunity.opportunity_code` | 商机编号 |
|
||
| `opportunityName` | string | `crm_opportunity.opportunity_name` | 商机名称 |
|
||
| `stageCode` | string | `crm_opportunity.stage` | 商机阶段编码（取自字典 `sj_xmjd`，未匹配时回退原值） |
|
||
| `stage` | string | 字典 `sj_xmjd.item_label` | 商机阶段名称（未匹配字典时按内置映射回退） |
|
||
| `confidence` | string | `crm_opportunity.confidence_pct` | 把握度等级：`A` / `B` / `C` |
|
||
| `pushedToOms` | boolean | `crm_opportunity.pushed_to_oms` | 是否已推送 OMS |
|
||
| `omsPushTime` | string | `crm_opportunity.oms_push_time` | 推送 OMS 时间，格式 `yyyy-MM-dd HH:mm`，未推送为空串 |
|
||
| `createdAt` | string | `crm_opportunity.created_at` | 创建时间，格式 `yyyy-MM-dd HH:mm` |
|
||
| `ownerUserId` | long | `crm_opportunity.owner_user_id` | 商机负责人 ID |
|
||
| `ownerName` | string | `sys_user.display_name` / `username` | 商机负责人姓名 |
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"code": "0",
|
||
"msg": "success",
|
||
"data": [
|
||
{
|
||
"opportunityCode": "OPP-20260916-001",
|
||
"opportunityName": "某某医院云桌面项目",
|
||
"stageCode": "bidding",
|
||
"stage": "招投标",
|
||
"confidence": "A",
|
||
"pushedToOms": true,
|
||
"omsPushTime": "2026-09-16 10:30",
|
||
"createdAt": "2026-09-10 09:12",
|
||
"ownerUserId": 1001,
|
||
"ownerName": "张三"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 实现说明
|
||
|
||
| 层 | 文件 |
|
||
| --- | --- |
|
||
| Controller | `backend/src/main/java/com/unis/crm/controller/OpportunityController.java`（`GET /all`） |
|
||
| Service | `OpportunityService#listAllOpportunities` / `OpportunityServiceImpl` |
|
||
| Mapper | `OpportunityMapper#selectAllOpportunities` |
|
||
| SQL | `backend/src/main/resources/mapper/opportunity/OpportunityMapper.xml` |
|
||
| DTO | `backend/src/main/java/com/unis/crm/dto/opportunity/OpportunityFullDTO.java` |
|
||
|
||
要点：
|
||
|
||
- 查询语句未加 `archived` 过滤，返回包含已归档/已签单在内的全部商机；
|
||
- 未拼接数据权限条件（`opportunityVisibilityCondition`），即不受当前用户数据可见范围限制，因此**仅允许内部系统调用**；
|
||
- 鉴权由 `OpportunityController#validateInternalSecret` 完成，并在 `application.yml` / `application-prod.yml` 的 `unisbase.security.permit-all-urls` 中放开 `/api/opportunities/all`；
|
||
- 已添加 `@Log(type = "商机集成", value = "查询全量商机")` 审计日志，记录调用留痕；
|
||
- 阶段名称通过 `sys_dict_item`（`type_code = 'sj_xmjd'`）关联获取，归档商机即使字典项被禁用也能取到名称；
|
||
- 时间字段统一由数据库格式化后返回字符串，未推送 OMS 时 `omsPushTime` 返回空串。
|