huangzhenpc
4bc7fa0e3f
包含 fork 自定义配置清单、构建测试命令、架构概览、编码规范和 skills 索引。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
86 lines
4.0 KiB
Markdown
86 lines
4.0 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Fork Identity
|
|
|
|
This is a **customized fork** of [Wei-Shaw/sub2api](https://github.com/Wei-Shaw/sub2api.git), branded as **StarFireAPI**. Upstream remote: `https://github.com/Wei-Shaw/sub2api.git`.
|
|
|
|
### Customizations to preserve on every upstream sync
|
|
|
|
| Category | Details |
|
|
|----------|---------|
|
|
| **Brand** | All user-facing `Sub2API` → `StarFireAPI` in `frontend/src/` (stores, i18n, views, components, router) |
|
|
| **Links** | GitHub links → `https://anthropic.edu.pl` in AppHeader, HomeView, i18n |
|
|
| **docker-compose** | Image: `starfireapi:latest`, port `6580:8080`, external Redis at `172.18.0.2:6379`, project name `xinghuoapi`, built-in Redis disabled |
|
|
| **Update module** | Disabled in `system_handler.go` (always returns no update), `app.ts` (forces `hasUpdate=false`), `VersionBadge.vue` (`isReleaseBuild=false`, removed GitHub release links) |
|
|
|
|
Full details: `skills/sync-upstream/SKILL.md`
|
|
|
|
## Build & Test Commands
|
|
|
|
```bash
|
|
# Full build (backend + frontend)
|
|
make build
|
|
|
|
# Backend only
|
|
cd backend && make build # Binary → bin/server
|
|
cd backend && make test # go test ./... + golangci-lint
|
|
cd backend && make test-unit # Unit tests only
|
|
cd backend && go test ./internal/service/... -run TestXxx # Single test
|
|
|
|
# Frontend only
|
|
cd frontend && pnpm install --frozen-lockfile
|
|
cd frontend && pnpm dev # Dev server
|
|
cd frontend && pnpm build # Type-check + production build
|
|
cd frontend && pnpm test:run # Vitest
|
|
cd frontend && pnpm lint:check # ESLint (no fix)
|
|
|
|
# Code generation (Ent ORM + Wire DI)
|
|
cd backend && make generate
|
|
```
|
|
|
|
## Architecture
|
|
|
|
**AI API Gateway**: receives requests with user API keys → authenticates → selects upstream account (sticky session / load-aware) → forwards to upstream AI service → records usage for billing.
|
|
|
|
### Backend (`backend/internal/`)
|
|
|
|
- **Entry**: `cmd/server/main.go` — supports setup mode, auto-setup (Docker), normal server
|
|
- **DI**: Google Wire (`cmd/server/wire.go`)
|
|
- **Layers**: handler → service → repository (enforced by `depguard` — service must not import repository)
|
|
- **Key services**: `GatewayService` (request forwarding, account selection, failover), `OpenAIGatewayService`, `GeminiMessagesCompatService`, `AntigravityGatewayService`
|
|
- **ORM**: Ent (`ent/schema/` for definitions, `ent/` for generated code)
|
|
- **Middleware stack**: Recovery → Logger → CORS → SecurityHeaders → RequestBodyLimit → ClientRequestID → APIKeyAuth
|
|
- **Run modes**: `standard` (full SaaS with billing) / `simple` (skip billing checks)
|
|
|
|
### Frontend (`frontend/src/`)
|
|
|
|
- **Framework**: Vue 3 + Pinia + Vue Router + TailwindCSS
|
|
- **State**: `stores/app.ts` (global), `stores/auth.ts` (JWT auth)
|
|
- **i18n**: `i18n/locales/en.ts`, `zh.ts` — all user-facing strings
|
|
- **Embedded**: production build goes to `backend/internal/web/dist/` and is embedded into the Go binary
|
|
|
|
### Gateway Routes
|
|
|
|
```
|
|
/v1/messages — Claude API compatible
|
|
/v1/responses — OpenAI API compatible
|
|
/v1beta/models/* — Gemini native API
|
|
/antigravity/v1/* — Antigravity platform
|
|
```
|
|
|
|
## Coding Conventions
|
|
|
|
- **Go**: `gofmt`, `golangci-lint` (see `backend/.golangci.yml`), max 3 levels of `if` nesting
|
|
- **Frontend**: Vue SFC + TypeScript, 2-space indent, ESLint, components `PascalCase.vue`, composables `useXxx.ts`
|
|
- **Commits**: Conventional Commits (`feat(scope):`, `fix(scope):`, `chore(scope):`)
|
|
- **JSON hot-path**: prefer `gjson` over `encoding/json` for read-only/partial extraction
|
|
- **Layering**: handler/service must NOT import repository/gorm/redis directly
|
|
|
|
## Skills (in `skills/`)
|
|
|
|
- **sync-upstream** — Pulls and merges upstream sub2api, re-applies all StarFireAPI customizations. Trigger: "拉取上游", "同步上游", "sync upstream"
|
|
- **bug-fix-expert** — Multi-agent bug fix workflow with worktree isolation and cross-validation
|
|
- **code-review-expert** — Parallel 5-dimension code review with worktree isolation
|