wonder
275e5cc886
- 01-architecture.md: 架构概览 - 02-backend-services.md: 后端服务层 - 03-frontend-interaction.md: 前端交互设计 - 04-database-design.md: 数据库设计 - 05-api-reference.md: API 接口文档 - 06-sse-streaming.md: SSE 流式传输 - 07-llm-integration.md: LLM 集成 - 08-deployment.md: 部署运维 - 09-development-guide.md: 开发指南 - 10-troubleshooting.md: 故障排查
164 lines
4.7 KiB
Markdown
164 lines
4.7 KiB
Markdown
# 架构概览
|
||
|
||
## 项目简介
|
||
|
||
PR-Helper 是一个自托管的 Web 服务，用于从 Git 历史自动生成 PR 描述并执行 AI 代码审查。专为内部/本地使用设计（无认证）。
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| 后端 | Go + Gin + MySQL + go-git |
|
||
| 前端 | Go html/template + HTMX + D3.js + diff2html + Tailwind CSS |
|
||
| LLM | OpenAI 兼容 API（SSE 流式传输） |
|
||
| 部署 | Docker |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
PR-Helper/
|
||
├── main.go # 应用入口
|
||
├── config/ # 配置加载
|
||
│ └── config.go
|
||
├── database/ # 数据库初始化和迁移
|
||
│ └── db.go
|
||
├── handlers/ # HTTP 处理器（页面 + JSON API + SSE）
|
||
│ ├── auth.go # 认证处理
|
||
│ ├── generate.go # PR 生成 SSE 端点
|
||
│ ├── pages.go # 页面渲染
|
||
│ ├── repos.go # 仓库管理 API
|
||
│ ├── review.go # 代码审查 SSE 端点
|
||
│ ├── settings.go # 设置 API
|
||
│ └── middleware.go # 中间件
|
||
├── models/ # 数据模型
|
||
│ ├── repository.go # 仓库模型
|
||
│ ├── analysis.go # 分析结果模型
|
||
│ └── settings.go # 默认设置
|
||
├── services/ # 业务逻辑
|
||
│ ├── git.go # Git 操作（克隆、差异、图形数据）
|
||
│ ├── llm.go # LLM API 调用（SSE 流式）
|
||
│ ├── generate.go # PR 描述生成
|
||
│ ├── review.go # AI 代码审查
|
||
│ ├── cache.go # 仓库缓存管理
|
||
│ └── notes.go # 审查笔记
|
||
├── templates/ # Go HTML 模板
|
||
│ ├── layouts/ # 布局模板
|
||
│ ├── pages/ # 页面模板
|
||
│ └── partials/ # 局部模板
|
||
├── static/ # 静态资源
|
||
│ ├── css/ # Tailwind 输出
|
||
│ ├── js/ # 自定义 JS
|
||
│ └── lib/ # 第三方库
|
||
└── data/ # 数据存储
|
||
└── repos/ # 克隆的仓库缓存
|
||
```
|
||
|
||
## 数据流
|
||
|
||
```
|
||
浏览器 ↔ Gin 处理器 → 服务层（git/llm）→ MySQL + 文件系统（data/）
|
||
```
|
||
|
||
### 请求流程
|
||
|
||
1. **浏览器** 发起 HTTP 请求（HTMX 或 fetch）
|
||
2. **Gin 路由** 匹配处理器函数
|
||
3. **中间件** 验证会话和用户认证
|
||
4. **处理器** 解析请求参数
|
||
5. **服务层** 执行业务逻辑
|
||
6. **数据库/文件系统** 持久化数据
|
||
7. **SSE 流** 返回实时更新（可选）
|
||
|
||
## 核心模块
|
||
|
||
### 配置模块 (config/)
|
||
|
||
- 从 `.env` 文件加载环境变量
|
||
- 提供默认值
|
||
- 生成随机会话密钥（如未配置）
|
||
|
||
### 数据库模块 (database/)
|
||
|
||
- MySQL 连接管理
|
||
- 自动迁移（CREATE TABLE IF NOT EXISTS）
|
||
- 增量迁移（ALTER TABLE，忽略重复列错误）
|
||
- 默认设置初始化
|
||
|
||
### 处理器模块 (handlers/)
|
||
|
||
- **页面处理器**: 渲染 HTML 模板
|
||
- **仓库处理器**: 克隆、删除、拉取、获取图形/差异
|
||
- **生成处理器**: PR 描述生成（SSE 流式）
|
||
- **审查处理器**: AI 代码审查（SSE 流式）
|
||
- **设置处理器**: 读取/更新用户设置
|
||
|
||
### 服务模块 (services/)
|
||
|
||
- **git.go**: 使用 go-git 库执行 Git 操作
|
||
- **llm.go**: OpenAI 兼容 API 调用，支持流式响应
|
||
- **generate.go**: 从提交历史和差异生成 PR 描述
|
||
- **review.go**: Top-N 策略的 AI 代码审查
|
||
- **cache.go**: 仓库缓存生命周期管理
|
||
|
||
### 前端模块 (static/js/)
|
||
|
||
- **sse.js**: SSE 客户端，支持 POST 请求
|
||
- **graph.js**: D3.js Git 图形可视化
|
||
- **diff-viewer.js**: diff2html 差异查看器
|
||
- **review-inline.js**: 内联 AI 建议
|
||
- **markdown.js**: Markdown 渲染
|
||
- **note-editor.js**: 审查笔记编辑器
|
||
|
||
## 关键设计决策
|
||
|
||
### 1. SSE 流式传输
|
||
|
||
选择 SSE 而非 WebSocket 的原因：
|
||
- 单向服务器到客户端通信足够
|
||
- HTTP 兼容性更好
|
||
- 实现更简单
|
||
- 自动重连
|
||
|
||
### 2. Top-N 策略
|
||
|
||
大型差异处理：
|
||
- 按变更行数排序文件
|
||
- 只分析前 N 个文件（默认 20）
|
||
- 每个文件独立分析
|
||
- 最后生成汇总
|
||
|
||
### 3. 三级审查笔记
|
||
|
||
- `overall`: 整体审查笔记
|
||
- `file`: 文件级别笔记
|
||
- `suggestion`: 建议级别笔记
|
||
|
||
### 4. 会话认证
|
||
|
||
- 基于 Cookie 的会话
|
||
- 7 天过期
|
||
- HttpOnly 标记
|
||
- 随机会话密钥
|
||
|
||
## 扩展性考虑
|
||
|
||
### 水平扩展
|
||
|
||
- 无状态设计（会话存储在 Cookie）
|
||
- 数据库可外部化
|
||
- 文件存储可替换为对象存储
|
||
|
||
### LLM 集成
|
||
|
||
- 支持任何 OpenAI 兼容 API
|
||
- 每用户独立配置
|
||
- 可扩展为多模型支持
|
||
|
||
## 安全考虑
|
||
|
||
- 仅限内部使用（无认证）
|
||
- 不暴露到公网
|
||
- SQL 参数化查询
|
||
- 会话 HttpOnly
|
||
- 凭证不明文存储在 JSON 响应中
|