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-rollback-artifact-transition-journal.md

6.6 KiB
Raw Permalink Blame History

Plugin Rollback Artifact And Transition Journal 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: Package deterministic rollback files with generated Plugin contributions and persist every Plugin publication pointer transition as an immutable, fingerprinted journal batch.

Architecture: Extend contribution payload and execution-step metadata with a resolved rollback output path and rollback SHA-256, then write rollback content into the same deterministic target ZIP under a separate path. Build canonical transition plans from installed release payloads and insert one journal row in the same transaction as publish, restore, bootstrap, or pointer repair operations.

Tech Stack: Java 8, Spring, MyBatis XML, Fastjson2, JUnit 4, Mockito, MySQL 5.7-compatible SQL, Node static UI tests.

Global Constraints

  • Preserve empty-contribution ZIP and fingerprint compatibility.
  • Rollback output paths are relative, traversal-safe, deterministic, and conflict-checked against generated and forward contribution files.
  • PUBLISH and BOOTSTRAP journal forward APPLY steps; RESTORE journals outgoing ROLLBACK steps followed by target APPLY steps; REPAIR is a zero-step pointer transition.
  • Journal insertion must succeed in the same Spring transaction as the current-version pointer update.
  • The journal audits catalog transitions and artifact batches; it does not claim that an external database or authorization system executed them.
  • Existing plaintext development credentials and TLS verification settings remain out of scope by explicit user decision.

Task 1: Deterministic Rollback Artifact

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/PluginContributionStep.java
  • Modify: ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/PluginContributionPayloadValidator.java
  • Modify: ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/PluginContributionResourceLoader.java
  • Modify: ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/PluginContributionArtifactExecutor.java
  • Test: ruoyi-generator/src/test/java/com/ruoyi/generator/factory/plugin/PluginContributionArtifactExecutorTest.java
  • Test: ruoyi-generator/src/test/java/com/ruoyi/generator/factory/plugin/PluginContributionResourceLoaderTest.java

Interfaces:

  • Produces: PluginContributionPayload.rollbackOutputPath and PluginContributionStep.rollbackOutputPath/rollbackContentHash.

  • Produces: deterministic fallback path rollback/<forward-output-path> when rollback content exists and no custom path is declared.

  • Write tests that expect rollback content in the target ZIP and matching metadata hashes.

  • Run focused tests and verify failure because rollback artifacts are not emitted.

  • Implement safe rollback path resolution, duplicate detection, deterministic ZIP output, and metadata hashing.

  • Run focused tests and verify all rollback artifact cases pass.

Task 2: Canonical Transition Plan

Files:

  • Create: ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/model/PluginTransitionStep.java
  • Create: ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/model/PluginTransitionPlan.java
  • Create: ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/PluginTransitionPlanner.java
  • Test: ruoyi-generator/src/test/java/com/ruoyi/generator/factory/plugin/PluginTransitionPlannerTest.java

Interfaces:

  • Produces: PluginTransitionPlanner.plan(String operation, String pluginCode, PluginVersionRecord fromVersion, PluginRelease fromRelease, PluginVersionRecord toVersion, PluginRelease toRelease).

  • Produces: stable ordered steps with direction, contribution identity, artifact path, and raw UTF-8 SHA-256.

  • Write tests for publish apply ordering, restore rollback-before-apply ordering, and repair zero-step plans.

  • Run the planner test and verify failure because the planner does not exist.

  • Implement the minimal canonical planner using installed immutable release payloads.

  • Run the planner test and verify all transition shapes pass.

Task 3: Immutable Transition Journal

Files:

  • Create: ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/model/PluginTransitionRecord.java
  • Modify: ruoyi-generator/src/main/java/com/ruoyi/generator/factory/plugin/model/PluginDefinitionDetail.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: ruoyi-generator/src/main/java/com/ruoyi/generator/service/FeaturePluginServiceImpl.java
  • 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/FeaturePluginServiceImplTest.java
  • Test: ruoyi-generator/src/test/java/com/ruoyi/generator/factory/plugin/PluginRegistrySchemaScriptTest.java

Interfaces:

  • Produces: PluginRegistryMapper.insertPluginTransition(PluginTransitionRecord) and selectPluginTransitions(Long pluginId).

  • Produces: detail API field transitions ordered newest first.

  • Write service and planner tests that require journal insertion after pointer update and cover publish, restore, bootstrap, and repair plans.

  • Write schema/mapper tests that require an append-only factory_plugin_transition table and insert/select mappings.

  • Run tests and verify failure on the missing journal contracts.

  • Implement models, mapper XML, SQL schema, detail query, canonical JSON/fingerprint creation, and transactional insertion.

  • Run focused service and schema tests and verify all journal cases pass.

Task 4: Documentation And Regression

Files:

  • Modify: docs/superpowers/specs/2026-07-10-ai-software-factory-roadmap.md

  • Create: docs/superpowers/plans/2026-07-10-plugin-rollback-artifact-transition-journal.md

  • Document D8d boundaries, data flow, and the distinction between recorded plans and external execution.

  • Run focused Plugin contribution and publication tests.

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

  • Run admin critical tests and frontend Plugin static tests/build.

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