142 lines
3.7 KiB
Markdown
142 lines
3.7 KiB
Markdown
# 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)
|