From 73abb71c65b17cb3d61a64283092f9d6cb9ce83f Mon Sep 17 00:00:00 2001 From: zlwu <704541015@qq.com> Date: Tue, 11 Aug 2026 10:43:52 +0800 Subject: [PATCH] docs: add OA approval task center filter design and HTML demo Document server-side filters, instant search UX, and page field matrix for pending/done/mine/cc lists. Co-authored-by: Cursor --- docs/demos/oa-approval-task-filter-demo.html | 591 ++++++++++++++++++ ...26-08-11-oa-approval-task-filter-design.md | 163 +++++ 2 files changed, 754 insertions(+) create mode 100644 docs/demos/oa-approval-task-filter-demo.html create mode 100644 docs/superpowers/specs/2026-08-11-oa-approval-task-filter-design.md diff --git a/docs/demos/oa-approval-task-filter-demo.html b/docs/demos/oa-approval-task-filter-demo.html new file mode 100644 index 00000000..dd5d0356 --- /dev/null +++ b/docs/demos/oa-approval-task-filter-demo.html @@ -0,0 +1,591 @@ + + + + + + OA 审批任务中心 · 检索区 Demo + + + + + + +
+
+ OA 审批 · 任务中心检索区 Demo + —— 样式对齐 Fresh Mint；交互为即时检索：输入/选择条件后防抖约 300ms 自动请求，无需点「搜索」。试着改下方任一条件即可看到触发提示。 +
+ +
+ + + + +
+ +
+
+

待办中心

