提交

2026-08-28 17:38:37 +08:00
1 parent 3d98104455
commit 0d52442902
@@ -0,0 +1,170 @@
+# OA 小程序端 · 发起表单「历史记录」设计
+
+**模块**: OA 审批 · mobile-oa-h5 / mobile-h5  
+**日期**: 2026-08-28  
+**状态**: 已实现（mobile-oa-h5）  
+**关联**: web 端历史记录已落地（WorkTab + `GET /instances/history`）  
+**决策记录**:
+- 打开方式: **方案 A** — 同 webview 内 H5 路由跳转，返回后继续填表
+- 权限: 与 web 一致 — `oa:start:history:all` 全员；无权限仅本人
+- 列表样式: 对齐小程序「我发起的」卡片模式（`mobile-h5/pages/oa/mine/index.vue`）
+- 不做: 导出、打印、状态/时间等其它筛选；检索暂时仅「申请人」（且仅全员权限时显示）
+
+---
+
+## 1. 背景与目标
+
+web-admin「发起审批」已支持按流程查看历史记录。用户希望在微信小程序工作台（`mobile-h5`）发起流程时，在表单填写页（`mobile-oa-h5` 的 `/oa-start`，经 `pages/oa/start/webview` 加载）底栏「取消」右侧增加「历史记录」，进入该流程的历史列表，并可查看详情。
+
+**成功标准**:
+- 表单底栏常显「历史记录」文字按钮（取消右侧）
+- 点击进入历史列表；卡片样式对齐「我发起的」
+- 有全员权限可看本租户该流程全部，并显示申请人检索；无权限仅本人、不显示申请人检索
+- 点击卡片进入只读详情；无打印、无导出
+- 从历史返回表单页时，可继续填写（同 webview 栈内返回）
+
+---
+
+## 2. 范围
+
+### 2.1 在范围内
+
+| 项 | 说明 |
+|----|------|
+| 入口按钮 | `mobile-oa-h5/src/views/OaStart.vue` 底栏 |
+| 历史列表页 | 新建 `OaHistory.vue` + 路由 `/oa-history` |
+| API 封装 | `mobile-oa-h5/src/api/oa.js` 增加 `fetchOaInstanceHistory` |
+| 详情 | 复用已有 `/oa-detail?instanceId=`（只读） |
+| 权限 | 后端已有；前端用响应 `canViewAll` 控制申请人检索显隐 |
+
+### 2.2 非目标
+
+- 导出 Excel
+- 打印
+- 审批状态 / 发起时间 / 完成时间等筛选（后续可加）
+- 改后端 history API 契约（复用现有即可）
+- 在「发起审批」流程宫格列表上增加历史入口（本期仅表单页）
+
+---
+
+## 3. 交互与信息架构
+
+```
+发起审批宫格 → webview 加载 /oa-start?appId=…
+                    │
+                    ├─ 取消 → closeToHost
+                    ├─ 历史记录 → /oa-history?appId=…  （同 H5 路由）
+                    │                 │
+                    │                 ├─ 上拉分页 / 申请人检索（可选）
+                    │                 └─ 点卡片 → /oa-detail?instanceId=…
+                    │                                   └─ 返回 → 历史列表
+                    ├─ 暂存草稿
+                    └─ 提交审批
+```
+
+- 历史列表页顶部可展示流程名称（来自模板详情或 query）
+- 浏览器/小程序 webview 内使用 Vue Router `push` / `back`，**不** `closeToHost` 离开宿主
+
+---
+
+## 4. UI 规范
+
+### 4.1 底栏按钮
+
+顺序：`取消` | `历史记录` | `暂存草稿` | `提交审批`
+
+- 「历史记录」为次要文字按钮，视觉权重对齐「取消」（非主色实心）
+- Token：三墙绿（`#0a9f6d` 系），**禁止** web-admin `#10b981`
+
+### 4.2 历史列表（对齐「我发起的」）
+
+参考：`mobile-h5/pages/oa/mine/index.vue` 的 `dd-card` 结构：
+
+| 区域 | 内容 |
+|------|------|
+| 角标 | 序号 |
+| 标题行 | 审批标题 / 流程名；右侧相对或绝对发起时间 |
+| 元信息 | 可选：申请人（全员时更有用）、当前节点、业务预览字段 1～2 行 |
+| 底栏 | 状态文案 + 语义色 Tag（进行中 / 已完成 / 已拒绝等） |
+
+检索区（仅 `canViewAll`）：
+
+- 单行「申请人」输入 + 确认搜索（样式可对齐 mine 顶栏 search-box，placeholder 改为「搜索申请人」）
+- 无权限：不渲染检索区
+
+空态 / 加载 / 加载更多：对齐 mine（VanEmpty 或等价、pulse、已经到底了）
+
+### 4.3 详情
+
+- `router.push({ path: '/oa-detail', query: { instanceId } })`
+- 不暴露打印入口（若详情页已有打印，历史入口进入时可通过 query 如 `from=history` 隐藏；若实现成本高且详情页本无打印，则无需改）
+
+---
+
+## 5. API
+
+复用：
+
+```
+GET /web/admin/oa-approval/instances/history
+  appId* | initiatorName? | page | pageSize
+```
+
+- 后端已按 JWT + `oa:start:history:all` 收窄范围
+- 响应含 `list`、`total`、`canViewAll`
+- 列表项已有：`id`、`appName`、`initiatorUserName`、`applyTime`、`finishTime`、`instanceStatus`、`currentNodeName`、`previewFields` 等
+
+`mobile-oa-h5/src/api/oa.js` 新增：
+
+```js
+export function fetchOaInstanceHistory(params) {
+  return get('/web/admin/oa-approval/instances/history', params)
+}
+```
+
+`mobile-h5` 侧本期可不封装（列表跑在 oa-h5 内）。
+
+---
+
+## 6. 路由
+
+`mobile-oa-h5/src/router.js` 增加：
+
+```js
+{ path: '/oa-history', component: OaHistory }
+```
+
+Query：`appId`（必填）；可选 `appName` 用于标题，避免再请求。
+
+---
+
+## 7. 实现要点
+
+1. **OaStart 底栏**：增加「历史记录」按钮；`onHistory` 取当前 `appId` / 流程名后 `router.push`
+2. **OaHistory.vue**：首屏拉 history；`canViewAll` 控制检索；分页 `page` 递增；卡片字段映射对齐 mine 的 `cardTitle` / `statusText` / `statusTone`
+3. **KeepAlive（可选）**：若返回表单丢数据，可为 `/oa-start` 加 keep-alive；优先验证默认行为，按需再加
+4. **权限文案**：无数据时区分「暂无历史记录」与「未找到相关记录」（有检索词时）
+
+---
+
+## 8. 测试要点
+
+- 无全员权限：仅本人数据；无申请人检索框
+- 有全员权限：可见他人；申请人检索生效
+- 从历史进详情再返回，仍在历史列表；再返回表单可继续编辑
+- 无 appId 时友好提示，不白屏
+- 视觉：底栏四钮不换行挤压；卡片风格与「我发起的」一致
+
+---
+
+## 9. 文件清单（预期）
+
+| 文件 | 变更 |
+|------|------|
+| `mobile-oa-h5/src/views/OaStart.vue` | 底栏按钮 + 跳转 |
+| `mobile-oa-h5/src/views/OaHistory.vue` | 新建列表页 |
+| `mobile-oa-h5/src/router.js` | 注册 `/oa-history` |
+| `mobile-oa-h5/src/api/oa.js` | `fetchOaInstanceHistory` |
+| （可选）`OaDetail.vue` | 隐藏打印若存在且需按来源隐藏 |
+
+后端 / 菜单 SQL：**无需**为本期新增。