# 流程模块架构审计报告

> 审计范围：`org.jeecg` 下 4 个流程模块（xispeak / xispeakfb / inspectimprove / inspectcloseout）
> 共 18 个 Java 文件，含 4 个 Config、4 个 Flow、10 个 Listener

## 一、模块概览

| 模块 | 文件数 | Flow 行数 | 业务完整度 | DI 健康度 |
|------|--------|-----------|-----------|-----------|
| xispeak | 9 (1C+1F+7L) | 432 | 完整 | 4/7 正常，3/7 有问题 |
| xispeakfb | 3 (1C+1F+1L) | 322 | 完整 | 正常 |
| inspectimprove | 3 (1C+1F+1L) | 164 | TODO 未完成 | 正常 |
| inspectcloseout | 3 (1C+1F+1L) | 132 | TODO 未完成 | 正常 |

---

## 二、P0 致命问题

### 2.1 `StringUtil` 拼写错误 — 编译/运行时报错

**文件** `AfterSDWApproveHqListener.java` 第 50 行：

```java
if(org.apache.commons.lang.StringUtil.isEmpty(url)) {
```

Apache Commons Lang 中不存在 `StringUtil` 类，应为 `StringUtils`。

**影响**：该行不会通过编译；如果通过（如 IDE 自动导入），运行时会抛出 `NoClassDefFoundError`。

### 2.2 链式调用直接 NPE（3 处）

**`XiSpeakFlow.java`：**

1. **行 166**：`xiSpeakConfig.getXiSpeak().getNeedSdwApproveCode()` — `getXiSpeak()` 可能返回 null（yml 缺失此段落时 Spring Boot 不会注入默认值，导致属性为 null）
2. **行 172**：`xiSpeakConfig.getXiSpeak().getFeedbackRightNowCode()` — 同上
3. **行 178**：`xiSpeakConfig.getXiSpeak().getSdwLeaderListKey()` — 同上

同类方法 `getBgDeptLdUserIdList()` 行 37-41 做了守卫判断，但上述 3 处遗漏。

**`XiSpeakFlow.java` 行 310：**

```java
public int getImplDeptIsEnd(DelegateExecution execution) {
    return getDeptApproveDetail(execution).getIsEnd();
}
```

`getDeptApproveDetail()` 可能返回 null（当 businessKey 为空、deptVar 为 null、entity 不存在时），直接调 `.getIsEnd()` 必抛 NPE。

### 2.3 `InspectImproveFlow` / `InspectCloseoutFlow` 所有公开方法配置 NPE

```java
public List<String> getMeasureResLeaderList(Object jsonData) {
    InspectImproveConfig.InspectImproveProperties props = inspectImproveConfig.getInspectImprove();
    return getListFromData(jsonData, props.getMeasureResLeaderKey(), "...");
}
```

`getInspectImprove()` 无 null 守卫。如果 yml 中 `inspect-improve` 或 `inspect-closeout` 配置节缺失，所有公开方法调用时接连抛出 NPE。

---

## 三、P1 高危问题

### 3.1 JSON 解析方法大面织重复（~180 行）

同一个 "JSONObject / JSONString / POJO 三种类型兼容解析" 逻辑在以下 7 个方法中独立实现：

| 类 | 方法 | 返回类型 |
|----|------|----------|
| `XiSpeakFlow` | `getCodeValueFromData` | `Integer` |
| `XiSpeakFlow` | `getListCodeValueFromData` | `List<String>` |
| `XiSpeakFlow` | `getImplDeptNums` | `Integer` (变体) |
| `InspectImproveFlow` | `getStringFromData` | `String` |
| `InspectImproveFlow` | `getListFromData` | `List<String>` |
| `InspectCloseoutFlow` | `getStringFromData` | `String` |
| `InspectCloseoutFlow` | `getListFromData` | `List<String>` |

**建议**：抽取为 `FlowJsonParser` 工具类，提供 `getString(jsonData, key)` / `getInteger(jsonData, key, default)` / `getStringList(jsonData, key)` 三个通用方法。

### 3.2 2 级父 Execution 攀爬逻辑三重复制（~135 行）

三个 Listener 中有逐行相同的 45 行核心逻辑，仅变量名不同：

| Listener | 存储变量名 |
|----------|-----------|
| `AfterImplDeptLeaderApproveListener` | 硬编码 `"tem_impl_leader"` |
| `AfterImplWorkerTemStoreListener` | 硬编码 `"tem_impl_worker"` |
| `AfterBgLeaderApproveListener` | 配置 `props.getTemBgLeaderKey()` |

