docs: 完善 CLAUDE.md，添加项目架构和开发指引

2026-06-18 22:31:58 +08:00
parent bad08a1be2
commit 46f1bbf0f1
1 changed files with 73 additions and 1 deletions
@@ -1 +1,73 @@
-在 ./PLAN.md 中规划
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+PR-Helper is a self-hosted web service that auto-generates PR descriptions from Git history and performs AI-powered code review. Designed for internal/local use only (no auth).
+
+## Tech Stack
+
+- **Backend**: Go + Gin + SQLite (go-sqlite3) + go-git + chromedp (PDF generation)
+- **Frontend**: Go html/template + HTMX + D3.js + diff2html + Tailwind CSS
+- **LLM**: OpenAI-compatible API (SSE streaming)
+- **Deploy**: Docker (includes Chromium for PDF)
+
+## Build & Run
+
+```bash
+# Build (CGO required for SQLite)
+CGO_ENABLED=1 go build -o pr-helper .
+
+# Run
+./pr-helper
+# Server listens on :8080
+
+# Docker
+docker compose up --build
+```
+
+## Architecture
+
+```
+handlers/   → HTTP handlers (pages + JSON API + SSE endpoints)
+services/   → Business logic (git ops, LLM calls, PDF gen, cache management)
+models/     → Data models (repository, settings, analysis)
+database/   → SQLite init and migrations
+config/     → Configuration loading
+templates/  → Go HTML templates (layouts/, pages/, partials/, reports/)
+static/     → CSS (Tailwind output), JS (graph, diff-viewer, sse), vendor libs
+```
+
+**Data flow**: Browser ↔ Gin handlers → services (git/llm/pdf) → SQLite + filesystem (`data/`)
+
+**Key service layer responsibilities**:
+- `services/git.go` — clone, diff, graph data extraction via go-git
+- `services/llm.go` — OpenAI-compatible API calls with SSE streaming
+- `services/generate.go` — PR description generation (commits + diff → LLM → structured output)
+- `services/review.go` — AI code review (per-file analysis + summary, Top-N strategy for large diffs)
+- `services/pdf.go` — chromedp HTML→PDF conversion
+- `services/cache.go` — repository cache lifecycle (clone, expiry cleanup)
+
+## Key Patterns
+
+- **SSE streaming**: Clone progress, PR generation, and AI review all use Server-Sent Events. Handlers write `event:` / `data:` lines; frontend consumes via `static/js/sse.js`.
+- **Large diff handling**: Diffs are split per-file, sorted by change size, truncated to Top-N (configurable, default 20). Each file analyzed independently by LLM, then a summary prompt aggregates results.
+- **Review notes**: Three-level scoping — `overall`, `file`, `suggestion` — stored in `review_notes` table. AI output is read-only; users append notes separately.
+- **Diff rendering**: diff2html in Split view by default. AI review suggestions are inline-embedded next to code lines via `line` + `side` fields from SSE.
+
+## Frontend Libraries (vendored in static/lib/)
+
+- HTMX 2.x, D3.js 7.x, diff2html 3.x, highlight.js 11.x
+- Tailwind CSS compiled to `static/css/style.css`
+
+## Data Storage
+
+- SQLite DB at `data/pr-helper.db` — settings (KV), repositories, analyses, review_notes
+- Cloned repos cached at `data/repos/` with configurable expiry (default 7 days)
+
+## Development Notes
+
+- Refer to `PLAN.md` for full specification including API routes, SSE event formats, SQL schema, and prompt templates.
+- No authentication — do not expose to public internet.
+- All LLM prompts are in PLAN.md §8; model/endpoint/key are configurable via the settings page.