# TradeMate (外贸小助手) — Agent Guide

## Architecture

- **Backend**: `backend/` — FastAPI + SQLAlchemy 1.4 async + asyncpg, single `app.main:app`
- **Frontend**: `uni-app/` — Vue 3 + uni-app (H5 first, later WeChat mini-program)
- **Config**: `backend/app/config.py` reads from `/.env` (project root) via pydantic BaseSettings
- **Auth**: JWT (python-jose). Default dep `get_current_user_id` in `backend/app/api/v1/deps.py`
- **AI Router**: `backend/app/ai/router.py` — singleton `AIRouter`, primary=`opencode_go`, fallbacks=sensenova/openai/anthropic
- **Database**: PostgreSQL via `asyncpg`, pool_size=20

## Dev Commands

```bash
# Backend (from project root — .env is there)
cd backend && source venv/bin/activate && uvicorn app.main:app --reload --port 8000

# Frontend
cd uni-app && npm run dev:h5

# Tests (backend — needs PostgreSQL running with foreign_trade_test DB)
cd backend && venv/bin/pytest              # all
venv/bin/pytest tests/test_auth_api.py     # single file
venv/bin/pytest tests/ -k "test_login"     # keyword filter

# Frontend build (produces uni-app/dist/build/h5/)
cd uni-app && npm run build:h5

# Alembic migrations
cd backend && alembic upgrade head
alembic revision --autogenerate -m "desc"
```

## Critical Quirks

- **Route ordering**: FastAPI matches top-down. Specific routes (`/{customer_id}/health`) must be registered **before** wildcard `/{customer_id}`.
- **AI `extract_info`**: Some models (e.g. deepseek-v4-flash) don't support `response_format={"type": "json_object"}`. `openai.py` catches the failure and retries without it.
- **Manual auth on some endpoints**: `keywords` and `competitor-analysis` endpoints use `authorization: str = Header(None)` instead of `Depends(get_current_user_id)`.
- **MarketingService fallback**: When no AI providers initialized, returns template content instead of crashing.
- **Onboarding service**: calls `mkt.generate(product_info={"name": ..., ...})`, not keyword args. Check `onboarding.py` for the exact dict shape.
- **Login**: `POST /api/v1/auth/login` uses JSON `LoginRequest` model, not `OAuth2PasswordRequestForm`.
- **CustomerHealthService**: `get_health_overview` endpoint must use `CustomerHealthService(db)` not `CustomerService(db)`.

## Project Conventions

- **No README.md** — key context is in `PROGRESS.md` and `docs/`
- **Chinese UI** — mobile-first, for foreign-trade SOHOs/small teams
- **No comments in code** unless explicitly asked
- **Commit messages** focus on "why" not "what", in English
- **Services** instantiate `MarketingService()` (no db needed). For customer health: `CustomerHealthService(db)`
- **AI providers** in `backend/app/ai/providers/` — inherit from `OpenAIProvider` if compatible with OpenAI API format
- **Static assets** go in `uni-app/src/static/`
- **Test DB**: `foreign_trade_test` (uses credentials from `conftest.py`, not `.env`)

## Remember

- Write tests for new features
- Run `cd backend && venv/bin/pytest` before committing
- Keep context compact — avoid bloating the session with unnecessary file reads