cisd/docs/plans/2026-03-10-init-execute-async-resume-plan.md

Init Execute Async Resume Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Make /api/v1/init/tasks/{taskId}/execute return immediately after accepting work, then run init steps in the background and resume from the first non-SUCCESS step on retry.

Architecture: Keep the existing task table and step table as the source of truth. Split InitService.executeTask into an accept-and-dispatch path plus a background execution path, and use existing step statuses to determine where to resume. Add a lightweight in-process guard so one taskId cannot be started twice concurrently in the same application instance.

Tech Stack: Spring Boot service/controller layer, Java concurrency utilities, MyBatis-style repositories already present in the module, JUnit 5

---

Task 1: Lock down current behavior with service tests

Files:

• Modify: /Users/waner/Work/CISD/文档/tms-framework/src/test/java/com/cisd/tms/modules/init/service/InitServiceTest.java
• Test: /Users/waner/Work/CISD/文档/tms-framework/src/test/java/com/cisd/tms/modules/init/service/InitServiceTest.java

Step 1: Write the failing tests

Add tests that assert:

• executeTask(taskId) returns before a deliberately blocking executor finishes all steps
• retry skips steps already marked SUCCESS and resumes from the first FAILED step
• residual RUNNING steps are treated as the resume point on retry
• duplicate execute calls for the same running task do not launch a second execution

Step 2: Run tests to verify they fail

Run: mvn -q -Dtest=InitServiceTest#shouldAcceptTaskExecutionAsynchronously,InitServiceTest#shouldResumeFromFirstFailedStepOnRetry,InitServiceTest#shouldResumeFromResidualRunningStep,InitServiceTest#shouldNotDispatchDuplicateBackgroundExecutionForSameTask test Expected: FAIL because execution is still synchronous and always starts from step 1.

Step 3: Write minimal test scaffolding

Extend the in-memory executor/repository helpers in the test file so they can:

• block on a latch or sleep
• count executed step codes
• fail a chosen step once and succeed on retry

Do not change production code in this step.

Step 4: Run tests to verify RED is stable

Run: mvn -q -Dtest=InitServiceTest#shouldAcceptTaskExecutionAsynchronously,InitServiceTest#shouldResumeFromFirstFailedStepOnRetry,InitServiceTest#shouldResumeFromResidualRunningStep,InitServiceTest#shouldNotDispatchDuplicateBackgroundExecutionForSameTask test Expected: FAIL with assertion mismatches that prove the new behavior is not implemented yet.

Step 5: Commit

Skip commit in the current dirty workspace per user instruction.

Task 2: Introduce async dispatch in InitService

Files:

• Modify: /Users/waner/Work/CISD/文档/tms-framework/src/main/java/com/cisd/tms/modules/init/service/InitService.java
• Modify: /Users/waner/Work/CISD/文档/tms-framework/src/test/java/com/cisd/tms/modules/init/service/InitServiceTest.java

Step 1: Implement minimal async acceptance path

Refactor InitService so executeTask(taskId):

• loads task and steps
• returns a snapshot response quickly
• submits real work to a background executor

Use a small in-process dispatcher owned by InitService:

• ExecutorService or equivalent
• active-task map keyed by taskId

Step 2: Keep the real execution logic in a dedicated method

Create a private method such as executeTaskInBackground(taskId) that:

• reloads task and steps from repository
• updates statuses
• runs steps serially
• persists each step result immediately
• updates final task status

Step 3: Run focused tests

Run: mvn -q -Dtest=InitServiceTest#shouldAcceptTaskExecutionAsynchronously,InitServiceTest#shouldNotDispatchDuplicateBackgroundExecutionForSameTask test Expected: PASS

Step 4: Refactor for readability

Extract helpers only if needed:

• build response snapshot
• mark task running
• remove active-task entry in finally

Do not add extra features.

Step 5: Commit

Skip commit in the current dirty workspace per user instruction.

Task 3: Implement resume-from-first-non-success semantics

Files:

