# 项目代码解读设计方案

## 背景

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