# WorkUtils 插件 UI 与代码可维护性审查

审查日期：2026-07-30

## 1. 结论

当前产品已经形成统一的左侧导航、颜色和基础按钮风格，但各插件仍是“每个 Window 自己搭 UI、自己开线程、自己管理 loading、自己处理错误”的实现方式。视觉统一停留在颜色层，交互状态和代码结构没有统一。

主要风险：

1. `Window` 类过大：8 个窗口平均约 824 行，`MobileUiAutomationWindow` 达 1702 行。
2. 异步状态没有统一模型：存在 `new Thread`、`Task`、`CompletableFuture`、布尔字段和手动 `Platform.runLater` 等多套实现。
3. loading 行为不一致：有的只禁用按钮，有的改文字，有的显示旋转图标，有的同时显示停止按钮；异常分支容易漏恢复状态。
4. UI 直接暴露敏感配置：Git 远程 URL 显示账号，数据库生成器显示完整 JDBC URL 和用户名。
5. 操作层级不清：刷新、执行、交换、终止、删除等按钮经常处于同一视觉层级。
6. 空状态普遍只是大片空白，用户无法判断是“尚未执行”“没有数据”还是“执行失败”。
7. UI、业务编排、文件操作、历史记录和线程控制混在同一个类里，AI 修改局部功能时需要理解整个窗口，误改概率高。

建议先建设公共 UI/异步基础设施，再逐插件迁移。不要同时重写所有插件。

## 2. 统一设计与代码基线

### 2.1 页面结构

所有插件统一为：

1. `PageHeader`：标题、简短说明、帮助入口。
2. `ConfigCard`：输入与选项。
3. `ActionBar`：一个主操作、零到两个次操作、一个条件显示的取消操作。
4. `OperationStatus`：阶段、进度、耗时、当前处理对象。
5. `ResultArea`：结果、空状态、失败状态。
6. `HistoryTable`：历史记录放在独立 Tab 或折叠区，不抢占主任务空间。

### 2.2 按钮状态

按钮不应由业务代码直接反复调用 `setText`、`setDisable`、`setGraphic`。统一使用状态：

```java
public enum OperationState {
    IDLE, VALIDATING, RUNNING, CANCELLING, SUCCEEDED, FAILED
}
```

统一按钮规范：

| 状态 | 主按钮 | 取消按钮 | 输入区 |
|---|---|---|---|
| IDLE | 可用，显示动作名称 | 隐藏 | 可编辑 |
| VALIDATING | spinner +“校验中” | 隐藏 | 禁用 |
| RUNNING | spinner + 阶段名称 | 显示 | 禁用 |
| CANCELLING | “正在停止…” | 禁用 | 禁用 |
| SUCCEEDED | 恢复动作名称 | 隐藏 | 可编辑 |
| FAILED | 恢复动作名称 | 隐藏 | 可编辑 |

建议增加公共组件：

```java
public final class AsyncAction {
    private final ReadOnlyObjectWrapper<OperationState> state =
            new ReadOnlyObjectWrapper<>(OperationState.IDLE);
    private final StringProperty message = new SimpleStringProperty("");
    private final DoubleProperty progress = new SimpleDoubleProperty(-1);

    public <T> void run(
            Supplier<T> work,
            Consumer<T> onSuccess,
            Consumer<Throwable> onFailure) {
        if (state.get() == OperationState.RUNNING) return;
        state.set(OperationState.RUNNING);

        Task<T> task = new Task<>() {
            @Override protected T call() { return work.get(); }
        };
        task.setOnSucceeded(e -> finish(() -> onSuccess.accept(task.getValue())));
        task.setOnFailed(e -> finish(() -> onFailure.accept(task.getException())));
        AppExecutors.io().execute(task);
    }

    private void finish(Runnable callback) {
        try {
            callback.run();
        } finally {
            state.set(OperationState.IDLE);
        }
    }
}
```

`LoadingButtonBinder` 只负责展示：

