From 6fe37bf941a856a18ce38f7c1c0bea4121ef1c0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BC=A0=E5=AE=B6=E8=AE=AD?= Date: Fri, 31 Jul 2026 19:08:42 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A7=84=E5=88=92=E5=85=AC=E5=85=B1=20UI=20?= =?UTF-8?q?=E5=9F=BA=E7=A1=80=E8=83=BD=E5=8A=9B=E6=94=B6=E5=B0=BE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../plans/2026-07-31-public-ui-foundation.md | 317 ++++++++++++++++++ .../2026-07-31-public-ui-foundation-design.md | 2 +- 2 files changed, 318 insertions(+), 1 deletion(-) create mode 100644 docs/superpowers/plans/2026-07-31-public-ui-foundation.md diff --git a/docs/superpowers/plans/2026-07-31-public-ui-foundation.md b/docs/superpowers/plans/2026-07-31-public-ui-foundation.md new file mode 100644 index 0000000..2f21e36 --- /dev/null +++ b/docs/superpowers/plans/2026-07-31-public-ui-foundation.md @@ -0,0 +1,317 @@ +# Public UI Foundation Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Consolidate notifications, history-file actions, progress semantics, and accessibility behavior without changing plugin business results. + +**Architecture:** Windows depend on narrow UI services instead of JavaFX dialogs, clipboard APIs, or operating-system helpers. Domain-specific progress records remain independent; shared panes own reusable accessibility behavior. Each migration is protected by unit or source-architecture tests before window code changes. + +**Tech Stack:** Java 17, JavaFX, JUnit 5, Maven Wrapper, PowerShell, existing `AsyncOperationController` and `SystemOpenHelper`. + +## Global Constraints + +- Do not modify Git Review, Mobile UI Automation, Settings, or Plugin Management. +- Do not change generated output formats or persisted history formats. +- Do not expose datasource passwords, tokens, or credential-bearing URLs in notifications. +- Keep MyBatis SQL Export cancellable; it cooperatively checks cancellation between projects. +- Scanner remains non-cancellable. +- Use `$env:JAVA_HOME='C:\Program Files\Java\jdk-17'` for Maven commands. +- Preserve unrelated untracked files under `docs/audit`, `docs/audit/screenshots`, and `src/main/resources`. + +--- + +### Task 1: Notification model and JavaFX presenter + +**Files:** +- Create: `src/main/java/com/example/workutils/system/ui/notification/NotificationLevel.java` +- Create: `src/main/java/com/example/workutils/system/ui/notification/NotificationMessage.java` +- Create: `src/main/java/com/example/workutils/system/ui/notification/NotificationCenter.java` +- Create: `src/main/java/com/example/workutils/system/ui/notification/FxNotificationCenter.java` +- Test: `src/test/java/com/example/workutils/system/ui/notification/NotificationMessageTest.java` +- Test: `src/test/java/com/example/workutils/system/ui/notification/FxNotificationCenterArchitectureTest.java` + +**Interfaces:** +- Produces: `NotificationMessage(NotificationLevel level, String title, String message)`. +- Produces: `NotificationCenter.info(String,String)`, `warning(String,String)`, `error(String,String)`, and `boolean confirm(String,String,String)`. +- Produces: `new FxNotificationCenter(Window owner)`. + +- [ ] **Step 1: Write failing notification value tests** + +Test trimming/default title, rejection of null or blank message, and preservation of multiline content: + +```java +assertEquals("提示", new NotificationMessage(INFO, " ", " 完成 ").title()); +assertEquals("完成", new NotificationMessage(INFO, " ", " 完成 ").message()); +assertThrows(IllegalArgumentException.class, + () -> new NotificationMessage(ERROR, "失败", " ")); +``` + +- [ ] **Step 2: Run the focused test and verify RED** + +Run: `$env:JAVA_HOME='C:\Program Files\Java\jdk-17'; .\mvnw.cmd -q -Dtest=NotificationMessageTest test` + +Expected: compilation failure because notification types do not exist. + +- [ ] **Step 3: Implement the model and narrow interface** + +Use this contract: + +```java +public interface NotificationCenter { + void show(NotificationMessage message); + boolean confirm(String title, String header, String message); + default void info(String title, String message) { show(new NotificationMessage(INFO, title, message)); } + default void warning(String title, String message) { show(new NotificationMessage(WARNING, title, message)); } + default void error(String title, String message) { show(new NotificationMessage(ERROR, title, message)); } +} +``` + +`FxNotificationCenter.show` must call immediately on the FX thread and otherwise use `Platform.runLater`. `confirm` must throw `IllegalStateException("confirm must be called on the JavaFX Application Thread")` off the FX thread. Map levels to JavaFX `AlertType`; use an expandable, read-only `TextArea` for long or multiline messages. + +- [ ] **Step 4: Add a source-architecture test for the threading contract** + +Read `FxNotificationCenter.java` and assert it contains `Platform.isFxApplicationThread()`, `Platform.runLater`, `initOwner(owner)`, and the exact confirmation-thread error. This test avoids displaying a modal dialog in CI. + +- [ ] **Step 5: Run focused tests and commit** + +Run: `$env:JAVA_HOME='C:\Program Files\Java\jdk-17'; .\mvnw.cmd -q -Dtest=NotificationMessageTest,FxNotificationCenterArchitectureTest test` + +Expected: PASS. + +Commit: `git commit -m "新增统一通知中心"` + +--- + +### Task 2: Migrate MyBatis Generator and Git Sync notifications + +**Files:** +- Modify: `src/main/java/com/example/workutils/biz/mybatisgenerator/MyBatisGeneratorWindow.java` +- Modify: `src/main/java/com/example/workutils/biz/git/GitSyncWindow.java` +- Modify: `src/test/java/com/example/workutils/biz/mybatisgenerator/MyBatisGeneratorWindowArchitectureTest.java` +- Create: `src/test/java/com/example/workutils/biz/git/GitSyncWindowArchitectureTest.java` + +**Interfaces:** +- Consumes: `FxNotificationCenter(Window)` and all `NotificationCenter` methods from Task 1. +- Produces: both windows contain one `NotificationCenter` field and no direct `new Alert`. + +- [ ] **Step 1: Tighten architecture tests before migration** + +Assert each target source contains `NotificationCenter` and `FxNotificationCenter`, and does not contain `new Alert`, `showAlert(`, or MyBatis's private `showInfo(`. Also assert Git's destructive confirmation text still contains `不可撤销`. + +- [ ] **Step 2: Run tests and verify RED** + +Run: `$env:JAVA_HOME='C:\Program Files\Java\jdk-17'; .\mvnw.cmd -q -Dtest=MyBatisGeneratorWindowArchitectureTest,GitSyncWindowArchitectureTest test` + +Expected: FAIL because both windows still construct alerts. + +- [ ] **Step 3: Migrate MyBatis Generator** + +Initialize `notificationCenter = new FxNotificationCenter(stage)` after the stage is available. Replace query/generation warnings with `warning`, generation results with `info`, and `confirmGeneration` with: + +```java +return notificationCenter.confirm( + "确认生成", + "即将为 " + plan.tables().size() + " 个表生成代码", + buildGenerationSummary(plan)); +``` + +Delete the private dialog methods and their now-unused JavaFX imports. + +- [ ] **Step 4: Migrate Git Sync without changing destructive behavior** + +Replace the missing-URL warning and bulk-reclone confirmation. Preserve the existing snapshot, row removal, thread start, delete/clone order, and confirmation wording. Only call `recloneAll` continuation when `confirm(...)` returns true. + +- [ ] **Step 5: Run focused tests and commit** + +Run: `$env:JAVA_HOME='C:\Program Files\Java\jdk-17'; .\mvnw.cmd -q -Dtest=NotificationMessageTest,MyBatisGeneratorWindowArchitectureTest,GitSyncWindowArchitectureTest test` + +Expected: PASS. + +Commit: `git commit -m "统一生成器与 Git 同步通知"` + +--- + +### Task 3: Shared result-file actions and three-window migration + +**Files:** +- Create: `src/main/java/com/example/workutils/system/ui/history/FileActionGateway.java` +- Create: `src/main/java/com/example/workutils/system/ui/history/SystemFileActionGateway.java` +- Create: `src/main/java/com/example/workutils/system/ui/history/ResultFileActions.java` +- Test: `src/test/java/com/example/workutils/system/ui/history/ResultFileActionsTest.java` +- Modify: `src/main/java/com/example/workutils/biz/apidoc/ApiDocWindow.java` +- Modify: `src/main/java/com/example/workutils/biz/scanner/ScannerWindow.java` +- Modify: `src/main/java/com/example/workutils/biz/mybatisexport/MyBatisExportWindow.java` +- Modify: `src/test/java/com/example/workutils/biz/apidoc/ApiDocWindowArchitectureTest.java` +- Create: `src/test/java/com/example/workutils/biz/scanner/ScannerWindowArchitectureTest.java` +- Create: `src/test/java/com/example/workutils/biz/mybatisexport/MyBatisExportWindowArchitectureTest.java` + +**Interfaces:** +- Produces: `FileActionGateway.open(Path)`, `edit(Path)`, `reveal(Path)`, `copyPath(String)`. +- Produces: `ResultFileActions(FileActionGateway, NotificationCenter, Consumer)` and `HistoryFileCommands commands()`. +- Consumes: `NotificationCenter` from Task 1 and existing `HistoryFileCommands`. + +- [ ] **Step 1: Write failing behavior tests using `@TempDir`** + +Use a recording gateway and notification fake. Cover open/edit/reveal delegation for an existing file; normalized absolute copy path; copying a missing path with a warning success message; rejection of blank paths; no gateway call for missing open targets; and gateway exception translated to `notificationCenter.error("文件操作失败", ...)`. + +- [ ] **Step 2: Run the focused test and verify RED** + +Run: `$env:JAVA_HOME='C:\Program Files\Java\jdk-17'; .\mvnw.cmd -q -Dtest=ResultFileActionsTest test` + +Expected: compilation failure because the action classes do not exist. + +- [ ] **Step 3: Implement gateway and action service** + +Production mapping must be exactly: + +```java +open -> SystemOpenHelper.openFile(path) +edit -> SystemOpenHelper.editFile(path) +reveal -> SystemOpenHelper.revealInFileManager(path.toString()) +copyPath -> Clipboard.getSystemClipboard().setContent(content) +``` + +`ResultFileActions.commands()` returns method references for the four existing `HistoryFileCommands` slots. Catch platform `RuntimeException` around gateway calls, but let constructor null errors and invalid program state fail immediately. + +- [ ] **Step 4: Add RED architecture constraints for the three windows** + +Assert all three sources contain `ResultFileActions` and do not contain `SystemOpenHelper`, `ClipboardContent`, `private void openFile`, `private void openWithNotepad`, or `private void openFolder`. + +- [ ] **Step 5: Migrate one shared command instance per window** + +Create the command bundle once during window construction, using `new SystemFileActionGateway()` and `new FxNotificationCenter(stage)`. Scanner keeps its `[INFO] 已复制路径` log consumer; API Doc and SQL Export use their existing feedback areas where available, otherwise `message -> {}`. Pass the shared commands to every `ExportHistoryPane`. + +- [ ] **Step 6: Run focused tests and commit** + +Run: `$env:JAVA_HOME='C:\Program Files\Java\jdk-17'; .\mvnw.cmd -q -Dtest=HistoryFileCommandsTest,ResultFileActionsTest,ApiDocWindowArchitectureTest,ScannerWindowArchitectureTest,MyBatisExportWindowArchitectureTest test` + +Expected: PASS. + +Commit: `git commit -m "统一导出历史文件操作"` + +--- + +### Task 4: Progress contracts and cancellation proof + +**Files:** +- Modify: `src/main/java/com/example/workutils/biz/scanner/application/ScanProgress.java` +- Modify: `src/main/java/com/example/workutils/biz/scanner/application/RunScanUseCase.java` +- Modify: `src/main/java/com/example/workutils/biz/mybatisexport/application/SqlExportProgress.java` +- Modify: `src/main/java/com/example/workutils/biz/mybatisexport/application/RunSqlExportUseCase.java` +- Create: `src/test/java/com/example/workutils/biz/scanner/application/ScanProgressTest.java` +- Create: `src/test/java/com/example/workutils/biz/mybatisexport/application/SqlExportProgressTest.java` +- Create: `src/test/java/com/example/workutils/biz/mybatisexport/application/RunSqlExportCancellationTest.java` +- Modify: `src/main/java/com/example/workutils/biz/scanner/ScannerWindow.java` +- Modify: `src/main/java/com/example/workutils/biz/mybatisexport/MyBatisExportWindow.java` + +**Interfaces:** +- Produces: validated existing record constructors and stable progress messages; no shared base interface. +- Preserves: `SqlExportProgress.fraction()` and SQL export's cooperative cancellation callback. + +- [ ] **Step 1: Write RED boundary tests** + +For `ScanProgress`, accept `-1`, `0`, and `1`; reject blank message, NaN, values below `-1`, and values above `1`. For SQL progress, accept `(0,0,"准备",0)` and `(2,2,"project",5)`; reject negative fields, blank project, and `current > total`. Assert `message()` returns `current + "/" + total + " " + projectName`, and `fraction()` returns the expected boundary value. + +- [ ] **Step 2: Prove SQL export cancellation propagation with a service fake** + +Capture the callback passed to `exportWithCallback`, request cancellation on the `OperationContext`, and assert `callback.isCancelled()` becomes true. The test must not connect to a database or write output files. + +- [ ] **Step 3: Run tests and verify RED** + +Run: `$env:JAVA_HOME='C:\Program Files\Java\jdk-17'; .\mvnw.cmd -q -Dtest=ScanProgressTest,SqlExportProgressTest,RunSqlExportCancellationTest test` + +Expected: DTO validation tests fail before compact constructors are added. + +- [ ] **Step 4: Add compact-constructor validation and explicit UI flags** + +Normalize record text with `trim()`. Make `RunScanUseCase` create `ScanProgress` values before reporting them, and make `RunSqlExportUseCase` report `SqlExportProgress.message()` and `fraction()` instead of rebuilding those values inline. Keep Scanner's `new OperationStatusPane(..., false)`. Make SQL Export's cancellability explicit with `new OperationStatusPane(..., true)` so future readers do not depend on the convenience constructor. + +- [ ] **Step 5: Run focused tests and commit** + +Run: `$env:JAVA_HOME='C:\Program Files\Java\jdk-17'; .\mvnw.cmd -q -Dtest=ScanProgressTest,SqlExportProgressTest,RunSqlExportCancellationTest test` + +Expected: PASS. + +Commit: `git commit -m "明确进度与取消契约"` + +--- + +### Task 5: Accessibility behavior in shared panes + +**Files:** +- Modify: `src/main/java/com/example/workutils/system/ui/history/ExportHistoryPane.java` +- Modify: `src/main/java/com/example/workutils/system/ui/EmptyStatePane.java` +- Modify: `src/main/java/com/example/workutils/system/ui/async/OperationStatusPane.java` +- Create: `src/test/java/com/example/workutils/system/ui/SharedPaneAccessibilityArchitectureTest.java` +- Modify: `src/test/java/com/example/workutils/system/ui/EmptyStateContentTest.java` + +**Interfaces:** +- Consumes: existing constructors; no call-site signature changes. +- Produces: consistent accessible text, focus traversal, keyboard open behavior, and no focusable cancel button for non-cancellable panes. + +- [ ] **Step 1: Write RED source and value tests** + +Assert the shared pane sources use `setAccessibleText`, `setFocusTraversable`, and key handling for `KeyCode.ENTER`. Assert `OperationStatusPane` conditionally adds the cancel button rather than always adding a hidden focusable control. Extend empty-state content tests to verify trimmed text used by the combined accessible label. + +- [ ] **Step 2: Run tests and verify RED** + +Run: `$env:JAVA_HOME='C:\Program Files\Java\jdk-17'; .\mvnw.cmd -q -Dtest=SharedPaneAccessibilityArchitectureTest,EmptyStateContentTest test` + +Expected: FAIL because accessibility calls and keyboard behavior are absent. + +- [ ] **Step 3: Implement minimal shared accessibility behavior** + +Set descriptive accessible text on table action buttons, history file cells, empty-state container/action, progress bar, status label, and cancel button. Clear file-cell text, tooltip, accessible text, and row reference when empty. On Enter, open the selected history row only when the table itself owns the key event; do not intercept Space or context-menu keys. Add cancel button to children only when `cancellable` is true. + +- [ ] **Step 4: Check component colors without broad theme changes** + +Search the three component files for inline `-fx-text-fill`, hexadecimal colors, and `Color.web`. If none exist, record no code change. If found, replace only those values with existing `Theme.TEXT_PRIMARY`, `Theme.TEXT_SECONDARY`, or established semantic style classes. + +- [ ] **Step 5: Run focused tests and commit** + +Run: `$env:JAVA_HOME='C:\Program Files\Java\jdk-17'; .\mvnw.cmd -q -Dtest=SharedPaneAccessibilityArchitectureTest,EmptyStateContentTest,HistoryFileCommandsTest test` + +Expected: PASS. + +Commit: `git commit -m "完善公共组件无障碍交互"` + +--- + +### Task 6: Full verification and audit closeout + +**Files:** +- Modify: `docs/audit/plugin-refactor-next.md` +- Test: all `src/test/java` tests. + +**Interfaces:** +- Consumes: all deliverables from Tasks 1-5. +- Produces: verified P1 public-foundation completion record. + +- [ ] **Step 1: Run all automated verification** + +Run: + +```powershell +$env:JAVA_HOME='C:\Program Files\Java\jdk-17' +.\mvnw.cmd -q test +.\mvnw.cmd -q -DskipTests compile +git diff --check +``` + +Expected: all commands exit 0. Record the exact test count from Maven reports. + +- [ ] **Step 2: Perform read-only UI smoke verification** + +Launch the existing application without stopping unrelated Java processes. Verify API Doc, Scanner, and MyBatis SQL Export history panes render and expose their actions; verify MyBatis Generator confirmation/result and Git Sync confirmation can be opened and cancelled. Do not execute file opens, database exports, code generation, repository deletion, or clone operations. + +- [ ] **Step 3: Update the audit todo** + +Move completed P1 items to the completed section. Record that SQL Export cancellation was retained after source verification, and leave Git Review, Mobile UI Automation, and Settings explicitly deferred/excluded. + +- [ ] **Step 4: Re-run documentation diff checks and commit** + +Run: `git diff --check; git status --short` + +Confirm only intended files are staged. + +Commit: `git commit -m "完成公共基础能力收尾"` diff --git a/docs/superpowers/specs/2026-07-31-public-ui-foundation-design.md b/docs/superpowers/specs/2026-07-31-public-ui-foundation-design.md index a3e4641..441220b 100644 --- a/docs/superpowers/specs/2026-07-31-public-ui-foundation-design.md +++ b/docs/superpowers/specs/2026-07-31-public-ui-foundation-design.md @@ -90,7 +90,7 @@ API 文档、Scanner、MyBatis SQL 导出删除各自的 `openFile`、`openWithN - `ScanProgress`：正文不可为空；进度必须是 `-1`（不确定）或 `[0, 1]`。 - `SqlExportProgress`：`current`、`total`、`recordCount` 不得为负，`current` 不得大于 `total`，项目名不可为空；`fraction()` 保持在 `[0, 1]`。 -DTO 只表达领域进度。窗口通过小型纯函数把 DTO 转换为 `OperationSnapshot` 所需的 message 和 fraction，转换函数独立测试。 +DTO 只表达领域进度，并提供展示所需的稳定 message/fraction。用例把 DTO 值报告给 `OperationContext`，窗口不再重复拼接进度文案；DTO 的边界和展示结果独立测试。 Scanner 没有中断协议，保持不显示停止按钮。MyBatis SQL 导出已经通过 `ExportCallback.isCancelled()` 在项目边界读取 `OperationContext.isCancellationRequested()`，属于真实的协作式取消，因此保留停止按钮。测试必须证明取消请求能传递到回调，且界面只在运行阶段显示停止按钮。