clz/billai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 智能复核添加快捷确认功能

Browse Source
This commit is contained in:
CHE LIANG ZHAO
2026-01-26 13:04:04 +08:00
parent 6e3756b2e1
commit 7b2d6a9fbb
4 changed files with 143 additions and 175 deletions
Download Patch File Download Diff File Expand all files Collapse all files

235
AGENTS.md
View File

@@ -1,114 +1,63 @@
# AGENTS.md - AI Coding Agent Guidelines
This document provides guidelines for AI coding agents working on the BillAI project.
Guidelines for AI coding agents working on BillAI - a microservices bill analysis system.
## Project Overview
## Architecture
- `web/` - SvelteKit 5 + TailwindCSS 4 + TypeScript
- `server/` - Go 1.21 + Gin + MongoDB
- `analyzer/` - Python 3.12 + FastAPI
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
## Build/Lint/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
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
# 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
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
# 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
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 all services
docker-compose ps # Check service status
docker-compose down # Stop all services
docker-compose logs -f web # Follow logs for specific service
docker-compose up -d --build # Start/rebuild all
docker-compose logs -f server # Follow service logs
```
## Code Style Guidelines
## Code Style
### TypeScript/Svelte (Frontend)
**Formatting (Prettier):**
- Use tabs for indentation
- Single quotes for strings
- No trailing commas
- Print width: 100 characters
### TypeScript/Svelte
**Prettier config:** Tabs, single quotes, no trailing commas, width 100
**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 { browser } from '$app/environment'; // SvelteKit
import { auth } from '$lib/stores/auth'; // Internal
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;
@@ -117,55 +66,20 @@ export interface UploadResponse {
}
```
**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
**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)
**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 Backend
**Structure:** `handler/` → `service/` → `repository/` → MongoDB
**JSON tags:** snake_case, omitempty for optional fields
```go
type UpdateBillRequest struct {
Category *string `json:"category,omitempty"`
@@ -173,9 +87,7 @@ type UpdateBillRequest struct {
}
```
**Response Format:**
- All API responses use consistent structure:
**Response format:**
```go
type Response struct {
Result bool `json:"result"`
@@ -184,12 +96,16 @@ type Response struct {
}
```
### Python (Analyzer)
**Error handling:**
```go
if err == repository.ErrNotFound {
c.JSON(http.StatusNotFound, Response{Result: false, Message: "not found"})
return
}
```
**Style:**
- Follow PEP 8
- Use type hints for function signatures
- Use Pydantic models for request/response validation
### Python Analyzer
**Style:** PEP 8, type hints, Pydantic models
```python
def do_clean(
@@ -199,56 +115,27 @@ def do_clean(
) -> tuple[bool, str, str]:
```
**Error Handling:**
- Raise `HTTPException` for API errors
- Use try/except for file operations
- Return structured responses
**Error handling:**
```python
if not success:
raise HTTPException(status_code=400, detail=message)
```
## Testing Guidelines
## Key Patterns
**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
**API Flow:** Frontend (SvelteKit proxy) → Go API → MongoDB + Python analyzer
```typescript
import { describe, it, expect } from 'vitest';
import { render } from 'vitest-browser-svelte';
**Auth:** JWT tokens, Bearer header, 401 → logout redirect
describe('/+page.svelte', () => {
it('should render h1', async () => {
render(Page);
await expect.element(page.getByRole('heading')).toBeInTheDocument();
});
});
```
**File Processing:** ZIP → extract → convert (GBK→UTF-8, xlsx→csv) → clean → import
## Important Patterns
**Testing:** Vitest + Playwright for frontend, Go test for backend
**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`
## 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)