118 lines
3.9 KiB
Markdown
118 lines
3.9 KiB
Markdown
# 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`（实际签约金额）表达签约状态，退单时三者一并清空。 |