wlt
7317fbe012
- New AgentPipeline model with JSONB pipeline_data for stages/leads/summary
- AgentOrchestrator service chains DiscoveryService search→analyze→outreach→auto-save
- 3 new API endpoints: POST /agent/start, GET /agent/pipelines, GET /agent/{id}
- Full Agent dashboard Vue component with stats, pipeline grid, leads table, outreach preview
- Sidebar redesigned with AI Agent as primary entry point
- Updated PROGRESS.md, AGENTS.md, DATABASE_SCHEMA.md with latest state
137 lines
9.2 KiB
Markdown
137 lines
9.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|