trade-assistant/AGENTS.md

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

# 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