# 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
- `server/` - Go 1.21 + Gin + MongoDB 
- `analyzer/` - Python 3.12 + FastAPI

## 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 code
npm run test                          # Run all tests
npx vitest run src/routes/+page.spec.ts  # Single test file
npx vitest run -t "test name"         # Test by name
```

### Backend (server/)
```bash
go run .                              # Start server
go build .                            # Build binary
go mod tidy                           # Clean dependencies
go test ./...                         # All tests
go test ./handler/...                 # Package tests
go test -run TestName                 # Single test
```

### Analyzer (analyzer/)
```bash
python server.py                      # Start FastAPI server
pytest                                # All tests
pytest test_file.py                   # Single file
pytest -k "test_name"                 # Test by pattern
```

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

## Code Style

### TypeScript/Svelte
**Prettier config:** Tabs, single quotes, no trailing commas, width 100

**Imports:**
```typescript
import { browser } from '$app/environment';  // SvelteKit
import { auth } from '$lib/stores/auth';     // Internal
import type { UIBill } from '$lib/models/bill';
```

**Types:**
```typescript
export interface UploadResponse {
  result: boolean;
  message: string;
  data?: UploadData;
}
```

**Naming:** PascalCase (types, components), camelCase (functions, variables)

**Error handling:**
```typescript
if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}
// Handle 401 -> logout redirect
```

### Go Backend
**Structure:** `handler/` → `service/` → `repository/` → MongoDB

**JSON tags:** snake_case, omitempty for optional fields
```go
type UpdateBillRequest struct {
    Category *string `json:"category,omitempty"`
    Amount   *float64 `json:"amount,omitempty"`
}
```

**Response format:**
```go
type Response struct {
    Result  bool        `json:"result"`
    Message string      `json:"message,omitempty"`
    Data    interface{} `json:"data,omitempty"`
}
```

**Error handling:**
```go
if err == repository.ErrNotFound {
    c.JSON(http.StatusNotFound, Response{Result: false, Message: "not found"})
    return
}
```

### Python Analyzer
**Style:** PEP 8, type hints, Pydantic models

```python
def do_clean(
    input_path: str,
    output_path: str,
    bill_type: str = "auto"
) -> tuple[bool, str, str]:
```

**Error handling:**
```python
if not success:
    raise HTTPException(status_code=400, detail=message)
```

## Key Patterns

**API Flow:** Frontend (SvelteKit proxy) → Go API → MongoDB + Python analyzer

**Auth:** JWT tokens, Bearer header, 401 → logout redirect

**File Processing:** ZIP → extract → convert (GBK→UTF-8, xlsx→csv) → clean → import

**Testing:** Vitest + Playwright for frontend, Go test for backend

## Important Files
- `web/src/lib/api.ts` - API client
- `web/src/lib/models/` - UI data models
- `server/handler/` - HTTP handlers
- `server/service/` - Business logic
- `server/model/` - Go data structures
- `analyzer/cleaners/` - Bill processing
- `mock_data/*.zip` - Test data (password: 123456)