AIEC_Skills/codebase_architecture_analyzer_v1/reference/report-generation.md

# Phase 5: 报告生成指南

**执行时间**：约 30 秒

**目标**：汇总所有分析结果，生成完整的架构分析报告

---

## 生成步骤

### 步骤 1: 收集所有分析结果

从前 4 个 Phase 收集以下信息：

1. **Phase 1 - 快速扫描**
   - 项目类型
   - 主要编程语言
   - 核心框架
   - 子系统列表
   - 代码规模

2. **Phase 2 - 系统架构**
   - 系统架构 Mermaid 图
   - 子系统清单（名称、路径、技术栈、入口文件）
   - 通信关系列表

3. **Phase 3 - 核心流程**
   - 工作流 Mermaid 图（stateDiagram-v2 / flowchart）
   - 执行单元清单（Agent / 服务 / 函数）
   - 关键决策点

4. **Phase 4 - 数据流**
   - 序列图 Mermaid
   - 数据模型清单
   - 数据转换链路

### 步骤 2: 使用模板生成报告

使用 `assets/report.md` 模板，将收集的信息填充到相应章节。

### 步骤 3: 添加快速上手指南

从项目文件中提取以下信息：

1. **环境要求**
   - 从 README.md 或 pyproject.toml 提取
   - Python/Node.js 版本要求
   - 系统依赖（Docker、Redis 等）

2. **安装步骤**
   - 依赖安装命令
   - 环境变量配置
   - 数据库初始化

3. **启动命令**
   - 开发环境启动命令
   - 生产环境部署命令
   - 测试运行命令

4. **核心入口文件**
   - 主入口文件路径
   - 配置文件路径
   - 关键模块路径

### 步骤 4: 生成代码位置索引

汇总所有关键文件的位置：

```
代码位置索引:
├─ 入口文件
│  ├─ 后端入口: backend/app/main.py:1
│  └─ 前端入口: frontend/src/main.tsx:1
├─ 核心模块
│  ├─ Agent 编排: agents/graph.py:23
│  ├─ 研究 Agent: agents/nodes.py:45
│  └─ 写作 Agent: agents/nodes.py:78
├─ API 端点
│  ├─ 研究 API: backend/app/routes.py:42
│  └─ WebSocket: backend/app/routes.py:58
└─ 数据模型
   ├─ ResearchTask: models/task.py:8
   └─ Report: models/report.py:22
```

### 步骤 5: 保存报告

将生成的报告保存到项目根目录：

- **保存路径**: `PROJECT_ARCHITECTURE.md`

---

## 报告结构模板

```markdown
# [项目名] 架构分析报告

> 生成时间: [YYYY-MM-DD HH:MM:SS]
> 分析工具: Claude Code - Codebase Architecture Analyzer

---

## 一、项目概览

**项目类型**: [自动推断]
**主要语言**: [Python 3.11]
**核心框架**: [FastAPI + LangGraph]
**代码规模**: [156 个 Python 文件, 89 个 TypeScript 文件]

**子系统**:
- frontend/ (React + TypeScript)
- backend/ (FastAPI + Python)
- agents/ (LangGraph)

---

## 二、系统架构

### 2.1 架构图

```mermaid
[Phase 2 生成的 Mermaid 图]
```

### 2.2 子系统详情

[Phase 2 生成的子系统清单]

### 2.3 通信机制

[Phase 2 生成的通信关系列表]

---

## 三、核心业务流程

### 3.1 流程图

```mermaid
[Phase 3 生成的 Mermaid 图]
```

### 3.2 执行单元清单

[Phase 3 生成的 Agent/服务/函数清单]

### 3.3 关键决策点

[Phase 3 识别的条件分支和路由规则]

---

## 四、数据流分析

### 4.1 序列图

```mermaid
[Phase 4 生成的 Mermaid 序列图]
```

### 4.2 数据模型清单

[Phase 4 生成的数据模型列表]

### 4.3 数据转换链路

[Phase 4 追踪的数据流转路径]

---

## 五、快速上手指南

### 5.1 环境要求

- Python 3.11+
- Node.js 18+
- Docker (可选)

### 5.2 安装步骤

```bash
# 1. 安装后端依赖
pip install -r backend/requirements.txt

# 2. 安装前端依赖
cd frontend && npm install

# 3. 配置环境变量
cp .env.example .env
```

### 5.3 启动命令

```bash
# 启动后端
cd backend && uvicorn app.main:app --reload

# 启动前端
cd frontend && npm start
```

### 5.4 核心入口文件

- 后端入口: `backend/app/main.py`
- 前端入口: `frontend/src/main.tsx`
- Agent 编排: `agents/graph.py`

---

## 六、代码位置索引

[Phase 2-4 汇总的所有关键文件位置]

---

## 附录：分析方法说明

本报告由 Claude Code 的 `codebase-architecture-analyzer` Skill 自动生成。

分析方法:
- Phase 1: 快速扫描（识别技术栈）
- Phase 2: 系统架构分析（Explore sub-agent）
- Phase 3: 核心流程提取（智能模式识别）
- Phase 4: 数据流追踪（类型追踪）
- Phase 5: 报告生成（本文档）
```

---

## 输出示例

执行完成后，向用户显示：

```
✓ 分析完成！

报告已保存: PROJECT_ARCHITECTURE.md

核心发现:
- 采用 LangGraph 编排 Multi-Agent 工作流
- 支持条件路由和循环优化
- 数据流: 查询 → 搜索 → 写作 → 审核 → 报告

快速上手:
1. 安装依赖: pip install -r requirements.txt
2. 配置环境: cp .env.example .env
3. 启动后端: uvicorn app.main:app --reload
4. 启动前端: cd frontend && npm start
```

---

## 注意事项

1. **Mermaid 图表检查**：确保所有 Mermaid 代码块语法正确
2. **代码位置准确性**：所有文件路径和行号必须准确
3. **快速上手可用性**：安装步骤必须可执行，不能遗漏关键步骤
4. **避免敏感信息**：不要在报告中包含 `.env` 文件内容或 API 密钥