TradeMate Dev
78 lines
3.9 KiB
Markdown
78 lines
3.9 KiB
Markdown
# 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 — uni-app (mobile)
|
|
cd uni-app && npm run dev:h5
|
|
|
|
# Admin frontend (PC management)
|
|
cd admin-frontend && npm run dev # port 5173, base: /admin/
|
|
|
|
# User workspace (PC workbench)
|
|
cd user-frontend && npm run dev # port 5174, base: /workspace/
|
|
|
|
# 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
|
|
|
|
# Builds
|
|
cd uni-app && npm run build:h5 # uni-app (mobile H5)
|
|
cd admin-frontend && npm run build # admin => /www/wwwroot/trade.yuzhiran.com/admin/
|
|
cd user-frontend && npm run build # workspace => /www/wwwroot/trade.yuzhiran.com/workspace/
|
|
|
|
# Alembic migrations
|
|
cd backend && alembic upgrade head
|
|
alembic revision --autogenerate -m "desc"
|
|
```
|
|
|
|
## Deployment
|
|
|
|
- **Landing page** at `trade.yuzhiran.com/` — static marketing HTML
|
|
- **SPA** at `trade.yuzhiran.com/app/` — uni-app build (mobile)
|
|
- **Admin** at `trade.yuzhiran.com/admin/` — Vue 3 + Element Plus (standalone)
|
|
- **Workspace** at `trade.yuzhiran.com/workspace/` — Vue 3 + Element Plus (standalone)
|
|
- **Nginx**: SPA fallbacks for `/app/`, `/admin/`, `/workspace/`
|
|
- **vite config**: each project has its own `base` path and dev port
|
|
- **API**: proxied via nginx `location /api/` to `127.0.0.1:8002`
|
|
|
|
## 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
|