yidaima/RuoYi-Vue/docs/superpowers/plans/2026-05-24-ai-generation-task-center.md

AI Generation Task Center 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: Convert long-running DeepSeek generation requests into trackable asynchronous tasks with generation records, basic quota accounting, cost usage, and retry support.

Architecture: Keep the existing synchronous IAiGenerateService methods as the actual generation engine and add a DB-backed task layer in front of them. A task service creates task rows, reserves quota, and a worker claims pending tasks with a short database lock before executing generation outside the claim transaction. The Vue workbench starts tasks, polls status, and applies the generated result after success.

Tech Stack: Spring Boot, MyBatis XML mappers, MySQL tables in sql/front_workbench.sql and sql/db.sql, existing RuoYi thread pool conventions, Vue 3 + Element Plus.

---

File Structure

• Create ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/AiGenerationTask.java: task queue domain object.
• Create ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/AiUsageLedger.java: usage/cost ledger domain object.
• Create ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/AiQuotaBucket.java: per-user quota bucket domain object.
• Create DTOs under ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto: AiGenerationTaskCreateRequest, AiGenerationTaskStatusResponse, AiQuotaResponse.
• Create mapper interfaces and XML files under ruoyi-generator/src/main/java/com/ruoyi/generator/mapper/front and ruoyi-generator/src/main/resources/mapper/front.
• Create services under ruoyi-generator/src/main/java/com/ruoyi/generator/service/front: IAiGenerationTaskService, AiGenerationTaskServiceImpl, AiGenerationTaskWorker, AiQuotaService, AiCostCalculator, AiTaskRetryPolicy.
• Modify ruoyi-admin/src/main/java/com/ruoyi/web/controller/front/FrontProjectController.java: add task create/status/retry/cancel/quota/history endpoints.
• Modify ruoyi-generator/src/main/java/com/ruoyi/generator/service/front/AiGenerateServiceImpl.java: expose execution helpers or keep using the public sync methods from worker.
• Modify easycode-web/src/api/project.js: add task APIs.
• Modify easycode-web/src/views/GenerateView.vue: replace blocking generation calls with task start + polling.
• Modify SQL scripts: add task, quota, and ledger tables.
• Add focused tests in ruoyi-generator/src/test/java/com/ruoyi/generator/service/front.

Task 1: Task Status and Retry Policy

Files:

• Create: ruoyi-generator/src/main/java/com/ruoyi/generator/service/front/AiTaskRetryPolicy.java

• Test: ruoyi-generator/src/test/java/com/ruoyi/generator/service/front/AiTaskRetryPolicyTest.java

• Step 1: Write failing tests

Test retryable messages: timeout, 429, 5xx, and DeepSeek unavailable retry. Test validation/permission/quota messages do not retry. Test backoff sequence returns 30 seconds, 2 minutes, 5 minutes.

• Step 2: Run test to verify it fails

Run: mvn -pl ruoyi-generator -Dtest=AiTaskRetryPolicyTest test Expected: compile failure because AiTaskRetryPolicy does not exist.

• Step 3: Implement minimal retry policy

Create constants for max attempts and retry delays. Add boolean canRetry(String errorMessage, int attempts, int maxAttempts) and Date nextRetryTime(int attempts, Date now).

• Step 4: Run test to verify it passes

Run: mvn -pl ruoyi-generator -Dtest=AiTaskRetryPolicyTest test Expected: PASS.

Task 2: Cost and Quota Services

Files:

• Create: ruoyi-generator/src/main/java/com/ruoyi/generator/service/front/AiCostCalculator.java

• Create: ruoyi-generator/src/main/java/com/ruoyi/generator/service/front/AiQuotaService.java

• Create: ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/AiQuotaBucket.java

• Create: ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/AiUsageLedger.java

• Test: ruoyi-generator/src/test/java/com/ruoyi/generator/service/front/AiCostCalculatorTest.java

• Test: ruoyi-generator/src/test/java/com/ruoyi/generator/service/front/AiQuotaServiceTest.java

• Step 1: Write failing tests

Test default quota allows a first task, blocks when daily count reaches 20, blocks when monthly cost reaches 5000 cents, reserves one running task, and releases running count on finish.

• Step 2: Run tests to verify they fail

Run: mvn -pl ruoyi-generator -Dtest=AiCostCalculatorTest,AiQuotaServiceTest test Expected: compile failure for missing services/domain types.

• Step 3: Implement minimal services

