yidaima/RuoYi-Vue/docs/superpowers/plans/2026-07-12-project-quality-run.md

# Project Quality Run 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:** Persist and execute four project quality checks, then require a matching passed Quality Run for certified download.

**Architecture:** Add a Run/Check ledger and a scheduled worker with conditional claims. The real executor uses an isolated source workspace, the existing MySQL preview initializer, bounded command execution, and the existing run-preview service for API smoke. Delivery readiness reads the latest run matching the current Generation Run and aggregate hash.

**Tech Stack:** Java 8, Spring, MyBatis, MySQL, JUnit 4, Mockito, Vue 3, Element Plus, Node test runner, Vite.

## Global Constraints

- Quality Run identity is server-derived from the current user, project, Generation Run and aggregate hash.
- Persist only sanitized summaries and bounded logs; never persist credentials, JDBC URLs or raw environment maps.
- Add schema to the upgrade script, `front_workbench.sql`, and `db.sql` in the same task.
- Do not freeze downloadable ZIP bytes in P1-L.
- Do not change model credential or TLS development configuration.

---

### Task 1: Quality Run schema and mapper

**Files:**
- Create: `sql/factory_project_quality_run.sql`
- Modify: `sql/front_workbench.sql`
- Modify: `sql/db.sql`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/quality/model/ProjectQualityRun.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/quality/model/ProjectQualityCheck.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/mapper/factory/ProjectQualityRunMapper.java`
- Create: `ruoyi-generator/src/main/resources/mapper/factory/ProjectQualityRunMapper.xml`
- Test: `ruoyi-generator/src/test/java/com/ruoyi/generator/factory/quality/ProjectQualityRunSchemaScriptTest.java`
- Test: `ruoyi-generator/src/test/java/com/ruoyi/generator/factory/quality/ProjectQualityRunMapperContractTest.java`

**Interfaces:**
- Produces mapper operations to insert a Run and four checks, query current/active runs, claim queued work, update checks, finish runs, and interrupt expired runs.

- [x] Write schema and mapper contract tests that require both tables in all three SQL files, immutable identity columns, unique check constraints, bounded claim queries and user/project-scoped reads.
- [x] Run the two tests and confirm they fail because files and mapper operations are absent.
- [x] Add models, SQL and mapper operations with conditional status transitions.
- [x] Parse all mapper XML and run the tests until green.

### Task 2: Run creation, query and worker state machine

**Files:**
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/quality/ProjectQualityRunService.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/quality/ProjectQualityRunWorker.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/quality/ProjectQualityExecution.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/quality/ProjectQualityExecutor.java`
- Test: `ruoyi-generator/src/test/java/com/ruoyi/generator/factory/quality/ProjectQualityRunServiceTest.java`
- Test: `ruoyi-generator/src/test/java/com/ruoyi/generator/factory/quality/ProjectQualityRunWorkerTest.java`

**Interfaces:**
- `ProjectQualityRunService.create(Long userId, Long projectId)` returns the existing active run or creates one Run plus four checks.
- `ProjectQualityRunService.list/getLatest` enforce project ownership.
- `ProjectQualityExecutor.execute(ProjectQualityRun run)` returns four ordered check executions.

- [x] Write failing tests for server-derived identity, active-run idempotency, ownership, fixed check order, all-pass completion, partial failure and interrupted lease release.
- [x] Run tests and confirm RED.
- [x] Implement transactional creation/query and the scheduled conditional-claim worker.
- [x] Run focused tests until green.

### Task 3: Real quality executor

