# REV004 未销违约金减免批量契约补齐实施记录（2026-04-14）

## 目标
补齐 `unsold-late-fee-reduce-batch-submit` 的批量 outer 契约，使其能够承接前端页面公共表单字段，并把字段真实透传到后端执行主链，而不是只停留在 controller VO。

## 本次实现
### 1. 批量 outer 契约补齐
文件：
- `sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/accountingadjust/accountProcess/vo/AccountingAdjustUnsoldLateFeeReduceBatchSubmitReqVO.java`
- `sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/accountingadjust/accountProcess/vo/AccountingAdjustUnsoldLateFeeReduceBatchItemReqVO.java`

新增 outer 字段：
- `lateFeeType`
- `applicant`
- `contactMobile`
- `applyReason`
- `remark`
- `attachmentRefs`

明细 item 独立为专用 VO：
- `chargeId`
- `adjustmentNo`
- `applyReason`（兼容旧逐项提交）
- `remark`（兼容旧逐项提交）
- `attachmentRefs`（兼容旧逐项提交）
- `lateFeeReduceAmount`
- `startDate`
- `endDate`

### 2. 共享 batch 主链承接 outer 字段
文件：
- `.../AccountingAdjustBatchSubmitReqVO.java`
- `.../AccountingAdjustActionController.java`
- `.../AccountingAdjustProcessServiceImpl.java`

处理方式：
- controller 先把 late-fee batch outer 字段规范化映射到 generic batch DTO
- process 主链在 `executeBatchSubmit` 中统一执行 outer -> item 合并
- 统一 batch 主链承接字段：
  - `reasonCode`
  - `reason`
  - `applicant`
  - `contactMobile`
  - `attachmentRefs`
  - `lateFeeType`

这避免了“专用 VO 上有字段，但 generic batch 主链吃不到”的伪完成。

### 3. amount / date 模式校验补齐
文件：
- `.../AccountingAdjustProcessServiceImpl.java`
- `.../AccountingAdjustReqVO.java`
- `.../ChargeServiceImpl.java`

规则：
- `lateFeeType=1`（按金额）
  - 要求 `lateFeeReduceAmount > 0`
  - 不允许同时传 `startDate/endDate`
- `lateFeeType=2`（按日期）
  - 要求 `startDate/endDate` 同时存在，且 `endDate >= startDate`
  - 不允许同时传 `lateFeeReduceAmount`
- 未显式传 `lateFeeType` 时：
  - 若存在日期字段，推导为 `2`
  - 否则默认 `1`

### 4. 执行日志落地字段补齐
文件：
- `.../AccountingAdjustReqVO.java`
- `.../ChargeServiceImpl.java`

新增写入 operat log detail 的字段：
- `lateFeeType`
- `applicant`
- `contactMobile`
- `startDate`
- `endDate`

## 验证结果
### 编译
命令：
```bash
mvn -pl sw-business/sw-business-server -DskipTests compile
```
结果：**PASS**

### 定向单测
命令：
```bash
mvn -pl sw-business/sw-business-server \
  -Dtest=AccountingAdjustActionControllerTest#batchCreateUnsoldLateFeeReduce_shouldReturnWrappedSuccess,AccountingAdjustProcessServiceImplTest#createUnsoldLateFeeReduce_shouldPassDateModeFieldsToUnifiedChargeService+createUnsoldLateFeeReduce_shouldRejectMixedAmountAndDateMode+batchCreateUnsoldLateFeeReduce_shouldMergeBatchOuterFieldsIntoItems \
  test
```
结果：**PASS（4 tests, 0 fail, 0 error）**

### 真实 DB 定向集成
命令：
```bash
REV004_IT_DB_URL=jdbc:postgresql://192.168.10.130:5436/sw_system \
REV004_IT_DB_USERNAME=sw_system \
REV004_IT_DB_PASSWORD='Em@123456' \
mvn -pl sw-business/sw-business-server \
  -Dtest=Rev004AccountProcessCanaryQueryIntegrationTest#unsoldLateFeeReduceBatchSubmit_shouldAcceptOuterFieldsAndDateModeContract \
  test
```
结果：**PASS（1 test, 0 fail, 0 error）**

集成验证确认：
- batch outer 字段可提交
- `lateFeeType=2` date-mode 契约可进入主链
- operat log detail 中可看到：
  - `lateFeeType=2`
  - `applicant`
  - `contactMobile`
  - `startDate`
  - `endDate`
  - `attachmentRefs`

## 当前边界与剩余风险
1. **本轮重点是“提交契约 + 主链承接 + 日志落地”**。
2. `lateFeeType=2` 的“按日期执行态/审批回写态”尚未展开为完整金额计算逻辑；当前已确保申请态与提交链路可用。
3. 由于仓库当前还存在其他在制改动，本轮只做了定向验证，没有把整个相关测试类全部拉绿。

## 结论
本轮已完成 REV004 未销违约金减免批量提交接口的主契约补齐，并把前端页面公共字段正式落到共享 batch 主链与日志记录中；可以支撑前端继续联调“按金额/按日期”两种提交形态。

## 追加收口（读模型展示字段）
### 本轮补齐
- `AccountingAdjustDetailRespVO` 新增：
  - `lateFeeType`
  - `applicant`
  - `contactMobile`
  - `startDate`
  - `endDate`
- `AccountingAdjustLogDetailRespVO` 新增同名字段
- `AccountingAdjustProcessRespVO` 新增：
  - `reasonCode`
  - `attachmentRefs`
  - `lateFeeType`
  - `applicant`
  - `contactMobile`
  - `startDate`
  - `endDate`

### 读取链路
- `AccountingAdjustQueryServiceImpl`：从 operat log detail 读取 late-fee 扩展字段并映射到 detail response
- `AccountingAdjustLogProcessServiceImpl`：从 request/action log detail 读取 late-fee 扩展字段并映射到 log-detail response
- `AccountingAdjustProcessServiceImpl#getProcess`：从 unified snapshot 读取并投影到 process response

### 追加验证
#### 定向读模型单测
```bash
mvn -pl sw-business/sw-business-server \
  -Dtest=AccountingAdjustQueryServiceImplTest,AccountingAdjustLogProcessServiceImplTest,AccountingAdjustProcessServiceImplTest#getProcess_shouldExposeLateFeeDisplayFieldsFromUnifiedSnapshot \
  test
```
结果：**PASS（7 tests, 0 fail, 0 error）**