141 lines
9.6 KiB
Markdown
141 lines
9.6 KiB
Markdown
# 流程管理页面 · 开发说明
|
||
|
||
> 依据《子应用流程与消息对接手册 v1.0》（2026-09-29）实现。
|
||
> 日期：2026-10-09
|
||
|
||
## 一、做了什么
|
||
|
||
在「请假设置」（路由 `/setting`，菜单 modId=170）中新增第 6 个 Tab **流程管理**，提供：
|
||
|
||
1. **流程列表** —— 实时拉取流程中心「流程编排」里已注册的流程（名称 / flowGuid / 版本 / 节点摘要）。
|
||
2. **流程绑定** —— 选中流程后绑定到本校，支持两级作用域；绑定即触发回调登记。
|
||
|
||
之所以做成设置页的 Tab 而非新路由：左侧菜单来自平台 `GetUserMod`，新增 modId 需平台侧配菜单才会出现；挂在已有的「请假设置」下可立即访问。后续若要在菜单单列，只需新增 `/flow` 路由（meta.modId 取新值）+ 平台配一条菜单，页面逻辑可直接复用。
|
||
|
||
## 二、手册要点落地对照
|
||
|
||
| 手册条款 | 实现 |
|
||
|---|---|
|
||
| §1.3 流程中心编排注册流程，记下 flowGuid；多套流程 = 多个 flowGuid | 流程列表来自 `YschFlowOpenApi.listFlows`；绑定表按 scope+scopeKey 存多条 |
|
||
| §3.2 bizType 恒等于 app_code，不可点分档 | 页面顶部明示 `bizType = leave`；发起时 `FlowApplyBody.bizType` 仍取 `LeaveFlowService.BIZ_TYPE` |
|
||
| §2.4 首次发起前完成回调登记 | `bind()` 保存绑定后立刻调用 `flowService.ensureRegistered(schId, flowGuid)` |
|
||
| §2.4 登记失败不要阻断业务 | 登记异常只 warn，绑定照常落库 |
|
||
| §6.4 别用异常过滤脏消息 | 流程中心不可达时不抛错，降级为 `centerReachable=false`，页面只展示已绑定关系 |
|
||
|
||
## 三、后端改动
|
||
|
||
### 新增文件
|
||
|
||
| 文件 | 作用 |
|
||
|---|---|
|
||
| `entity/LeaveFlowBind.java` | 流程绑定实体，表 `leave_flow_bind` |
|
||
| `repository/LeaveFlowBindRepository.java` | 按 (sch_id, bind_scope, scope_key) 查询 |
|
||
| `model/leave/FlowItemVo.java` | 流程列表项 + 绑定标记（是否默认 / 绑定到哪些类型） |
|
||
| `model/leave/FlowBindVo.java` | 已绑定关系行 |
|
||
| `model/leave/FlowManageVo.java` | 页面聚合视图（列表 + 绑定 + 请假类型 + 可达性） |
|
||
| `model/leave/LeaveTypeOptionVo.java` | 请假类型选项 |
|
||
| `model/leave/FlowBindRequest.java` | 绑定入参 |
|
||
| `service/ILeaveFlowBindService.java`<br>`service/impl/LeaveFlowBindService.java` | 列表 / 绑定 / 解绑 / 发起时解析 flowGuid |
|
||
| `controller/api/LeaveFlowController.java` | `/api/leave/flow/List`、`/Bind`、`/Unbind` |
|
||
|
||
### 修改文件
|
||
|
||
- `flow/ILeaveFlowService.java` + `flow/LeaveFlowService.java`：新增 `listFlows(schId)`，封装 `YschFlowOpenApi.listFlows(schId, FlowSummary.class)`。
|
||
- `service/impl/LeaveApplyService.java`：`startFlow()` 的 flowGuid 由「配置默认值」改为「绑定解析」：
|
||
|
||
```
|
||
单据已定(重提沿用) → 按请假类型绑定 → 学校默认绑定 → 配置 leave.flow.guid
|
||
```
|
||
|
||
- `resources/sql/workleave_schema.sql`：补充 `leave_flow_bind` 建表脚本（线上以 `ddl-auto=update` 自动建表，该脚本用于人工建库/核对）。
|
||
|
||
### 数据表
|
||
|
||
```sql
|
||
leave_flow_bind(
|
||
sch_id, bind_scope(0=全校默认 / 1=按请假类型), scope_key,
|
||
flow_guid, flow_name, flow_version, node_summary, ...
|
||
)
|
||
```
|
||
|
||
`scope=0` 时 `scope_key` 固定为 `-`。未建物理唯一索引（避免不同环境 `ddl-auto=update` 追加约束失败），唯一性由服务层 upsert 保证。
|
||
|
||
## 四、前端改动
|
||
|
||
- `types/leave.ts`：`FlowBindScope` / `FlowItemVo` / `FlowBindVo` / `LeaveTypeOptionVo` / `FlowManageVo` / `FlowBindRequest`。
|
||
- `api/module/leave.ts`：新增 `leaveFlowApi`（`List` / `Bind` / `Unbind`），导出 `leaveFlowApi`。
|
||
- `views/leave/LeaveSetting.vue`：新增「流程管理」Tab，含
|
||
- 全校默认流程卡片（流程名 / 版本 / flowGuid / 节点摘要 + 更换 / 解除）
|
||
- 流程列表表格（设为默认、按类型绑定；名称列以徽标展示绑定的请假类型名称，超过 2 个折叠为 +N、悬停看全量）
|
||
- 绑定弹窗（范围单选 + 请假类型多选下拉 + 流程下拉 + 节点摘要预览；按类型绑定时预选该流程已绑类型，提交为替换语义——未勾选的原绑定类型自动解除）
|
||
- 流程中心不可达时的告警条
|
||
- 样式沿用页面既有 CSS 变量（`--set-*`），并补了 `prefers-color-scheme: dark` 深色覆写
|
||
|
||
> 2026-10-10 调整：移除独立的「按请假类型指定」表格卡片（类型绑定统一从流程列表「按类型绑定」入口操作）；
|
||
> 绑定弹窗请假类型由单选改为多选（后端 `FlowBindRequest` 新增 `scopeKeys` 列表，一次把多个类型绑到同一流程）；
|
||
> 流程列表名称列直接展示绑定的类型名称（原先只显示「N 个类型」计数）。
|
||
>
|
||
> 2026-10-10 二次调整：列表去掉「流程标识（flowGuid）」列，绑定类型从名称列徽标拆为独立
|
||
> 「绑定的请假类型」列（超 2 个折叠 +N、悬停看全量，未绑定显示灰字）；页面不再裸露 flowGuid——
|
||
> 默认流程卡片、绑定弹窗预览、默认流程空态（回落值改为显示流程名，中心查不到才显示配置值）同步收敛，
|
||
> 顶部提示删去 flowGuid 说明语句。
|
||
|
||
## 五、验收情况
|
||
|
||
- 后端 `mvn -o compile`（JDK8）通过。
|
||
- 前端 `vue-tsc --noEmit -p tsconfig.leave.json` 通过；`vite build --mode base` 通过（154 modules transformed）。
|
||
- **未做真链路联调**：本地不出站（手册 §5.0），流程中心不可达时页面走降级分支。需在 160 环境用真实 flowGuid 验证「列表拉取 → 绑定 → 发起 → 回调」。
|
||
|
||
## 六、遗留事项
|
||
|
||
1. 本地 `yh.flow-callback.enabled=false`，回调登记会跳过并 warn——属预期，上环境后由公共配置覆盖打开。
|
||
2. 前端仓库根目录残留一个构建校验产物目录 `E:\YHXT\view\WorkLeave\dist-verify`（沙箱回收站不可用未能删除），可手动删除。
|
||
|
||
## 七、条件路由判断开放接口 `/oapi/flow/dept-judge`（2026-10-10）
|
||
|
||
流程中心 CONDITION 节点（`routerKey=work-leave.dept-judge`，路由注册表 path=`/oapi/flow/dept-judge`，
|
||
serviceKey=work-leave）激活时**同步**回调本端点，按请假时长选出口：**小于3天 / 大于等于3天**。
|
||
|
||
已发布流程 `d2237a5b…`（v4）/ `c3e9c6ee…`（v7）「请假申请（小于3天或大于等于3天）」的两条出边
|
||
name 即出口契约：`小于3天`、`大于等于3天`。
|
||
|
||
**契约**（对齐 noticeservice `OapiFlowRouteController` 参考实现，收在 `/oapi/*` 下由 AppAuthFilter
|
||
验 flow-center 签名）：
|
||
|
||
- 入参：POST JSON `{schId, instanceId, instanceVersion, bizType, bizId, nodeId, nodeName, routerKey, outlets, variables}`
|
||
- `bizId` 形态 `{leaveId}-{attempt}`，取首段定位 `leave_apply`；
|
||
- `outlets`：流程定义的出口名集合；`variables`：发起时透传的 formData（含 `totalHours`/`days`）。
|
||
- 出参：`{"outlet": "小于3天" | "大于等于3天"}`。
|
||
- 时长口径：**3天 = 24小时**（一天按作息 8 小时折算，同 `LeaveFlowService#buildFormData` 的
|
||
`days=totalHours/8`）；恰好 24h 归「大于等于3天」。
|
||
- 免查库：`variables.totalHours` 存在则直接用（与发起口径同源），缺失回落按 bizId 查表。
|
||
- 契约纪律：计算出的 outlet 不在 `outlets` 集合内 → 抛业务错让 flow-center 挂起，**绝不默认放行**；
|
||
单据不存在 / 无时长同样挂起。
|
||
|
||
**鉴权**：`yh.app-auth.server.enforce-patterns: [/oapi/*]`（本次新增，对齐 noticeservice 生产姿势）——
|
||
`/oapi/**` 无签名一律 401，有签名走中央密钥链校验；`application-local.yml` 已用永不匹配 pattern
|
||
`[/__local_no_match__]` 关闭（不能直接置空：base 的 `enforce-patterns[0]` 索引键仍会使条件命中，
|
||
而空 pattern 列表会让 FilterRegistration 启动报错），本地无签名联调不受影响。
|
||
|
||
**代码**：`controller/oapi/FlowJudgeController.java`（端点）+ `FlowJudgeControllerTest`（9 项单测：
|
||
出口两分支 / 恰好3天边界 / variables 免查库与回落查表 / bizId 带重提后缀解析 / 出口不命中与缺时长挂起）。
|
||
|
||
**响应包装**：端点裸返回 `{"outlet":...}`，由 yh-api-std `ApiResponseAdvice` 统一包成
|
||
`{code:0, msg, data:{outlet}}` —— notice 参考实现（生产在用）同受此包装，flow-center 读 `data.outlet`，行为一致。
|
||
|
||
**病假绑定与真链路测试（2026-10-10）**：
|
||
|
||
- 病假 = LT002（全局字典，schId=0），已在「流程管理」把 LT001/LT002/LT003/LT004/LT005 五类绑到
|
||
c3e9c6ee（请假申请(小于3天或大于等于3天) v7，启用中）。v7 结构：CONDITION →「小于3天」审批人
|
||
10007 /「大于等于3天」审批人 10008（lijing），两分支汇合后抄送 10008 → END。
|
||
- 本地直连契约测试（模拟 flow-center 请求体）全过：16h→`小于3天`；24h 整→`大于等于3天`；
|
||
variables 缺 totalHours→回落查表；出口不命中→业务错挂起（`code=2` + 明确 message）。
|
||
- ⚠️ **平台侧前置缺口：流程中心的判断调用走开放网关 `{gateway}{basePath}{path}`
|
||
（=`open.yunhaixingtong.com/work-leave/oapi/flow/dept-judge`），网关当前无 `/work-leave` 路由
|
||
（404；对照 `/notice` 路由存在、401=已到达 notice 服务）⇒ 网关出不了 160，调用永远到不了本机，
|
||
CONDITION 实例按设计**挂起在 u1c**。需平台部署 work-leave / 注册网关路由后真链路才能闭环。
|
||
- 挂起实例可正常**撤回**（flow.withdrawn 正常回调，单据回已撤回）——是卡单的恢复路径。
|
||
- 遗留：病假测试单 id=18（10-19 一天）在绑定生效前提交，走了兜底流程 d2237a5b 并卡在 u1c，
|
||
可在「我的请假」撤回后重提（重提将按绑定走 c3e9c6ee）。
|
||
|