jsowell-charger-web/docs/plan/2026-07-16-todo-center-task-tracker.md

# 待办事项中心开发任务跟踪

## 任务概述

- 需求来源：`docs/PRD-待办事项功能.md`
- 开发目标：先交付面向当前登录用户的通用待办闭环，再接入首期开票业务，最后补充管理和扩展能力。
- 后端仓库：当前根仓库，分支 `feature-待办中心`
- 前端仓库：`jsowell-charge-ui/` 独立 Git 仓库，当前分支 `dev`
- 状态定义：`todo` 未开始、`in_progress` 进行中、`blocked` 阻塞、`done` 已完成

## 优先级说明

- P0：首期上线必需，缺失时无法形成可用闭环。
- P1：首期开票业务落地和运营管理必需，可在通用能力稳定后接入。
- P2：安全、运维和体验增强，不阻塞首期核心流程。
- P3：后续业务扩展和实时化能力。

## 关键设计决策

### 幂等键生命周期

PRD 同时要求“幂等键唯一”和“任务完成后允许同一业务重新产生任务”。MySQL 普通唯一索引无法同时满足这两个要求，因此采用双字段方案：

- `idempotent_key`：保存业务方传入的原始幂等键，历史记录不修改。
- `active_idempotent_key`：仅非终态任务保存原始幂等键，并建立唯一索引。
- 任务进入 `COMPLETED`、`CANCELLED` 或 `EXPIRED` 后，将 `active_idempotent_key` 置空。

该方案利用 MySQL 唯一索引允许多个 `NULL` 的特性，保证并发创建时只有一条有效待办，同时允许终态后再次创建。

### 数据权限边界

- 用户端接口不接收接收人 ID，统一从当前登录态获取用户 ID。
- 用户端详情、已读、完成和取消更新均在 SQL 条件中携带 `assignee_user_id`，避免先查后改产生越权窗口。
- 管理端能力使用独立路径和权限标识，不复用用户端接口绕过接收人过滤。

### 首期两个开票场景

- 充电订单开票：沿用 `order_invoice_record` 创建事件，接收人收敛为对应运营商管理员；通过 `todo.operator-admin-role-id` 配置管理员角色 ID，默认沿用现有运营商创建流程的 `role_id = 3`。
- 提现向平台开票：监听 `clearing_withdraw_info.withdraw_status` 从处理中变为已提现（`1`）的成功事件；每笔成功提现创建一条 `MERCHANT_WITHDRAW_INVOICE` 待办。
- 提现开票完成不能只依赖手工点完成，新增开票信息记录，保存发票状态、发票号码、凭证地址、提交人和提交时间，提交成功后与待办在同一事务内完成。

### 前后端仓库边界

`jsowell-charge-ui/` 是独立 Git 仓库。后端和前端分别提交中文 commit，不将前端目录作为未跟踪目录加入后端仓库。

## 执行批次

| 批次 | 范围 | 优先级 | 状态 | 验收结果 | Commit |
| --- | --- | --- | --- | --- | --- |
| B01 | 任务拆分、数据表和索引 | P0 | done | SQL 结构和索引评审通过 | `e65017ab2` |
| B02 | 实体、命令模型、枚举、Mapper、Service | P0 | done | 模块编译和 Mapper XML 校验通过 | `181d4a5b4` |
| B03 | 当前用户查询、已读、完成、取消接口及测试 | P0 | done | 全量依赖编译、9 个专项测试通过 | `f84ec43ce` |
| B04 | 前端 API、待办中心页面和路由跳转 | P0 | done | ESLint 和生产构建通过 | 前端 `ff6b890` |
| B05 | 首页待办卡片、数量展示和轮询刷新 | P0 | done | ESLint 和生产构建通过 | 前端 `0627061` |
| B05-F1 | 待办中心页面上下间距优化 | P0 | done | ESLint 和生产构建通过 | 前端 `380e2dc` |
| B06 | 菜单权限 SQL、联调和首期回归 | P0 | done | 菜单 SQL、构建和专项回归通过；待测试库执行 SQL | `974e68cf5` |
| B07 | 提现成功后向平台开票待办 | P1 | done | 提现回调、开票记录、待办、提交/关闭接口和财务页闭环完成；待测试库执行建表 SQL | 后端 `3e299f40f`；前端 `b16865a` |
| B08 | 充电订单开票申请待办接入 | P1 | done | 已接入业务事件并收敛为运营商管理员接收 | `cbc2e3c72`、`5c7f4dcce` |
| B08-F1 | 充电订单开票接收人和文案收敛 | P1 | done | 后端编译和 14 个专项测试通过；前端 ESLint、生产构建通过 | 后端 `5c7f4dcce`；前端 `967a9bf` |
| B09 | 管理端创建、分配、取消和隐藏能力 | P1 | done | 全量查询、人工创建、重新分配、取消和终态隐藏接口完成；独立权限默认授予系统管理员 | `558949f4e` |
| B10 | 归档清理、过期任务和操作审计增强 | P2 | done | 到期流转、至少 180 天终态归档和每日维护任务完成；待测试库配置 Quartz | `b6b052b9d` |
| B11 | 路由白名单、性能压测和安全专项验证 | P2 | done | 路由及参数白名单、首页排序索引和验证清单完成；待测试库执行真实数据基准 | `1bffb95b1` |
| B12 | 汇付、清分、订单异常和实时推送扩展 | P3 | todo | - | - |