**建议**：提取抽象模板方法，参数化变量名和日志前缀。

### 3.3 `getListSize()` 重复定义（3 处）

`XiSpeakFlow` 行 340、`InspectImproveFlow` 行 155、`InspectCloseoutFlow` 行 123 都有语义完全相同的实现。

**建议**：移入共用工具类。

### 3.4 依赖注入混乱（3 个 Listener）

| Listener | 注入方式 | 问题 |
|----------|---------|------|
| `AfterSDWApproveHqListener` | `@RequiredArgsConstructor`(2 final) **+** `@Autowired` 字段注入 `RuntimeService` | 混合注入，风格撕裂 |
| `AfterImplDeptLeaderApproveListener` | `@RequiredArgsConstructor` 零 final + `static { SpringContextUtils.getBean(...) }` | 注解虚设，static 块获取 Bean 有容器未就绪风险 |
| `AfterImplWorkerTemStoreListener` | 同上 | 同上 |

**建议**：统一为 `@RequiredArgsConstructor(onConstructor_ = @Autowired)` + private final 字段。

### 3.5 事务注解缺失

`AfterBgWorkerFinalApproveListener` 执行 `bgXiSpeakService.updateById(entity)` 却**没有** `@Transactional`。

虽然 MyBatis-Plus 的 `updateById` 自身在一条 SQL 中完成，但如果后续有人在此方法中增加第二个 DB 操作，不会感知到缺少事务边界。

### 3.6 悲观锁 vs 无锁策略不一致

| Listener | 读方法 | 锁 |
|----------|--------|----|
| `AfterImplWorkerApproveListener` | `getByIdForUpdate` | 悲观锁 (SELECT FOR UPDATE) |
| `AfterImplDeptLeaderStoreJsonListener` | `getById` | 无锁 |
| xispeakfb `AfterImplDeptLeaderApproveListener` | `getById` | 无锁 |

多实例并行会签场景下，无锁的 `getById` →修改→ `updateById` 存在**丢失更新**风险。

---

## 四、P2 中危问题

### 4.1 `parseDeptId` 两个版本功能不对等

- **xispeak 版** (`AfterImplDeptLeaderStoreJsonListener` 行 115-137)：处理 null / Collection / 普通字符串 / `[1001,1002]` 数组字符串
- **xispeakfb 版** (`AfterImplDeptLeaderApproveListener` 行 115-123)：仅处理 Collection / 普通字符串，缺失数组字符串兼容

如果 xispeakfb 流程中传入 `[deptA, deptB]` 格式的变量值（这在 xispeak 流程中很常见），解析结果会包含方括号导致后续匹配失败。

### 4.2 流程变量 fallback 模式重复（4 处）

同一 "先 `getVariableLocal` 再 `getVariable`" 的 4 行模式出现在 4 个不同位置，无统一封装。

### 4.3 `AfterSDWApproveHqListener` 日志硬编码字段名

行 80 的日志 `"解析 JSON 字段 pending_depts_id 失败"` 硬编码了特定字段名，与运行时通过 `props.getImplDeptKey()` 读取的实际字段名可能不一致，降低排查效率。

### 4.4 StringUtils 库引用混乱

| 类 | 使用的 StringUtils |
|----|--------------------|
| `XiSpeakFlow` | `org.apache.shiro.util.StringUtils`、`org.apache.commons.lang.StringUtils`、`org.apache.commons.lang3.StringUtils` — 三个库混用 |
| `XiSpeakFeedbackFlow` | `org.apache.commons.lang3.StringUtils` 统一 |
| `InspectImproveFlow` | `org.apache.commons.lang.StringUtils` (lang) |
| `InspectCloseoutFlow` | `org.apache.commons.lang.StringUtils` (lang) |
| 各 Listener | lang 和 lang3 混用 |

同一类中三种 `StringUtils` 混用增加混淆。Apache Commons Lang (`lang`) 是旧版，`lang3` 是新版，`shiro` 是第三方。

---

## 五、P3 低危问题

### 5.1 两个新的 Listener 含 TODO 未实现

- `AfterInspectImproveCompleteListener` 行 44：只输出日志，未更新业务表
- `AfterCloseoutApprovedListener` 行 35：同上

### 5.2 大量未使用的 Import

约 7 个 Listener 包含从模板复刻过来的未使用 import（如 `LambdaQueryWrapper`、`FlowNodeExpression`、`WorkFlowGlobals`、`TaskTask`、`ITaskTaskService`），推测是从其他文件复制后未清理。