```java
LoadingButtonBinder.bind(
        exportButton,
        exportAction.stateProperty(),
        "开始导出",
        "导出中…"
);
```

这样异常、提前返回和取消都不会遗漏恢复按钮。

### 2.3 推荐的插件目录边界

```text
biz/<plugin>/
  <Plugin>.java                 # 插件元数据和装配
  application/
    <UseCase>.java              # 一次用户任务的编排
    <Request>.java
    <Result>.java
  domain/
    ...                         # 纯业务模型和规则
  infrastructure/
    ...                         # Git、DB、文件、进程等外部访问
  ui/
    <Plugin>Pane.java           # 只组装区域
    <Plugin>ViewModel.java      # 可观察状态与命令
    components/
      ...
```

限制规则：

- `Pane` 不直接创建线程、访问文件、调用 Git/DB 或拼接业务结果。
- `ViewModel` 不创建 JavaFX 节点。
- `UseCase` 不依赖 JavaFX。
- 表格 cell 不直接执行文件操作，调用明确的 command。
- 单文件建议不超过 350 行；超过 500 行必须拆分。
- 每个异步操作只有一个拥有者，禁止窗口和 Service 同时管理线程生命周期。

## 3. 主框架

证据：`screenshots/00-home.png`

### UI 问题

- 欢迎页信息价值低，大片空白；没有最近任务、常用插件或配置健康状态。
- 顶部只有重复的插件图标和名称，无法承载状态、帮助或全局通知。
- 导航图标来源不统一，部分图标显示风格和宽度不一致。
- 插件说明只存在元数据中，导航和页面内没有有效呈现。

### 重构

- 欢迎页改为“最近使用 + 配置状态 + 快捷入口”，不要重复罗列功能名称。
- `MainWindow` 只负责路由与壳层；拆出 `NavigationPane`、`WorkspaceHeader`、`WelcomePane`。
- 增加统一 `NotificationCenter`，插件错误使用页内 banner 或 toast，不要各自弹 Alert。
- 用图标库统一图标，不再把 Emoji 当 UI 图标。

## 4. Git 仓库同步

证据：`screenshots/01-git-sync.png`

### UI 问题

- 项目表直接展示含账号的远程 URL，既敏感又占据大量宽度。
- “Git …”列标题被截断，列宽策略失效。
- 69 个项目没有搜索、状态筛选和批量选择反馈。
- “同步执行”和“损坏仓库处理”以 Tab 分割，但用户无法看到同步任务与项目选择的关系。
- loading 主要靠禁用“同步”和启用“停止”，缺少总进度、当前项目、成功/失败计数。

### 设计

- 项目列表顶部：搜索、状态筛选、`已选择 N 项`。
- URL 默认显示 `host/group/repo`，账号信息掩码；完整值仅通过“复制地址”获得。
- 同步操作采用固定底部 ActionBar：`同步选中项目` + 条件显示 `停止`。
- 运行时展示：总进度、当前仓库、成功/跳过/失败计数；失败项留在结果列表。
- “损坏仓库处理”作为失败结果的后续动作，而不是并列一级 Tab。

### 代码重构

- `GitSyncWindow` 拆为 `ProjectTablePane`、`SyncProgressPane`、`DamagedRepoPane`。
- 从 `GitSyncPlugin` 中迁出 Git 命令、进程输出和 URL 解析，形成 `GitRepositoryGateway`。
- `SyncRepositoriesUseCase` 返回结构化事件，不向 UI 传原始日志字符串：

```java
sealed interface SyncEvent {
    record Started(int total) implements SyncEvent {}
    record RepositoryStarted(String repository, int index) implements SyncEvent {}
    record RepositoryFinished(String repository, SyncOutcome outcome) implements SyncEvent {}
    record Completed(SyncSummary summary) implements SyncEvent {}
}
```

## 5. Git 分支评审

证据：`screenshots/02-git-review.png`

### UI 问题