## 任务清单

### TODO-001 建表和索引

- 优先级：P0
- 批次：B01
- 状态：done
- 目标：创建 `sys_todo_task` 表，覆盖任务状态、阅读状态、业务路由、接收人、幂等和审计字段。
- 验收标准：
  - 有效任务幂等键具备数据库唯一约束。
  - 当前用户首页和列表查询具备组合索引。
  - 业务单据、运营商范围和历史清理具备查询索引。
  - SQL 可重复交付，不包含真实环境配置或数据。

### TODO-002 通用领域模型和服务

- 优先级：P0
- 批次：B02
- 状态：done
- 目标：新增实体、创建命令、状态常量、Mapper 和统一 `TodoTaskService`。
- 验收标准：
  - 创建接口校验必要字段并设置默认状态、优先级和阅读状态。
  - 并发重复创建返回已有有效任务，不产生重复记录。
  - 完成、取消和过期操作释放有效幂等键并记录操作信息。
  - 业务模块仅依赖 Service，不直接依赖 Mapper。

### TODO-003 当前用户后端接口

- 优先级：P0
- 批次：B03
- 状态：done
- 目标：实现未完成数量、首页列表、分页列表、详情、已读、全部已读、完成和取消接口。
- 验收标准：
  - 所有用户端查询和更新强制使用当前登录用户 ID。
  - 首页最多返回 10 条，默认 3 条，按优先级和创建时间倒序。
  - 已完成、已取消和已过期任务不计入首页数量。
  - 状态流转非法时返回明确业务错误。
  - 核心 Service 和 Controller 权限边界有自动化测试。

### TODO-004 待办中心前端页面

- 优先级：P0
- 批次：B04
- 状态：done
- 目标：增加 API 封装、待办中心列表、筛选、分页、批量已读和安全跳转。
- 验收标准：
  - 支持任务状态、阅读状态、任务类型和关键字筛选。
  - 未读任务有清晰样式，点击后标记已读。
  - 跳转只使用后端返回的已配置路由名称，并附带 `businessType`、`businessId`、`todoId`。
  - 已完成记录默认保留展示，不执行物理删除。

### TODO-005 首页待办卡片

- 优先级：P0
- 批次：B05
- 状态：done
- 目标：在运营商工作台首页展示未完成数量和最近 3 条任务。
- 验收标准：
  - 数量超过 99 显示 `99+`。
  - 无任务时显示空状态。
  - 页面打开立即加载，并按 60 秒轮询刷新。
  - 完成任务或返回首页后主动刷新。

### TODO-006 菜单权限和联调

- 优先级：P0
- 批次：B06
- 状态：done
- 当前进展：
  - 菜单、查询、已读、完成和取消权限 SQL 已完成。
  - 列表、查询和已读权限默认授予正常角色；完成和取消权限保留为按业务角色授权。
  - 后端 9 个专项测试、前端专项 ESLint 和生产构建已通过。
  - 待在测试库执行 `docs/sql/sys_todo_menu.sql` 后进行登录态 HTTP 联调。
- 目标：补充菜单与权限 SQL，完成前后端构建和核心流程联调。
- 验收标准：
  - 普通用户只看到本人待办。
  - 无权限用户不能访问管理接口或完成无权业务。
  - 原 `sys_notice` 功能和菜单不受影响。
  - 后端编译、相关测试、前端 lint/build 通过或记录环境阻塞原因。

### TODO-007 提现成功后向平台开票接入

