clz
bb717faac3
Some checks failed
Deploy BillAI / Deploy to Production (push) Has been cancelled
- Update changelog.go to use binary directory as base path - Uses os.Executable() instead of relative path '..' - Automatically adapts to local and Docker environments - Modify server Dockerfile build context - Change context from ./server to project root (.) - Update COPY commands for new context - Add CHANGELOG.md to container image - Update AGENTS.md guidelines - Explicitly specify relative path format for file references This ensures the changelog API works correctly in both local development and Docker deployment environments.
124 lines
5.5 KiB
Markdown
124 lines
5.5 KiB
Markdown
# AGENTS.md - AI Coding Agent Guidelines
|
|
|
|
Guidelines for AI coding agents working on BillAI - a microservices bill analysis system.
|
|
|
|
**Current Version:** 1.4.0 | Go: 1.24.0 | Node: 20+ | Python: 3.12+
|
|
|
|
## Architecture
|
|
- `web/` - SvelteKit 5 + TailwindCSS 4 + TypeScript (Frontend, port 3000)
|
|
- `server/` - Go 1.24 + Gin + MongoDB (API, port 8080)
|
|
- `analyzer/` - Python 3.12 + FastAPI (Data cleaning, port 8001)
|
|
|
|
SvelteKit proxies `/api/*` requests to Go backend via `web/src/routes/api/[...path]/+server.ts`.
|
|
|
|
## Build/Lint/Test Commands
|
|
|
|
### Frontend (web/)
|
|
```bash
|
|
npm run dev # Start dev server
|
|
npm run build # Production build
|
|
npm run check # TypeScript check
|
|
npm run lint # Prettier + ESLint
|
|
npm run format # Format with Prettier
|
|
npm run test # Run all tests (CI mode)
|
|
npx vitest run src/xxx.spec.ts # Run single test file
|
|
npx vitest run -t "pattern" # Run by name pattern
|
|
```
|
|
|
|
### Backend (server/)
|
|
```bash
|
|
go run . # Start server
|
|
go build -o server . # Build binary
|
|
go test ./... # Run all tests
|
|
go test ./handler/... # Run handler tests
|
|
go test -run TestName ./... # Run single test
|
|
go test -v ./handler/... # Verbose output
|
|
```
|
|
|
|
### Analyzer (analyzer/)
|
|
```bash
|
|
python server.py # Start FastAPI
|
|
uvicorn server:app --reload # Hot reload
|
|
pytest # Run all tests
|
|
pytest test_jd_cleaner.py # Single test file
|
|
pytest -k "pattern" # Run by pattern
|
|
```
|
|
|
|
### Docker
|
|
```bash
|
|
docker-compose up -d --build # Start/rebuild all services
|
|
docker-compose logs -f server # Follow logs
|
|
docker-compose down # Stop services
|
|
```
|
|
|
|
## Code Style
|
|
|
|
### General
|
|
- **Comments:** Chinese common for business logic; English for technical.
|
|
- **Conventions:** Follow existing patterns. Check `package.json`/`go.mod`/`requirements.txt` before adding dependencies.
|
|
|
|
### TypeScript/Svelte (web/)
|
|
- **Formatting:** Prettier (tabs, single quotes, printWidth 100)
|
|
- **Naming:** `PascalCase` for types/components, `camelCase` for variables
|
|
- **Imports:** Use `$lib` alias, `$app/*` for SvelteKit builtins. No relative paths for lib modules.
|
|
- **Svelte 5:** Use runes (`$state`, `$derived`, `$effect`, `$props`). Event: `onclick={fn}`.
|
|
- **Types:** `export interface` for models. Frontend `camelCase`, API `snake_case`. Converters in `$lib/models/bill.ts`.
|
|
- **Error Handling:** Check `response.ok`, throw `Error(\`HTTP ${status}\`)`. On 401: `auth.logout()` + redirect.
|
|
- **Auth:** `createAuthStore()` in `$lib/stores/auth.ts`. Token in `localStorage` key `auth`. Use `apiFetch()` in `$lib/api.ts`.
|
|
|
|
### Go Backend (server/)
|
|
- **Layer:** `handler` → `service` → `adapter`/`repository` → `model`. No business logic in handlers.
|
|
- **Struct tags:** JSON `snake_case`, `omitempty` optional. Pointer for optional patch fields. Sensitive: `json:"-"`.
|
|
- **Error handling:** 500 for DB errors, 400 for bad requests, 404 not found. Wrap with `fmt.Errorf("context: %w", err)`.
|
|
- **Response:** `Result bool`, `Message`, `Data *T`. Auth: `success bool`, `error`, `data`.
|
|
- **Time:** Use custom `LocalTime` type (serializes as `2006-01-02 15:04:05`).
|
|
- **Soft delete:** Never hard-delete. Filter `is_deleted: false` in queries.
|
|
|
|
### Python Analyzer (analyzer/)
|
|
- **Style:** PEP 8. `snake_case` variables, `UPPER_CASE` constants. Prefix private globals with `_`.
|
|
- **Type hints:** Mandatory. Use `Optional[str]` or `str | None`.
|
|
- **Models:** `pydantic.BaseModel` for API schemas.
|
|
- **Cleaners:** Extend `BaseCleaner(ABC)` from `cleaners/base.py`. Category rules in `config/category.yaml`.
|
|
|
|
## Key Patterns
|
|
|
|
### API Flow
|
|
```
|
|
Browser → SvelteKit proxy → Go (Gin) → handler → service → adapter → Python FastAPI
|
|
└→ repository → MongoDB
|
|
```
|
|
|
|
### Authentication
|
|
- JWT (HS256). Token in `localStorage` key `auth`. Header: `Authorization: Bearer <token>`.
|
|
- `middleware.AuthRequired()` wraps `/api/*` (except `/api/auth/*`).
|
|
- 401 anywhere → `auth.logout()` + redirect `/login`.
|
|
|
|
### File Processing
|
|
Upload: ZIP/XLSX → Extract → Convert UTF-8 CSV → Detect bill type → Deduplicate → Clean → Save to MongoDB.
|
|
|
|
### Adapter (Go ↔ Python)
|
|
`adapter.Cleaner` interface: HTTP (`adapter/http`, default) or subprocess (`adapter/python`). Set via `ANALYZER_MODE` env var.
|
|
|
|
## Important Files
|
|
| File | Role |
|
|
|---|---|
|
|
| `web/src/lib/api.ts` | Central API client, auth injection |
|
|
| `web/src/lib/stores/auth.ts` | Auth state, JWT handling |
|
|
| `web/src/lib/models/bill.ts` | UIBill model + converters |
|
|
| `server/main.go` | Entry point |
|
|
| `server/handler/upload.go` | Full upload pipeline |
|
|
| `server/handler/bills.go` | List/filter bills |
|
|
| `server/model/bill.go` | Bill models, LocalTime type |
|
|
| `server/adapter/adapter.go` | Cleaner interface |
|
|
| `server/repository/mongo/repository.go` | MongoDB implementation |
|
|
| `analyzer/server.py` | FastAPI entry |
|
|
| `analyzer/cleaners/base.py` | BaseCleaner ABC |
|
|
| `analyzer/category.py` | Category inference |
|
|
|
|
## Agent Guidelines
|
|
- **Before coding:** Search codebase to understand existing patterns and dependencies
|
|
- **Dependencies:** Check `package.json`/`go.mod`/`requirements.txt` before adding new packages
|
|
- **Tests:** Always run relevant test suite before committing changes
|
|
- **Git commits:** Provide clear messages explaining the "why" of changes
|
|
- **File references:** Use relative `file_path:line_number` format (e.g., `server/handler/changelog.go:12`) when mentioning code locations
|