---
mode: plan
cwd: D:\jsowell\IdeaProjects\jsowell-charger-web
task: 白名单支付订单在异常/待结算时自动修正为订单完成
complexity: medium
planning_method: builtin
created_at: 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`