• Modify: /Users/waner/Work/CISD/文档/tms-framework/src/main/java/com/cisd/tms/modules/init/service/InitService.java
• Modify: /Users/waner/Work/CISD/文档/tms-framework/src/test/java/com/cisd/tms/modules/init/service/InitServiceTest.java

Step 1: Implement step selection logic

Before running steps in the background:

• convert residual RUNNING steps to FAILED
• skip every step already marked SUCCESS
• start execution at the first non-SUCCESS step

Preserve current semantics after the resume point:

• mark current step RUNNING
• on success mark SUCCESS
• on failure mark FAILED and stop

Step 2: Preserve response counters

Ensure successSteps in InitTaskExecuteResponse reflects the current number of successful steps, including successes from earlier runs.

Step 3: Run focused tests

Run: mvn -q -Dtest=InitServiceTest#shouldResumeFromFirstFailedStepOnRetry,InitServiceTest#shouldResumeFromResidualRunningStep test Expected: PASS

Step 4: Run the earlier async tests again

Run: mvn -q -Dtest=InitServiceTest#shouldAcceptTaskExecutionAsynchronously,InitServiceTest#shouldNotDispatchDuplicateBackgroundExecutionForSameTask,InitServiceTest#shouldResumeFromFirstFailedStepOnRetry,InitServiceTest#shouldResumeFromResidualRunningStep test Expected: PASS

Step 5: Commit

Skip commit in the current dirty workspace per user instruction.

Task 4: Align controller and API-facing semantics

Files:

• Modify: /Users/waner/Work/CISD/文档/tms-framework/src/main/java/com/cisd/tms/modules/init/controller/InitInternalController.java
• Modify: /Users/waner/Work/CISD/文档/tms-framework/src/main/java/com/cisd/tms/modules/init/dto/InitTaskExecuteResponse.java
• Modify: /Users/waner/Work/CISD/文档/tms-framework/src/test/java/com/cisd/tms/modules/init/service/InitServiceTest.java

Step 1: Make the API comments and DTO semantics match async behavior

Update JavaDoc/comments so they describe:

• execute endpoint only accepts and starts background work
• polling should use existing detail/step/log APIs

If needed, add a field only if tests prove it is necessary. Prefer reusing the current DTO unchanged.

Step 2: Run focused verification

Run: mvn -q -Dtest=InitServiceTest test Expected: PASS for all service tests, including the pre-existing create/query/execute cases.

Step 3: Review the controller surface

Check that:

• route path stays unchanged
• response wrapper stays unchanged
• no new endpoint is introduced unnecessarily

Step 4: Commit

Skip commit in the current dirty workspace per user instruction.

Task 5: Final verification

Files:

• Verify only

Step 1: Run init service tests

Run: mvn -q -Dtest=InitServiceTest test Expected: PASS

Step 2: Run init executor regression tests touched by earlier behavior changes

Run: mvn -q -Dtest=ConfigurableInitStepExecutorTest#shouldInjectDatabaseCredentialsWhenExecutingStandardDbApplyCommand,ConfigurableInitStepExecutorTest#shouldExposeStandardInitScriptTemplates,ConfigurableInitStepExecutorTest#shouldStartStandardCmspCmtpWithConfiguredCommand test Expected: PASS

Step 3: Run compile

Run: mvn -q -DskipTests compile Expected: PASS

Step 4: Review focused diff

Run: git diff -- src/main/java/com/cisd/tms/modules/init/service/InitService.java src/main/java/com/cisd/tms/modules/init/controller/InitInternalController.java src/main/java/com/cisd/tms/modules/init/dto/InitTaskExecuteResponse.java src/test/java/com/cisd/tms/modules/init/service/InitServiceTest.java docs/plans/2026-03-10-init-execute-async-resume-design.md docs/plans/2026-03-10-init-execute-async-resume-plan.md Expected: only async-dispatch, resume logic, and related documentation changes.

Step 5: Commit

Skip commit in the current dirty workspace per user instruction.