# AGENTS.md - AI Coding Agent Guidelines

Guidelines for AI coding agents working on BillAI - a microservices bill analysis system.

## Architecture
- `web/` - SvelteKit 5 + TailwindCSS 4 + TypeScript (Frontend, port 3000)
- `server/` - Go 1.21 + 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 |