From ee78477e8fb3ffde73013e04274846cb5cbdd3fd Mon Sep 17 00:00:00 2001
From: tangweijie <877588133@qq.com>
Date: Fri, 17 Apr 2026 10:52:11 +0800
Subject: [PATCH] Record prestorage formal-table rollout evidence for REV004

This documents the prestorage formal-table rollout status, including test DB
DDL application, HTTP smoke evidence, cleanup proof, and the updated
formal-table status matrix for REV004.

Constraint: Documentation must stay scoped to prestorage formal-table evidence and status updates only
Rejected: Fold unrelated REV004 evidence backlog into this commit | would dilute the deliverable and review scope
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: When process/attachments become strict formal-first, update the status matrix and evidence instead of replacing this rollout record
Tested: Evidence file cross-checked against backend compile/test/DB/HTTP smoke outputs
Not-tested: No independent docs rendering/export verification performed
---
 ...ge-formal-table-dev-db-apply-2026-04-16.md | 237 ++++++++++++++++++
 .../REV004_FORMAL_TABLE_STATUS_MATRIX.md      | 220 ++++++++++++++++
 2 files changed, 457 insertions(+)
 create mode 100644 docs/evidence/rev004-prestorage-formal-table-dev-db-apply-2026-04-16.md
 create mode 100644 docs/guides/REV004_FORMAL_TABLE_STATUS_MATRIX.md