- 页面信息密度过高，“粘贴识别”“手动字段”“IDEA 命令”“执行日志”同时出现。
- 主按钮“准备评审”含义不明确，实际上会拉取、切分支并打开 IDEA，副作用较大。
- 来源/目标依靠 A、B 解释，用户仍容易反向操作。
- 运行时 `runButton` 和 `historyOpenButton` 被同一 `running` 状态控制，两个无关动作耦合。
- 日志区默认空白，缺少阶段式反馈。

### 设计

- 改为三步：①识别评审信息；②确认仓库和分支方向；③执行并查看结果。
- 主按钮文案明确为“切换到目标分支并打开评审”。
- 在执行前展示摘要：`来源 A → 目标 B`、将执行的 Git 操作、工作区是否干净。
- 每个操作拥有独立状态：识别、刷新、执行、打开历史互不锁死。

### 代码重构

- `ReviewTextParser` 独立且纯函数化。
- `GitReviewViewModel` 持有表单和 `reviewAction`。
- `GitReviewService` 拆成 `GitStatusReader`、`BranchPreparationService`、`IdeaLauncher`。
- 用 `ReviewPlan` 表达执行前计划，使 UI 可预览，也便于单测。

## 6. 文本对比

证据：`screenshots/03-diff.png`

### UI 问题

- 空状态完全空白，没有示例或输入提示。
- 结果区在未比较时仍占据大半页面。
- “开始对比”对于本地 CPU 操作没有 loading；大文本可能冻结 JavaFX 线程。
- 上一处/下一处在无结果时只是灰色，未解释差异数量。
- 原文/对比文缺少文件导入、编码和换行符信息。

### 设计

- 输入区增加拖入文件/粘贴入口和字符、行数统计。
- 首次使用显示简短示例；比较后将结果区扩展。
- ActionBar 显示 `发现 N 处差异`，导航按钮显示当前位置 `3/18`。
- 大文本比较进入后台任务，按钮显示“比较中…”，并支持取消。

### 代码重构

- 当前 `DiffWindow` 同时包含 LCS、字符分段、HTML 渲染和 UI，应拆为：
  - `DiffEngine`
  - `DiffResult`
  - `DiffHtmlRenderer`
  - `DiffViewModel`
  - `DiffPane`
- `DiffResult` 保留结构化行和字符片段，UI 不再解析 HTML 来导航。

## 7. MyBatis SQL 导出

证据：`screenshots/04-mybatis-export.png`

### UI 问题

- “执行日志”在未执行时是空白大框；历史表反而成为页面视觉重点。
- “导出/终止”始终并列，终止按钮即使禁用也持续占位。
- 缺少项目范围、目标目录和预估数量摘要。
- 历史表列标题被截断，文件名过长，核心信息难扫描。
- loading 有进度文本，但没有进度条和错误计数。

### 设计

- 配置卡显示过滤条件、项目范围、输出目录。
- 主按钮为“导出 SQL”；运行后才出现“停止”。
- 状态区显示 `12/69`、当前项目、已导出 SQL 数、错误数。
- 历史记录放第二 Tab，文件名单行省略，Tooltip 展示完整路径。

### 代码重构

- `MyBatisExportWindow` 和 `ScannerWindow` 的历史表、打开/目录菜单高度重复，提取 `ExportHistoryPane<T>`。
- 用 `ExportRequest` 替代多个散落参数。
- `MyBatisExportService` 通过 `ProgressSink<ExportProgress>` 上报结构化进度。

## 8. MyBatis 逆向工程

证据：`screenshots/05-mybatis-generator.png`

### UI 问题

- 顶部展示完整 JDBC URL 和用户名，存在泄露风险。
- 左侧项目树与右侧表查询、输出目录并排，用户任务顺序不清。
- 三个输出路径通常相关，却要求逐项浏览/填充。
- “取消”实际是关闭窗口，在嵌入模式下语义不成立。
- 查询表和生成操作没有统一 loading，也缺少连接失败后的就地恢复。

