# 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 Proxy & UI)
- `server/` - Go 1.21 + Gin + MongoDB (Main API & Data Storage)
- `analyzer/` - Python 3.12 + FastAPI (Data Cleaning & Analysis Service)

## Build/Lint/Test Commands

### Frontend (web/)
**Working Directory:** `/Users/clz/Projects/BillAI/web`

```bash
npm run dev                           # Start dev server
npm run build                         # Production build
npm run check                         # TypeScript check (svelte-check)
npm run lint                          # Prettier + ESLint
npm run format                        # Format code (Prettier)
npm run test:unit                     # Run all unit tests (Vitest)
npx vitest run src/routes/+page.spec.ts  # Run single test file
npx vitest run -t "test name"         # Run test by name pattern
```

### Backend (server/)
**Working Directory:** `/Users/clz/Projects/BillAI/server`

```bash
go run .                              # Start server
go build -o server .                  # Build binary
go mod tidy                           # Clean dependencies
go test ./...                         # Run all tests
go test ./handler/...                 # Run package tests
go test -run TestName                 # Run single test function
go test -v ./handler/...              # Run tests with verbose output
```

### Analyzer (analyzer/)
**Working Directory:** `/Users/clz/Projects/BillAI/analyzer`

```bash
python server.py                      # Start FastAPI server directly
uvicorn server:app --reload           # Start with hot reload
pytest                                # Run all tests
pytest test_file.py                   # Run single test file
pytest -k "test_name"                 # Run test by name pattern
pip install -r requirements.txt       # Install dependencies
```

### Docker
**Working Directory:** `/Users/clz/Projects/BillAI`

```bash
docker-compose up -d --build          # Start/rebuild all services
docker-compose logs -f server         # Follow service logs
docker-compose down                   # Stop all services
```

## Code Style

### General
- **Comments:** Existing comments often use Chinese for business logic explanations. Maintain this style where appropriate, but English is also acceptable for technical explanations.
- **Conventions:** Follow existing patterns strictly. Do not introduce new frameworks or libraries without checking `package.json`/`go.mod`/`requirements.txt`.

### TypeScript/Svelte (web/)
- **Formatting:** Prettier (Tabs, single quotes, no trailing commas, printWidth 100).
- **Naming:** `PascalCase` for types/components/interfaces, `camelCase` for variables/functions.
- **Imports:** Use `$lib` alias for internal imports.
  ```typescript
  import { browser } from '$app/environment';
  import { auth } from '$lib/stores/auth';
  import type { UIBill } from '$lib/models/bill';
  ```
- **Types:** Define interfaces for data models. Use `export interface`.
- **Error Handling:** Check `response.ok`. Throw `Error` with status for UI to catch.

### Go Backend (server/)
- **Structure:** `handler` (HTTP) → `service` (Logic) → `repository` (DB) → `model` (Structs).
- **Tags:** Use `json` (snake_case) and `form` tags. Use `omitempty` for optional fields.
  ```go
  type UpdateBillRequest struct {
      Category *string `json:"category,omitempty" form:"category"`
  }
  ```
- **Error Handling:** Return `500` for DB errors, `400` for bad requests. Wrap errors with context.
  ```go
  if err != nil {
      c.JSON(http.StatusInternalServerError, Response{Result: false, Message: err.Error()})
      return
  }
  ```

### Python Analyzer (analyzer/)
- **Style:** PEP 8. Use `snake_case` for variables/functions.
- **Type Hints:** Mandatory for function arguments and return types.
- **Models:** Use `pydantic.BaseModel` for API schemas.
  ```python
  class CleanRequest(BaseModel):
      input_path: str
      bill_type: Optional[str] = "auto"
  ```
- **Docstrings:** Use triple quotes. Chinese descriptions are common for API docs.

## Key Patterns

- **API Flow:**
  - Frontend talks to `server` (Go) via `/api` proxy.
  - `server` handles auth, DB operations, and delegates complex file processing to `analyzer` (Python).
  - `analyzer` cleanses CSV/Excel files and returns structured JSON/CSV to `server`.

- **Authentication:**
  - JWT based. Token stored in frontend.
  - Header: `Authorization: Bearer <token>`.
  - Backend middleware checks token. 401 triggers logout/redirect.

- **File Processing:**
  - Flow: Upload (ZIP/XLSX) -> Extract/Convert (to UTF-8 CSV) -> Clean (normalize columns) -> Import to DB.
  - `analyzer` uses `openpyxl` for Excel and regex for cleaning text.

## Important Files
- `web/src/lib/api.ts` - Centralized API client methods.
- `web/src/lib/models/*.ts` - Frontend data models (should match backend JSON).
- `server/handler/*.go` - HTTP endpoint definitions.
- `server/repository/mongo.go` - MongoDB connection and queries.
- `analyzer/server.py` - FastAPI entry point and routing.
- `analyzer/cleaners/*.py` - Specific logic for Alipay/Wechat/JD bills.