tangweijie
3eccab2cf9
1. AGENTS.md 更新 - water-docs: 新增 specs/ 与 docs/design/ 生命周期规则章节 - water-backend: 更新协作引用（建设期/建成后、evidence 模块化） 2. specs/ 重复合并 - 006-reminder-event-design 合并入 003-rev006-reminder-event-design - 001-rev004-accounting 删除冗余 data-model.md + contracts/ - 002-rev005-invoice-flow 删除冗余 data-model.md + contracts/ 3. evidence 按模块归档 - 35 个 REV-004 文件归入 evidence/rev004-accounting/ - 7 个通用 bugfix 文件归入 evidence/bugfix/ 和 bugfix/frontend/ - 新建 rev005-invoice/、rev006-reminder/、rev007-statistics/ 目录 4. guides/ 清理 - 14 个 REV004_*.md 移入 evidence/rev004-accounting/ 5. 遗留文件处理 - docs/research/ 归档到 Archive/06_Migration_Plans/ - backend-check detached worktrees 清理 6. 交叉引用修复 - 006-reminder-event-design → 003-rev006-reminder-event-design - docs/guides/REV004_ → docs/evidence/rev004-accounting/REV004_ 7. DB 设计文档修正（01_Database_Design.md） - biz_invoice 明确为开票配置表，非发票记录表 - 新增 biz_invoice_record 为发票申请/结果主表 - 新增 biz_charge_invoice_rel 账单-发票关联说明 - REV-005 承接口径表名全部修正 8. 发票审计证据 - 新增 evidence/rev005-invoice/2026-06-16-invoice-document-audit.md
115 lines
3.5 KiB
Markdown
115 lines
3.5 KiB
Markdown
# 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`
|