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 结构和索引评审通过	本批提交
B02	实体、命令模型、枚举、Mapper、Service	P0	todo	-	-
B03	当前用户查询、已读、完成、取消接口及测试	P0	todo	-	-
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
• 状态：todo
• 目标：新增实体、创建命令、状态常量、Mapper 和统一 TodoTaskService。
• 验收标准：
  • 创建接口校验必要字段并设置默认状态、优先级和阅读状态。
  • 并发重复创建返回已有有效任务，不产生重复记录。
  • 完成、取消和过期操作释放有效幂等键并记录操作信息。
  • 业务模块仅依赖 Service，不直接依赖 Mapper。

TODO-003 当前用户后端接口

• 优先级：P0
• 批次：B03
• 状态：todo
• 目标：实现未完成数量、首页列表、分页列表、详情、已读、全部已读、完成和取消接口。
• 验收标准：
  • 所有用户端查询和更新强制使用当前登录用户 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 hash 在下一批记录中回填。