alai-dev/trade-assistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
04924e3bc46b3ce9a4c8ed74f4c064231a83b3f8
trade-assistant/AGENTS.md
T

13 KiB
Raw Blame History

TradeMate (外贸小助手) — Agent Guide

Chrome 浏览器扩展 🆕

  • 目录: browser-extension/ — 完整 Chrome 插件
  • 功能: popup 面板调用 AI 翻译/回复/提取客户信息、网页右键菜单集成、自动填写报价单
  • 兼容平台: LinkedIn / Amazon / AliExpress 等外贸平台页面
  • 安装: 打开 chrome://extensions → 加载已解压的扩展 → 选择 browser-extension/ 目录
  • API 客户端: browser-extension/api/client.js — 封装后端 API 调用，支持 JWT 认证

UX Design

  • PC 工作台: 侧边栏 5 项精简导航 (首页/客户/业务/翻译/更多) + CommandK 命令面板 (Ctrl+K)
  • 移动端 H5: 底部 4 Tab 导航 (首页/客户/业务/我的)
  • 工作区合并: Customers/Discovery/Followup → WorkspaceCustomer；Translate/Products/Quotations/Marketing → WorkspaceBiz
  • 路由: 旧页面保留隐藏路由，保证兼容性

uni-app 移动端 H5 (改版后)

  • Tab Bar: 4 项底部导航 — 首页 / 客户 / 业务 / 我的
  • 主页 pages/index/index.vue — 简化仪表盘 (统计卡片 + 快捷入口矩阵 + 待办提醒)
  • 客户工作台 pages/workspace-customer/workspace-customer.vue — NEW 3 个内联标签 (客户列表 / 挖掘新客 / 智能跟进)
  • 业务工作台 pages/workspace-biz/workspace-biz.vue — NEW 4 个内联标签 (翻译 / 产品库 / 报价单 / 营销素材)
  • 个人中心 pages/profile/profile.vue — 更新导航 (通知中心 / 数据分析 / 团队 / 升级会员 / 联系客服)
  • 旧页面保留 (customers, discovery, followup, translate, product, quotation, marketing 等仍可通过 deep link 访问)
  • pages.json — 标签栏从 5 项变为 4 项，新增 workspace-customer 和 workspace-biz 页面
  • config.js — PAGES 配置新增 WORKSPACE_CUSTOMER / WORKSPACE_BIZ
  • 部署路径: trade.yuzhiran.com/app/ — nginx SPA fallback try_files $uri $uri/ /app/index.html

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() → 自动保存高匹配客户
  • 前端入口: user-frontend/src/views/Agent.vue 已接入路由 /workspace/agent 与 UserLayout.vue 侧边栏 "AI数字员工" (MagicStick 图标)；/agent 重定向到 /workspace/agent
  • 迁移: 需要运行 alembic revision --autogenerate -m "add agent_pipelines" 创建 agent_pipelines 表

收费方式（免费试用 / 私有化部署 / 买断源码）

  • 页面: user-frontend/src/views/Upgrade.vue + UpgradeModal.vue、uni-app/src/pages/upgrade/upgrade.vue、浏览器插件升级入口均改为三种方案：免费试用 / 私有化部署（年付授权）/ 买断源码（一次性）
  • 企业线索: 私有化部署与买断源码的 CTA 提交到 POST /api/v1/leads（模型 EnterpriseLead，表 enterprise_leads），无需登录；admin 可在 enterprise_leads 表查看
  • 价格占位: Upgrade.vue 中 PRICING 对象（¥39,800/年、¥98,000 一次性）为可配置展示值
  • 说明: 旧的按月订阅套餐（/credits/subscribe）仍存在于后端，但前端不再主推；如彻底下线订阅需同步清理 credits.py 订阅逻辑

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 (seeded by seed_from_env()): Sensenova (商汤, if SENSENOVA_API_KEY set), NVIDIA (if NVIDIA_API_KEY set), 阿里翻译 alibaba-mt (always inserted) — at most 3 rows. Do NOT assume 5 providers exist.
  • Removed: Claude, DeepL, Local, OpencodeGo, 讯飞 Spark — provider implementations were git rm'd; don't re-add them.
  • 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
# pytest.ini: asyncio_mode=auto (no @pytest.mark.asyncio needed) and
# addopts adds --cov=app coverage automatically on every run.

# 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
  • Makefile make deploy references docker-compose.prod.yml / docker-compose.staging.yml, which do not exist (only docker-compose.yml is present). Those targets are currently broken.

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

  • Docs: README.md (overview), PROGRESS.md (task status), docs/ (API/schema/architecture). README references this file for dev norms.
  • 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
Reference in New Issue View Git Blame Copy Permalink