diff --git a/docs/plan/2026-07-16-todo-center-task-tracker.md b/docs/plan/2026-07-16-todo-center-task-tracker.md new file mode 100644 index 000000000..e83935fa0 --- /dev/null +++ b/docs/plan/2026-07-16-todo-center-task-tracker.md @@ -0,0 +1,176 @@ +# 待办事项中心开发任务跟踪 + +## 任务概述 + +- 需求来源:`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 在下一批记录中回填。 diff --git a/docs/sql/sys_todo_task.sql b/docs/sql/sys_todo_task.sql new file mode 100644 index 000000000..0222fe7af --- /dev/null +++ b/docs/sql/sys_todo_task.sql @@ -0,0 +1,39 @@ +-- 待办事项中心任务表 +-- 说明:active_idempotent_key 仅在非终态任务中保留,终态时置空, +-- 用于同时满足“有效任务唯一”和“终态后允许重新创建”的要求。 + +CREATE TABLE `sys_todo_task` ( + `todo_id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '待办任务主键', + `task_type` varchar(64) NOT NULL COMMENT '待办类型编码', + `title` varchar(200) NOT NULL COMMENT '待办标题', + `summary` varchar(500) DEFAULT NULL COMMENT '待办摘要', + `content` text COMMENT '待办详细内容(纯文本)', + `business_type` varchar(64) NOT NULL COMMENT '业务类型编码', + `business_id` varchar(64) NOT NULL COMMENT '业务主键或单号', + `route_name` varchar(100) NOT NULL COMMENT '前端白名单路由名称', + `route_params` varchar(1000) DEFAULT NULL COMMENT '前端路由参数 JSON', + `assignee_user_id` bigint(20) NOT NULL COMMENT '接收用户 ID', + `assignee_merchant_id` varchar(64) DEFAULT NULL COMMENT '接收运营商 ID', + `priority` tinyint(3) NOT NULL DEFAULT '1' COMMENT '优先级(1普通 2重要 3紧急)', + `task_status` varchar(20) NOT NULL DEFAULT 'PENDING' COMMENT '任务状态(PENDING PROCESSING COMPLETED CANCELLED EXPIRED)', + `read_status` char(1) NOT NULL DEFAULT '0' COMMENT '阅读状态(0未读 1已读)', + `read_time` datetime DEFAULT NULL COMMENT '阅读时间', + `due_time` datetime DEFAULT NULL COMMENT '截止时间', + `completed_time` datetime DEFAULT NULL COMMENT '完成时间', + `completed_by` bigint(20) DEFAULT NULL COMMENT '完成人用户 ID', + `cancel_reason` varchar(500) DEFAULT NULL COMMENT '取消原因', + `idempotent_key` varchar(200) NOT NULL COMMENT '业务原始幂等键', + `active_idempotent_key` varchar(200) DEFAULT NULL COMMENT '有效任务幂等键,终态置空', + `create_by` varchar(64) DEFAULT NULL COMMENT '创建者', + `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + `update_by` varchar(64) DEFAULT NULL COMMENT '更新者', + `update_time` datetime DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + `remark` varchar(500) DEFAULT NULL COMMENT '备注', + `del_flag` char(1) NOT NULL DEFAULT '0' COMMENT '逻辑删除(0正常 2删除)', + PRIMARY KEY (`todo_id`) USING BTREE, + UNIQUE KEY `uk_todo_active_idempotent` (`active_idempotent_key`) USING BTREE, + KEY `idx_todo_user_status` (`assignee_user_id`, `task_status`, `read_status`, `priority`, `create_time`) USING BTREE, + KEY `idx_todo_merchant_status` (`assignee_merchant_id`, `task_status`, `create_time`) USING BTREE, + KEY `idx_todo_business` (`business_type`, `business_id`) USING BTREE, + KEY `idx_todo_history_cleanup` (`del_flag`, `task_status`, `completed_time`) USING BTREE +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 ROW_FORMAT=DYNAMIC COMMENT='用户待办任务表';