update

AGENTS.md

@@ -0,0 +1,48 @@
+# Repository Guidelines
+
+This repository contains a Java 8, multi-module Spring Boot backend plus a separate Vue 2 (Vue CLI) admin UI.
+
+## Project Structure & Module Organization
+
+- Backend parent: `pom.xml` (aggregates the Maven modules).
+- Backend modules live under `jsowell-*/`.
+  - Entry point/service: `jsowell-admin/` (Spring Boot app).
+  - Shared/core: `jsowell-common/`, `jsowell-framework/`, `jsowell-system/`.
+  - Business/integrations: `jsowell-pile/`, `jsowell-netty/`, `jsowell-thirdparty/`, plus schedulers/generator/settlement modules.
+- UI: `jsowell-ui/` (not part of the Maven build). Code is in `jsowell-ui/src/`, static assets in `jsowell-ui/public/`.
+- Reference material: `doc/`, `docs/`; database scripts: `sql/`; helper batch scripts: `bin/`.
+
+## Build, Test, and Development Commands
+
+Backend (from repo root):
+- `mvn clean compile`: compile all modules.
+- `mvn clean package -DskipTests` (or `bin\\package.bat`): build artifacts.
+- `mvn test` (or `mvn -pl jsowell-admin test`): run backend tests.
+- `mvn -pl jsowell-admin spring-boot:run -Dspring-boot.run.profiles=dev`: run the API locally.
+
+UI (from `jsowell-ui/`):
+- `npm run dev`: start dev server (uses `jsowell-ui/.env.*` modes).
+- `npm run build:prd`: production build.
+- `npm run lint`: ESLint on `src/`.
+
+## Coding Style & Naming Conventions
+
+- Java: follow existing conventions (4 spaces; `PascalCase` types; `camelCase` methods; `UPPER_SNAKE_CASE` constants). Keep changes scoped to one module when possible.
+- UI: follow `jsowell-ui/.editorconfig` + `jsowell-ui/.eslintrc.js` (2 spaces, single quotes, no semicolons). Run `npm run lint` before PRs.
+
+## Testing Guidelines
+
+- Backend tests are primarily in `jsowell-admin/src/test/java` and use Spring Boot + JUnit.
+- Prefer `*Test.java` naming and avoid tests that depend on external services unless clearly marked/configured.
+
+## Commit & Pull Request Guidelines
+
+- Commit subjects commonly use short prefixes: `add ...`, `update ...`, `bugfix ...`. Keep them under ~72 chars; add module context when helpful (example: `jsowell-ui: update login flow`).
+- PRs should target `dev` unless agreed otherwise, include a clear description, and link the relevant issue/ticket.
+- Include screenshots for UI changes and migration notes for DB/API changes (`sql/`, request/response examples).
+
+## Security & Configuration Notes
+
+- Environment config lives in `jsowell-admin/src/main/resources/application-*.yml` and `jsowell-ui/.env.*`.
+- Do not commit real secrets/keys; use placeholders and local overrides.
+- See `CLAUDE.md` for deeper architecture and operational notes.

issues/2026-01-23_17-04-15-whitelist-order-status-complete.csv

