tangweijie 3eccab2cf9 docs: 文档治理统一 — AGENTS.md 生命周期规则 + 模块归档 + DDL 修正

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

2026-06-16 11:47:16 +08:00

3.9 KiB

Raw Blame History

REV004 预存调整 prestorage-submit 开发环境调用记录（2026-04-23）

验证日期：2026-04-23
后端仓基线：21714d64822268d8dcb7cd1296656b4c19ff95fa
前端仓基线：d2698e1f5d107422f64928086d89d4b803cd12ae
目标环境：root@192.168.10.130
服务端口：sw-gateway -> 127.0.0.1:48080，sw-business-server -> 127.0.0.1:48090
配置依据：
- water-backend/sw-gateway/src/main/resources/application-dev.yaml
- water-backend/sw-business/sw-business-server/src/main/resources/application-dev.yaml
鉴权方式：开发环境 sw.security.mock-enable=true，使用 Authorization: Bearer emsoft1 + tenant-id: 1

1. 实际调用 payload

{
  "applicant": "李四",
  "applyReason": "充值错误",
  "attachmentRefs": [],
  "contactMobile": "19928382738",
  "custCode": "26041011111",
  "refundAmount": 2,
  "remark": "ssa"
}

2. 实际调用命令

2.1 直连 business

curl -X POST 'http://127.0.0.1:48090/admin-api/business/accounting-adjust/prestorage-submit' \
  -H 'Authorization: Bearer emsoft1' \
  -H 'tenant-id: 1' \
  -H 'Content-Type: application/json' \
  --data '{"applicant":"李四","applyReason":"充值错误","attachmentRefs":[],"contactMobile":"19928382738","custCode":"26041011111","refundAmount":2,"remark":"ssa"}'

2.2 走 gateway

curl -X POST 'http://127.0.0.1:48080/admin-api/business/accounting-adjust/prestorage-submit' \
  -H 'Authorization: Bearer emsoft1' \
  -H 'tenant-id: 1' \
  -H 'Content-Type: application/json' \
  --data '{"applicant":"李四","applyReason":"充值错误","attachmentRefs":[],"contactMobile":"19928382738","custCode":"26041011111","refundAmount":2,"remark":"ssa"}'

3. 调用结果

直连 business 与走 gateway 返回一致：

{"code":500,"data":null,"msg":"系统异常"}

4. 后端日志根因

sw-business-server 日志显示真实异常为：

java.lang.IllegalArgumentException: 账户预存余额不足
at cn.com.emsoft.sw.business.service.accountingadjust.accountProcess.AccountingAdjustProcessServiceImpl.createPrestorageAction(AccountingAdjustProcessServiceImpl.java:213)

对应代码位置：

water-backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/accountingadjust/accountProcess/AccountingAdjustProcessServiceImpl.java

关键逻辑：

读取客户与账户
将 deposit == null 视为 0
校验 deposit < refundAmount 时抛出 IllegalArgumentException("账户预存余额不足")

5. 数据库核验

开发库（sw_system）中当前客户与账户数据：

select id, code, name, population, address, status, tenant_id
from biz_cust
where deleted = 0 and code = '26041011111';

select id, cust_id, deposit, uncheck_money, overdraft, status, deleted, tenant_id
from biz_account
where cust_id = 67 and deleted = 0;

结果：

biz_cust:
67 | 26041011111 | liao | 3 | 11 | 0 | 1

biz_account:
65 | 67 | null | null | 0.0000 | 0 | 0 | 1

结论：当前测试客户 26041011111 的 biz_account.deposit 为空，业务侧按 0 处理，因此退款金额 2 会命中“账户预存余额不足”。

6. 结论

本次 prestorage-submit 调用链路本身可达，鉴权可用，接口也已命中后端业务逻辑。失败原因不是网关/路由/权限，而是当前测试数据不满足退款校验条件：

客户存在
账户存在
账户预存余额为空（按 0 处理）
refundAmount = 2，因此提交失败

7. 后续建议

二选一：

修正该测试客户的 biz_account.deposit，使其大于等于 2
改用当前开发库中预存余额充足的客户进行 prestorage-submit 联调

附带观察：当前前端收到的是泛化后的 系统异常，而非后端真实业务提示 账户预存余额不足。如果需要提升联调效率，可后续评估是否将该类参数/业务校验异常以明确业务消息返回前端。

3.9 KiB Raw Blame History Unescape Escape