wangpeng/yidaima
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
yidaima/RuoYi-Vue/docs/superpowers/plans/2026-07-10-plugin-transition-execution-receipts.md

6.9 KiB
Raw Permalink Blame History

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

  • Write failing tests for apply/rollback compensation identity and trusted payload hash verification.

  • Implement compensation metadata, release payload lookup, direction-aware content resolution, and mismatch rejection.

  • 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

  • Write failing tests for configured executor selection, unsupported target rejection, and deterministic dry-run receipt identity.

  • Implement the SPI, configured registry lookup, and no-side-effect dry-run executor.

  • 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

  • Write failing tests for successful execution, persisted failure, idempotent re-entry, retry guards, and reverse compensation order.

  • Add immutable execution/receipt tables and MyBatis mappings.

  • Implement transition fingerprint verification, locking, attempt numbering, state guards, step dispatch, and receipt persistence.

  • 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

  • Write failing controller/static UI contracts for execute, retry, compensate, status, and receipt inspection.

  • Add permission-protected APIs and menu permission.

  • Add execution status, explicit actions, and receipt dialog to the existing transition table.

  • 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

  • Document D8e1 behavior and the dry-run boundary.

  • Run focused Plugin execution tests.

  • Run generator full regression and compare only against the documented 18 baseline failures.

  • Run admin critical tests, frontend static tests, and the production build.

  • Confirm local EasyCode and RuoYi UI development endpoints still respond.