yidaima/RuoYi-Vue/docs/superpowers/plans/2026-07-10-plugin-transition-execution-receipts.md

# Plugin Transition Execution Receipts 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:** Execute recorded Plugin transition plans through a pluggable target executor while persisting idempotent batch and step receipts with retry and compensation controls.

**Architecture:** Transition steps gain immutable compensation artifact identity. A payload resolver rehydrates trusted content from the installed release and verifies the recorded SHA-256 before dispatching to a configured executor SPI; the built-in executor is `dry-run:v1` and performs no external writes. Execution batches and step receipts use a database-backed state machine independent from Plugin publication transactions.

**Tech Stack:** Java 8, Spring, MyBatis XML, Fastjson2, JUnit 4, Mockito, MySQL 5.7-compatible SQL, Vue 2, Element UI, Node test runner.

## Global Constraints

- Default execution is `dry-run:v1`; it must not connect to or modify a target database, permission service, or menu service.
- Every step body is reloaded from the trusted installed release and must match the hash recorded in the immutable Transition Plan.
- `EXECUTE` is idempotent after success; `RETRY` is allowed only after a failed forward attempt; `COMPENSATE` is allowed only after a successful forward attempt and runs reversible steps in reverse order.
- Executor failures are persisted as `FAILED` receipts and returned as data; validation and illegal state transitions fail before a new batch is created.
- Existing publication and rollback transactions continue to create only the immutable Transition Journal; external execution is a separate explicit action.
- Existing plaintext development credentials and TLS verification settings remain out of scope by explicit user decision.

---

### Task 1: Compensation Identity And Payload Resolution

**Files:**
- 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/PluginTransitionPlanner.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/execution/ResolvedPluginContribution.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/execution/PluginContributionContentResolver.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 apply/rollback compensation identity and trusted payload hash verification.
- [x] Implement compensation metadata, release payload lookup, direction-aware content resolution, and mismatch rejection.
- [x] Verify planner and resolver tests pass.

### Task 2: Target Executor SPI

**Files:**
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/config/PluginExecutionProperties.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/execution/PluginContributionExecutionContext.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/execution/PluginContributionExecutionResult.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/execution/PluginContributionTargetExecutor.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/execution/PluginContributionExecutorRegistry.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/execution/DryRunPluginContributionTargetExecutor.java`
- Test: `ruoyi-generator/src/test/java/com/ruoyi/generator/factory/plugin/execution/PluginContributionExecutorRegistryTest.java`

- [x] Write failing tests for configured executor selection, unsupported target rejection, and deterministic dry-run receipt identity.
- [x] Implement the SPI, configured registry lookup, and no-side-effect dry-run executor.
- [x] Verify executor tests pass.

### Task 3: Execution Batch And Step Receipt State Machine

**Files:**
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/model/PluginTransitionExecution.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/model/PluginTransitionStepReceipt.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/mapper/factory/PluginTransitionExecutionMapper.java`
- Create: `ruoyi-generator/src/main/resources/mapper/factory/PluginTransitionExecutionMapper.xml`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/service/PluginTransitionExecutionService.java`
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/model/PluginTransitionRecord.java`
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/mapper/factory/PluginRegistryMapper.java`
- Modify: `ruoyi-generator/src/main/resources/mapper/factory/PluginRegistryMapper.xml`
- Modify: `sql/factory_plugin_registry.sql`
- Modify: `sql/front_workbench.sql`
- Modify: `sql/db.sql`
- Test: `ruoyi-generator/src/test/java/com/ruoyi/generator/service/PluginTransitionExecutionServiceTest.java`
- Test: `ruoyi-generator/src/test/java/com/ruoyi/generator/factory/plugin/PluginRegistrySchemaScriptTest.java`

- [x] Write failing tests for successful execution, persisted failure, idempotent re-entry, retry guards, and reverse compensation order.
- [x] Add immutable execution/receipt tables and MyBatis mappings.
- [x] Implement transition fingerprint verification, locking, attempt numbering, state guards, step dispatch, and receipt persistence.
- [x] Verify service and schema tests pass.

### Task 4: API And Admin UI

**Files:**
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/controller/FeaturePluginController.java`
- Modify: `ruoyi-ui/src/api/generator/plugin.js`
- Modify: `ruoyi-ui/src/views/generator/plugin/index.vue`
- Modify: `ruoyi-ui/test/pluginRegistryView.test.mjs`
- Modify: `sql/plugin_registry_menu.sql`

- [x] Write failing controller/static UI contracts for execute, retry, compensate, status, and receipt inspection.
- [x] Add permission-protected APIs and menu permission.
- [x] Add execution status, explicit actions, and receipt dialog to the existing transition table.
- [x] Verify frontend contracts and production build pass.

### Task 5: Documentation And Regression

**Files:**
- Modify: `docs/superpowers/specs/2026-07-10-ai-software-factory-roadmap.md`
- Create: `docs/superpowers/plans/2026-07-10-plugin-transition-execution-receipts.md`

- [x] Document D8e1 behavior and the dry-run boundary.
- [x] Run focused Plugin execution tests.
- [x] Run generator full regression and compare only against the documented 18 baseline failures.
- [x] Run admin critical tests, frontend static tests, and the production build.
- [x] Confirm local EasyCode and RuoYi UI development endpoints still respond.