316 lines
9.1 KiB
Markdown
316 lines
9.1 KiB
Markdown
# REV004 / accountProcess 接口真值矩阵（2026-04-13）
|
||
|
||
## 目的
|
||
给前端/联调/验收一个“当前代码真实口径”矩阵：
|
||
- 哪个页面/弹窗对应哪些接口
|
||
- 每个接口当前稳定返回哪些关键字段
|
||
- 哪些字段已经被真实库测试覆盖
|
||
- 哪些地方仍然是页面编排层面的剩余缺口
|
||
|
||
> 口径来源：`water-backend` 当前控制器 + Req/RespVO + 已落地真实库 canary。
|
||
|
||
---
|
||
|
||
## 一、页面 / 弹窗 -> 接口映射
|
||
|
||
### 1. 预存调整页
|
||
#### 查询区
|
||
- `GET /admin-api/business/accounting-adjust/prestorage-page`
|
||
- `GET /admin-api/business/accounting-adjust/prestorage-stat`
|
||
- `GET /admin-api/business/accounting-adjust/prestorage-detail?id={id}`
|
||
|
||
#### 动作区
|
||
- `POST /admin-api/business/accounting-adjust/prestorage-submit`
|
||
- `POST /admin-api/business/accounting-adjust/prestorage-revoke`
|
||
- `GET /admin-api/business/accounting-adjust/prestorage-process?adjustmentNo=...`
|
||
- `GET /admin-api/business/accounting-adjust/prestorage-attachments?adjustmentNo=...`
|
||
|
||
#### 维护区
|
||
- `POST /prestorage-customer-update`
|
||
- `POST /prestorage-meter-update`
|
||
- `POST /prestorage-billing-update`
|
||
- `POST /prestorage-discount-update`
|
||
- `POST /prestorage-cost-component-update`
|
||
|
||
### 2. 已销调整页
|
||
#### 查询区
|
||
- `GET /admin-api/business/accounting-adjust/sold-page`
|
||
- `GET /admin-api/business/accounting-adjust/sold-stat`
|
||
|
||
#### 动作区
|
||
- `POST /admin-api/business/accounting-adjust/sold-submit`
|
||
- `POST /admin-api/business/accounting-adjust/sold-batch-revoke`
|
||
|
||
### 3. 未销调整页
|
||
#### 查询区
|
||
- `GET /admin-api/business/accounting-adjust/unsold-page`
|
||
- `GET /admin-api/business/accounting-adjust/unsold-stat`
|
||
|
||
#### 动作区（按弹窗切换）
|
||
- 调整：`POST /unsold-adjust-submit`
|
||
- 分账：`POST /unsold-split-submit`
|
||
- 违约金减免：`POST /unsold-late-fee-reduce-submit`
|
||
- 价差调整：`POST /unsold-price-diff-submit`
|
||
- 呆坏账：`POST /unsold-bad-debt-submit`
|
||
|
||
#### 批量区
|
||
- `POST /unsold-adjust-batch-submit`
|
||
- `POST /unsold-split-batch-submit`
|
||
- `POST /unsold-late-fee-reduce-batch-submit`
|
||
- `POST /unsold-price-diff-batch-submit`
|
||
- `POST /unsold-bad-debt-batch-submit`
|
||
|
||
### 4. 账务日志页
|
||
#### 查询区
|
||
- `GET /admin-api/business/accounting-adjust/log-page`
|
||
- `GET /admin-api/business/accounting-adjust/log-stat`
|
||
- `GET /admin-api/business/accounting-adjust/log-detail?adjustmentNo=...`
|
||
|
||
#### 二次动作弹窗
|
||
- 转退款：`POST /admin-api/business/accounting-adjust/log-refund`
|
||
- 转预存：`POST /admin-api/business/accounting-adjust/log-prestorage`
|
||
- 撤销：`POST /admin-api/business/accounting-adjust/log-revoke`
|
||
|
||
#### 辅助弹窗
|
||
- `GET /admin-api/business/accounting-adjust/log-process?adjustmentNo=...`
|
||
- `GET /admin-api/business/accounting-adjust/log-attachments?adjustmentNo=...`
|
||
|
||
---
|
||
|
||
## 二、关键返回字段真值
|
||
|
||
### A. 通用动作返回 `AccountingAdjustRespVO`
|
||
适用：
|
||
- `prestorage-submit`
|
||
- `sold-submit`
|
||
- `unsold-*submit`
|
||
- `log-refund`
|
||
- `log-prestorage`
|
||
|
||
当前稳定字段：
|
||
- `adjustmentNo`：主联调键
|
||
- `objectType`：对象类型；未销调整 AMOUNT/USAGE 场景可能为空，其他场景一般有值
|
||
- `resultStatus`：推荐前端主读字段
|
||
- `approvalStatus`
|
||
- `writeBackStatus`
|
||
- `approvalRequired`
|
||
- `resultObjectNo`
|
||
- `msg`
|
||
- `status`：兼容旧字段
|
||
- `message`：兼容旧字段
|
||
|
||
前端推荐：
|
||
- **优先读** `resultStatus / approvalStatus / writeBackStatus / msg`
|
||
- `status / message` 仅做兼容保底
|
||
|
||
### B. 撤销 / 审批动作返回 `AccountingAdjustActionRespVO`
|
||
适用：
|
||
- `prestorage-revoke`
|
||
- `log-revoke`
|
||
|
||
当前稳定字段：
|
||
- `adjustmentNo`
|
||
- `objectType`
|
||
- `actionType`（当前撤销返回 `REVOKE`）
|
||
- `approvalStatus`
|
||
- `resultStatus`
|
||
- `writeBackStatus`
|
||
- `message`
|
||
- `actionTime`
|
||
|
||
### C. 预存分页 `AccountingAdjustPrestoragePageRespVO`
|
||
关键字段：
|
||
- `id`
|
||
- `adjustmentNo`
|
||
- `custId`
|
||
- `workOrderStatus`
|
||
- `adjustmentType`
|
||
- `custCode / custName / custAddress`
|
||
- `targetCustCode`
|
||
- `adjustAmount / preBalance / postBalance`
|
||
- `adjustReason / remark`
|
||
- `createTime / creatorName`
|
||
- `canRevoke / canViewAttachment`
|
||
|
||
补充：
|
||
- `prestorage-detail` 在上面基础上增加：
|
||
- `objectType`
|
||
- `resultStatus`
|
||
- `approvalStatus`
|
||
- `writeBackStatus`
|
||
- `processInstanceId`
|
||
- `attachmentRefs`
|
||
|
||
### D. 已销分页 `AccountingAdjustSoldPageRespVO`
|
||
关键字段：
|
||
- `id`
|
||
- `custId`
|
||
- `accountMonth`
|
||
- `custCode / custName / custAddress`
|
||
- `waterNature`
|
||
- `billedWaterVolume`
|
||
- `actualAmount`
|
||
- `billedAmount`
|
||
- `penaltyAmount`
|
||
- `collectionMethod`
|
||
- `collector`
|
||
- `collectionDate`
|
||
- `canAdjust`
|
||
- `canBatchRevoke`
|
||
|
||
注意：
|
||
- 已销查询页**不是调整日志页**，所以这里没有 `adjustmentNo`
|
||
- `sold-submit` 提交后，前端若要看申请单号，应跳到 `log-*` 维度或使用提交返回值保存的 `adjustmentNo`
|
||
|
||
### E. 未销分页 `AccountingAdjustUnsoldPageRespVO`
|
||
关键字段：
|
||
- `id`
|
||
- `custId`
|
||
- `custCode / custName / custAddress`
|
||
- `waterType`
|
||
- `accountMonth`
|
||
- `waterVolume`
|
||
- `totalAmount / billAmount / penaltyAmount`
|
||
- `waterFee / sewageFee / garbageFee / resourcesFee / overPlanFee / seasonalSupplement`
|
||
- `canAdjust / canSplit / canLateFeeReduce / canPriceDiffAdjust / canBadDebtAdjust`
|
||
|
||
### F. 日志分页 `AccountingAdjustLogPageRespVO`
|
||
关键字段：
|
||
- `id`
|
||
- `adjustmentNo`
|
||
- `accountMonth`
|
||
- `custId / custCode / custName / custAddress`
|
||
- `accountTypeCode / accountType`
|
||
- `processMethodCode / processMethod`
|
||
- `amount`
|
||
- `description`
|
||
- `registrant / handler`
|
||
- `handleTime / createTime`
|
||
- `statusCode / status`
|
||
- `targetCustCode`
|
||
- `originalPrestore / newPrestore`
|
||
- `originalBill / newBill`
|
||
- `originalWaterVolume / newWaterVolume`
|
||
- `originalPenalty / newPenalty`
|
||
- `billChange / waterVolumeChange / penaltyChange`
|
||
- `canRevoke / canRefund / canPrestore`
|
||
|
||
### G. 日志详情 `AccountingAdjustLogDetailRespVO`
|
||
在日志分页基础上增加：
|
||
- `objectType`
|
||
- `resultStatus`
|
||
- `approvalStatus`
|
||
- `writeBackStatus`
|
||
- `originalTranSeq`
|
||
- `originalSysTranSeq`
|
||
- `attachmentRefs`
|
||
- `details[]`
|
||
|
||
### H. 流程 / 附件
|
||
#### `AccountingAdjustProcessRespVO`
|
||
关键字段：
|
||
- `adjustmentNo`
|
||
- `objectType`
|
||
- `adjustType`
|
||
- `chargeId`
|
||
- `actionAmount`
|
||
- `resultStatus`
|
||
- `approvalStatus`
|
||
- `writeBackStatus`
|
||
- `taskId`
|
||
- `processState`
|
||
- `latestMessage`
|
||
- `latestOperationTime`
|
||
- `stages[]`
|
||
|
||
#### `AccountingAdjustAttachmentRespVO`
|
||
关键字段：
|
||
- `adjustmentNo`
|
||
- `ref`
|
||
- `resolved`
|
||
- `id / name / link / size / extension`
|
||
- `message`
|
||
|
||
---
|
||
|
||
## 三、当前已经被真实库测试证明的字段/链路
|
||
|
||
### 已证明
|
||
#### 预存
|
||
- `prestorage-submit` 返回 `adjustmentNo/resultStatus/writeBackStatus`
|
||
- `prestorage-page` 可见新记录
|
||
- `prestorage-stat` 可统计到 `refundCount`
|
||
- `prestorage-detail` 可按 `id` 回看 `resultStatus/writeBackStatus`
|
||
- `prestorage-revoke` 可回滚余额并生成撤销日志
|
||
|
||
#### 已销
|
||
- `sold-submit` 返回 `adjustmentNo/resultStatus=PENDING_APPROVAL`
|
||
- `sold-page` 可见原账单，且 `canBatchRevoke=true`
|
||
- `sold-stat` 可统计 `totalCount / totalActualAmount`
|
||
- `sold-batch-revoke` 可按营业账 ID 执行撤销
|
||
|
||
#### 未销
|
||
- 五类 submit 均已跑通真实库 happy path：
|
||
- adjust
|
||
- split
|
||
- late-fee-reduce
|
||
- price-diff
|
||
- bad-debt
|
||
- 动作返回值与 operat_log 写入已被验证
|
||
|
||
#### 日志
|
||
- `log-page / log-stat / log-detail / log-process / log-attachments` 已形成一组真实库联动回看
|
||
- `log-refund`、`log-prestorage`、`log-revoke` 已打通闭环
|
||
- `log-detail` 中 `originalTranSeq / attachmentRefs` 已被验证
|
||
|
||
---
|
||
|
||
## 四、前端使用建议（当前真值口径）
|
||
|
||
### 1. 提交后立即展示
|
||
提交类动作完成后，前端应优先使用提交响应里的：
|
||
- `adjustmentNo`
|
||
- `resultStatus`
|
||
- `approvalStatus`
|
||
- `writeBackStatus`
|
||
- `msg`
|
||
|
||
### 2. 页面列表回看
|
||
- 预存页：查 `prestorage-page`
|
||
- 已销页：查 `sold-page`
|
||
- 未销页：查 `unsold-page`
|
||
- 若要看“申请/动作留痕”，查 `log-page`
|
||
|
||
### 3. 二次动作弹窗
|
||
- 日志页弹窗（退款/转预存/撤销）都应以 `adjustmentNo` 作为主键
|
||
- 已销批量撤销当前以 `chargeIds[]` 为入参，不是 `adjustmentNo[]`
|
||
|
||
### 4. 状态口径
|
||
- 预存页 `workOrderStatus`：0未处理 / 1已审核 / 2已完成 / 3已撤销
|
||
- 通用动作结果：
|
||
- `resultStatus`
|
||
- `approvalStatus`
|
||
- `writeBackStatus`
|
||
- 日志页状态：
|
||
- `statusCode/status` 为页面状态投影，不等于 `workOrderStatus`
|
||
|
||
---
|
||
|
||
## 五、剩余缺口
|
||
1. 还没有做“前端弹窗 A/B/C 切换路径”的 UI 级编排，只做到了接口级真实库链路。
|
||
2. 还没有把所有字段做成“页面元素 -> 字段 -> 接口 -> 证据”的逐项勾稽表。
|
||
3. 若后续要做最终验收，建议再补一版：
|
||
- 弹窗功能分组矩阵
|
||
- 字段级 contract/assertion matrix
|
||
|
||
---
|
||
|
||
## 六、证据索引
|
||
- 集成测试 bootstrap 与累计验证：
|
||
- `docs/evidence/rev004-accountprocess-integration-testing-bootstrap-2026-04-13.md`
|
||
- 代码位置：
|
||
- `sw-business-server/src/main/java/.../accountProcess/*Controller.java`
|
||
- `sw-business-server/src/main/java/.../accountProcess/vo/*ReqVO.java`
|
||
- `sw-business-server/src/main/java/.../accountProcess/vo/*RespVO.java`
|
||
- `sw-business-server/src/test/java/.../integration/rev004/accountprocess/Rev004AccountProcessCanaryQueryIntegrationTest.java`
|