+
+ +
+
+
+
+ + +
+ +
+ + +
+ +
+ +
+ + 至 + +
+
+ +
+ + +
+ +
+ + +
+
+ +
+
+ + +
+
+
+ +
+ 交互：条件变更 → 防抖 300ms → 自动检索（页码回第 1 页）。本页字段：流程名称· 申请人· 申请时间· 流程状态 +
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
序号流程名称申请人申请时间当前节点当前审批人流程状态阅读状态操作
1请假审批张三2026-08-10 09:20:00部门负责人李四进行中未读
2加班申请王五2026-08-09 18:05:00人事复核赵六进行中已读
3差旅报销陈七2026-08-08 11:30:00——已同意已读 + + +
+ +
+
+
+ +
+
已触发即时检索
+
防抖 300ms · 页码重置为 1
+
+ + + + diff --git a/docs/superpowers/specs/2026-08-11-oa-approval-task-filter-design.md b/docs/superpowers/specs/2026-08-11-oa-approval-task-filter-design.md new file mode 100644 index 00000000..a2898543 --- /dev/null +++ b/docs/superpowers/specs/2026-08-11-oa-approval-task-filter-design.md @@ -0,0 +1,163 @@ +# OA 审批任务中心检索区设计 + +**模块**: OA 审批 · 待办 / 已办 / 我发起的 / 抄送我的 +**日期**: 2026-08-11 +**状态**: 待审核 +**UI Demo**: `docs/demos/oa-approval-task-filter-demo.html` +**决策记录**: +- 实现方案: **方案 B**（后端扩展 `list_tasks` 查询参数 + 四页各自加 `filter-block`） +- 交互: **即时检索**（`watchDebounced` 300ms）+ 保留「搜索」「重置」 +- 暂不抽公共筛选组件（方案 C 可后续再做） + +--- + +## 1. 背景与目标 + +四页任务列表（`pending` / `done` / `mine` / `cc`）目前仅分页拉取，抄送页仅有「阅读状态」筛选。用户需要在列表上方按流程名称、申请时间、流程状态等条件检索，并在输入/选择条件后自动触发查询，无需依赖点击「搜索」才能看到结果。 + +**成功标准**: +- 四页均具备 Fresh Mint 规范的 `filter-block` 检索区 +- 条件变更防抖 300ms 后自动请求；点「搜索」立即请求；「重置」清空后请求 +- 筛选在服务端分页前生效，`total` 与列表一致 + +--- + +## 2. 范围 + +### 2.1 页面与字段 + +| 页面 | 路由视图 | 流程名称 | 申请人 | 申请时间 | 流程状态 | 阅读状态 | +|------|----------|:--------:|:------:|:--------:|:--------:|:--------:| +| 待办中心 | `views/oa-approval/pending/index.vue` | ✓ | ✓ | ✓ | ✓ | — | +| 已办中心 | `views/oa-approval/done/index.vue` | ✓ | ✓ | ✓ | ✓ | — | +| 我发起的 | `views/oa-approval/mine/index.vue` | ✓ | — | ✓ | ✓ | — | +| 抄送我的 | `views/oa-approval/cc/index.vue` | ✓ | ✓ | ✓ | ✓ | ✓（已有） | + +字段语义: +- **流程名称**: 模糊匹配应用名 `oa_app.app_name`；同时允许匹配实例标题 `oa_instance.title` +- **申请人**: 模糊匹配发起人 `sys_user.nick_name`（与 `_user_name_map` / 列表列 `initiatorUserName` 同源） +- **申请时间**: 日期区间，过滤实例 `create_time`（与列表列 `applyTime` 同源） +- **流程状态**: 精确匹配 `oa_instance.status` +- **阅读状态**: 仅抄送，沿用现有 `readStatus=unread|read|all` + +### 2.2 流程状态下拉枚举 + +与 `oa_instance.status` 注释及引擎终态标签一致（不含任务态 `approved` / `pending` 等）: + +| value | 展示文案 | +|-------|----------| +| `""` | 全部 | +| `running` | 进行中 | +| `completed` | 已完成 | +| `rejected` | 已拒绝 | +| `returned` | 已打回 | +| `cancelled` | 已撤销 | + +### 2.3 非目标 + +- 不做前端对当前页数据的假过滤 +- 本迭代不抽取跨页公共筛选组件 +- 不改变列表列、操作列、详情跳转等既有行为 +- 不改动待办数 / 抄送未读角标统计接口的过滤语义（角标仍为全量未读/待办计数） + +--- + +## 3. 交互设计 + +对齐 Fresh Mint §5 与现有列表页（单位列表、订单列表、展馆预约、抄送我的）: + +1. 结构: `panel-top` → `filter-block` →（抄送保留工具栏）→ `list-body list-wrap` → 分页 +2. 筛选区: `filter-form` + 四列 `filter-grid` + `filter-actions-row` +3. 操作按钮: **重置**（`btn-ghost` + RefreshLeft）+ **搜索**（`btn-main` + Search） +4. **即时检索**: 对 `searchForm`（及日期区间）使用 `watchDebounced(..., { debounce: 300, deep: true })`；触发时将 `page` 置为 1 再 `load` +5. **搜索按钮**: 清除等待中的防抖（若有）并立即 `load`（页码回 1） +6. **重置**: 恢复默认值（抄送 `readStatus` 默认仍为 `unread`；其余为空），页码回 1 并 `load` +7. 文本框支持 clearable；日期使用 `el-date-picker` `type="daterange"`，`value-format="YYYY-MM-DD"` + +参考 Demo: `docs/demos/oa-approval-task-filter-demo.html` + +--- + +## 4. API 设计 + +### 4.1 端点 + +继续使用: + +`GET {OA_BASE}/tasks/{kind}` + +`kind ∈ { pending, done, mine, cc }` + +### 4.2 新增 / 沿用 Query 参数 + +| 参数 | 必填 | 说明 | +|------|------|------| +| `appName` | 否 | 流程名称关键词，trim 后非空才参与 LIKE | +| `initiatorName` | 否 | 申请人姓名关键词；`mine` 可不传 | +| `applyTimeFrom` | 否 | 申请日起始日 `YYYY-MM-DD`（含当日 00:00:00） | +| `applyTimeTo` | 否 | 申请日结束日 `YYYY-MM-DD`（含当日 23:59:59） | +| `instanceStatus` | 否 | 实例状态精确匹配；不在 §2.2 枚举内的值视为未传（不加状态条件） | +| `readStatus` | 否 | 仅 `cc`，现有行为不变 | +| `page` / `pageSize` | 否 | 现有行为不变 | + +响应形状不变: `{ list, total }`。 + +### 4.3 后端实现要点（`list_tasks`） + +- **mine**: 以 `OaInstance` 为主查询；按条件 join `OaApp` / `SysUser`（发起人）过滤；`order_by create_time DESC` 后分页 +- **pending / done / cc**: 以 `OaTask` 为主查询（既有 kind 条件保留）；通过 `instance_id` join `OaInstance`，再按需 join `OaApp` / 发起人 `SysUser`；过滤后对任务分页 +- 所有业务查询继续带 `tenant_no` + `del_flag=0` +- 空字符串参数视为未传 + +--- + +## 5. 前端改动清单 + +| 文件 | 改动 | +|------|------| +| `web-admin/src/api/oaApproval.ts` | `fetchOaTasks` params 扩展上述字段并透传 | +| `web-admin/src/views/oa-approval/pending/index.vue` | 增加筛选区 + 即时检索 | +| `web-admin/src/views/oa-approval/done/index.vue` | 同上 | +| `web-admin/src/views/oa-approval/mine/index.vue` | 同上（无申请人字段） | +| `web-admin/src/views/oa-approval/cc/index.vue` | 在现有阅读状态筛选上扩展字段 + 改为即时检索 | + +建议四页共用同一套状态文案/选项常量（可在各页内联小常量或抽到 `oa-approval` 下小 util；本设计不强制新文件）。 + +--- + +## 6. 后端改动清单 + +| 文件 | 改动 | +|------|------| +| `backend/app/api/oa_approval.py` | `list_oa_tasks` 增加 Query，传入 `list_tasks` | +| `backend/app/services/oa_engine.py` | `list_tasks` 增加过滤参数并在分页前应用 | +| `backend/tests/test_oa_engine.py` 或新测文件 | 覆盖名称 / 时间 / 状态 / 抄送组合过滤 | + +无表结构变更，无需新 SQL DDL。 + +--- + +## 7. 测试计划 + +1. **后端单测**: 各 kind 在带 `appName` / `initiatorName` / 时间区间 / `instanceStatus` 时结果与 total 正确；`cc` + `readStatus` 与新条件可组合 +2. **前端手测**: 四页输入流程名即时刷新；改状态下拉即时刷新；点搜索无额外延迟感；重置恢复默认；抄送默认仍为未读；分页切换后改条件回到第 1 页 +3. **回归**: 无筛选时列表与改前一致；待办/抄送角标行为不变 + +--- + +## 8. 风险与注意点 + +- 申请人模糊检索使用 `SysUser.nick_name`（与 `_user_name_map` 一致），避免「筛得到但展示名对不上」 +- `applyTimeTo` 须包含结束日全天，避免只比较日期字符串导致漏当日下午数据 +- 即时检索会增加请求频率，300ms 防抖与现有业务页一致；连续输入以最后一次为准 +- 待办列表中实例多为 `running`，「流程状态」在待办页仍保留以支持边界数据与体验统一 + +--- + +## 9. 验收对照 + +- [ ] Demo 视觉结构在四页落地（`filter-block` / 四列栅格 / 重置+搜索） +- [ ] 条件变更 300ms 内自动出结果；搜索立即；重置清空 +- [ ] 服务端过滤 + 分页 total 正确 +- [ ] 抄送阅读状态行为不回退 +- [ ] 相关后端测试通过