@@ -0,0 +1,7 @@
+"id","priority","phase","area","title","description","acceptance_criteria","test_mcp","review_initial_requirements","review_regression_requirements","dev_state","review_initial_state","review_regression_state","git_state","owner","refs","notes"
+"WLOS-010","P0","1","backend","澄清白名单修正规则与验收口径","明确白名单支付订单的判定字段与状态修正边界，形成可实现/可测试的规则清单。","明确并在PR/变更说明中写清：1) 白名单判定字段（order_basic_info.pay_mode 是否足够，是否需校验 order_pay_record.pay_mode）；2) 仅当 payMode=3 且订单状态为 ABNORMAL(4) 或 STAY_SETTLEMENT(2) 才允许修正；3) 修正为 ORDER_COMPLETE(6) 时需要同步的字段列表（settlement_time/金额字段/pay_status 等）与缺失数据的默认策略。","AUTOSERVER","Review过程中持续检查：规则是否与枚举一致；字段同步是否会影响分账/退款/通知/解锁等后续链路；是否需要审计/日志记录原状态。","完成后复核：规则与验收口径在代码/测试/接口行为三者一致；对非白名单/非目标状态无副作用。","未开始","未开始","未开始","未提交","","plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:16; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:17; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:18; jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderPayModeEnum.java:11; jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderStatusEnum.java:12; jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderStatusEnum.java:14",""
+"WLOS-020","P0","2","backend","定位异常/待结算状态写入点并梳理影响面","确认订单进入 ABNORMAL/待结算/完成 的关键写入路径，决定修正应放在写入点还是补偿点，并列出受影响链路。","输出可审计的影响面清单（写在PR描述或变更说明中）：至少包含白名单批量入口、订单标记异常位置、结算后落库完成位置；明确最终选择的修正插入点（例如统一补偿方法 + 入口调用）。","AUTOSERVER","检查是否存在并发/重复调用场景；是否有事务边界；是否会触发远程停机/拉取交易记录等外部依赖；异常原因字段/审计日志是否保留。","回归时覆盖：修正路径不会破坏正常结算完成流程；不会将真实异常订单误判为完成。","未开始","未开始","未开始","未提交","","plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:20; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:22; jsowell-admin/src/main/java/com/jsowell/service/TempService.java:1504; jsowell-admin/src/main/java/com/jsowell/api/uniapp/customer/TempController.java:1043; jsowell-admin/src/main/java/com/jsowell/service/OrderService.java:528; jsowell-pile/src/main/java/com/jsowell/pile/service/programlogic/AbstractProgramLogic.java:247",""
+"WLOS-030","P0","3","backend","设计并落地统一的白名单订单完成补偿方法","在订单领域服务中新增可复用且幂等的补偿方法，专门用于白名单订单从异常/待结算修正为完成，并补齐必要字段。","新增补偿方法（如 completeWhitelistOrderIfNeeded(orderCode) 或等价实现）：1) 判定 payMode=3 且状态在 {ABNORMAL, STAY_SETTLEMENT}；2) 幂等（重复调用不产生额外副作用）；3) 更新为 ORDER_COMPLETE 并处理 settlement_time（为空则置当前时间）及约定的金额/状态字段默认值；4) 记录可追溯日志（至少包含订单号、原状态、新状态）。","AUTOSERVER","检查金额字段默认策略是否会影响对账；时间字段是否符合既有语义；方法是否避免不必要的外部调用（如远程停机/拉交易）。","回归验证：在真实/模拟数据上重复调用、并发调用无异常；下游依赖（通知/解锁/MQ/分账退款）要么保持一致，要么明确不触发并有说明。","进行中","进行中","未开始","未提交","","plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:27; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:30; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:54; jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderStatusEnum.java:14; jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderPayModeEnum.java:11","picked_reason:unblocks core capability for WLOS-040/WLOS-050"
+"WLOS-040","P0","4","backend","改造白名单结算入口以支持异常/待结算并复用补偿逻辑","调整 TempService.whiteListSettlement 及对应接口，使其支持 ABNORMAL/待结算两种状态并调用统一补偿方法，避免硬编码与不必要外部依赖。","1) TempService.whiteListSettlement 支持状态=ABNORMAL 或 STAY_SETTLEMENT；2) payMode 判断改为使用 OrderPayModeEnum.PAYMENT_OF_WHITELIST.getValue()；3) 默认走统一补偿方法完成状态修正；4) 若保留 manualSettlementOrder 调用，需明确触发条件与降级策略（避免依赖外部设备/交易服务导致批量失败）。","AUTOSERVER","Review时重点：权限/入参校验是否合理；批量处理时的错误隔离与日志；是否需要对调用方预期做兼容（原先只允许异常）。","回归时验证：接口对非白名单/非目标状态不改动；批量输入中单个失败不影响其他（如有此需求则实现并说明）。","未开始","未开始","未开始","未提交","","plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:35; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:39; jsowell-admin/src/main/java/com/jsowell/service/TempService.java:1504; jsowell-admin/src/main/java/com/jsowell/api/uniapp/customer/TempController.java:1043; jsowell-admin/src/main/java/com/jsowell/service/OrderService.java:749; jsowell-common/src/main/java/com/jsowell/common/enums/ykc/OrderPayModeEnum.java:11",""
+"WLOS-050","P0","5","backend","补齐白名单状态修正的单测/集成测试与回归场景","为白名单订单状态修正逻辑新增测试用例，确保异常/待结算均可修正且非白名单不会被误改。","新增/更新测试并通过：1) 白名单+异常(4) -> 完成(6)；2) 白名单+待结算(2) -> 完成(6)；3) 非白名单订单不变；4) 关键字段（如 settlement_time）按约定填充；执行 `mvn -pl jsowell-admin test` 通过。","AUTOSERVER","Review时关注：测试数据构造是否贴近真实（金额/时间/状态）；是否覆盖幂等与边界输入（空字段、重复调用）。","完成后回归：全量后端测试通过；若有接口层变化，补充接口测试或Mock验证。","未开始","未开始","未开始","未提交","","plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:41; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:46; jsowell-admin/src/main/java/com/jsowell/service/TempService.java:1504",""
+"WLOS-060","P0","6","backend","测试环境演练与上线前数据校验/回滚预案","在测试环境按订单号列表演练修正接口，校验DB字段变化，并准备可执行的回滚/审计方案。","1) 在测试环境对选定订单号列表调用 /whiteListSettlement（或等价入口）成功；2) DB 校验：order_basic_info.order_status=6 且 settlement_time/金额字段符合约定；3) 形成可执行回滚步骤（SQL/脚本/手工流程）并记录在PR描述或运维文档中；4) 日志中可追溯到修正前后状态。","AUTOE2E","Review过程中确认：是否需要灰度/限流；批量处理失败的可观测性（日志/告警）；是否保留原状态用于追溯。","上线前回归：随机抽样多笔订单复测；验证不会导致下游不一致（通知/解锁/MQ/分账退款）或已明确不会触发并可接受。","未开始","未开始","未开始","未提交","","plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:48; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:50; plan/2026-01-23_16-45-56-whitelist-order-status-complete.md:52; jsowell-admin/src/main/java/com/jsowell/api/uniapp/customer/TempController.java:1043",""

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

@@ -0,0 +1,63 @@
+---
+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`