wangpeng/yidaima

Fork 0

Files

王鹏 c28a2a04f7 docs: add project code analysis design

2026-07-07 16:08:10 +08:00

11 KiB

Raw Blame History

项目代码解读设计方案

背景

当前 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。

如果项目尚未生成源码预览，代码解读页提示用户先生成项目预览，并提供跳转到源码预览或工作台的入口。

用户体验

新增路由：

/project/:projectId/code-analysis

推荐入口：

ProjectListView.vue 的项目操作区增加“代码解读”。
PreviewView.vue 的源码预览工具栏增加“代码解读”。
GenerateView.vue 的生成结果区增加“代码解读”。

页面布局参考截图中的代码解读结果页：

顶部显示项目名、源码状态、文件数量、估算字符数和最近生成状态。
左侧为章节导航：项目概述与技术栈、系统架构与核心模块、核心业务流程、数据库设计、答辩准备。
右侧为报告内容区，默认显示最新成功报告；没有报告时显示开始分析空态。
顶部操作包含：开始 AI 解读、继续生成、刷新状态、历史。
报告区支持预览和编辑两个标签页，允许用户继续修改报告内容。
支持 Markdown 和 Word 兼容文档导出，复用 PaperDraftView.vue 的下载方式。

历史抽屉或弹窗展示 generate_type = code_analysis 的记录：

生成时间、状态、耗时、token 估算、错误信息。
点击成功记录可恢复该报告。
失败记录可重新发起生成。

报告结构

AI 输出统一为 Markdown，返回对象建议为：

{
  "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": []
}

报告必须包含这五章：

项目概述与技术栈
系统架构与核心模块
核心业务流程
数据库设计
答辩准备

继续生成时沿用同一结构。后端把上一版报告、缺失章节、用户补充要求和当前源码摘要传给 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 任务集成

新增生成类型：

code_analysis

需要修改：

AiGenerationTaskServiceImpl.validateRequest() 允许 code_analysis。
AiGenerationTaskWorker.execute() 分流到代码解读生成方法。
AiGenerationTaskWorker.initialProgress() 和 initialCurrentStep() 增加代码解读状态。
IAiGenerateService 增加 generateCodeAnalysis(Long userId, Long projectId, GenerateCodeAnalysisRequest request)。
AiGenerateServiceImpl 增加代码解读 prompt 构建和响应解析。

请求 DTO 建议：

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 表。

后端接口

新增或扩展接口：

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

11 KiB Raw Blame History Unescape Escape