fujian_water_biz_doc/specs/003-rev006-reminder-event-design/contracts/rev006-interface-contract.md

Contract: REV-006 催缴事件与通知协同

1. Formal Interface Allocation

Interface	Role	Direction
IF-REV-013	REV-006 催缴任务生成、任务查询、结果承接的正式业务接口	SYS-002 内部正式业务接口
IF-EXT-008	SYS-002 与 SYS-010 的消息触达协同接口	SYS-002 -> SYS-010 发送，SYS-010 -> SYS-002 回写

约束：

• IF-REV-009 继续保留给 REV-005 发票结果查询，不得再用于 REV-006。
• IF-REV-013 是本 feature 新增的正式业务接口编号。

2. IF-REV-013 Business Contract

Purpose

统一承接催缴任务生成、任务状态查询和业务侧结果查看，不承担消息平台内部发送逻辑。

Request Shape

Field	Meaning	Required
taskNo	催缴任务号	查询时是；生成时否
custId	客户标识	是
chargeIds	账单集合	是
billPeriod	账期	是
arrearsAmount	欠费金额	是
strategyCode	催缴策略编码	是
channelType	触达渠道	是
triggerType	触发方式	是
eventNo	业务事件号	生成后返回；回写承接时是

Response Shape

Field	Meaning
taskNo	催缴任务号
interfaceCode	固定为 IF-REV-013
status	PENDING / SUCCESS / FAIL / MANUAL_VERIFIED
resultTime	最近结果时间
failureReason	失败原因
relatedDisposalRef	关联停复水或工单引用

3. IF-EXT-008 Collaboration Contract

Outbound to SYS-010

Field	Meaning
eventNo	业务事件号
taskNo	催缴任务号
custId	客户标识
receiver	接收目标
channelType	触达渠道
templateCode	消息模板编码
arrearsAmount	欠费金额
billPeriod	账期
triggerType	自动/人工

Writeback from SYS-010

Field	Meaning
eventNo	业务事件号
status	SUCCESS / FAIL / PENDING
failureReason	失败原因
resultChannel	实际触达渠道
resultTime	结果时间

Manual Verification Supplement

当外部结果长期未定或与业务侧核查结论不一致时，由 SYS-002 将任务状态补记为 MANUAL_VERIFIED，并保留核查人和核查说明。

4. State Contract

State	Meaning	Allowed Source
PENDING	已生成任务，等待协同结果或人工核查	SYS-002
SUCCESS	已确认触达成功	SYS-010 回写
FAIL	已确认发送失败	SYS-010 回写或失败确认
MANUAL_VERIFIED	经过人工核查后补记为有效结果	SYS-002 人工核查

5. History Query Contract

历史查询最小字段集必须支持：

• 客户号
• 账期
• 催缴方式
• 执行结果
• 发送时间
• 发送对象
• 关联账单
• 关联停复水/工单引用

该查询合同用于：

• 正式设计中的历史只读口径
• 迁移验收对账
• 后续催缴与停复水核查