**Files:**
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/quality/ProjectQualityWorkspace.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/quality/ProjectQualityCommandRunner.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/factory/quality/DefaultProjectQualityExecutor.java`
- Test: `ruoyi-generator/src/test/java/com/ruoyi/generator/factory/quality/ProjectQualityWorkspaceTest.java`
- Test: `ruoyi-generator/src/test/java/com/ruoyi/generator/factory/quality/ProjectQualityCommandRunnerTest.java`
- Test: `ruoyi-generator/src/test/java/com/ruoyi/generator/factory/quality/DefaultProjectQualityExecutorTest.java`

**Interfaces:**
- Workspace safely extracts the current source ZIP under `easycode.quality.workspace-root` and rejects traversal.
- Command runner returns exit code, duration, timeout flag and a sanitized bounded log.
- Executor runs `JAVA_TEST`, `FRONTEND_BUILD`, `SQL_IMPORT`, `API_SMOKE` in fixed order and always cleans database, preview and workspace resources.

- [x] Write failing tests for ZIP traversal, backend/frontend discovery, command timeout/log truncation, four-check ordering and cleanup on failure.
- [x] Run tests and confirm RED.
- [x] Implement the workspace, runner and executor using existing preview services.
- [x] Run focused tests until green.

### Task 4: Delivery readiness and HTTP API

**Files:**
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/ProjectDeliveryReadiness.java`
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/service/front/ProjectDeliveryReadinessServiceImpl.java`
- Modify: `ruoyi-admin/src/main/java/com/ruoyi/web/controller/front/FrontProjectController.java`
- Modify: `ruoyi-generator/src/test/java/com/ruoyi/generator/service/front/ProjectDeliveryReadinessServiceImplTest.java`
- Modify: `ruoyi-admin/src/test/java/com/ruoyi/web/controller/front/FrontProjectControllerRunPreviewTest.java`

**Interfaces:**
- Delivery readiness exposes `baselineReady` and latest sanitized Quality Run details.
- `qualityAccepted` requires a matching `PASSED` Quality Run; certified download continues to use the same server gate.
- Controller exposes create/list/latest endpoints using `SecurityUtils.getUserId()` only.

- [x] Write failing tests for no run, failed run, stale run, passed matching run, controller ownership and certified download gating.
- [x] Run tests and confirm RED.
- [x] Implement readiness integration and APIs.
- [x] Install the generator module and run admin tests until green.

### Task 5: EasyCode quality report

**Files:**
- Modify: `easycode-web/src/api/project.js`
- Modify: `easycode-web/src/components/ProjectDeliveryReadinessPanel.vue`
- Modify: `easycode-web/src/views/GenerateView.vue`
- Modify: `easycode-web/src/components/projectDeliveryReadinessPanel.test.mjs`

**Interfaces:**
- API exposes create/list/latest Quality Run calls.
- Panel emits `start-quality-run`, renders four checks, and disables duplicate starts while queued/running.
- Generate view polls the latest run and refreshes delivery readiness on terminal status.

- [x] Write failing source-contract tests for API methods, four check labels, start/retry action and terminal refresh.
- [x] Run tests and confirm RED.
- [x] Implement API, panel and polling integration.
- [x] Run EasyCode main-flow tests and production build until green.

### Task 6: Regression and roadmap

**Files:**
- Modify: `docs/superpowers/specs/2026-07-10-ai-software-factory-roadmap.md`
- Modify: `docs/superpowers/specs/2026-07-12-project-quality-run-design.md`
- Modify: `docs/superpowers/plans/2026-07-12-project-quality-run.md`

- [x] Run P1-H through P1-L focused backend tests and `ruoyi-admin` full tests.
- [x] Run EasyCode focused tests and `npm run build`.
- [x] Parse Mapper XML, inspect SQL consistency, check whitespace and verify `http://localhost:5174`.
- [x] Record P1-L completion, validation evidence and the remaining P1-M artifact-freezing boundary.

## Completion Record

- Completed on 2026-07-12.
- P1-H through P1-L focused backend suite: 50 tests passed.
- `ruoyi-admin` full suite: 43 tests passed.
- EasyCode main-flow suite: 73 tests passed; production build passed.
- Quality Run Mapper XML parsed successfully, SQL consistency tests passed, and `http://localhost:5174` returned HTTP 200.
- No external database migration was executed. Deployments must apply `sql/factory_project_quality_run.sql` or the synchronized aggregate schema.
- P1-M remains open: certified downloads still regenerate ZIP bytes at request time and do not yet serve an immutable, hashed artifact frozen from the passed Quality Run.