carcost/AGENTS.md

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/)

# 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/)

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