### 设计

- 分成 ①数据源 ②选择表 ③生成配置 ④确认生成 四个区域或步骤。
- 数据源仅显示别名、数据库名、主机掩码和连接状态，完整连接串只在设置页维护。
- 输出目录选择一个项目根目录，再实时预览三个派生目录。
- “生成”前显示将覆盖/创建的文件摘要；完成后展示文件列表和打开目录。
- 嵌入模式去掉“取消”，改为“重置配置”。

### 代码重构

- `GeneratorFormState` 统一持有表选择与目录规则。
- `DatasourceSummary` 是脱敏 DTO，UI 禁止接触密码和原始 URL。
- `QueryTablesUseCase` 与 `GenerateArtifactsUseCase` 使用两个独立 `AsyncAction`。
- 路径推导放入 `OutputLayoutPolicy`，避免三个按钮各自维护逻辑。

## 9. 扫描功能

证据：`screenshots/06-scanner.png`

### UI 问题

- 页面写“扫描类型：关键词扫描”，但描述称支持关键词/Redis/Dubbo，入口和能力不一致。
- 正则匹配只是一个 Checkbox，缺少风险提示和表达式校验。
- 当前状态只显示“就绪”，位置和视觉权重过低。
- 历史表抢占主页面，空白结果/当前任务没有清晰区分。
- 开始扫描只禁用按钮，不展示 spinner、进度或取消能力。

### 设计

- 扫描类型使用单选卡或下拉，并根据类型切换专属字段。
- 正则模式提供即时校验和示例。
- 执行区域展示扫描目录、项目数、匹配数和当前项目。
- 当前结果与历史记录分 Tab。
- 主按钮 loading 文案为“扫描中 12/69”，提供取消。

### 代码重构

- 将 `ScanConfig` 升级为按类型区分的 sealed request，避免大量可空字段。
- `ScannerService` 不使用默认 `CompletableFuture` 线程池，统一注入受控 Executor。
- `ScannerWindow` 与历史文件操作解耦，复用公共历史组件。

## 10. API 接口文档导出

证据：`screenshots/07-api-doc.png`

### UI 问题

- 三张模式卡占据大量空间，但下方关键输入没有标签，依赖 placeholder。
- “全限定名”“批量导出”的说明文字对非作者用户不够明确。
- 主按钮横跨整个页面，视觉重量过大。
- 导出配置、导出历史、基类配置同属一级 Tab，但基类配置是低频系统设置。
- 文件/目录选择也使用 loading，操作通常瞬时完成，产生假的忙碌感。
- loading 通过节点属性保存旧文字，且部分代码再次直接覆盖文字，状态来源不唯一。

### 设计

- 模式切换改为紧凑 Segmented Control。
- 每种模式只显示相关字段，并有明确 Label、示例和校验错误。
- 主按钮右对齐，显示导出范围摘要。
- 基类配置移入系统设置或高级设置。
- 只有解析/生成过程进入 loading；文件选择不显示 spinner。
- 结果页显示生成文件、接口数、方法数、耗时和“打开/复制路径”。

### 代码重构

- `ApiDocWindow` 拆成 `ExportConfigPane`、`ExportHistoryPane`、`BaseClassConfigPane`。
- `ExportMode` 各自实现 request 构造，避免 `startExport` 中按模式分支。
- `ApiDocExportUseCase` 负责 parse/generate/history，UI 只提交 `ApiDocExportRequest`。
- 删除窗口内 `setBtnLoading`，接入统一 `AsyncAction`。
- HTML 调试代理作为单独能力开关，不在生成 HTML 时隐式启动。

## 11. 手机 UI 自动化

运行时当前禁用，结论基于源码；不能作为截图可验证的 UI 结论。

### 主要问题

