From 74a971cd6e4eda3ed9f2919ff747327a994bd299 Mon Sep 17 00:00:00 2001
From: TradeMate Dev <dev@trademate.com>
Date: Sat, 16 May 2026 08:18:07 +0800
Subject: [PATCH] doc: add AGENTS.md with architecture, commands, and quirks
 for agent onboarding

---
 AGENTS.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..b158514
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,59 @@
+# 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