# 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`