# 全量商机查询接口文档

> 提供 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` 返回空串。