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