yidaima/RuoYi-Vue/docs/superpowers/specs/2026-07-11-preview-sql-delivery-rehearsal-design.md

Preview SQL Delivery Rehearsal Design

Context

P2-D8e2b provides a real, default-disabled sql-jdbc:v1 Executor, but every installed PageBlock release still has an empty delivery payload. The execution framework therefore has no reviewed built-in release that proves a real classpath SQL artifact can move through publication, immutable Transition planning, trusted content re-resolution, target deduplication, and compensation.

P2-D8e2c adds one deliberately small delivery Plugin and a read-only target probe. It does not enable the SQL target, publish a release, enqueue a Transition, or connect to a production database automatically.

Delivery Plugin

The installed release is delivery.preview-baseline@1.0.0, provided by ruoyi-factory with Plugin type delivery. It declares one DATABASE_MIGRATION contribution named V1__preview_delivery_baseline.

The apply resource:

• creates the dedicated factory_delivery_baseline_marker table with IF NOT EXISTS;
• uses INSERT IGNORE to add the immutable delivery.preview-baseline marker;
• is declared idempotent=true;
• contains no control-database table and no dynamic catalog name.

The rollback resource uses only DROP TABLE IF EXISTS factory_delivery_baseline_marker. The table is dedicated to this Plugin release, so compensation does not remove data owned by another feature.

The Plugin is a normal Spring FeaturePlugin. It appears in installed Registry manifests and can be bootstrapped through the existing publication workflow. Installation alone has no target-side effect. Operators must still publish the release and explicitly enqueue its Transition.

Manual Target Probe

Registry status continues to report only local configuration readiness. A separate POST /generator/plugin/sql-target/probe operation performs an explicit, read-only probe under generator:plugin:list permission.

The probe:

1. returns DISABLED without opening a connection when the target is disabled;
2. returns INVALID_CONFIGURATION without opening a connection when local validation fails;
3. opens the guarded isolated connection, which rechecks target catalog and control-database identity;
4. runs a zero-row query against factory_plugin_target_receipt;
5. returns READY, UNAVAILABLE, or LEDGER_UNAVAILABLE with a generic message.

The response contains only state, enabled/config-ready/reachable/ledger-ready booleans, environment code, allowed catalog, and a generic message. It has no JDBC URL, username, password, driver exception, SQLState, or server error text. Probe results are not persisted and never run migration payloads.

Admin UI

When SQL target configuration is enabled, the Registry status band shows a compact manual probe command and the last result held in the browser. The initial state is NOT_CHECKED. A successful result confirms isolation checks and receipt-table visibility, not permission to modify arbitrary application tables.

The existing execution dialog remains the only place where an operator starts a published Transition. The probe cannot publish, execute, retry, or compensate a Plugin.

End-To-End Rehearsal Test

The integration test uses H2 1.4.200 in MySQL mode and the real classpath apply/rollback resources. It performs this path without replacing core steps with mocks:

1. construct the installed Plugin and validate its manifest/payload fingerprint;
2. plan a schema 1.2 PUBLISH Transition;
3. re-resolve the apply content from the installed release;
4. execute through sql-jdbc:v1 and the target receipt ledger;
5. redeliver the same logical step and verify one marker row and one target execution;
6. resolve the planned compensation and execute it under a separate stable key;
7. verify the marker table is absent and both target receipts are SUCCEEDED.

Separate probe tests cover disabled, invalid, ready, unreachable, and missing-ledger outcomes with mocked JDBC boundaries. No test attempts a production target connection.

Activation Order

1. Apply sql/factory_plugin_sql_target.sql to an isolated preview catalog.
2. Configure and enable the SQL target, then restart.
3. Use the manual target probe and require READY.
4. Bootstrap or create the delivery.preview-baseline definition and publish version 1.0.0.
5. Inspect the immutable Transition Plan and enqueue execution.
6. Verify the marker and target receipt, then exercise compensation before considering a broader Plugin.

Scope

This stage proves one small database delivery artifact and closes the target-readiness observability gap. It does not add permission/menu adapters, arbitrary SQL upload, automatic execution, scheduled probes, production credentials, or production rollout approval. Existing plaintext development credential and TLS settings remain deferred by explicit user decision.