From 9cdd984bcdbd19b1b32be64759f324d6a5eb3f6c Mon Sep 17 00:00:00 2001
From: jsowell <123@jsowell.com>
Date: Thu, 16 Jul 2026 15:48:42 +0800
Subject: [PATCH] =?UTF-8?q?=E6=8F=90=E4=BA=A4PRD=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/PRD-待办事项功能.md | 364 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 364 insertions(+)
 create mode 100644 docs/PRD-待办事项功能.md

diff --git a/docs/PRD-待办事项功能.md b/docs/PRD-待办事项功能.md
new file mode 100644
index 000000000..768d42a6f
--- /dev/null
+++ b/docs/PRD-待办事项功能.md
@@ -0,0 +1,364 @@
+# 待办事项中心 PRD
+
+## 1. 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 产品名称 | 运营商工作台待办事项中心 |
+| 文档类型 | 产品需求文档（PRD） |
+| 版本 | V1.0 |
+| 状态 | 待评审 |
+| 适用端 | RuoYi-Vue 管理后台、运营商工作台 |
+
+## 2. 背景与目标
+
+当前项目已有 RuoYi 的通知公告功能，支持管理员维护全平台公告，但不支持按用户生成业务任务、展示未处理数量和跳转处理业务。
+
+截图中的“待办事项”属于业务任务中心：任务面向具体用户，用户需要进入业务页面完成处理，处理后任务应自动完成或由用户确认完成。
+
+本需求目标：
+
+1. 在运营商工作台首页增加待办事项卡片。
+2. 展示当前登录用户未处理的待办数量。
+3. 支持点击待办跳转到对应业务详情或处理页面。
+4. 支持待办状态、优先级、已读状态和完成状态管理。
+5. 建立统一待办能力，后续可接入开票、提现、汇付开户、清分异常等业务。
+
+## 3. 产品定位
+
+待办事项与通知公告、站内信的关系如下：
+
+```text
+消息中心
+├── 待办事项：需要用户处理的业务任务
+├── 业务通知：业务结果或状态变化提醒
+├── 系统公告：面向全体用户的运营公告
+└── 系统消息：登录、安全、权限等系统提醒
+```
+
+本期只建设“待办事项”，不替换现有 `sys_notice` 通知公告模块。
+
+## 4. 用户与权限
+
+### 4.1 用户角色
+
+| 用户 | 权限 |
+| --- | --- |
+| 运营商负责人 | 查看和处理本人或本运营商范围内的待办 |
+| 运营商财务人员 | 查看和处理财务类待办 |
+| 平台运营人员 | 创建、分配、转派和关闭待办，可查看全量待办 |
+| 系统管理员 | 管理待办类型、权限和异常任务 |
+
+### 4.2 数据权限
+
+默认只返回当前登录用户的待办。平台管理员是否可以查看全量待办，由现有 RuoYi 权限和数据权限控制，不允许通过修改请求参数绕过接收人过滤。
+
+## 5. 首期业务范围
+
+### 5.1 开票待办
+
+首期优先实现截图中的开票场景：
+
+| 待办类型 | 触发条件 | 处理页面 | 完成条件 |
+| --- | --- | --- | --- |
+| 平台采购开票 | 平台审核拒绝或要求补充材料 | 发票详情/开票申请页 | 用户重新提交或平台关闭任务 |
+| 司机开票申请 | 收到司机开票申请 | 发票申请处理页 | 审核通过、驳回或关闭 |
+
+### 5.2 预留业务类型
+
+| 待办类型 | 触发条件 |
+| --- | --- |
+| 汇付企业开户审核 | 企业开户失败或需要补充资料 |
+| 结算账户异常 | 结算账户创建失败、删除失败或状态不一致 |
+| 提现处理 | 提现失败、人工审核或补充资料 |
+| 清分异常 | 清分失败、分账配置错误或账单待处理 |
+| 订单异常 | 订单退款、结算或支付异常需要人工介入 |
+
+首期只实现开票待办，其他类型只完成通用模型和扩展接口，不要求全部接入。
+
+## 6. 业务流程
+
+### 6.1 创建流程
+
+```text
+业务事件发生
+    ↓
+判断是否需要人工处理
+    ↓
+确定接收人和业务权限
+    ↓
+按幂等键创建待办
+    ↓
+首页待办数量增加
+    ↓
+用户点击待办
+    ↓
+进入业务处理页面并标记已读
+    ↓
+业务处理成功后自动完成待办
+```
+
+### 6.2 状态定义
+
+待办状态和阅读状态分开保存：
+
+| 字段 | 值 | 含义 |
+| --- | --- | --- |
+| `task_status` | `PENDING` | 待处理 |
+| `task_status` | `PROCESSING` | 处理中 |
+| `task_status` | `COMPLETED` | 已完成 |
+| `task_status` | `CANCELLED` | 已取消 |
+| `task_status` | `EXPIRED` | 已过期 |
+| `read_status` | `0` | 未读 |
+| `read_status` | `1` | 已读 |
+
+已读只表示用户看过，不能代表业务已经处理完成。只有业务动作完成、平台关闭或管理员取消时，待办才进入完成或取消状态。
+
+### 6.3 幂等规则
+
+同一业务任务不能重复生成待办。建议使用以下幂等键：
+
+```text
+task_type + business_type + business_id + assignee_user_id
+```
+
+例如同一个发票申请给同一个用户只能有一条有效待办。任务完成或取消后，允许业务重新产生新的任务，但必须保留历史记录。
+
+## 7. 首页交互设计
+
+### 7.1 待办卡片
+
+位置：运营商工作台首页右侧，与截图中的“待办事项”位置一致。
+
+展示规则：
+
+- 标题：`待办事项`。
+- 标题右侧显示未完成数量，最多显示 `99+`。
+- 默认展示最近 3 条未完成待办。
+- 按优先级倒序、创建时间倒序排列。
+- 每条显示：类型、标题、简要内容、时间和箭头。
+- 无待办时显示“暂无待办事项”。
+- 点击“查看全部”进入待办中心。
+- 点击单条任务进入业务处理页面。
+
+### 7.2 待办中心
+
+页面建议：`src/views/system/todo/index.vue`。
+
+功能：
+
+- 全部、待处理、已完成、已取消筛选。
+- 全部、未读筛选。
+- 按待办类型筛选。
+- 关键字搜索标题和业务单号。
+- 分页查询。
+- 点击进入业务详情。
+- 支持批量标记已读。
+- 支持隐藏已完成待办，不直接物理删除历史任务。
+
+### 7.3 详情处理
+
+待办本身不重复实现业务处理表单。点击待办后跳转已有业务页面，并携带：
+
+```text
+businessType
+businessId
+todoId
+```
+
+业务页面处理成功后调用待办完成接口，或由后端业务事务自动完成待办。
+
+## 8. 数据库设计
+
+建议新增主表 `sys_todo_task`：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `todo_id` | bigint | 主键 |
+| `task_type` | varchar(64) | 待办类型编码 |
+| `title` | varchar(200) | 待办标题 |
+| `summary` | varchar(500) | 摘要 |
+| `content` | text | 详细内容 |
+| `business_type` | varchar(64) | 业务类型 |
+| `business_id` | varchar(64) | 业务主键或单号 |
+| `route_name` | varchar(100) | 前端路由名称 |
+| `route_params` | varchar(1000) | 路由参数 JSON |
+| `assignee_user_id` | bigint | 接收用户 ID |
+| `assignee_merchant_id` | varchar(64) | 运营商 ID，可为空 |
+| `priority` | tinyint | 优先级：1普通、2重要、3紧急 |
+| `task_status` | varchar(20) | 任务状态 |
+| `read_status` | char(1) | 0未读、1已读 |
+| `read_time` | datetime | 阅读时间 |
+| `due_time` | datetime | 截止时间，可为空 |
+| `completed_time` | datetime | 完成时间 |
+| `completed_by` | bigint | 完成人 |
+| `cancel_reason` | varchar(500) | 取消原因 |
+| `idempotent_key` | varchar(200) | 幂等键 |
+| `create_time` | datetime | 创建时间 |
+| `update_time` | datetime | 更新时间 |
+| `del_flag` | char(1) | 逻辑删除 |
+
+建议索引：
+
+```sql
+unique key uk_todo_idempotent (idempotent_key)
+key idx_todo_user_status (assignee_user_id, task_status, read_status, create_time)
+key idx_todo_merchant_status (assignee_merchant_id, task_status, create_time)
+key idx_todo_business (business_type, business_id)
+```
+
+如果后续需要同一任务分配给多个用户，建议拆分为：
+
+- `sys_todo_task`：任务主体。
+- `sys_todo_recipient`：接收人和每个接收人的阅读状态、处理状态。
+
+V1 只有单接收人时可以先使用单表，避免过早复杂化；但字段和 Service 设计应预留多接收人扩展。
+
+## 9. 后端接口设计
+
+### 9.1 用户端接口
+
+```text
+GET  /system/todo/unreadCount
+GET  /system/todo/homeList?limit=3
+GET  /system/todo/list
+GET  /system/todo/{todoId}
+PUT  /system/todo/{todoId}/read
+PUT  /system/todo/readAll
+PUT  /system/todo/{todoId}/complete
+PUT  /system/todo/{todoId}/cancel
+```
+
+接口规则：
+
+- 所有查询自动使用当前登录用户 ID，不接收任意 `userId` 作为唯一权限依据。
+- `read` 只能修改当前用户的阅读状态。
+- `complete` 必须校验当前用户有对应业务处理权限。
+- `complete` 和具体业务更新建议放在同一事务中，避免业务完成但待办仍为待处理。
+- 已完成任务默认仍可查询，但不计入未读数量和首页待办数量。
+
+### 9.2 管理端接口
+
+```text
+GET    /system/todo/admin/list
+POST   /system/todo/admin/create
+PUT    /system/todo/admin/{todoId}/assign
+PUT    /system/todo/admin/{todoId}/cancel
+DELETE /system/todo/admin/{todoId}
+```
+
+管理端用于异常任务处理和人工补发，普通业务待办优先由业务事件自动生成。
+
+## 10. 待办服务设计
+
+新增统一服务接口：
+
+```java
+TodoTaskService.createTask(TodoTaskCreateCommand command);
+TodoTaskService.markRead(Long todoId, Long userId);
+TodoTaskService.complete(Long todoId, Long userId);
+TodoTaskService.cancel(Long todoId, Long operatorId, String reason);
+TodoTaskService.countUnread(Long userId);
+```
+
+业务模块只依赖 `TodoTaskService`，不直接操作待办表。
+
+例如开票业务：
+
+```java
+todoTaskService.createTask(TodoTaskCreateCommand.builder()
+    .taskType("INVOICE_REVIEW")
+    .title("司机开票申请")
+    .summary("有新的开票申请需要处理")
+    .businessType("INVOICE_APPLY")
+    .businessId(invoiceId.toString())
+    .assigneeUserId(operatorUserId)
+    .routeName("InvoiceApplyDetail")
+    .idempotentKey("INVOICE_REVIEW:" + invoiceId + ":" + operatorUserId)
+    .build());
+```
+
+## 11. 通知刷新策略
+
+### V1 推荐：轮询
+
+- 登录后加载未读数量。
+- 首页每 30～60 秒刷新一次数量和最近待办。
+- 打开待办中心时立即刷新。
+- 处理完成后主动刷新当前列表和数量。
+
+轮询实现简单，不需要改造现有 Netty、RabbitMQ 或新增 WebSocket 基础设施，适合本项目首期落地。
+
+### V2 可选：实时推送
+
+当待办实时性要求提高时，再增加 WebSocket 或 SSE。实时推送只负责通知前端刷新，不直接承载任务数据；前端收到事件后仍通过接口重新查询。
+
+## 12. 非功能要求
+
+- 接口必须使用当前登录用户做数据权限过滤。
+- 内容字段需要进行 XSS 处理，详情页禁止直接渲染未经处理的 HTML。
+- 所有状态变更记录操作人、操作时间和操作原因。
+- 待办创建必须幂等，避免重复点击或重复回调产生重复任务。
+- 首页查询应使用索引，目标响应时间不超过 500ms。
+- 默认保留已完成任务至少 180 天，定时任务归档或清理历史数据。
+- 待办跳转路由必须使用服务端生成或白名单校验，禁止直接执行前端传入的任意路由。
+
+## 13. 验收标准
+
+### 首页
+
+- 用户登录后可以看到待办事项卡片。
+- 未完成数量准确，数量为 0 时不显示红色数字或显示 0。
+- 默认最多展示 3 条待办。
+- 点击“查看全部”可以进入待办中心。
+- 点击单条待办可以跳转对应业务页面。
+
+### 状态
+
+- 首次进入列表时未读待办显示未读样式。
+- 点击待办后变为已读，但仍保持待处理状态。
+- 业务处理成功后变为已完成，不再计入首页数量。
+- 取消或过期任务不再计入待办数量。
+- 重复触发同一业务事件不会产生重复有效待办。
+
+### 权限
+
+- 用户无法查询其他用户的待办。
+- 无业务处理权限的用户不能完成待办。
+- 管理员可以按权限查看和关闭异常待办。
+
+### 首期业务
+
+- 平台采购开票待办可以正常生成、展示、跳转和完成。
+- 司机开票申请待办可以正常生成、展示、跳转和完成。
+- 原有 `sys_notice` 公告功能不受影响。
+
+## 14. 实施拆分
+
+### 第一期：基础能力
+
+- 建表和索引。
+- 实体、Mapper、Service、Controller。
+- 未读数、首页列表、分页列表、已读和完成接口。
+- 首页待办卡片和待办中心页面。
+
+### 第二期：开票接入
+
+- 接入平台采购开票事件。
+- 接入司机开票申请事件。
+- 配置业务路由和完成条件。
+- 增加接口和页面联调测试。
+
+### 第三期：平台业务扩展
+
+- 接入汇付开户、结算账户和提现异常。
+- 接入清分异常和订单异常。
+- 评估 WebSocket/SSE 实时推送。
+
+## 15. 与现有 RuoYi 模块的关系
+
+- `sys_notice` 继续作为全平台通知公告管理。
+- 新增 `sys_todo_task` 作为用户待办任务管理。
+- 沿用 RuoYi 的 `SysUser`、权限注解、数据权限和分页组件。
+- 沿用现有 `BaseController`、`AjaxResult`、`TableDataInfo` 和前端 `request` 封装。
+- 不建议把待办字段直接塞入 `sys_notice`，避免公告和业务任务互相污染。