feat: 支持ZIP压缩包上传（含密码保护）
This commit is contained in:
CHE LIANG ZHAO
254
AGENTS.md
Normal file
254
AGENTS.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# AGENTS.md - AI Coding Agent Guidelines
|
||||
|
||||
This document provides guidelines for AI coding agents working on the BillAI project.
|
||||
|
||||
## Project Overview
|
||||
|
||||
BillAI is a microservices-based personal bill analysis system supporting WeChat and Alipay bill parsing, intelligent categorization, and visualization.
|
||||
|
||||
**Architecture:**
|
||||
- `web/` - Frontend (SvelteKit 5 + TailwindCSS 4.x + TypeScript)
|
||||
- `server/` - Backend API (Go 1.21 + Gin + MongoDB)
|
||||
- `analyzer/` - Python analysis service (Python 3.12 + FastAPI)
|
||||
|
||||
## Build, Lint, and Test Commands
|
||||
|
||||
### Frontend (web/)
|
||||
|
||||
```bash
|
||||
# Development
|
||||
npm run dev # Start dev server (Vite)
|
||||
|
||||
# Build
|
||||
npm run build # Production build
|
||||
npm run preview # Preview production build
|
||||
|
||||
# Type checking
|
||||
npm run check # svelte-check with TypeScript
|
||||
npm run check:watch # Watch mode
|
||||
|
||||
# Linting and formatting
|
||||
npm run lint # Prettier check + ESLint
|
||||
npm run format # Format with Prettier
|
||||
|
||||
# Testing
|
||||
npm run test # Run all tests once
|
||||
npm run test:unit # Run tests in watch mode
|
||||
npx vitest run src/demo.spec.ts # Run single test file
|
||||
npx vitest run -t "sum test" # Run tests matching name
|
||||
npx vitest run src/routes/page.svelte.spec.ts # Run component test
|
||||
```
|
||||
|
||||
### Backend (server/)
|
||||
|
||||
```bash
|
||||
# Run
|
||||
go run . # Start development server
|
||||
|
||||
# Build
|
||||
go build . # Build binary
|
||||
|
||||
# Dependencies
|
||||
go mod download # Install dependencies
|
||||
go mod tidy # Clean up dependencies
|
||||
|
||||
# Testing (if tests exist)
|
||||
go test ./... # Run all tests
|
||||
go test ./handler/... # Run tests in specific package
|
||||
go test -run TestName # Run single test by name
|
||||
```
|
||||
|
||||
### Analyzer (analyzer/)
|
||||
|
||||
```bash
|
||||
# Setup
|
||||
python -m venv venv
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Run
|
||||
python server.py # Start FastAPI server
|
||||
|
||||
# Testing (if tests exist)
|
||||
pytest # Run all tests
|
||||
pytest test_file.py # Run single test file
|
||||
pytest -k "test_name" # Run tests matching name
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
docker-compose up -d --build # Start all services
|
||||
docker-compose ps # Check service status
|
||||
docker-compose down # Stop all services
|
||||
docker-compose logs -f web # Follow logs for specific service
|
||||
```
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
### TypeScript/Svelte (Frontend)
|
||||
|
||||
**Formatting (Prettier):**
|
||||
- Use tabs for indentation
|
||||
- Single quotes for strings
|
||||
- No trailing commas
|
||||
- Print width: 100 characters
|
||||
|
||||
**Imports:**
|
||||
- Use `$lib/` alias for imports from `src/lib/`
|
||||
- Use `$app/` for SvelteKit internals
|
||||
- Group imports: external packages, then internal modules
|
||||
|
||||
```typescript
|
||||
import { browser } from '$app/environment';
|
||||
import { auth } from '$lib/stores/auth';
|
||||
import type { UIBill } from '$lib/models/bill';
|
||||
```
|
||||
|
||||
**Types:**
|
||||
- Define interfaces for API responses and requests
|
||||
- Use `type` for unions and simple type aliases
|
||||
- Export types from dedicated files in `$lib/types/` or alongside models
|
||||
|
||||
```typescript
|
||||
export interface UploadResponse {
|
||||
result: boolean;
|
||||
message: string;
|
||||
data?: UploadData;
|
||||
}
|
||||
```
|
||||
|
||||
**Naming Conventions:**
|
||||
- PascalCase: Components, interfaces, types
|
||||
- camelCase: Functions, variables, properties
|
||||
- Use descriptive names: `fetchBills`, `UIBill`, `checkHealth`
|
||||
|
||||
**Error Handling:**
|
||||
- Wrap API calls in try/catch
|
||||
- Throw `Error` with HTTP status for API failures
|
||||
- Handle 401 responses with logout redirect
|
||||
|
||||
```typescript
|
||||
if (!response.ok) {
|
||||
throw new Error(`HTTP ${response.status}`);
|
||||
}
|
||||
```
|
||||
|
||||
### Go (Backend)
|
||||
|
||||
**Project Structure:**
|
||||
- `handler/` - HTTP request handlers
|
||||
- `service/` - Business logic
|
||||
- `repository/` - Data access layer
|
||||
- `model/` - Data structures
|
||||
- `adapter/` - External service integrations
|
||||
- `config/` - Configuration management
|
||||
- `middleware/` - Auth and other middleware
|
||||
|
||||
**Naming Conventions:**
|
||||
- PascalCase: Exported types, functions, constants
|
||||
- camelCase: Unexported functions, variables
|
||||
- Use descriptive names: `UpdateBillRequest`, `parseBillTime`
|
||||
|
||||
**Error Handling:**
|
||||
- Define sentinel errors in `repository/errors.go`
|
||||
- Return errors up the call stack
|
||||
- Use structured JSON responses for HTTP errors
|
||||
|
||||
```go
|
||||
if err == repository.ErrNotFound {
|
||||
c.JSON(http.StatusNotFound, Response{Result: false, Message: "not found"})
|
||||
return
|
||||
}
|
||||
```
|
||||
|
||||
**JSON Tags:**
|
||||
- Use snake_case for JSON field names
|
||||
- Use `omitempty` for optional fields
|
||||
- Match frontend API expectations
|
||||
|
||||
```go
|
||||
type UpdateBillRequest struct {
|
||||
Category *string `json:"category,omitempty"`
|
||||
Amount *float64 `json:"amount,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
**Response Format:**
|
||||
- All API responses use consistent structure:
|
||||
|
||||
```go
|
||||
type Response struct {
|
||||
Result bool `json:"result"`
|
||||
Message string `json:"message,omitempty"`
|
||||
Data interface{} `json:"data,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
### Python (Analyzer)
|
||||
|
||||
**Style:**
|
||||
- Follow PEP 8
|
||||
- Use type hints for function signatures
|
||||
- Use Pydantic models for request/response validation
|
||||
|
||||
```python
|
||||
def do_clean(
|
||||
input_path: str,
|
||||
output_path: str,
|
||||
bill_type: str = "auto"
|
||||
) -> tuple[bool, str, str]:
|
||||
```
|
||||
|
||||
**Error Handling:**
|
||||
- Raise `HTTPException` for API errors
|
||||
- Use try/except for file operations
|
||||
- Return structured responses
|
||||
|
||||
```python
|
||||
if not success:
|
||||
raise HTTPException(status_code=400, detail=message)
|
||||
```
|
||||
|
||||
## Testing Guidelines
|
||||
|
||||
**Frontend Tests:**
|
||||
- Use Vitest with Playwright for browser testing
|
||||
- Component tests: `*.svelte.spec.ts`
|
||||
- Unit tests: `*.spec.ts`
|
||||
- Tests require assertions: `expect.assertions()` or explicit expects
|
||||
|
||||
```typescript
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { render } from 'vitest-browser-svelte';
|
||||
|
||||
describe('/+page.svelte', () => {
|
||||
it('should render h1', async () => {
|
||||
render(Page);
|
||||
await expect.element(page.getByRole('heading')).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Important Patterns
|
||||
|
||||
**API Communication:**
|
||||
- Frontend proxies API calls through SvelteKit to avoid CORS
|
||||
- Backend uses Gin framework with JSON responses
|
||||
- Analyzer communicates via HTTP (preferred) or subprocess
|
||||
|
||||
**Data Flow:**
|
||||
- Frontend (SvelteKit) -> Backend (Go/Gin) -> MongoDB
|
||||
- Backend -> Analyzer (Python/FastAPI) for bill parsing
|
||||
|
||||
**Authentication:**
|
||||
- JWT tokens stored in frontend auth store
|
||||
- Bearer token sent in Authorization header
|
||||
- 401 responses trigger logout and redirect
|
||||
|
||||
## File Locations
|
||||
|
||||
- API types: `web/src/lib/api.ts`
|
||||
- UI models: `web/src/lib/models/`
|
||||
- Go handlers: `server/handler/`
|
||||
- Go models: `server/model/`
|
||||
- Python API: `analyzer/server.py`
|
||||
Reference in New Issue
Block a user