From 453f22d920f54658ddfdfc3a6a751d8b12688bdb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E9=B9=8F?= Date: Tue, 7 Jul 2026 22:28:31 +0800 Subject: [PATCH] docs: design core code analysis selection --- ...-07-code-analysis-core-selection-design.md | 139 ++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 RuoYi-Vue/docs/superpowers/specs/2026-07-07-code-analysis-core-selection-design.md diff --git a/RuoYi-Vue/docs/superpowers/specs/2026-07-07-code-analysis-core-selection-design.md b/RuoYi-Vue/docs/superpowers/specs/2026-07-07-code-analysis-core-selection-design.md new file mode 100644 index 0000000..fa6bb52 --- /dev/null +++ b/RuoYi-Vue/docs/superpowers/specs/2026-07-07-code-analysis-core-selection-design.md @@ -0,0 +1,139 @@ +# Code Analysis Core Source Selection Design + +## Background + +The current code-analysis flow collects preview source from `backend`, `frontend`, `admin_frontend`, and `sql`, reads every allowed source-like file, and then truncates the assembled prompt context at 120KB. This works for small projects, but it can send too much low-value code to the AI and leave less room for the files that explain the real architecture and business flow. + +The requested change is to send fewer files while keeping the most useful Java, Vue, SQL, and mapper/config context. The AI should receive a curated source snapshot, not a broad dump of every allowed file. + +## Goal + +Make `ProjectCodeAnalysisService` intelligently select a compact set of core files for AI code interpretation. The default expanded source budget is 60KB, with clear metadata and warnings for files that were skipped, summarized, or truncated. + +## Non-Goals + +- Do not add a second AI call to ask the model which files to choose. +- Do not require the user to manually pick files. +- Do not scan arbitrary server directories or uploaded ZIP files. +- Do not remove existing ownership checks or preview-read safeguards. +- Do not change the report page layout in this feature. + +## Selection Strategy + +The backend keeps using the existing preview source tree as input: + +- `frontProjectPreviewService.getStructure(userId, projectId, "backend")` +- `frontProjectPreviewService.getStructure(userId, projectId, "frontend")` +- `frontProjectPreviewService.getStructure(userId, projectId, "admin_frontend")` +- `frontProjectPreviewService.getStructure(userId, projectId, "sql")` + +Instead of sending every allowed file until the prompt is full, the service will score each candidate file and assemble the prompt from highest-value files first. + +High-priority files: + +- Java controllers, especially paths or class names containing `Controller` +- Java services and service implementations +- Java mappers and mapper XML files +- Java entity/domain/model/DTO classes +- SQL files containing table definitions +- Vue route files, API wrappers, and core page components +- Project dependency/config files such as `pom.xml`, `package.json`, `application.yml`, and router files + +Low-priority or skipped files: + +- Build artifacts and dependency folders: `target`, `dist`, `node_modules`, `.git`, `.idea` +- Static assets, generated bundles, minified files, maps, images, fonts, archives, binaries +- Tests, screenshots, audit artifacts, demo-only files, mockups, and style-only files unless no better frontend files exist +- Very large files after their useful header and structural content have been captured + +## Budget Rules + +The default expanded prompt source budget is 60KB. This is the total size of actual source content sent to the AI, not counting a small file manifest. + +Recommended limits: + +- Total expanded source budget: `60 * 1024` characters +- Per-file expanded budget for Java/Vue/XML/SQL/config: about `20 * 1024` characters +- Keep a compact manifest of selected and skipped files outside the expanded source body +- If the budget is exhausted, include remaining important file names in metadata, but do not expand their contents + +The AI prompt should explicitly say that the source snapshot is curated and compact. It must not infer details from files that were not expanded. + +## Data Shape + +Reuse `CodeAnalysisSourceSummary` and its existing file/skipped-file lists where possible. + +Expected summary behavior: + +- `includedFiles` contains only selected core files with content or compact extracted content +- `skippedFiles` includes non-core files and budget-excluded files with a reason +- `warnings` describes budget limits and any important omitted areas +- `promptContext` contains the curated file manifest and expanded core source blocks +- `analyzedFileCount` reflects selected files, while `fileCount` still reflects all scanned candidate files + +Example prompt context shape: + +```text +Selected core source files: +- backend / src/main/java/.../UserController.java (controller, expanded) +- backend / src/main/java/.../UserServiceImpl.java (service, expanded) +- backend / src/main/resources/mapper/.../UserMapper.xml (mapper, expanded) +- sql / user.sql (table schema, expanded) +- frontend / src/views/user/index.vue (vue page, expanded) + +Skipped or summarized files: +- frontend / src/styles/index.scss (style-only) +- frontend / src/utils/request.js (lower priority after budget) + +## backend / src/main/java/.../UserController.java +... +``` + +## Scoring Details + +The score should be deterministic and testable. A simple weighted rule set is enough for this feature. + +Suggested scoring: + +- SQL schema files: very high +- `*Controller.java`: very high +- `*Service.java` and `*ServiceImpl.java`: high +- `*Mapper.java` and `*Mapper.xml`: high +- `domain`, `entity`, `model`, `dto`: medium-high +- Vue views/pages and router/API files: medium-high +- `application.yml`, `pom.xml`, `package.json`: medium +- Utility, style, test, demo, and docs files: low or skipped + +Tie-breakers: + +- Prefer files with shorter, clearer business paths over generic utility paths +- Keep a balanced mix of backend, frontend, and SQL rather than letting one layer consume all 60KB +- Preserve current stable ordering where scores are equal to avoid noisy test changes + +## Prompt Requirements + +Update the code-analysis prompt wording to make the source selection explicit: + +- "The following source snapshot is a curated subset of core files." +- "Use only the expanded source and listed metadata as evidence." +- "If a detail is not present in the selected source, say it cannot be confirmed." +- "When explaining architecture, cite real class, method, component, table, or field names from the selected files." + +## Testing Plan + +Backend tests should cover: + +- Core files are selected before low-value files when budget is limited +- Controller, Service, Mapper/XML, Vue page/API/router, and SQL files appear in the prompt when present +- Style-only, test, demo, dependency, and build artifact files are skipped or deprioritized +- Total expanded source context stays near the 60KB budget +- A large high-priority file is truncated per-file instead of consuming the whole prompt +- Budget-excluded but relevant files are recorded in skipped files or warnings + +## Acceptance Criteria + +- Code analysis sends a compact curated source snapshot by default. +- The expanded source content sent to AI is about 60KB, not the previous 120KB broad dump. +- Java, Vue, SQL, and mapper/config files receive priority based on their architectural value. +- The prompt includes enough metadata for the AI to know which important files were selected or omitted. +- Existing code-analysis generation, streaming, history, and continuation flows keep working.