### 5.3 缺少 `@Override`

xispeakfb `AfterImplDeptLeaderApproveListener` 的 `notify()` 方法缺少 `@Override`，失去编译期接口契约校验。

### 5.4 硬编码变量名 vs 配置化

`AfterImplDeptLeaderApproveListener` 和 `AfterImplWorkerTemStoreListener` 分别硬编码 `"tem_impl_leader"` 和 `"tem_impl_worker"`，而 `AfterBgLeaderApproveListener` 正确地通过 Config 读取。行为不一致。

### 5.5 `getImplDeptLeader()` 逻辑矛盾

```java
// XiSpeakFlow 行 246-252
public String getImplDeptLeader(DelegateExecution execution) {
    DeptApproveDetail detail = getDeptApproveDetail(execution);
    if (detail != null && detail.getIsEnd() != null) {
        return String.valueOf(detail.getImplWorker());   // isEnd 非 null → 取 implWorker
    }
    return detail == null ? "" : detail.getImplWorker(); // isEnd 为 null → 也取 implWorker
}
```

两个分支返回同一个字段，`isEnd` 判断形同虚设（可能是条件写反）。

---

## 六、架构演进建议

### 6.1 短期（本迭代）

1. 修复 4 处 P0 致命问题（`StringUtil` 拼写、3 处 NPE）
2. 统一 `AfterSDWApproveHqListener` 注入方式
3. 统一两处错误注入（static 块 → 构造注入）
4. 补上 `AfterInspectImproveCompleteListener` 和 `AfterCloseoutApprovedListener` 的 TODO

### 6.2 中期（下个迭代）

5. 将 `getStringFromData` / `getListFromData` / `getListSize` 提取为共用 `FlowJsonParser` 工具类
6. 将 2 级父 Execution 攀爬逻辑提取为可复用的模板方法或工具方法
7. 统一 `parseDeptId` 到完整版
8. 统一 `StringUtils` 引用为 `org.apache.commons.lang3.StringUtils`
9. 清理未使用的 import

### 6.3 长期（架构层面）

10. 考虑引入流程模块 SDK 层（`flow-module-sdk`），包含：
    - 基类 `AbstractFlowConfig` / `AbstractFlowExpression`
    - 泛型 JSON 解析器
    - 通用 Listener 模板（变量攀爬、审批记录持久化）
11. 统一事务策略文档：哪些 Listener 需要 `@Transactional`，何时用悲观锁 vs 乐观锁
12. 建立模块创建 CheckList，新模块上线前逐项验证（DI 一致性、NPE 防御、事务标注、无硬编码等）

---

## 七、CheckList：新流程模块自查项

| # | 检查项 | 说明 |
|---|--------|------|
| 1 | Config 注入方式 | `@Component` + `@ConfigurationProperties(prefix = "flow-biz")` |
| 2 | Config 内嵌类 | 属性名与 yml key 中划线自动映射驼峰 |
| 3 | Flow 注入方式 | `@RequiredArgsConstructor(onConstructor_ = @Autowired)` + private final |
| 4 | Flow Bean 命名 | `@Component("xxxFlow")`，避免与其它模块冲突 |
| 5 | 所有公开方法守卫 null | Flow 方法中检查 `getXxx()` 返回 null |
| 6 | 是否复用 `getStringFromData` / `getListFromData` | 优先使用共用工具类，不复写 |
| 7 | Listener 注入方式 | 统一构造注入，禁止 static 块和字段注入 |
| 8 | Listener 类型选择 | 需在任务创建前初始化变量 → ExecutionListener；任务完成回调 → TaskListener |
| 9 | 事务注解 | 有 DB 写操作加 `@Transactional(rollbackFor = Exception.class)` |
| 10 | 锁策略 | 并发写同一行 → `getByIdForUpdate`；无并发 → `getById` |
| 11 | 异常处理策略 | 需阻断流程 → rethrow；可容忍 → catch + log + 返回默认值 |
| 12 | `StringUtils` | 统一使用 `org.apache.commons.lang3.StringUtils` |
| 13 | 无硬编码变量名 | 变量名统一从 Config 读取 |
| 14 | 无未使用 import | 提交前 IDE 自动优化 imports |
| 15 | `@Override` | 所有 `notify()` 方法加 `@Override` |
| 16 | yml 配置节 | 与 Config 内嵌类属性一一对应 |
| 17 | 无 TODO | 功能完整的 Listener 不应留 TODO |
| 18 | 日志规范 | 异常用 `log.error`、业务用 `log.info`、跳过/降级用 `log.warn` |