# 流程管理页面 · 开发说明

> 依据《子应用流程与消息对接手册 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）。