# CarCost - Agent Instructions

## Project Overview
Full-stack vehicle expense tracking application.
- **Frontend**: Vue 3 + Vite + Element Plus + ECharts (`web/`)
- **Backend**: FastAPI + SQLAlchemy + PostgreSQL (`api/`)

## Architecture

### Monorepo Structure
```
web/src/
├── App.vue                   # Main app component
├── main.js                   # Entry with Element Plus + ECharts setup
└── components/               # Reusable components
    ├── panels/               # List panels with charts + table
    │   ├── FuelRecordsPanel.vue   # Desktop & mobile shared
    │   └── CostRecordsPanel.vue   # Desktop & mobile shared
    ├── charts/               # Chart components
    │   └── DashboardCharts.vue
    ├── cards/                # Card components
    │   └── StatsCards.vue
    └── dialogs/              # Dialog components
        ├── vehicle/
        ├── fuel/
        └── cost/
```

**Responsive Design Pattern**:
- `App.vue` uses CSS media queries to switch between desktop/mobile layouts
- `*Panel.vue` components handle both desktop and mobile via `showCharts`/`showList` props
- Desktop: Dual-column layout with StatsCards + DashboardCharts + Panels side-by-side
- Mobile: Single-column with view switching (dashboard/fuel/cost tabs)

### API Routing Convention
All API routes include `/carcost` prefix:
- `/carcost/vehicles/*` - Vehicle CRUD
- `/carcost/fuel_records/*` - Fuel records
- `/carcost/costs/*` - Cost records
- `/carcost/dashboard/*` - Dashboard data

Frontend uses: `API_BASE = 'https://api.yuany3721.site/carcost'`

### Database Models
- **Vehicle**: `id`, `name`, `purchase_date`, `initial_mileage`, `is_deleted`
- **FuelRecord**: `id`, `vehicle_id`, `date`, `mileage`, `fuel_amount`, `fuel_price`, `total_cost`, `is_full_tank`
- **Cost**: `id`, `vehicle_id`, `date`, `type`, `amount`, `mileage`, `is_installment`, `installment_months`

All models use soft delete (`is_deleted` boolean).

## Development Commands

### Backend (api/)
```bash
# Setup (requires Python 3.x)
cd api
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run dev server
python main.py
# or
uvicorn main:app --host 0.0.0.0 --port 7030 --reload

# Run tests
python test_api.py
```

### Frontend (web/)
```bash
cd web
npm install

# Dev server (exposes to all hosts)
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview
```

## Key Configuration Files

### api/.env
```
DATABASE_URL=postgresql://user:pass@host:port/carcost
DEBUG=true
```

### web/vite.config.js
- `server.allowedHosts: ['yuany3721.site', '.yuany3721.site']` - Required for production domain access

## Code Patterns

### Frontend (Vue 3 Composition API)
- Uses `<script setup>` syntax
- Element Plus for UI components (with Chinese text labels)
- ECharts registered globally via `vue-echarts`
- Axios for API calls
- Responsive design with mobile/desktop layouts

### Backend (FastAPI)
- Routers auto-create tables via `Base.metadata.create_all()`
- CORS configured for all origins (dev-friendly, restrict in production)
- SQLAlchemy 2.0 style with `declarative_base()`
- Database connection pooling: `pool_size=5, max_overflow=10`

## Testing
- `api/test_api.py`: Integration tests against live API (api.yuany3721.site)
- Tests cover costs CRUD operations and type validation

## Important Notes
- **Port**: Backend runs on 7030, frontend dev server typically on 5173
- **CORS**: Backend allows all origins (`["*"]`) - change for production
- **Soft Deletes**: All entities use `is_deleted` flag; queries should filter it
- **Cost Types**: 保养/维修/保险/停车/洗车/违章/过路费/其他
- **Frontend Max Width**: Content constrained to 900px centered