- 优先级：P1
- 批次：B07
- 状态：done
- 现有入口：`AdapayService.drawCash()` 创建提现记录，提现成功回调 `cashSucceeded()` 将状态更新为 `1`。
- 目标：提现成功后为对应运营商管理员创建“向平台开票”待办，并提供提交发票信息后自动完成的闭环。
- 任务拆分：
  - 新增提现开票信息表及唯一提现单号约束。
  - 在提现成功状态更新事务中创建待办，使用 `MERCHANT_WITHDRAW_INVOICE` 类型。
  - 新增查询提现开票详情、提交发票信息、平台关闭任务接口。
  - 财务详情页增加待办处理入口，跳转携带 `merchantId`、`withdrawCode`、`todoId`。
- 完成情况：
  - 新增 `clearing_withdraw_invoice` 表脚本，以提现编号唯一约束保证一笔提现只有一条开票记录。
  - 提现成功回调在同一事务中更新提现和清分账单状态、创建开票记录，并为运营商管理员幂等创建待办。
  - 当前待办接收人可查询并提交发票号码及凭证；提交后同一提现的全部待办自动完成。
  - 平台关闭接口复用 `system:todo:cancel` 权限，关闭开票记录并取消关联待办。
  - 财务详情页从待办跳转后自动打开开票弹窗，支持上传 PDF 或图片凭证。
  - 待在测试库执行 `docs/sql/clearing_withdraw_invoice.sql`，并使用真实提现成功回调完成登录态联调。
- 验收标准：同一提现成功事件对同一管理员只产生一条有效待办；提交发票号码和凭证后待办自动完成；提现失败不创建该待办。

### TODO-008 充电订单开票申请接入

- 优先级：P1
- 批次：B08
- 状态：done
- 目标：收到用户充电订单开票申请时创建待办，运营商完成开票、驳回或关闭时完成。
- 当前实现：已接入 `order_invoice_record` 创建、完成和关闭事件，并与业务事务绑定。
- 当前实现：接收人仅解析运营商部门树下拥有配置角色的正常管理员；默认管理员角色 ID 为 `3`，可通过 `todo.operator-admin-role-id` 覆盖。
- 验收标准：创建和完成与开票业务事务一致，异常回滚时不产生脏任务状态。

### TODO-008-F1 充电订单开票接收人和文案收敛

- 优先级：P1
- 批次：B08-F1
- 状态：done
- 目标：将现有 `INVOICE_REVIEW` 待办的标题、类型文案从“司机开票申请”统一为“充电订单开票申请”，接收人限制为运营商管理员。
- 完成情况：后端创建待办时只查询配置的运营商管理员角色；前端移除不存在的“平台采购开票”筛选和类型文案，统一显示“充电订单开票申请”。
- 验收标准：运营商普通财务或普通操作员不会收到该待办；管理员收到的待办可正常跳转、完成和关闭。

### TODO-009 管理端异常任务处理

- 优先级：P1
- 批次：B09
- 状态：done
- 目标：实现管理员列表、人工创建、分配、取消和逻辑隐藏。
- 完成情况：
  - 新增 `/system/todo/admin` 管理接口，覆盖全量分页查询、人工创建、重新分配、管理员取消和终态逻辑隐藏。
  - 人工创建和重新分配均校验目标用户为正常用户，并按业务与接收人重建有效幂等键。
  - 待处理任务必须先取消才能隐藏，避免隐藏有效任务后幂等键长期占用。
  - 新增五项 `system:todo:admin:*` 独立权限，菜单 SQL 默认只授予 `role_key = 'admin'` 的系统管理员。
  - 待在测试库重新执行 `docs/sql/sys_todo_menu.sql`，完成管理接口登录态验证。
- 验收标准：接口具备独立权限标识和操作日志，普通用户不能访问。

### TODO-010 运维与安全增强

- 优先级：P2
- 批次：B10-B11
- 状态：done
- 目标：补充过期、180 天归档清理、操作审计、路由白名单和性能验证。
- 当前进展：
  - B10 已完成：到期待办批量转为 `EXPIRED`，同步记录终态时间并释放有效幂等键。
  - B10 已完成：终态任务按 `todo.retention-days` 逻辑归档，配置小于 180 天时强制按 180 天保留。
  - B10 已完成：新增 `todoTaskMaintenanceTask.maintain()` 每日维护任务和幂等 Quartz 配置脚本。
  - 待在测试库执行 `docs/sql/sys_todo_maintenance_job.sql` 并观察首轮任务日志。
  - B11 已完成：待办创建仅允许 `todo.route-whitelist` 中的路由，路由参数限制为安全标量 JSON。
  - B11 已完成：新增首页待办排序索引迁移脚本和安全/性能验证清单。
  - 待按 `docs/plan/2026-07-17-todo-center-security-performance-checklist.md` 在测试库执行真实数据量 EXPLAIN、P95 和越权验证。
