269 lines
11 KiB
Markdown
269 lines
11 KiB
Markdown
# 项目代码解读设计方案
|
||
|
||
## 背景
|
||
|
||
当前 `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。
|
||
- 不分析服务器任意目录。
|
||
- 不把代码解读做成独立源码商城功能。
|
||
- 不在第一版实现流式输出。
|
||
- 不在第一版实现多人协作编辑。
|
||
- 不在第一版新增代码解读专用持久化表，除非实现中发现现有历史表无法满足基本历史和继续生成。
|