# Contract: IF-REV-013 催缴任务生成与结果承接接口

## 1. 合同定位

- 接口编号：`IF-REV-013`
- 归属模块：`REV-006`
- 责任系统：`SYS-002`
- 协同系统：`SYS-010`
- 合同类型：业务接口设计合同

## 2. 业务职责

`IF-REV-013` 负责：

- 基于欠费账单、策略与渠道偏好生成催缴任务
- 查询催缴任务状态与历史催缴记录
- 承接消息协同后的业务侧四态状态
- 记录人工核查补记和处置引用

`IF-REV-013` 不负责：

- 短信、微信、站内信等渠道实际发送
- 停复水内部审批、派工和现场执行
- 扩展五态以上的细粒度业务状态

## 3. 输入合同

### 3.1 任务生成

| 字段 | 说明 | 约束 |
|------|------|------|
| strategyCode | 催缴策略编码 | 必填 |
| triggerType | 触发类型 | 自动 / 人工 |
| candidateList | 催缴候选对象集合 | 至少 1 条 |
| channelPreference | 渠道优先级 | 至少 1 项 |
| operator | 操作人或任务来源 | 人工触发时必填 |

### 3.2 任务查询

| 字段 | 说明 | 约束 |
|------|------|------|
| taskNo | 催缴任务号 | 与条件查询二选一 |
| custId | 客户标识 | 可选 |
| billPeriod | 账期 | 可选 |
| status | 任务状态 | 仅允许四态 |
| channelType | 渠道类型 | 可选 |

### 3.3 人工核查

| 字段 | 说明 | 约束 |
|------|------|------|
| taskNo | 催缴任务号 | 必填 |
| verifyResult | 人工核查结果 | 当前固定映射 `MANUAL_VERIFIED` |
| verifyNote | 核查说明 | 必填 |
| disposalRefNo | 关联处置引用号 | 可选 |
| operator | 核查人 | 必填 |

## 4. 输出合同

### 4.1 任务生成返回

| 字段 | 说明 |
|------|------|
| interfaceCode | 固定返回 `IF-REV-013` |
| taskNo | 生成的催缴任务号 |
| eventNo | 业务事件号 |
| status | 初始状态，固定为 `PENDING` |
| taskCount | 本次生成任务数 |
| skippedReasonSummary | 被排除对象摘要 |

### 4.2 状态查询返回

| 字段 | 说明 |
|------|------|
| taskNo | 催缴任务号 |
| eventNo | 业务事件号 |
| status | `PENDING` / `SUCCESS` / `FAIL` / `MANUAL_VERIFIED` |
| channelType | 当前渠道 |
| receiver | 触达对象 |
| sendTime | 发送发起时间 |
| lastCallbackTime | 最近回写时间 |
| failReason | 失败原因 |
| disposalRefs | 关联处置引用 |

## 5. 业务规则合同

1. 催缴对象必须来源于有效欠费账单，不得把已收费、已作废或已进入不允许催缴流程的账单纳入任务。
2. 同一候选对象在频控窗口内不得重复生成同策略、同渠道的正式任务。
3. 正式状态只允许四态，不扩展其他临时枚举值。
4. 历史催缴、停水、预存短信记录按只读查询口径挂接，不表述为新建平行在线主表。
5. 处置引用只承担追溯职责，不在本接口中展开停复水或工单内部流程。

## 6. 失败与阻断语义

| 场景 | 阻断要求 | 返回语义 |
|------|----------|----------|
| 候选账单不满足欠费前提 | 阻断生成 | 返回排除原因摘要 |
| 策略编码无效 | 阻断生成 | 返回策略校验失败 |
| 频控规则命中 | 可部分阻断 | 返回被跳过对象与原因 |
| 外部结果未定 | 不强制失败 | 保持 `PENDING` 或经人工核查转 `MANUAL_VERIFIED` |
| 外部明确失败 | 回写失败 | 更新为 `FAIL` 并记录原因 |

## 7. 可追溯字段最小集

- `taskNo`
- `eventNo`
- `strategyCode`
- `channelType`
- `triggerType`
- `status`
- `failReason`
- `receiver`
- `sendTime`
- `disposalRefNo`