- 验收标准：首页查询目标响应时间小于 500ms，路由不能被请求参数任意覆盖，历史任务按策略保留。

### TODO-011 后续业务扩展

- 优先级：P3
- 批次：B12
- 状态：todo
- 目标：接入汇付开户、结算账户、清分和订单异常，并评估 WebSocket/SSE。
- 验收标准：新增业务只通过统一待办 Service 接入，不修改通用数据权限和状态模型。

## 提交记录

每完成一个批次，在此追加：完成时间、验证命令、结果和 commit hash。

- 2026-07-16，B01：完成优先级拆分、任务跟踪文档和 `sys_todo_task` 建表脚本；通过 SQL 人工结构评审与 `git diff --check`；commit `e65017ab2`。
- 2026-07-16，B01 环境进展：用户已在测试数据库创建 `sys_todo_task` 表，可供后续接口联调。
- 2026-07-16，B02：完成领域模型、创建/查询 DTO、状态常量、Mapper 和统一 Service；`mvn -pl jsowell-system -am -DskipTests compile` 与 Mapper XML 语法校验通过；commit `181d4a5b4`。
- 2026-07-16，B03：完成当前用户数量、首页列表、分页列表、详情、已读、全部已读、完成和取消接口；`mvn -pl jsowell-admin -am -DskipTests compile` 通过，9 个 Service/Controller 专项测试通过；commit `f84ec43ce`。
- 2026-07-16，B04：完成前端 API、待办中心筛选分页、批量已读和安全路由跳转；新增文件专项 ESLint 通过，`NODE_OPTIONS=--openssl-legacy-provider npm run build:prd` 构建通过；前端 commit `ff6b890`。
- 2026-07-16，B05：完成首页右侧待办卡片、`99+` 数量、最近 3 条、空状态、错误重试和 60 秒轮询；专项 ESLint 与生产构建通过；前端 commit `0627061`。
- 2026-07-16，B06：完成幂等菜单/权限 SQL；列表、查询和已读权限默认授予正常角色，完成和取消权限需按业务角色显式授权；后端 9 个专项测试再次通过，前端构建沿用 B05 验证结果；commit `974e68cf5`。
- 2026-07-16，B08：司机开票记录创建后，按运营商部门树为正常后台用户幂等创建待办；开票状态更新为已开票时自动完成，删除/关闭记录时自动取消；业务与待办状态处于同一事务；全依赖编译和 12 个专项测试通过；commit `cbc2e3c72`。
- 2026-07-17，B05-F1：局部覆盖全局卡片纵向内边距，并补充待办页面顶部和底部留白；专项 ESLint 与生产构建通过；前端 commit `380e2dc`。
- 2026-07-17，需求调整：移除不存在的平台采购开票场景，新增“提现成功后运营商向平台开票”场景，并将充电订单开票接收人明确为运营商管理员。
- 2026-07-17，B08-F1：充电订单开票待办仅分配给配置的运营商管理员角色，统一前后端文案并移除不存在的平台采购开票选项；后端全依赖编译和 14 个专项测试通过，前端专项 ESLint 与生产构建通过；后端 commit `5c7f4dcce`，前端 commit `967a9bf`。
- 2026-07-17，B07：新增提现开票信息表脚本、提现成功事务闭环、运营商管理员待办、发票详情/提交/关闭接口及财务详情页处理弹窗；后端 20 个相关测试通过，前端新增 API 和待办页面专项 ESLint、生产构建通过；后端 commit `3e299f40f`，前端 commit `b16865a`。
- 2026-07-17，B09：新增管理端全量查询、人工创建、重新分配、管理员取消和终态逻辑隐藏接口，补充独立权限和系统管理员默认授权；全依赖编译、6 个专项测试通过；commit `558949f4e`。
- 2026-07-17，B10：新增到期待办自动过期、终态任务至少保留 180 天后逻辑归档、每日 Quartz 维护任务及配置 SQL；全依赖编译、8 个相关测试通过；commit `b6b052b9d`。
- 2026-07-17，B11：新增可配置路由白名单和安全路由参数校验，补充首页排序索引迁移脚本及测试库安全/性能验证清单；全依赖编译、24 个相关测试通过，应用 YAML 解析通过；commit `1bffb95b1`。