- `MobileUiAutomationWindow` 1702 行、67 个方法、30 个 action、36 处线程/回调相关代码，是最高风险文件。
- 环境安装、设备管理、用例运行、录制、截图轮询、步骤编辑、报告历史全部集中在一个类。
- 使用 `isRunning`、按钮文字和内联 style 共同表达状态，容易不一致。
- 截图轮询拥有独立线程，窗口生命周期与线程停止逻辑难验证。
- “运行/停止”和“开始录制/停止并生成用例”通过改文字复用按钮，状态机不明确。

### 设计

- 一级拆为“运行用例”“录制用例”“环境与设备”三个页面。
- 顶部设备条只显示当前设备和健康状态；安装工具放入环境页。
- 运行页显示用例、参数、实时步骤和报告；录制页聚焦截图与步骤列表。
- 运行和录制使用显式状态机，停止按钮独立出现。

### 代码重构

至少拆成：

```text
mobileuiauto/ui/
  MobileAutomationPane.java
  DeviceBar.java
  run/RunCasePane.java
  run/RunCaseViewModel.java
  record/RecordCasePane.java
  record/RecordCaseViewModel.java
  environment/EnvironmentPane.java
  environment/EnvironmentViewModel.java
```

新增两个状态机：

```java
enum RunState { IDLE, STARTING, RUNNING, STOPPING, SUCCEEDED, FAILED }
enum RecordState { IDLE, STARTING, RECORDING, GENERATING, FAILED }
```

截图轮询封装为 `ScreenshotStream extends AutoCloseable`，由录制 ViewModel 持有并在页面离开时关闭。

## 12. 系统设置

### UI 问题

- Tab 数量多但缺少分类，配置文件编辑依赖外部编辑器。
- “重新加载”的反馈不明确。
- 数据源、项目路径、插件管理本质是结构化配置，不应主要依赖文本文件。

### 重构

- 分类为“常规 / 项目与数据源 / 插件 / 外观”。
- 配置项使用表单并提供校验、保存成功状态和恢复默认。
- 所有敏感字段支持显示/隐藏；列表页面只使用脱敏 DTO。

## 13. 建议实施顺序

1. 建立 `OperationState`、`AsyncAction`、`LoadingButtonBinder`、`OperationStatusPane`。
2. 提取 `ExportHistoryPane`、`EmptyStatePane`、`NotificationCenter`。
3. 先迁移 Scanner 和 MyBatis SQL 导出，验证公共组件。
4. 迁移 API 文档导出和 MyBatis 逆向工程。
5. 拆分 Git 同步和 Git 评审。
6. 抽离 DiffEngine。
7. 最后单独重构手机 UI 自动化，不与其他插件并行大改。

## 14. AI 友好编码约束

- 每个需求先定位到一个 UseCase 和一个 ViewModel，避免直接修改 Window。
- 不允许新增裸 `new Thread`。
- 不允许在业务代码直接调用 `Button#setText/setDisable/setGraphic`。
- 不允许使用 `Node#getProperties()` 保存业务状态。
- 不允许在 Window 中出现 Git、SQL、HTTP、进程命令或文件遍历。
- 所有跨线程结果必须是不可变 DTO。
- 所有状态使用 enum，不使用多个 boolean 拼状态。
- 每个 ViewModel 为每个 action 提供独立状态，禁止一个 `running` 锁住无关按钮。
- 为 Request 校验、状态迁移、UseCase 成功/失败/取消路径编写单元测试。
- UI 测试只验证绑定和可见性，不重复测试业务逻辑。

## 15. 证据范围

已实际捕获并复核：主界面、Git 同步、Git 分支评审、文本对比、MyBatis SQL 导出、MyBatis 逆向工程、扫描、API 文档导出。

未实际触发具有副作用的同步、切分支、数据库查询、生成、导出和删除操作，因此 loading、取消、错误恢复的结论同时参考了源码。手机 UI 自动化因当前配置禁用，仅完成源码审查。截图不能证明完整键盘访问、焦点顺序、屏幕阅读器语义或颜色对比合规，这些需要专项测试。