Use mapper methods for load/create/update quota rows. Cost calculator returns 0 when tokens are missing and uses configurable defaults for DeepSeek estimates.

• Step 4: Run tests to verify they pass

Run: mvn -pl ruoyi-generator -Dtest=AiCostCalculatorTest,AiQuotaServiceTest test Expected: PASS.

Task 3: Task Persistence

Files:

• Create: AiGenerationTask domain and mapper XML/interface.

• Create: AiUsageLedgerMapper and AiQuotaBucketMapper.

• Modify: sql/front_workbench.sql

• Modify: sql/db.sql

• Step 1: Write mapper/service tests

Add tests for creating task rows, selecting task by user/project/task, selecting claimable tasks, updating lock/status, and inserting usage ledger.

• Step 2: Run tests to verify they fail

Run: mvn -pl ruoyi-generator -Dtest=AiGenerationTaskServiceImplTest test Expected: compile failure for missing domain/mapper/service methods.

• Step 3: Implement MyBatis domain and XML

Use status values QUEUED, RUNNING, RETRY_WAITING, SUCCEEDED, FAILED, CANCELED. Add indexes for (status, next_retry_time), (user_id, project_id), and generation_id.

• Step 4: Run tests to verify they pass

Run: mvn -pl ruoyi-generator -Dtest=AiGenerationTaskServiceImplTest test Expected: PASS.

Task 4: Task Service and Worker

Files:

• Create: IAiGenerationTaskService

• Create: AiGenerationTaskServiceImpl

• Create: AiGenerationTaskWorker

• Modify: FrontProjectController

• Test: AiGenerationTaskServiceImplTest

• Step 1: Write failing service tests

Test task creation validates project ownership, reserves quota, creates a front_project_generation row, creates a queued task, returns status DTO, and deduplicates a still-running same request hash.

• Step 2: Run test to verify it fails

Run: mvn -pl ruoyi-generator -Dtest=AiGenerationTaskServiceImplTest test Expected: compile failure or assertion failure before implementation.

• Step 3: Implement task creation and status queries

Generate request hash from generateType + normalized request JSON. Store request payload as JSON. Return taskId, status, currentStep, progress, generationId.

• Step 4: Write failing worker tests

Test worker executes app blueprint, database, and business blueprint tasks by delegating to existing sync service methods, marks success, records elapsed time, inserts ledger, and schedules retry for retryable failures.

• Step 5: Implement worker

Claim tasks using locked_by and locked_until, run outside the claim transaction, then update status. Keep max attempts at 3.

• Step 6: Run tests to verify they pass

Run: mvn -pl ruoyi-generator -Dtest=AiGenerationTaskServiceImplTest,AiGenerationTaskWorkerTest test Expected: PASS.

Task 5: REST API

Files:

• Modify: ruoyi-admin/src/main/java/com/ruoyi/web/controller/front/FrontProjectController.java

• Test: service tests remain the main safety net.

• Step 1: Add controller endpoints

Add POST /front/project/{projectId}/ai-tasks, GET /front/project/{projectId}/ai-tasks/{taskId}, POST /front/project/{projectId}/ai-tasks/{taskId}/retry, POST /front/project/{projectId}/ai-tasks/{taskId}/cancel, GET /front/project/{projectId}/generations, and GET /front/project/ai-quota.

• Step 2: Run compile tests

Run: mvn -pl ruoyi-admin -DskipTests compile Expected: SUCCESS.

Task 6: Frontend Polling Experience

Files:

• Modify: easycode-web/src/api/project.js

• Modify: easycode-web/src/views/GenerateView.vue

• Step 1: Add task API helpers

Add createAiTask, getAiTask, retryAiTask, cancelAiTask, getAiQuota, and listGenerations.

• Step 2: Update generation handlers

Replace direct calls to generateAppBlueprint, generateDatabase, and generateBusinessBlueprint with createAiTask plus polling. Keep the old direct API helpers for compatibility.

• Step 3: Show task state

Display status, progress, error message, retry button, and quota summary in the existing generate page.

• Step 4: Run frontend tests/build

Run direct .mjs tests with Node 20 and run Vite build. Expected: tests and build pass.

Task 7: Final Verification

Files:

• No new files.

• Step 1: Run backend tests

Run: mvn test Expected: SUCCESS.

• Step 2: Run frontend tests/build

Run easycode-web direct .mjs tests and Vite build. Expected: SUCCESS.

• Step 3: Inspect git diff

Run: git diff --stat and git status --short. Expected: only intended AI task center files changed.