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，避免先查后改产生越权窗口。
• 管理端能力使用独立路径和权限标识，不复用用户端接口绕过接收人过滤。

前后端仓库边界

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

执行批次

批次	范围	优先级	状态	验收结果	Commit
B01	任务拆分、数据表和索引	P0	done	SQL 结构和索引评审通过	e65017ab2
B02	实体、命令模型、枚举、Mapper、Service	P0	done	模块编译和 Mapper XML 校验通过	181d4a5b4
B03	当前用户查询、已读、完成、取消接口及测试	P0	done	全量依赖编译、9 个专项测试通过	本批提交
B04	前端 API、待办中心页面和路由跳转	P0	todo	-	-
B05	首页待办卡片、数量展示和轮询刷新	P0	todo	-	-
B06	菜单权限 SQL、联调和首期回归	P0	todo	-	-
B07	平台采购开票待办接入	P1	todo	-	-
B08	司机开票申请待办接入	P1	todo	-	-
B09	管理端创建、分配、取消和隐藏能力	P1	todo	-	-
B10	归档清理、过期任务和操作审计增强	P2	todo	-	-
B11	路由白名单、性能压测和安全专项验证	P2	todo	-	-
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
• 状态：todo
• 目标：增加 API 封装、待办中心列表、筛选、分页、批量已读和安全跳转。
• 验收标准：
  • 支持任务状态、阅读状态、任务类型和关键字筛选。
  • 未读任务有清晰样式，点击后标记已读。
  • 跳转只使用后端返回的已配置路由名称，并附带 businessType、businessId、todoId。
  • 已完成记录默认保留展示，不执行物理删除。

TODO-005 首页待办卡片

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

TODO-006 菜单权限和联调

• 优先级：P0
• 批次：B06
• 状态：todo
• 目标：补充菜单与权限 SQL，完成前后端构建和核心流程联调。
• 验收标准：
  • 普通用户只看到本人待办。
  • 无权限用户不能访问管理接口或完成无权业务。
  • 原 sys_notice 功能和菜单不受影响。
  • 后端编译、相关测试、前端 lint/build 通过或记录环境阻塞原因。

TODO-007 平台采购开票接入

• 优先级：P1
• 批次：B07
• 状态：todo
• 目标：在平台采购开票审核拒绝或要求补充材料时创建待办，重新提交或平台关闭时完成。
• 验收标准：同一开票事件对同一接收人只产生一条有效待办，跳转参数和完成条件正确。

TODO-008 司机开票申请接入

• 优先级：P1
• 批次：B08
• 状态：todo
• 目标：收到司机开票申请时创建待办，审核通过、驳回或关闭时完成。
• 验收标准：创建和完成与开票业务事务一致，异常回滚时不产生脏任务状态。

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

• 优先级：P1
• 批次：B09
• 状态：todo
• 目标：实现管理员列表、人工创建、分配、取消和逻辑隐藏。
• 验收标准：接口具备独立权限标识和操作日志，普通用户不能访问。

TODO-010 运维与安全增强

• 优先级：P2
• 批次：B10-B11
• 状态：todo
• 目标：补充过期、180 天归档清理、操作审计、路由白名单和性能验证。
• 验收标准：首页查询目标响应时间小于 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 hash 在下一批记录中回填。