From c28a2a04f7058ca77aa72e17271a82c4d2eb247b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E9=B9=8F?= <wangpengv@yonyou.com>
Date: Tue, 7 Jul 2026 16:08:10 +0800
Subject: [PATCH] docs: add project code analysis design

---
 ...2026-07-07-project-code-analysis-design.md | 268 ++++++++++++++++++
 1 file changed, 268 insertions(+)
 create mode 100644 RuoYi-Vue/docs/superpowers/specs/2026-07-07-project-code-analysis-design.md

diff --git a/RuoYi-Vue/docs/superpowers/specs/2026-07-07-project-code-analysis-design.md b/RuoYi-Vue/docs/superpowers/specs/2026-07-07-project-code-analysis-design.md
new file mode 100644
index 0000000..bdca98d
--- /dev/null
+++ b/RuoYi-Vue/docs/superpowers/specs/2026-07-07-project-code-analysis-design.md
@@ -0,0 +1,268 @@
+# 项目代码解读设计方案
+
+## 背景
+
+当前 `easycode-web` 已经有完整的项目前台工作台：
+
+- 项目生成、源码预览和下载由 `FrontProjectController`、`IFrontProjectPreviewService`、`PreviewView.vue` 串起来。
+- AI 异步任务由 `front_ai_generation_task`、`AiGenerationTaskServiceImpl`、`AiGenerationTaskWorker` 负责。
+- 生成历史由 `front_project_generation` 保存，前端已有 `listGenerations(projectId)` 接口。
+- 论文初稿页已经提供报告预览、编辑和 Markdown/Word 导出体验，可作为代码解读报告页的交互参考。
+
+本次目标是在项目内部增加“代码解读”功能。用户不上传 ZIP，系统只分析当前用户拥有的、已经生成源码预览的项目代码，调用现有 AI 服务生成报告，并支持历史查看和继续生成。
+
+## 范围
+
+功能入口只放在 `easycode-web` 前台项目工作台，不在 `ruoyi-ui` 后台管理端新增菜单。
+
+首期只分析当前项目的生成源码预览，包括后端、前台前端、后台前端和 SQL 模板输出。系统不读取用户手填的服务器路径，不扫描当前 RuoYi-Vue 开发仓库，也不支持上传外部 ZIP。
+
+如果项目尚未生成源码预览，代码解读页提示用户先生成项目预览，并提供跳转到源码预览或工作台的入口。
+
+## 用户体验
+
+新增路由：
+
+```text
+/project/:projectId/code-analysis
+```
+
+推荐入口：
+
+- `ProjectListView.vue` 的项目操作区增加“代码解读”。
+- `PreviewView.vue` 的源码预览工具栏增加“代码解读”。
+- `GenerateView.vue` 的生成结果区增加“代码解读”。
+
+页面布局参考截图中的代码解读结果页：
+
+- 顶部显示项目名、源码状态、文件数量、估算字符数和最近生成状态。
+- 左侧为章节导航：项目概述与技术栈、系统架构与核心模块、核心业务流程、数据库设计、答辩准备。
+- 右侧为报告内容区，默认显示最新成功报告；没有报告时显示开始分析空态。
+- 顶部操作包含：开始 AI 解读、继续生成、刷新状态、历史。
+- 报告区支持预览和编辑两个标签页，允许用户继续修改报告内容。
+- 支持 Markdown 和 Word 兼容文档导出，复用 `PaperDraftView.vue` 的下载方式。
+
+历史抽屉或弹窗展示 `generate_type = code_analysis` 的记录：
+
+- 生成时间、状态、耗时、token 估算、错误信息。
+- 点击成功记录可恢复该报告。
+- 失败记录可重新发起生成。
+
+## 报告结构
+
+AI 输出统一为 Markdown，返回对象建议为：
+
+```json
+{
+  "title": "项目代码解读报告",
+  "markdown": "# 项目代码解读报告\n...",
+  "sections": [
+    { "key": "overview", "title": "项目概述与技术栈", "complete": true },
+    { "key": "architecture", "title": "系统架构与核心模块", "complete": true },
+    { "key": "business", "title": "核心业务流程", "complete": true },
+    { "key": "database", "title": "数据库设计", "complete": true },
+    { "key": "defense", "title": "答辩准备", "complete": true }
+  ],
+  "sourceSnapshot": {
+    "fileCount": 86,
+    "analyzedFileCount": 72,
+    "skippedFileCount": 14,
+    "charCount": 420000,
+    "estimatedTokens": 105000
+  },
+  "warnings": []
+}
+```
+
+报告必须包含这五章：
+
+1. 项目概述与技术栈
+2. 系统架构与核心模块
+3. 核心业务流程
+4. 数据库设计
+5. 答辩准备
+
+继续生成时沿用同一结构。后端把上一版报告、缺失章节、用户补充要求和当前源码摘要传给 AI，让 AI 只补齐或扩写缺失内容，避免重写整篇报告。
+
+## 源码采集
+
+新增后端服务建议命名为 `ProjectCodeAnalysisService`，负责从已有源码预览采集代码上下文。
+
+采集来源：
+
+- `frontProjectPreviewService.getStructure(userId, projectId, "backend")`
+- `frontProjectPreviewService.getStructure(userId, projectId, "frontend")`
+- `frontProjectPreviewService.getStructure(userId, projectId, "admin_frontend")`
+- `frontProjectPreviewService.getStructure(userId, projectId, "sql")`
+- 对树节点调用现有 `getFileContent` 能力读取文件内容。
+
+允许分析的文件：
+
+- 后端：`.java`、`.xml`、`.yml`、`.yaml`、`.properties`、`pom.xml`
+- 前端：`.vue`、`.js`、`.ts`、`.json`、`.scss`、`.css`、`package.json`
+- 数据库：`.sql`
+- 文档提示：`README.md`、`.md`
+
+跳过规则：
+
+- 跳过图片、字体、压缩包、二进制文件和构建产物。
+- 跳过 `node_modules`、`target`、`dist`、`.git`、`.idea`。
+- 单文件超过 100KB 时只保留文件头部、关键类名/函数名和摘要提示。
+- 总输入超过模型预算时按优先级裁剪：数据库 SQL、Controller、Service、Mapper、实体、前端路由和页面优先。
+
+源码快照输出包含：
+
+- 文件树摘要。
+- 关键文件清单。
+- 技术栈线索。
+- 数据库表和字段摘要。
+- 模块、Controller、Service、Mapper、页面之间的映射关系。
+- 被跳过文件及原因。
+
+## AI 任务集成
+
+新增生成类型：
+
+```text
+code_analysis
+```
+
+需要修改：
+
+- `AiGenerationTaskServiceImpl.validateRequest()` 允许 `code_analysis`。
+- `AiGenerationTaskWorker.execute()` 分流到代码解读生成方法。
+- `AiGenerationTaskWorker.initialProgress()` 和 `initialCurrentStep()` 增加代码解读状态。
+- `IAiGenerateService` 增加 `generateCodeAnalysis(Long userId, Long projectId, GenerateCodeAnalysisRequest request)`。
+- `AiGenerateServiceImpl` 增加代码解读 prompt 构建和响应解析。
+
+请求 DTO 建议：
+
+```java
+public class GenerateCodeAnalysisRequest {
+    private String mode; // fresh 或 continue
+    private Long previousGenerationId;
+    private String previousMarkdown;
+    private String extraRequirements;
+}
+```
+
+任务结果写入现有：
+
+- `front_ai_generation_task.result_payload`
+- `front_project_generation.response_payload`
+- `front_project_generation.generate_type = code_analysis`
+
+首期不新增代码解读专用表。历史记录直接从 `front_project_generation` 读取，按 `generate_type = code_analysis` 过滤。若后续需要保存用户编辑后的报告，再考虑新增 `front_project_code_analysis` 表。
+
+## 后端接口
+
+新增或扩展接口：
+
+```text
+GET  /front/project/{projectId}/code-analysis/source-summary
+GET  /front/project/{projectId}/code-analysis/history
+GET  /front/project/{projectId}/code-analysis/history/{generationId}
+POST /front/project/{projectId}/code-analysis/tasks
+POST /front/project/{projectId}/code-analysis/tasks/continue
+```
+
+首期前端调用上述代码解读语义化接口。后端接口内部构造 `generateType = code_analysis` 的 `AiGenerationTaskCreateRequest`，并复用现有 AI 任务服务创建、轮询、重试和记录历史。
+
+权限要求：
+
+- 所有接口先通过 `frontProjectService.getProject(userId, projectId)` 校验项目归属。
+- 读取历史时必须校验 `generation.projectId` 和 `generation.userId`。
+- 不允许前端传入服务器文件路径。
+
+## 前端改造
+
+新增文件：
+
+- `easycode-web/src/views/CodeAnalysisView.vue`
+- `easycode-web/src/views/codeAnalysisView.test.mjs`
+
+修改文件：
+
+- `easycode-web/src/router/index.js`：新增代码解读路由。
+- `easycode-web/src/api/project.js`：新增代码解读 API 包装。
+- `easycode-web/src/components/AppHeader.vue`：首期不新增全局入口，代码解读从具体项目进入。
+- `ProjectListView.vue`、`PreviewView.vue`、`GenerateView.vue`：增加项目内入口。
+
+`CodeAnalysisView.vue` 负责：
+
+- 加载项目详情、源码摘要、历史和最新报告。
+- 创建代码解读任务并轮询任务状态。
+- 继续生成时携带上一条成功报告或当前编辑内容。
+- 渲染 Markdown 预览、编辑区、章节导航、历史抽屉。
+- 导出 Markdown 和 Word 兼容文档。
+
+可复用：
+
+- `renderMarkdown()` 渲染报告。
+- `saveBlob()` 下载报告。
+- `AiTaskStatusPanel.vue` 的状态展示模式，必要时抽出公共任务轮询 helper。
+
+## Prompt 要求
+
+代码解读 prompt 必须明确：
+
+- 基于提供的代码上下文分析，不要编造未出现的模块。
+- 如果源码上下文不足，写明“不足以确认”，并列出需要人工核验的文件。
+- 输出 Markdown。
+- 必须覆盖五个固定章节。
+- 数据库设计优先来自 SQL 和实体字段，不要只凭项目名称推断。
+- 答辩准备要围绕当前项目真实技术栈、模块和业务流程。
+
+继续生成 prompt 额外要求：
+
+- 保留上一版报告已有内容。
+- 只补齐缺失章节、扩写过短章节或修复明显不一致处。
+- 输出完整合并后的 Markdown，而不是只输出增量片段。
+
+## 错误处理
+
+- 未生成源码预览：提示“请先生成源码预览后再进行代码解读”。
+- 源码为空或全部被过滤：提示用户重新生成项目或检查生成结果。
+- AI 任务失败：展示错误信息，允许重试。
+- 历史记录为空：展示开始分析空态。
+- 历史记录响应无法解析：显示原始 Markdown 或提示该记录不可预览。
+- 继续生成没有上一版报告：自动降级为开始 AI 解读。
+
+## 测试计划
+
+后端测试：
+
+- 源码采集服务能按文件类型筛选，并跳过二进制和构建产物。
+- 源码采集超过预算时按优先级裁剪。
+- `code_analysis` 能通过任务校验并进入 worker 分流。
+- 历史接口只返回当前用户当前项目的 `code_analysis` 记录。
+- 继续生成请求能带入上一版报告。
+
+前端测试：
+
+- 路由包含 `/project/:projectId/code-analysis` 且需要登录。
+- 代码解读页包含章节导航、历史、开始 AI 解读、继续生成。
+- 没有报告时显示空态和开始分析按钮。
+- 有成功历史时默认显示最新报告。
+- Markdown 和 Word 导出按钮在有报告后可用。
+- 项目列表和源码预览页包含代码解读入口。
+
+## 验收标准
+
+- 用户无需上传 ZIP，即可对当前项目生成源码解读报告。
+- 只有项目拥有者能读取源码摘要、发起解读和查看历史。
+- 项目未生成源码预览时不会调用 AI，页面给出明确跳转。
+- 成功报告包含固定五章，并能在页面内预览。
+- 历史中能看到多次代码解读记录，并能切换查看。
+- 继续生成能基于上一版报告补齐内容，结果保存为新的历史记录。
+- 失败任务可重试，页面能展示失败原因。
+- 不在 `ruoyi-ui` 后台新增菜单，不支持外部 ZIP 上传。
+
+## 非目标
+
+- 不上传 ZIP。
+- 不分析服务器任意目录。
+- 不把代码解读做成独立源码商城功能。
+- 不在第一版实现流式输出。
+- 不在第一版实现多人协作编辑。
+- 不在第一版新增代码解读专用持久化表，除非实现中发现现有历史表无法满足基本历史和继续生成。