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	-	-

首期交付结论

• P0、P1、P2 开发批次已完成；B12 属于 PRD 明确预留、首期不要求接入的后续业务扩展。
• 后端最终专项回归共 30 个测试通过；前端专项 ESLint 和生产构建通过。
• 测试环境部署时按顺序执行或复核：
  1. docs/sql/sys_todo_menu.sql
  2. docs/sql/clearing_withdraw_invoice.sql
  3. docs/sql/sys_todo_performance_index.sql
  4. docs/sql/sys_todo_maintenance_job.sql
• 登录态、真实提现回调和性能基准按 docs/plan/2026-07-17-todo-center-security-performance-checklist.md 执行并记录结果。

任务清单

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。
• 2026-07-17，首期最终回归：待办通用服务、两个开票业务、管理端、维护任务和路由安全共 30 个专项测试通过；前端沿用 B07 的专项 ESLint 与生产构建结果；P3 预留业务保留在后续迭代。