diff --git a/docs/evidence/rev004-prestorage-formal-table-dev-db-apply-2026-04-16.md b/docs/evidence/rev004-prestorage-formal-table-dev-db-apply-2026-04-16.md
new file mode 100644
index 0000000..7d08b68
--- /dev/null
+++ b/docs/evidence/rev004-prestorage-formal-table-dev-db-apply-2026-04-16.md
@@ -0,0 +1,237 @@
+# REV004 prestorage formal-table 已应用到 application-dev 测试库（2026-04-16）
+
+## 目标库
+依据：
+- `sw-business/sw-business-server/src/main/resources/application-dev.yaml`
+
+解析结果：
+- Host：`192.168.10.130`
+- Port：`5436`
+- DB：`sw_system`
+- User：`sw_system`
+
+即当前 `application-dev` 指向的测试数据库为：
+`jdbc:postgresql://192.168.10.130:5436/sw_system`
+
+## 已执行脚本
+- `sql/rev004/REV004_prestorage_formal_tables_deploy.sql`
+
+执行命令：
+```bash
+PGPASSWORD='Em@123456' \
+psql -h 192.168.10.130 -p 5436 -U sw_system -d sw_system \
+  -v ON_ERROR_STOP=1 \
+  -f sql/rev004/REV004_prestorage_formal_tables_deploy.sql
+```
+
+## 执行结果
+结果：**PASS**
+
+执行输出显示：
+- `biz_prestorage_adjust_seq` 创建成功
+- `biz_prestorage_adjust_detail_seq` 创建成功
+- `biz_prestorage_adjust` 创建成功
+- `biz_prestorage_adjust_detail` 创建成功
+- 主表索引、明细表索引创建成功
+- 外键 `fk_biz_prestorage_adjust_detail_main` 创建成功
+
+## 回读校验
+### 表
+已确认存在：
+- `biz_prestorage_adjust`
+- `biz_prestorage_adjust_detail`
+
+### 序列
+已确认存在：
+- `biz_prestorage_adjust_seq`
+- `biz_prestorage_adjust_detail_seq`
+
+### 关键索引
+已确认存在：
+- `uk_biz_prestorage_adjust_no`
+- `idx_biz_prestorage_adjust_source`
+- `idx_biz_prestorage_adjust_target`
+- `idx_biz_prestorage_adjust_type`
+- `idx_biz_prestorage_adjust_status`
+- `idx_biz_prestorage_adjust_executed_at`
+- `idx_biz_prestorage_adjust_detail_main`
+- `idx_biz_prestorage_adjust_detail_type`
+- `idx_biz_prestorage_adjust_detail_charge`
+- `idx_biz_prestorage_adjust_detail_bill_month`
+
+### 外键
+已确认存在：
+- `fk_biz_prestorage_adjust_detail_main`
+  - `biz_prestorage_adjust_detail(prestorage_adjust_id) -> biz_prestorage_adjust(id)`
+
+## Smoke 验证
+### 1. 代码层最小验证
+执行：
+```bash
+mvn -pl sw-business/sw-business-server -DskipTests compile
+mvn -pl sw-business/sw-business-server -Dtest=AccountingAdjustProcessServiceImplTest,AccountingAdjustPrestorageProcessServiceImplTest test
+```
+
+结果：**PASS**
+
+说明：
+- prestorage submit / revoke 接线后的 Java 编译通过
+- `AccountingAdjustProcessServiceImplTest` 通过（13/13）
+- `AccountingAdjustPrestorageProcessServiceImplTest` 通过（4/4）
+- 合计目标测试：`17/17` 通过
+
+### 2. 数据库 transactional smoke
+执行：在测试库开启事务后，插入一笔 `biz_prestorage_adjust` 主表记录 + 一笔 `biz_prestorage_adjust_detail` 明细记录，随后回读计数，再 `ROLLBACK`。
+
+验证点：
+- 主表可写
+- 明细表可写
+- 外键约束正常
+- 回读可见
+- 回滚后不污染测试库
+
+实际结果：
+- `main_count=1`
+- `detail_count=1`
+- 回滚后再次检查 `adjustment_no='SMOKE-REV004-PRE-001'` 计数为 `0`
+
+结果：**PASS**
+
+## 当前结论
+`application-dev` 指向的测试数据库现在已经具备 REV004 prestorage formal-table 结构，可直接用于：
+1. 预存退款 / 预存转账 formal-table 双写
+2. prestorage page/detail/stat formal-table 优先投影联调
+3. 后续真实接口 smoke / canary 验证
+
+## 真实 HTTP smoke（补充于 2026-04-16 18:00 +08:00）
+为了避免命中本地旧 jar 进程，额外完成了以下动作：
+1. 使用最新代码重新执行 `mvn -pl sw-business/sw-business-server -DskipTests package`
+2. 以 `java -jar ... --server.port=48091` 启动一份隔离的新实例
+3. 通过 `login-user` 头模拟管理员上下文，直连 `/admin-api/business/accounting-adjust/*` 接口做 smoke
+
+### smoke 前置数据
+向测试库临时插入：
+- 源客户：`REV004_PRE_SMOKE_SRC`
+- 目标客户：`REV004_PRE_SMOKE_TGT`
+- 源账户余额：`100.00`
+- 目标账户余额：`5.00`
+
+### 1. prestorage-submit（refund）
+请求成功，返回：
+- `adjustmentNo = REV004-PRF-990001-20260416180029`
+- `resultStatus = SUCCESS`
+
+DB 回读确认：
+- `biz_prestorage_adjust` 新增 1 条 `REFUND`
+- `biz_prestorage_adjust_detail` 新增 1 条 `REFUND_RESULT`
+- 源账户余额由 `100.00 -> 90.00`
+
+### 2. prestorage-submit（transfer）
+请求成功，返回：
+- `adjustmentNo = REV004-PTR-990001-20260416180029`
+- `resultStatus = SUCCESS`
+
+DB 回读确认：
+- `biz_prestorage_adjust` 新增 1 条 `TRANSFER`
+- `biz_prestorage_adjust_detail` 新增 2 条：
+  - `SOURCE_ACCOUNT`
+  - `TARGET_ACCOUNT`
+- 源账户余额由 `90.00 -> 70.00`
+- 目标账户余额由 `5.00 -> 25.00`
+
+### 3. prestorage-page / prestorage-detail
+在 48091 新实例上验证：
+- `prestorage-page` 返回 2 条 smoke 数据
+- `prestorage-detail?id=3` 可正常返回 transfer formal 详情
+- transfer 记录状态为：
+  - `workOrderStatus = 2`
+  - `resultStatus = SUCCESS`
+  - `writeBackStatus = UPDATED`
+
+### 4. prestorage-process / prestorage-attachments
+在 48091 新实例上验证：
+- `prestorage-process?adjustmentNo=REV004-PTR-990001-20260416180029` 返回成功
+- `prestorage-attachments?...` 返回空数组 `[]`
+
+说明：
+- 当前 `process/attachments` 仍主要经 unified/legacy 查询口径返回，但因为 submit 继续写 `operat_log`，链路可正常工作
+- 这两条在本轮已不构成阻塞性故障
+
+### 5. prestorage-revoke
+调用：
+- `prestorage-revoke adjustmentNo=REV004-PTR-990001-20260416180029`
+
+返回：
+- `message = 预存转账撤销成功`
+- `resultStatus = SUCCESS`
+
+DB 回读确认：
+- `biz_prestorage_adjust` 中该 transfer 主记录状态变为：
+  - `result_status = REVOKED`
+  - `execute_status = REVOKED`
+- 对应 detail 状态均变为：
+  - `detail_status = REVOKED`
+  - `proc_type = REVOKE`
+- 账户余额恢复为：
+  - 源账户 `90.00`
+  - 目标账户 `5.00`
+- `prestorage-page` 再查可见该 transfer 记录：
+  - `workOrderStatus = 3`
+  - `canRevoke = false`
+
+## 测试数据清理
+为避免污染测试库，smoke 完成后已执行清理：
+- 删除临时 `biz_operat_log / detail`
+- 删除临时 `biz_prestorage_adjust / detail`
+- 删除临时 `biz_account`
+- 删除临时 `biz_cust`
+
+回读结果：
+- `formal_main_left = 0`
+- `operat_log_left = 0`
+- `cust_left = 0`
+
+## 当前仍未完全覆盖的点
+1. 本轮已经证明 HTTP submit/query/revoke 主链路可工作；
+2. 但 `prestorage-process / prestorage-attachments` 目前仍不是 strict formal-first，而是依赖 unified/legacy 口径兜底；
+3. 如果后续目标是“彻底以 formal-table 为唯一真值”，还需要继续收口这两条查询路径。
+
+## 建议后续
+1. backend PR 可以先按 prestorage formal-table 独立批次提交；
+2. PR 描述中明确：
+   - `process/attachments` 当前可用，但仍保留 legacy/unified 查询兜底；
+   - 后续可再开一批做 strict formal-first 收口；
+3. 保留 `REV004_prestorage_formal_tables_deploy.sql` 作为测试库 / 联调库初始化脚本。
+
+
+## 补充复核（2026-04-16 17:36 +08:00）
+### 1. 部署脚本幂等重放
+再次执行：
+```bash
+PGPASSWORD='Em@123456' psql -h 192.168.10.130 -p 5436 -U sw_system -d sw_system   -v ON_ERROR_STOP=1   -f sql/rev004/REV004_prestorage_formal_tables_deploy.sql
+```
+
+结果：**PASS**
+
+关键输出：
+- existing sequence/table/index 均以 `already exists, skipping` 形式跳过
+- 没有出现失败或约束重复异常
+
+说明：
+- `REV004_prestorage_formal_tables_deploy.sql` 具备测试库重放幂等性
+- 适合作为联调库/测试库初始化脚本继续使用
+
+### 2. 本地服务存活验证
+执行：
+```bash
+curl -sS http://127.0.0.1:48090/actuator/health
+```
+
+返回：
+```json
+{"status":"UP"}
+```
+
+说明：
+- 当前本地 `sw-business-server` 进程存活
+- 后续若补真实 HTTP 接口 smoke，可直接基于该运行实例继续
diff --git a/docs/guides/REV004_FORMAL_TABLE_STATUS_MATRIX.md b/docs/guides/REV004_FORMAL_TABLE_STATUS_MATRIX.md
new file mode 100644
index 0000000..0bcacc9
--- /dev/null
+++ b/docs/guides/REV004_FORMAL_TABLE_STATUS_MATRIX.md
@@ -0,0 +1,220 @@
+# REV004 原系统独立表 vs 当前新系统落地状态对照表
+
+## 文档目的
+梳理：
+1. 原系统数据字典中，这些账务处理对象是否按独立表建模
+2. 当前新系统 backend 是否已经恢复为独立 formal-table
+3. 哪些对象当前仍停留在日志骨架 / 兼容接口模式
+
+方便后续做对象化恢复排期判断。
+
+---
+
+## 一、结论总览
+
+| 对象 | 原系统数据字典 | 当前新系统状态 | 备注 |
+|---|---|---|---|
+| 预存退款 | 有独立表 | **已实现 formal-table（待进一步收口）** | prestorage formal-table 代码已接线，测试库 DDL 已落，HTTP smoke 已完成 |
+| 预存退款详情 | 有独立表 | **已实现 formal-table（待进一步收口）** | `biz_prestorage_adjust_detail` 已建模、落测试库并完成 HTTP smoke 验证 |
+| 预存转账 | 属于预存调整类型 | **已实现 formal-table（待进一步收口）** | transfer submit/revoke/page/detail 已接入 prestorage formal-table，process/attachments 仍保留 legacy/unified fallback |
+| 违约金减免汇总 | 有独立表 | **已独立 formal-table** | `biz_latefee_reduce` |
+| 违约金减免明细 | 有独立表 | **已独立 formal-table** | `biz_latefee_reduce_detail` |
+| 分账调整汇总 | 有独立表 | **已独立 formal-table** | `biz_split_adjust` |
+| 分账调整明细 | 有独立表 | **已独立 formal-table** | `biz_split_adjust_detail` |
+| 呆坏账汇总 | 有独立表 | 未独立 formal-table | 当前仍走兼容接口 |
+| 呆坏账明细 | 有独立表 | 未独立 formal-table | 当前无独立主从表 |
+| 已销调整汇总 | 有独立表 | 未独立 formal-table | 当前仍走兼容接口 |
+| 已销调整明细 | 有独立表 | 未独立 formal-table | 当前无独立主从表 |
+| 价差调整汇总 | 有独立表 | 未独立 formal-table | 当前仍走兼容接口 |
+| 价差调整明细 | 有独立表 | 未独立 formal-table | 当前无独立主从表 |
+| 退款账 | 有独立结果对象 | 未独立 formal-table | 当前未恢复为正式对象表 |
+
+---
+
+## 二、原系统字典里能确认的对象
+
+依据：
+- `docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md`
+
+在“收费、账务处理”目录项中，明确出现过以下对象/表：
+
+### 预存相关
+- `预存退款`
+- `预存退款详情表`
+
+### 违约金减免
+- `账单-违约金减免汇总表`
+- `账单-违约金减免详情表`
+
+### 分账
+- `分账调整汇总`
+- `分账调整明细`
+
+### 呆坏账
+- `账单-呆坏帐汇总表`
+- `账单-呆坏帐详情表`
+
+### 已销调整
+- `已销调整汇总`
+- `已销调整明细`
+
+### 价差调整
+- `价差调整汇总`
+- `价差调整明细`
+
+### 退款结果类
+- `退款账`
+
+这说明：  
+**原系统数据字典口径中，这些对象不是只靠统一日志表达，而是按独立业务表设计。**
+
+---
+
+## 三、原系统字典里的相关字典项
+
+原系统字典中，还单独存在这些字典项：
+
+- `预存调整类型`
+- `预存调整原因`
+- `违约金减免类型`
+- `违约金减免原因`
+- `分账调整类型`
+- `分账调整原因`
+- `呆坏账类型`
+- `呆坏账原因`
+- `价差调整原因`
+- `已销调整原因`
+
+其中：
+
+### 预存调整类型
+- `1 = 预存退款`
+- `2 = 预存转账`
+
+这说明：
+**原系统对“预存退款 / 预存转账”不只是页面操作概念，而是明确的业务类型定义。**
+
+---
+
+## 四、当前新系统已经恢复的对象
+
+## 4.1 分账 `SPLIT_ADJUST`
+
+### 已落地表
+- `biz_split_adjust`
+- `biz_split_adjust_detail`
+
+### 已有接口
+- `POST /admin-api/business/split-adjust/submit`
+- `GET /admin-api/business/split-adjust/page`
+- `GET /admin-api/business/split-adjust/detail`
+- `GET /admin-api/business/split-adjust/result`
+
+### 当前判断
+**已恢复为正式对象。**
+
+---
+
+## 4.2 违约金减免 `LATE_FEE_REDUCE`
+
+### 已落地表
+- `biz_latefee_reduce`
+- `biz_latefee_reduce_detail`
+
+### 已有接口
+- `POST /admin-api/business/accounting-adjust/unsold-late-fee-reduce-submit`
+- `POST /admin-api/business/accounting-adjust/unsold-late-fee-reduce-batch-submit`
+- 查询/审批继续走 `accounting-adjust` 兼容入口
+
+### 当前判断
+**已恢复为正式对象。**
+
+---
+
+## 五、当前新系统还没恢复的对象
+
+## 5.1 预存退款 / 预存转账
+
+### 当前实现
+- `biz_account`：余额变化
+- `biz_operat_log` / `biz_operat_log_detail`：兼容留痕
+- `biz_prestorage_adjust` / `biz_prestorage_adjust_detail`：formal-table 新实现
+
+### 当前判断
+**已实现 formal-table，当前处于“可提交独立 PR、后续继续收口 process/attachments strict formal-first”的状态。**
+
+当前已完成：
+- prestorage DO / Mapper / FormalizationService
+- submit / revoke 双写接线
+- `page/detail/stat` formal-table 优先投影
+- 测试库 DDL 已落
+- compile / targeted tests 通过
+- 真实 HTTP smoke（refund/transfer/revoke/page/detail/process/attachments）已完成
+
+当前未完成：
+- `process/attachments` strict formal-first 真值口径最终收口
+
+---
+
+## 5.2 坏账 `BAD_DEBT_RECORD`
+
+### 当前实现
+- 走 `accounting-adjust` 提交/查询/审批兼容链路
+- 没有独立主表/明细表
+
+### 当前判断
+**还不是 formal-table。**
+
+---
+
+## 5.3 已销调整 / 核销 `WRITTENOFF_ADJUST`
+
+### 当前实现
+- 走兼容接口
+- 无独立 formal-table
+
+### 当前判断
+**还不是 formal-table。**
+
+---
+
+## 5.4 价差调整 `PRICE_DIFF_ADJUST`
+
+### 当前实现
+- 走兼容接口
+- 无独立 formal-table
+
+### 当前判断
+**还不是 formal-table。**
+
+---
+
+## 六、最简判断口径
+
+### 原系统
+**是“对象独立建模”口径**
+- 业务对象有独立表
+- 类型/原因有独立字典
+
+### 当前新系统
+**是“部分恢复”口径**
+- 已恢复：
+  - 分账
+  - 违约金减免
+- 未恢复：
+  - 预存
+  - 坏账
+  - 核销
+  - 价差
+
+---
+
+## 七、建议后续确认口径
+
+可以直接对外说明：
+
+> 原系统字典里，预存退款、违约金减免、分账、坏账、已销调整、价差调整等对象，都是按独立表设计的。  
+> 当前新系统只恢复了“分账”和“违约金减免”两条 formal-table 路线，其他对象仍主要走日志骨架 / 兼容接口模式。  
+> 因此后续若继续做对象化恢复，优先需要确认：预存、坏账、核销、价差哪些要继续恢复成独立 formal-table。
+
+---