jsowell-charger-web/plan/2026-01-23_16-45-56-whitelist-order-status-complete.md

mode, cwd, task, complexity, planning_method, created_at

mode	cwd	task	complexity	planning_method	created_at
plan	D:\jsowell\IdeaProjects\jsowell-charger-web	白名单支付订单在异常/待结算时自动修正为订单完成	medium	builtin	2026-01-23T16:45:56.6767838+08:00

Plan: 白名单支付订单状态修正（异常/待结算 -> 完成）

🎯 任务概述 当前系统中存在白名单支付（payMode=3）的订单，在某些场景下可能停留在“异常(4)”或“待结算(2)”状态。目标是在满足白名单支付条件时，将这些订单状态修正为“订单完成(6)”，并确保必要的结算时间/金额字段与后续流程（通知、解锁、分账/退款）保持一致或可控。

📋 执行计划

1. 需求澄清与验收口径

   • 明确“白名单支付”的判定字段：order_basic_info.pay_mode 是否恒为 3（参考 OrderPayModeEnum.PAYMENT_OF_WHITELIST），以及是否需要同时检查支付流水 order_pay_record.pay_mode。
   • 定义修正规则：仅对白名单支付订单，且当前状态 ∈ {ABNORMAL(4), STAY_SETTLEMENT(2)} 时修正为 ORDER_COMPLETE(6)；确认是否需要同步设置 settlement_time、order_amount、refund_amount、virtual_amount、settle_amount、pay_status 等字段。

2. 代码定位与影响面梳理

   • 定位现有白名单异常订单批量处理入口：jsowell-admin/src/main/java/com/jsowell/service/TempService.java 的 whiteListSettlement 与 jsowell-admin/src/main/java/com/jsowell/api/uniapp/customer/TempController.java 的 /whiteListSettlement。
   • 查找订单状态被设置为异常/待结算的路径，确认修正应放在“状态写入点”还是“事后补偿点”。重点关注：
     • jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderStatusEnum.java
     • jsowell-admin/src/main/java/com/jsowell/service/OrderService.java（存在将充电中订单标记为异常的逻辑）
     • jsowell-pile/src/main/java/com/jsowell/pile/service/impl/OrderBasicInfoServiceImpl.java、jsowell-pile/src/main/java/com/jsowell/pile/service/programlogic/AbstractProgramLogic.java（结算后会落库为完成）

3. 设计修正策略（推荐“统一补偿方法”）

   • 在订单领域服务中新增一个可复用的方法（命名示例：completeWhitelistOrderIfNeeded(orderCode)），封装：
     • 判定：payMode=3 且状态为异常/待结算。
     • 修正：更新为 ORDER_COMPLETE，补齐 settlement_time（无则置当前时间），并根据现有数据填充金额字段（缺失时以 0 或合理默认值），确保幂等。
   • 选择调用点：
     • 扩展现有 /whiteListSettlement：允许处理 ABNORMAL 与 STAY_SETTLEMENT 两种状态；内部改为调用统一补偿方法。
     • 视业务需要补充一个定时任务/管理端按钮做批量修复（避免仅靠人工接口）。

4. 实现细节落地

   • 调整 TempService.whiteListSettlement：
     • 将“只允许异常订单”的校验扩展为“异常或待结算”。
     • 将硬编码 payMode == "3" 改为使用枚举 OrderPayModeEnum.PAYMENT_OF_WHITELIST.getValue()。
     • 明确是否继续调用 orderService.manualSettlementOrder(...)（它会尝试远程停机、拉取交易记录）；若目标仅是状态修正，优先走新的补偿方法，避免不必要的外部依赖。

5. 测试与回归

   • 增加单元/集成测试覆盖：
     • 白名单订单 + 状态=异常 -> 修正为完成。
     • 白名单订单 + 状态=待结算 -> 修正为完成。
     • 非白名单订单不应被修正。
   • 运行验证命令：mvn -pl jsowell-admin test（必要时指定测试类）。

6. 数据校验与上线准备

   • 在测试环境执行一次“选定订单号列表”的演练：调用 /whiteListSettlement，检查 DB 中 order_basic_info.order_status 与关键金额/时间字段。
   • 记录回滚策略：如发现误改，可按订单号将状态回退到原值（建议在修正前记录原状态/时间到日志或审计表）。

⚠️ 风险与注意事项

• 业务风险：将异常/待结算直接置为完成可能掩盖真实设备/交易异常；需确认是否仍需要保留异常原因字段或额外审计。
• 技术风险：如果修正流程绕过了“解锁卡/VIN、推送MQ、实时数据落库”等步骤，可能导致下游状态不一致；应明确是否需要补做这些副作用。
• 兼容性：TempService.whiteListSettlement 当前只允许异常订单，放宽后需确认调用方预期与权限控制。

📎 参考

• jsowell-admin/src/main/java/com/jsowell/service/TempService.java
• jsowell-admin/src/main/java/com/jsowell/api/uniapp/customer/TempController.java
• jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderStatusEnum.java
• jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderPayModeEnum.java
• jsowell-admin/src/main/java/com/jsowell/service/OrderService.java
• jsowell-pile/src/main/java/com/jsowell/pile/service/programlogic/AbstractProgramLogic.java