101 lines
6.6 KiB
Markdown
101 lines
6.6 KiB
Markdown
# Plugin SQL Target Executor 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:** Add a default-disabled, isolated, idempotent MySQL target Executor with a target-side receipt ledger.
|
|
|
|
**Architecture:** Transition Plan 1.2 freezes an idempotence declaration. A Druid-AST policy accepts only a repeatable SQL subset, a guarded connection factory proves the target differs from the control catalog, and `sql-jdbc:v1` claims a target-side leased receipt before running normalized statements.
|
|
|
|
**Tech Stack:** Java 8, Spring Boot 2.5, Druid SQL AST 1.2.23, JDBC, MySQL 5.7-compatible DDL, H2 1.4.200 test scope, JUnit 4, Mockito, Vue 2.
|
|
|
|
## Global Constraints
|
|
|
|
- `sql-jdbc:v1` is disabled by default and never falls back to the control DataSource.
|
|
- JDBC URL, username, and password must never appear in API responses or logs.
|
|
- Real SQL requires immutable `idempotent=true` and Transition Plan schema 1.2.
|
|
- Only the SQL AST whitelist in the design may execute; no string-based SQL splitting is allowed.
|
|
- Existing plaintext development credentials and TLS verification settings remain out of scope by explicit user decision.
|
|
|
|
---
|
|
|
|
### Task 1: Immutable Idempotence Contract
|
|
|
|
**Files:**
|
|
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/model/PluginContributionPayload.java`
|
|
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/model/PluginTransitionStep.java`
|
|
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/model/PluginTransitionPlan.java`
|
|
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/PluginTransitionPlanner.java`
|
|
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/execution/ResolvedPluginContribution.java`
|
|
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/execution/PluginContributionContentResolver.java`
|
|
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/execution/PluginTransitionWorkResolver.java`
|
|
- Test: `ruoyi-generator/src/test/java/com/ruoyi/generator/factory/plugin/PluginTransitionPlannerTest.java`
|
|
- Test: `ruoyi-generator/src/test/java/com/ruoyi/generator/factory/plugin/execution/PluginContributionContentResolverTest.java`
|
|
|
|
- [x] Write failing tests for Plan 1.2 idempotence identity, changed declaration rejection, and 1.1 compensation compatibility.
|
|
- [x] Propagate and verify the immutable idempotence flag through payload, plan, and resolved contribution.
|
|
- [x] Run planner/resolver tests and confirm they pass.
|
|
|
|
### Task 2: Target Configuration And Connection Isolation
|
|
|
|
**Files:**
|
|
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/config/PluginSqlTargetProperties.java`
|
|
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/execution/sql/PluginSqlTargetConnectionFactory.java`
|
|
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/execution/sql/ConfiguredPluginSqlTargetConnectionFactory.java`
|
|
- Modify: `ruoyi-admin/src/main/resources/application.yml`
|
|
- Test: `ruoyi-generator/src/test/java/com/ruoyi/generator/factory/plugin/execution/sql/PluginSqlTargetConfigurationTest.java`
|
|
|
|
- [x] Write failing tests for disabled defaults, bounded lease, required safe identifiers, MySQL URL restriction, catalog match, and control-target rejection.
|
|
- [x] Implement configuration validation and guarded DriverManager connection creation.
|
|
- [x] Run configuration tests and confirm they pass.
|
|
|
|
### Task 3: Strict SQL AST Policy
|
|
|
|
**Files:**
|
|
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/execution/sql/PluginSqlMigrationParser.java`
|
|
- Test: `ruoyi-generator/src/test/java/com/ruoyi/generator/factory/plugin/execution/sql/PluginSqlMigrationParserTest.java`
|
|
|
|
- [x] Write failing parser tests for allowed repeatable DDL/DML, literal semicolons, unsupported statements, missing idempotent clauses, statement limits, and cross-catalog references.
|
|
- [x] Implement Druid MySQL AST parsing, table-source inspection, and normalized statement output.
|
|
- [x] Run parser tests and confirm they pass.
|
|
|
|
### Task 4: Target Receipt Ledger And Executor
|
|
|
|
**Files:**
|
|
- Create: `sql/factory_plugin_sql_target.sql`
|
|
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/execution/sql/PluginSqlTargetReceiptClaim.java`
|
|
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/execution/sql/PluginSqlTargetReceiptLedger.java`
|
|
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/execution/sql/SqlJdbcPluginContributionTargetExecutor.java`
|
|
- Modify: `ruoyi-generator/pom.xml`
|
|
- Test: `ruoyi-generator/src/test/java/com/ruoyi/generator/factory/plugin/execution/sql/SqlJdbcPluginContributionTargetExecutorTest.java`
|
|
|
|
- [x] Write failing H2 MySQL-mode tests for first execution, deterministic receipt, duplicate success deduplication, active target lease rejection, expired/failed replay, and rollback contribution execution.
|
|
- [x] Implement target receipt claim/complete/fail transactions and the `sql-jdbc:v1` Executor.
|
|
- [x] Add the isolated target receipt DDL and H2 test dependency.
|
|
- [x] Run Executor tests and confirm they pass.
|
|
|
|
### Task 5: Readiness Status And Admin UI
|
|
|
|
**Files:**
|
|
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/model/PluginRegistryStatus.java`
|
|
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/controller/FeaturePluginController.java`
|
|
- Modify: `ruoyi-generator/src/test/java/com/ruoyi/generator/controller/FeaturePluginControllerTest.java`
|
|
- Modify: `ruoyi-ui/src/views/generator/plugin/index.vue`
|
|
- Modify: `ruoyi-ui/test/pluginRegistryView.test.mjs`
|
|
|
|
- [x] Write failing backend/frontend contracts for configured Executor and non-secret SQL target readiness.
|
|
- [x] Expose only executor code, enabled/readiness, environment code, and allowed catalog.
|
|
- [x] Add the concise target state to the existing Registry status band.
|
|
- [x] Run controller/static UI tests and the production build.
|
|
|
|
### Task 6: Documentation And Regression
|
|
|
|
**Files:**
|
|
- Modify: `docs/superpowers/specs/2026-07-10-ai-software-factory-roadmap.md`
|
|
- Modify: `docs/superpowers/plans/2026-07-11-plugin-sql-target-executor.md`
|
|
|
|
- [x] Document D8e2b activation order, SQL whitelist, target receipt semantics, and remaining permission/menu boundary.
|
|
- [x] Run focused Plugin/Outbox/SQL Executor tests.
|
|
- [x] Run generator full regression and compare with the documented 18 baseline failures.
|
|
- [x] Run admin critical tests, frontend static tests, and the production build.
|
|
- [x] Confirm EasyCode and RuoYi UI endpoints still return HTTP 200.
|