update

2026-05-10 04:50:11 +08:00 · 2026-05-07 16:35:05 +08:00
parent 6badd656fe
commit 87afb3680a
20 changed files with 7 additions and 7 deletions
--- a/docs/plan/2026-01-23_16-45-56-whitelist-order-status-complete.md
+++ b/docs/plan/2026-01-23_16-45-56-whitelist-order-status-complete.md
@@ -0,0 +1,104 @@
+---
+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` 等字段。
+
+✅ 规则清单（可实现/可测试）
+- 白名单判定：以 `order_basic_info.pay_mode == OrderPayModeEnum.PAYMENT_OF_WHITELIST(3)` 为主（系统业务字段）；若存在支付流水，可选做一致性校验 `order_pay_record.pay_mode == OrderPayRecordEnum.WHITELIST_PAYMENT(3)`，不一致时仅记录告警日志，不阻断补偿。
+- 修正边界：仅当订单状态 ∈ {`ABNORMAL(4)`, `STAY_SETTLEMENT(2)`} 才允许修正为 `ORDER_COMPLETE(6)`；其余状态必须保持不变。
+- 字段同步（补偿落库时）：
+  - `order_status`：置为 `ORDER_COMPLETE(6)`
+  - `settlement_time`：为空则置当前时间；非空保持原值
+  - 金额字段默认策略（尽量沿用既有结算逻辑的语义）：
+    - `order_amount`：优先保留已有值；为空则使用 `pay_amount`，仍为空则置 0；若 `order_amount > pay_amount` 则以 `pay_amount` 为准
+    - `virtual_amount`：白名单支付场景置为 `order_amount`（不参与结算对账）
+    - `settle_amount` / `actual_received_amount`：置为 `order_amount - virtual_amount`（白名单场景为 0）
+    - `refund_amount`：为空则置为 `max(pay_amount - order_amount, 0)`
+  - `pay_status`：优先保留原值；为空则置 `OrderPayStatusEnum.pay_nothing(2)`
+- 副作用约束：补偿方法为 DB/缓存层修正，不应触发远程停机、拉交易记录、MQ 推送、解锁等额外链路（如需触发，应另起规则与验收）。
+- 审计日志：至少记录 `orderCode`、原状态、目标状态（必要时补充关键字段快照）。
+
+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`（结算后会落库为完成）
+
+📌 影响面清单（可审计）
+- 白名单批量入口（人工/管理接口）：`TempController#/whiteListSettlement` → `TempService#whiteListSettlement`（当前仅允许异常订单、且硬编码 payMode=3，并调用 `OrderService#manualSettlementOrder`，会触发远程停机/拉交易记录等外部依赖）。
+- 订单标记异常（后管查询触发）：`OrderService#getOrderDetail` 在“充电中”但实时数据缺失/超时场景会将订单置为 `ABNORMAL(4)` 并落库。
+- 待结算写入点（设备/交易链路）：
+  - `RemoteStopChargingStrategy`：停机成功→`STAY_SETTLEMENT(2)`；停机失败→`ABNORMAL(4)`。
+  - `TransactionRecordsStrategy`：收到交易记录后，若订单为 `ABNORMAL(4)` 会先改为 `STAY_SETTLEMENT(2)`，随后进入 `ProgramLogicFactory#getProgramLogic(...).settleOrder(...)` 完成结算落库。
+  - 其他协议/平台（同类写入点）：`jsowell-netty` 的 yunkuaichong handlers、`jsowell-thirdparty` 的 Huawei 等也存在将订单置为 `STAY_SETTLEMENT(2)` 的路径（需避免在这些写入点引入“白名单直接完成”造成副作用扩散）。
+- 结算后落库完成（核心）：`AbstractProgramLogic#returnUpdateOrderBasicInfo` 会设置 `ORDER_COMPLETE(6)` 并写入结算时间/金额字段（及可能补 SOC）。
+
+🧭 修正插入点选择（结论）
+- 选择“事后补偿点”而不是在各类“状态写入点”分散修正：以统一补偿方法 + 白名单批量入口调用为主（后续可扩展定时任务/管理按钮复用该方法）。
+- 理由：避免侵入设备协议/交易记录链路（风险大、场景多）；补偿方法可控、幂等、日志可追溯，且明确不触发远程停机/拉交易/MQ/解锁等外部副作用。
+
+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. 数据校验与上线准备
+   - 演练入口：`POST /temp/whiteListSettlement`
+     - body（示例）：`{"orderCodeList":["O1","O2"]}`
+   - 演练前（务必留存快照，用于回滚/审计）：
+     - DB 快照（示例 SQL）：
+       - `SELECT order_code,pay_mode,order_status,pay_status,settlement_time,order_amount,virtual_amount,settle_amount,actual_received_amount,refund_amount,reason FROM order_basic_info WHERE order_code IN ('O1','O2');`
+     - 将查询结果保存到工单/PR/运维记录（CSV/截图均可）。
+   - 演练后（校验点）：
+     - `order_basic_info.order_status = 6`
+     - `settlement_time`：原为空则已填充；原非空保持不变
+     - 金额字段符合“规则清单”默认策略（白名单虚拟金额/结算金额等）
+     - 日志可追溯：搜索 `completeWhitelistOrderIfNeeded updated orderCode:`，应包含订单号与状态变更前后值
+   - 回滚预案（可执行）：
+     - 原则：以“演练前快照”为准逐单回退（避免盲目回退影响正常订单）。
+     - 回滚 SQL（模板，按快照逐单生成）：
+       - `UPDATE order_basic_info SET order_status='<before_status>', settlement_time='<before_settlement_time>', order_amount=<before_order_amount>, virtual_amount=<before_virtual_amount>, settle_amount=<before_settle_amount>, actual_received_amount=<before_actual_received_amount>, refund_amount=<before_refund_amount>, pay_status='<before_pay_status>' WHERE order_code='<order_code>';`
+
+⚠️ 风险与注意事项
+- 业务风险：将异常/待结算直接置为完成可能掩盖真实设备/交易异常；需确认是否仍需要保留异常原因字段或额外审计。
+- 技术风险：如果修正流程绕过了“解锁卡/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`
--- a/docs/plan/2026-03-21_08-48-24-ykc-midnight-offline-fix-tracker.md
+++ b/docs/plan/2026-03-21_08-48-24-ykc-midnight-offline-fix-tracker.md
@@ -0,0 +1,433 @@
+---
+mode: plan
+cwd: /Users/guoqiusi/Workspace/jsowell-charger-web
+task: 云快充1.6协议凌晨离线问题修复与协议对齐
+complexity: high
+planning_method: builtin
+created_at: 2026-03-21T08:48:24+08:00
+---
+
+# Plan: 云快充1.6凌晨离线修复跟踪
+
+## 任务概述
+
+当前项目中，云快充 1.6 协议设备在凌晨时段存在离线现象。经代码与协议文档对照，未发现明确的“凌晨主动断链”定时任务，更可能是夜间网络/SIM 抖动触发了当前偏激进的离线判定逻辑，导致短时弱网被放大为设备离线。
+
+本计划用于跟踪以下三类工作：
+
+1. 先止血：降低“短时抖动即离线”的敏感度。
+2. 再纠偏：按协议修正登录、心跳、费率、对时流程。
+3. 最后收敛：统一实现入口，减少后续维护风险。
+
+## 关键结论
+
+- 协议要求：
+  - `0x03` 心跳为 10 秒周期上送，连续 3 次未收到才视为网络异常并重新登录。
+  - `0x13` 实时监测数据周期上送，待机 5 分钟、充电 15 秒。
+  - `0x05 -> 0x06 -> 0x09 -> 0x0A` 为费率模型校验与拉取闭环。
+  - `0x56` 对时为 1 天周期发送。
+- 当前实现中的高风险点：
+  - Netty 读空闲 30 秒即触发关闭连接。
+  - 断链后立即将枪口置离线，并将充电中订单改异常。
+  - 桩状态按“任意枪口离线即整桩离线”计算。
+  - `0x05` 校验请求当前固定返回“一致”，未真正校验费率模型。
+  - 登录后主动下发 `0x58`，与协议标准流程不完全一致。
+  - 对时仅在登录后发送一次，未发现每日自动对时任务。
+  - 线上实际走老 Handler 链路，新 Strategy 链路当前不生效。
+
+## 目标与验收口径
+
+### 业务目标
+
+- 凌晨 `00:00-06:00` 时段，短时网络抖动不再导致桩状态频繁离线。
+- 单次 `30-40s` 的弱网抖动不应直接把充电中订单改为异常。
+- 桩在线状态与真实链路状态更一致，减少前端“在线/离线闪断”。
+
+### 协议目标
+
+- `0x03` 按协议节奏与容错逻辑处理。
+- `0x05/0x06/0x09/0x0A` 恢复为真实校验与请求链路。
+- `0x56/0x55` 具备每日自动对时能力和执行记录。
+
+### 验收标准
+
+- 短时网络抖动：
+  - 30-40 秒无上行数据后恢复，不直接离线。
+  - 宽限期内重连成功，不产生订单异常。
+- 长时网络中断：
+  - 超出配置阈值后，设备进入离线状态。
+  - 若有正在充电订单，按规则进入异常处理。
+- 协议链路：
+  - 桩上报旧费率模型时，平台能正确返回不一致并等待 `0x09` 请求。
+  - 每日自动对时后，可看到 `0x55` 应答记录。
+- 排障能力：
+  - 日志能够还原“最后正常通信 -> 空闲超时 -> 关闭连接 -> 是否重连成功”的完整链路。
+
+## 执行批次
+
+### 第一批：先止血
+
+- 调整 Netty 空闲断链策略。
+- 引入断链宽限期，避免瞬断即离线。
+- 补连接生命周期日志。
+- 修复 channel 映射清理。
+
+### 第二批：协议纠偏
+
+- 修复费率模型校验与拉取闭环。
+- 新增每日自动对时。
+- 将关键阈值配置化。
+
+### 第三批：实现收敛
+
+- 收敛云快充双实现，只保留一条实际生效链路。
+- 补齐专项回归验证与联调记录。
+
+## 任务清单
+
+### YKC-001
+
+- 优先级：P0
+- 状态：done
+- 目标：将云快充连接保活从“30 秒空闲直接断开”改为“允许短时抖动，按连续丢心跳或宽限期判定断链”。
+- 当前进展：
+  - 已按第一批止血方案落地为 `15s tick + 连续 3 次 READER_IDLE 才关闭`。
+  - 已补 `idleCount / lastFrameType / lastReceiveAt / lastSerialNumber / disconnectReason` 连接属性。
+- 修改文件：
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/server/yunkuaichong/NettyServerChannelInitializer.java`
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/server/yunkuaichong/NettyServerHandler.java`
+- 设计要点：
+  - `IdleStateHandler` 读空闲阈值调整为 `40-45s` 或等效容错值。
+  - `userEventTriggered` 不再第一次超时就 `close()`。
+  - 结合最近通信时间和连续空闲次数处理。
+- 验收标准：
+  - 单次 `30-40s` 无上行数据不直接断链。
+  - 凌晨弱网时连接不会频繁抖动为离线。
+- 风险：
+  - 阈值过宽会延迟真实离线发现，需要与业务确认容忍度。
+
+### YKC-002
+
+- 优先级：P0
+- 状态：done
+- 目标：增加“断链宽限期”，避免瞬断立刻将枪口置离线、订单置异常。
+- 当前进展：
+  - 已落地 `60s` 离线确认宽限期。
+  - 已引入 `pile_pending_disconnect` 和 `pile_offline_confirmed` 标记，并在恢复通信后自动清理。
+- 修改文件：
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/service/yunkuaichong/impl/YKCBusinessServiceImpl.java`
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/OrderBasicInfoServiceImpl.java`
+- 设计要点：
+  - `exit()` 中先记录“断链待确认”状态。
+  - 宽限期结束且未恢复登录时，才正式落离线和订单异常。
+  - 若宽限期内重连，取消离线确认。
+- 验收标准：
+  - 短时断链后在宽限期内重连，不产生订单异常。
+  - 真正长断链后仍能正确离线。
+- 风险：
+  - 需防止宽限期任务重复执行或状态竞争。
+
+### YKC-003
+
+- 优先级：P0
+- 状态：in_progress
+- 目标：补齐连接生命周期日志，支持“凌晨离线”专项排查。
+- 当前进展：
+  - 已补空闲告警、连续空闲关闭、异常断链、宽限恢复、正式离线确认等主链路日志。
+  - `LoginRequestHandler` / `UploadRealTimeMonitorHandler` 维度的专项日志尚未单独补齐。
+- 修改文件：
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/server/yunkuaichong/NettyServerHandler.java`
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong/HeartbeatRequestHandler.java`
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong/LoginRequestHandler.java`
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong/UploadRealTimeMonitorHandler.java`
+- 设计要点：
+  - 统一打印 `pileSn`、`channelId`、远端 IP、最后一帧类型、最后上报时间、IdleState 类型、重连耗时。
+  - 对凌晨时段日志加清晰关键词，便于筛查。
+- 验收标准：
+  - 一次离线事件能从日志完整还原链路。
+- 风险：
+  - 需控制日志量，避免高频心跳刷爆日志。
+
+### YKC-004
+
+- 优先级：P0
+- 状态：done
+- 目标：修复 channel 映射清理不完整的问题，避免旧连接残留。
+- 当前进展：
+  - 已补 `removeByPileSnAndChannelId()` 安全删除。
+  - 已补 `channelId -> pileSn` 反向映射维护，并修复删除时的脏映射残留问题。
+- 修改文件：
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/service/yunkuaichong/impl/YKCBusinessServiceImpl.java`
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-common/src/main/java/com/jsowell/common/enums/ykc/PileChannelEntity.java`
+- 设计要点：
+  - 恢复 `removeByPileSn/removeByChannelId` 的正常调用。
+  - 确保断链、异常、重连时旧 `channel` 被清理。
+- 验收标准：
+  - 同一桩重连后只保留一个有效 `channel`。
+  - 下行命令不会打到死连接。
+- 风险：
+  - 需避免误删新连接。
+
+### YKC-005
+
+- 优先级：P1
+- 状态：in_progress
+- 目标：将桩离线判定从“任意枪状态为离线即整桩离线”改为“最近通信时间 + 枪状态 + 宽限期”的综合判定。
+- 当前进展：
+  - 已完成 `checkPileOffLine()` 优先识别 `PILE_OFFLINE_CONFIRMED` 标记。
+  - 仍未重写 `getPileStatus/getPileStatusV2` 的整桩聚合规则，暂按第一批止血范围保留现状。
+- 修改文件：
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/PileConnectorInfoServiceImpl.java`
+- 设计要点：
+  - `getPileStatus/getPileStatusV2/checkPileOffLine` 使用统一判定逻辑。
+  - 将固定 3 分钟阈值改为可配置。
+- 验收标准：
+  - 前端在线状态与真实通信状态一致。
+  - 短时抖动不出现整桩离线闪断。
+- 风险：
+  - 旧缓存与新判定逻辑可能短期不一致，需要同步清理策略。
+
+### YKC-006
+
+- 优先级：P1
+- 状态：todo
+- 目标：按协议修正费率模型交互，去掉“固定返回一致”的实现。
+- 修改文件：
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong/BillingTemplateValidateRequestHandler.java`
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong/BillingTemplateRequestHandler.java`
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong/LoginRequestHandler.java`
+- 设计要点：
+  - `0x05` 真比较平台模型号与桩上报模型号。
+  - 不一致返回 `0x01`。
+  - 由桩继续发 `0x09`，平台回 `0x0A`。
+  - 登录后主动 `0x58` 改为开关控制或移除。
+- 验收标准：
+  - 费率模型链路符合协议。
+  - 跨天费率切换时行为可解释、可追踪。
+- 风险：
+  - 需确认现网桩程序是否依赖“登录后强推模板”的兼容行为。
+
+### YKC-007
+
+- 优先级：P1
+- 状态：done
+- 目标：补每日自动对时，降低跨天时钟漂移的影响。
+- 当前进展：
+  - 已新增 `jsowellTask.dailyProofreadTimeForYkcV160()`。
+  - 已补 `0x56` 下发记录和 `0x55` 应答记录。
+  - 待上线时补 Quartz 任务配置。
+- 修改文件：
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/YKCPushCommandServiceImpl.java`
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong/TimeCheckSettingResponseHandler.java`
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-quartz/src/main/java/com/jsowell/quartz/task/JsowellTask.java`
+- 设计要点：
+  - 每日定时给在线桩批量发 `0x56`。
+  - 记录 `0x55` 应答结果与桩回传时间。
+- 验收标准：
+  - 每日有自动对时执行记录。
+  - 对时失败可重试，可观测。
+- 风险：
+  - 大批量对时可能集中打到凌晨，需控制任务节奏。
+
+### YKC-008
+
+- 优先级：P1
+- 状态：todo
+- 目标：将关键超时和离线参数配置化，避免硬编码。
+- 修改文件：
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/server/yunkuaichong/NettyServerChannelInitializer.java`
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-pile/src/main/java/com/jsowell/pile/service/impl/PileConnectorInfoServiceImpl.java`
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-admin/src/main/resources/application.yml`
+- 设计要点：
+  - 至少抽出：
+    - `readerIdleSeconds`
+    - `offlineConfirmSeconds`
+    - `lastConnectionOfflineMinutes`
+    - `dailyTimeSyncCron`
+- 验收标准：
+  - 不改代码即可在环境配置中调整离线策略。
+- 风险：
+  - 需注意各环境默认值兼容。
+
+### YKC-009
+
+- 优先级：P2
+- 状态：todo
+- 目标：收敛云快充双实现，避免后续修错入口。
+- 修改文件：
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/service/yunkuaichong/impl/YKCBusinessServiceImpl.java`
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/handler/yunkuaichong`
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/strategy/ykc`
+- 设计要点：
+  - 确认唯一线上入口。
+  - 如果保留老 Handler，则冻结或移除 Strategy。
+  - 如果迁移到 Strategy，则需一次性迁完。
+- 验收标准：
+  - 线上只存在一套实际生效的云快充处理链路。
+- 风险：
+  - 涉及面较大，需单独回归。
+
+### YKC-010
+
+- 优先级：P1
+- 状态：todo
+- 目标：补专项回归验证和凌晨专项验证脚本或测试用例。
+- 修改文件：
+  - `/Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-admin/src/test/java`
+- 设计要点：
+  - 覆盖场景：
+    - `30-40s` 无心跳但恢复。
+    - 宽限期内重连。
+    - 费率模型不一致重新请求。
+    - 每日对时成功和失败。
+- 验收标准：
+  - 每个修复点至少有一条可复现、可回归的验证路径。
+- 风险：
+  - 若缺真实协议模拟器，需先补测试桩或伪报文能力。
+
+## 推荐执行顺序
+
+1. YKC-001
+2. YKC-002
+3. YKC-003
+4. YKC-004
+5. YKC-005
+6. YKC-008
+7. YKC-006
+8. YKC-007
+9. YKC-010
+10. YKC-009
+
+## 文件级改造备注
+
+### 连接与断链主链路
+
+- `NettyServerChannelInitializer`
+  - 负责 IdleState 参数配置。
+- `NettyServerHandler`
+  - 负责空闲事件、异常事件、连接关闭事件的断链控制。
+- `YKCBusinessServiceImpl`
+  - 负责断链后离线和订单状态变更逻辑。
+
+### 在线状态与业务影响主链路
+
+- `PileChannelEntity`
+  - 管理桩与 channel 的映射。
+- `PileConnectorInfoServiceImpl`
+  - 管理枪口状态、桩状态聚合与前端在线判断。
+- `OrderBasicInfoServiceImpl`
+  - 管理充电订单异常状态的最终落库。
+
+### 协议对齐主链路
+
+- `LoginRequestHandler`
+  - 登录后当前有对时和费率主动推送逻辑。
+- `HeartbeatRequestHandler`
+  - 心跳包处理与最后通信时间刷新。
+- `BillingTemplateValidateRequestHandler`
+  - 当前实现与协议偏差最大。
+- `BillingTemplateRequestHandler`
+  - 负责 `0x09 -> 0x0A`。
+- `TimeCheckSettingResponseHandler`
+  - 用于记录 `0x55` 对时应答。
+
+## 风险清单
+
+- 现网桩程序可能已适配当前“非标准但可用”的平台行为，协议纠偏前需确认兼容性。
+- 离线判定放宽后，真实离线的发现速度会变慢，需要平衡运维体验。
+- 订单异常处理若改为延迟确认，需防止漏处理真正断电或断网导致的异常订单。
+- 双实现收敛前，所有改动应明确打在老 Handler 链路上，避免误改新 Strategy 无法生效。
+
+## 当前进度快照
+
+- 更新时间：2026-03-21 11:14:17 +0800
+- `done`：
+  - `YKC-001`
+  - `YKC-002`
+  - `YKC-004`
+  - `YKC-007`
+- `in_progress`：
+  - `YKC-003`
+  - `YKC-005`
+- `todo`：
+  - `YKC-006`
+  - `YKC-008`
+  - `YKC-009`
+  - `YKC-010`
+
+## 进度记录模板
+
+```md
+### 进度记录
+
+- 任务ID: YKC-001
+- 优先级: P0
+- 状态: todo
+- 负责人:
+- 开始时间:
+- 完成时间:
+- 目标: 调整 Netty 空闲断链策略，避免 30 秒无上行直接断链
+- 修改文件:
+  - /Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/server/yunkuaichong/NettyServerChannelInitializer.java
+  - /Users/guoqiusi/Workspace/jsowell-charger-web/jsowell-netty/src/main/java/com/jsowell/netty/server/yunkuaichong/NettyServerHandler.java
+- 验收结果:
+- 备注/风险:
+```
+
+## 最终上线注意项
+
+- 本次建议作为一个整体上线，包含：
+  - 第一批凌晨离线止血。
+  - `YKC-007` 云快充 1.6 每日自动对时。
+- 当前最终基线以“离线判定正确性优先”为准，同时保留必要性能优化：
+  - 保留 `EchoServerHandler` 绑定 `businessGroup`。
+  - 保留 `PileChannelEntity` 的 `channelId -> pileSn` 反向映射。
+  - 保留 `NettyServerHandler` 的消息处理耗时监控。
+  - 不采用“心跳全异步 + 公共线程池 DiscardOldestPolicy”组合。
+- 已确认的最终收口原则：
+  - `HeartbeatRequestHandler` 中 `saveLastTimeAndCheckChannel()` 必须同步执行，保证任意上行立即刷新 `PILE_LAST_CONNECTION`，并立即清除 `PILE_PENDING_DISCONNECT / PILE_OFFLINE_CONFIRMED`。
+  - `HeartbeatRequestHandler` 中 `updateStatus()` 继续异步执行，避免数据库操作拖长心跳回包链路。
+  - `ThreadPoolConfig.threadPoolTaskExecutor` 保持 `CallerRunsPolicy`，避免关键任务被静默丢弃。
+  - `PileChannelEntity.removeByPileSnAndChannelId()` 必须同步清理反向映射，避免旧连接脏数据残留。
+
+### Quartz 配置建议
+
+- 新增每日对时任务：
+  - `invokeTarget`: `jsowellTask.dailyProofreadTimeForYkcV160()`
+- 不建议把任务压在 `00:00` 整点，建议放到低峰时段，例如 `03:15`。
+- 每日对时任务默认只扫描“当前有活连接的云快充 1.6 桩”，并按小间隔逐台发送，避免凌晨集中打满链路。
+
+### 上线后重点观察
+
+- 是否还出现“凌晨批量掉线后立刻落离线”的情况。
+- 是否能看到 `pile_pending_disconnect` 在恢复通信后于宽限期内被清除。
+- 是否出现“正式离线确认”日志明显下降。
+- 是否能看到 `0x56` 下发记录与 `0x55` 应答记录。
+- 是否持续出现 `【性能警告】` 日志堆积。
+
+### 建议回归项
+
+- 连续触发 1 次、2 次、3 次 `READER_IDLE`：
+  - 预期仅第 3 次关闭连接。
+- 第 3 次空闲关闭后 60 秒内重连：
+  - 预期不落 `OFF_NETWORK`，不改订单异常。
+- 第 3 次空闲关闭后 60 秒内未恢复：
+  - 预期才正式落离线。
+- 手工执行一次 `jsowellTask.dailyProofreadTimeForYkcV160()`：
+  - 预期仅对在线云快充 1.6 桩发对时。
+- 检查 `TimeCheckSettingResponseHandler`：
+  - 预期能记录 `0x55` 对时应答及桩端回传时间。
+
+### 编译验证记录
+
+- 已执行：
+  - `mvn -pl jsowell-quartz,jsowell-netty -am -DskipTests compile`
+  - `mvn -pl jsowell-netty,jsowell-framework,jsowell-common -am -DskipTests compile`
+- 结果：
+  - 通过。
+
+## 当前建议
+
+- 先以第一批任务为本周主线，尽快止住凌晨离线误判。
+- 第二批在止血完成后推进，避免协议纠偏与连接策略变更叠加，增加联调复杂度。
+- 第三批收敛放在前两批稳定后执行。