trade-assistant/AGENTS.md

TradeMate (外贸小助手) — Agent Guide

AI Assistant (Frontend AI Chatbot)

• Components: user-frontend/src/components/AiAssistant.vue + admin-frontend/src/components/AiAssistant.vue
• Backend: backend/app/api/v1/ai_assistant.py — POST /api/v1/ai/chat, GET /api/v1/ai/quick-questions
• Action types (configurable via ACTION_INSTRUCTIONS): create_customer, create_product, create_quotation, scan_followups, generate_marketing, discovery_search, navigate, search_users, update_user, update_config, review_certification, process_invoice
• Frontend action dispatch: AiAssistant.vue switch/case calls corresponding API from @/api
• Layout integration: <AiAssistant /> in UserLayout.vue + AdminLayout.vue, floating button bottom-right
• Quick questions: configurable via ai_assistant_quick_questions SystemConfig key
• System prompt: configurable via ai_assistant_prompt SystemConfig key

AI 数字员工 (Agent Orchestrator) 🆕

• Dashboard: user-frontend/src/views/Agent.vue — 全功能仪表盘，位于 /agent 路由
• 编排服务: backend/app/services/agent_orchestrator.py — AgentOrchestrator 类
  • start_pipeline(user_id, product_name, product_description, target_market) — 启动完整流程
  • get_pipeline(pipeline_id, user_id) — 获取流水线详情
  • list_pipelines(user_id, page, size) — 分页列表
• 数据模型: backend/app/models/agent_pipeline.py — AgentPipeline (表: agent_pipelines)
  • JSONB pipeline_data 存储 stages + leads + summary
• API 端点: backend/app/api/v1/agent.py — 3 个端点
  • POST /api/v1/agent/start — 启动新任务 (timeout: 300s)
  • GET /api/v1/agent/pipelines — 任务列表
  • GET /api/v1/agent/{pipeline_id} — 任务详情
• 流程: 用户输入产品+市场 → AgentOrchestrator 串接 DiscoveryService.search() → analyze() → outreach() → 自动保存高匹配客户
• 前端入口: UserLayout.vue 侧边栏首位 "AI数字员工" (MagicStick 图标)
• 迁移: 需要运行 alembic revision --autogenerate -m "add agent_pipelines" 创建 agent_pipelines 表

Architecture

• Backend: backend/ — FastAPI + SQLAlchemy 1.4 async + asyncpg, single app.main:app
• Frontends: uni-app/ (mobile H5/mini-program), admin-frontend/ (PC admin), user-frontend/ (PC workspace)
• 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, DB-driven providers + DB-driven routing rules. Routing reads ai_routing from system_configs table.
• Database: PostgreSQL via asyncpg, pool_size=20

AI Providers

• Active: Sensenova (商汤), NVIDIA, 阿里机器翻译 (alibaba-mt) — 5 providers in DB
• Removed: Claude, DeepL, Local, OpencodeGo, 讯飞 Spark — all git rm'd
• DB-driven: AIProvider model + admin_ai.py API — manage providers at runtime. router.seed_from_env() loads from .env on startup
• ECS RAM role: 阿里翻译使用 ECS 实例 RAM 角色 trademate-translate 获取 STS 临时凭证
• Provider type mapping in router.py._build_provider(): sensenova, nvidia, alibaba-mt

Security

• CORS: middleware.py — whitelist origins, restricted methods/headers
• Rate Limit: endpoint-specific — login 5/min, register 3/h, password 3/5min, payment 20/min, admin 30/min
• CSRF: core/csrf.py — double-submit cookie pattern. Required on auth/payment/profile. Webhooks skipped.
• Login: JSON LoginRequest model, not OAuth2PasswordRequestForm

Customer Discovery

• discovery.py + discovery_record.py — Google Custom Search integration
• Contact extraction from company websites (email/phone/WhatsApp/WeChat)

Dev Commands

# Backend (from project root — .env is there)
# Dev: matches Vite proxy (both frontends proxy /api → localhost:8000)
cd backend && source venv/bin/activate && uvicorn app.main:app --reload --port 8000
# Production: nginx proxies /api/ → localhost:8002
cd backend && source venv/bin/activate && uvicorn app.main:app --port 8002

# Mobile H5
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: trade.yuzhiran.com/ — static marketing HTML
• SPA: trade.yuzhiran.com/app/ — uni-app build (mobile)
• Admin: trade.yuzhiran.com/admin/ — Vue 3 + Element Plus (standalone)
• Workspace: 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:8000

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.
• CustomerHealthService: get_health_overview endpoint must use CustomerHealthService(db) not CustomerService(db).
• CSRF: Sensitive endpoints (auth/payment/profile) require X-CSRF-Token header. Token available via csrf_token cookie / X-CSRF-Token response header.
• AI Router reload: After modifying AI providers via admin API, call POST /api/v1/admin/ai/reload to refresh in-memory providers.
• Payment: Uses unified pay-api gateway (UnifiedPayService). NOT direct WeChat/Alipay integration. Credentials: PAY_API_KEY/PAY_API_SECRET from .env. HMAC-SHA256 auth. Webhook at POST /api/v1/payment/webhook skips CSRF.
• Payment gateway config: PAY_API_KEY, PAY_API_SECRET, PAY_API_BASE_URL, PAY_WEBHOOK_URL in config.py. pay_type param: "alipay" (returns pay_url) or "wechat" (returns code_url). UnifiedPayService normalizes legacy native/jsapi/pc to wechat/alipay.
• Stripe: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET in .env. StripePaymentService via Checkout Sessions. Selected when pay_type is card/stripe. Webhook POST /api/v1/payment/stripe-webhook.
• PayPal: PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_WEBHOOK_ID, PAYPAL_SANDBOX=True in .env. PayPalPaymentService via Orders v2 API. Selected when pay_type is paypal. Webhook POST /api/v1/payment/paypal-webhook.
• Credit purchase: POST /api/v1/credits/stripe-purchase with gateway: "stripe"|"paypal" for overseas payments (USD), returns session_url for redirect. Gateway-agnostic: gateway param selects the provider.
• Agent Pipeline timeout: POST /api/v1/agent/start may take 2-3 minutes to complete (it chains search → analyze → outreach synchronously). Frontend timeout set to 300s.
• Agent auto-save: High-scoring leads (>=70 match_score) are auto-saved as Customer records with source='ai_agent:{pipeline_id}'. Duplicate check by name+user_id.
• Agent pipeline_data JSONB: Contains stages progress, leads array (with outreach content), and summary stats. This is the source of truth for the frontend dashboard rendering.

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). For agent: AgentOrchestrator(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