# OMS 退单回调接口文档

> OMS 系统退单后，主动回调 CRM，将对应商机的项目阶段更新为 `S4`，并清空签约信息。

## 基本信息

| 项目 | 内容 |
| --- | --- |
| 接口路径 | `POST /api/oms/callback/order-return` |
| 调用方 | OMS 系统 |
| 请求头鉴权 | `X-Internal-Secret`（内部接口密钥） |
| 幂等性 | 可重试，重复调用不产生副作用 |

## 鉴权方式

与商机集成更新接口 `PUT /api/opportunities/integration/update` 保持一致，使用 `unisbase.internal-auth` 配置的密钥校验。

- 请求头字段：`X-Internal-Secret`（可通过 `unisbase.internal-auth.header-name` 覆盖）
- 秘钥值：`unisbase.internal-auth.secret`
- 校验逻辑：
  - 当 `unisbase.internal-auth.enabled=true` 时强制校验，头信息与配置密钥不一致则返回鉴权失败；
  - 当 `enabled=false` 时跳过鉴权（仅用于本地开发）。

请求示例：

```
POST /api/oms/callback/order-return
Content-Type: application/json
X-Internal-Secret: <配置的secret>
```

## 请求参数

### Body（application/json）

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `opportunityCode` | string | 是 | CRM 商机编号，用于定位商机（≤50 字符） |
| `orderNo` | string | 否 | OMS 退单号，仅用于日志记录（≤50 字符） |

请求体示例：

```json
{
  "opportunityCode": "OPP-20260916-001",
  "orderNo": "OMS-20260916-0001"
}
```

## 业务处理逻辑

退单回调成功后，CRM 对目标商机执行如下更新：

| 字段 | 更新后值 |
| --- | --- |
| 项目阶段 `stage` | `S4` |
| 状态 `status` | `active` |
| 实际签约金额 `actual_signed_amount` | 置空（`null`） |
| 是否签约 `archived` | `false` |
| 签约/归档时间 `archived_at` | 置空（`null`） |
| 更新时间 `updated_at` | `now()` |

定位逻辑：按 `opportunity_code` 精确匹配商机；未匹配到或编号为空时抛出异常，不更新任何数据。整个操作在同一事务内完成。

## 响应

统一响应体：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | int | 业务状态码，`0` 表示成功，非 `0` 表示失败 |
| `message` | string | 提示信息 |
| `data` | object | 返回数据 |

### 成功响应

`data` 为被更新商机的 `id`（Long）。

```json
{
  "code": 0,
  "message": "success",
  "data": 123
}
```

### 失败响应

| 场景 | 说明 |
| --- | --- |
| 鉴权失败 | 内部接口鉴权失败（`X-Internal-Secret` 不匹配时抛异常） |
| 商机编号为空 | 商机编号不能为空 |
| 商机不存在 | 未按 `opportunityCode` 匹配到商机 |
| 更新失败 | 数据库更新影响行数为 0 |

失败示例：

```json
{
  "code": 1,
  "message": "内部接口鉴权失败",
  "data": null
}
```

> 注：`message` 具体文案以实际业务异常为准，示例仅供参考。

## 相关代码

- Controller：[OmsCallbackController.java](file:///Users/kangwenjing/Downloads/crm/unis_crm/backend/src/main/java/com/unis/crm/controller/OmsCallbackController.java)
- 请求 DTO：[OmsOrderReturnRequest.java](file:///Users/kangwenjing/Downloads/crm/unis_crm/backend/src/main/java/com/unis/crm/dto/opportunity/OmsOrderReturnRequest.java)
- Service 接口：[OpportunityService.java](file:///Users/kangwenjing/Downloads/crm/unis_crm/backend/src/main/java/com/unis/crm/service/OpportunityService.java)
- Service 实现：[OpportunityServiceImpl.java](file:///Users/kangwenjing/Downloads/crm/unis_crm/backend/src/main/java/com/unis/crm/service/impl/OpportunityServiceImpl.java)
- Mapper 实现：[OpportunityMapper.xml](file:///Users/kangwenjing/Downloads/crm/unis_crm/backend/src/main/resources/mapper/opportunity/OpportunityMapper.xml)

## 备注

- `crm_opportunity` 表无独立的「签约时间/是否签约」列，系统以 `archived`（是否签单）、`archived_at`（归档/签约时间）、`actual_signed_amount`（实际签约金额）表达签约状态，退单时三者一并清空。