Initial commit: TradeMate 外贸小助手 MVP
项目结构: - backend/ Python FastAPI 后端 - uni-app/ uni-app跨端前端 - docs/ 设计文档 - docker-compose.yml Docker编排 - nginx/scripts/systemd 运维配置 已完成功能: - 用户认证 (JWT) - 智能翻译 + 回复建议 - 营销素材生成 - 客户管理 + 沉默检测 - 报价单管理 - 产品库管理 - 汇率换算 - 推送通知 (uni-push) - WhatsApp Webhook框架 - Celery定时任务
This commit is contained in:
TradeMate Dev
@@ -0,0 +1,352 @@
|
||||
# 外贸小助手 (TradeMate) — API 设计文档
|
||||
|
||||
> 版本: v1.0
|
||||
> 创建日期: 2026-05-08
|
||||
|
||||
---
|
||||
|
||||
## 一、Base URL
|
||||
|
||||
```
|
||||
Production: https://api.trademate.example.com/api/v1
|
||||
Development: http://localhost:8000/api/v1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、认证方式
|
||||
|
||||
采用 JWT Bearer Token 认证，请求 Header 中需携带：
|
||||
|
||||
```
|
||||
Authorization: Bearer <access_token>
|
||||
```
|
||||
|
||||
Token 刷新：access_token 有效期 24 小时，可使用 refresh_token 换新。
|
||||
|
||||
---
|
||||
|
||||
## 三、API 端点清单
|
||||
|
||||
### 1. 认证 API (`/auth`)
|
||||
|
||||
| 方法 | 路径 | 描述 | 认证 |
|
||||
|------|------|------|------|
|
||||
| POST | `/auth/register` | 用户注册 | 否 |
|
||||
| POST | `/auth/login` | 用户登录 | 否 |
|
||||
| POST | `/auth/refresh` | 刷新 Token | 是 |
|
||||
| GET | `/auth/me` | 获取当前用户信息 | 是 |
|
||||
|
||||
#### 注册
|
||||
```http
|
||||
POST /auth/register
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"username": "string",
|
||||
"phone": "string",
|
||||
"password": "string"
|
||||
}
|
||||
```
|
||||
|
||||
#### 登录
|
||||
```http
|
||||
POST /auth/login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"username": "string",
|
||||
"password": "string"
|
||||
}
|
||||
```
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"access_token": "string",
|
||||
"refresh_token": "string",
|
||||
"token_type": "bearer",
|
||||
"user": {
|
||||
"id": "uuid",
|
||||
"username": "string",
|
||||
"tier": "free"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 客户管理 API (`/customers`)
|
||||
|
||||
| 方法 | 路径 | 描述 | 认证 |
|
||||
|------|------|------|------|
|
||||
| GET | `/customers` | 获取客户列表 | 是 |
|
||||
| GET | `/customers/silent` | 获取沉默客户列表 | 是 |
|
||||
| GET | `/customers/{id}` | 获取单个客户详情 | 是 |
|
||||
| POST | `/customers` | 创建新客户 | 是 |
|
||||
| PATCH | `/customers/{id}` | 更新客户信息 | 是 |
|
||||
| DELETE | `/customers/{id}` | 删除客户 | 是 |
|
||||
| GET | `/customers/{id}/conversation` | 获取客户对话记录 | 是 |
|
||||
|
||||
#### 列表查询参数
|
||||
- `status`: 筛选状态 (lead/negotiating/customer/lost)
|
||||
- `page`: 页码 (默认 1)
|
||||
- `size`: 每页数量 (默认 20)
|
||||
|
||||
#### 沉默客户
|
||||
```http
|
||||
GET /customers/silent?days=3
|
||||
```
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"customers": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "Carlos",
|
||||
"country": "Mexico",
|
||||
"last_contact_at": "2026-05-01T10:00:00Z",
|
||||
"silence_days": 5
|
||||
}
|
||||
],
|
||||
"count": 10,
|
||||
"silence_days": 3
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 翻译与回复 API (`/translate`)
|
||||
|
||||
| 方法 | 路径 | 描述 | 认证 |
|
||||
|------|------|------|------|
|
||||
| POST | `/translate` | 翻译文本 | 是 |
|
||||
| POST | `/translate/reply` | 生成回复建议 | 是 |
|
||||
| POST | `/translate/extract` | 提取关键信息 | 是 |
|
||||
| POST | `/translate/feedback` | 反馈翻译质量 | 是 |
|
||||
|
||||
#### 翻译
|
||||
```http
|
||||
POST /translate
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"text": "How much for 500pcs FOB Shanghai?",
|
||||
"source": "en",
|
||||
"target": "zh"
|
||||
}
|
||||
```
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"original": "How much for 500pcs FOB Shanghai?",
|
||||
"translated": "上海离岸价500件多少钱？",
|
||||
"provider": "deepl",
|
||||
"tokens_used": 45
|
||||
}
|
||||
```
|
||||
|
||||
#### 回复建议
|
||||
```http
|
||||
POST /translate/reply
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"customer_message": "Hi, I'm interested in your outdoor chairs. Can you give me a quote for 500pcs?",
|
||||
"product_context": "户外折叠椅，承重150kg",
|
||||
"tone": "professional"
|
||||
}
|
||||
```
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"suggestions": [
|
||||
{
|
||||
"text": "Thank you for your inquiry. Our FOB Shanghai price for 500pcs is $12.5/pc. Lead time is 25 days. Payment terms: T/T 30% deposit.",
|
||||
"tone": "professional",
|
||||
"reasoning": "Based on询价 context, direct quote with terms"
|
||||
},
|
||||
{
|
||||
"text": "Hi! Thanks for reaching out. I'd be happy to help you with our outdoor folding chairs. $12.5/pc for 500pcs, FOB Shanghai. Want more details?",
|
||||
"tone": "friendly",
|
||||
"reasoning": "More casual approach for initial contact"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 营销素材 API (`/marketing`)
|
||||
|
||||
| 方法 | 路径 | 描述 | 认证 |
|
||||
|------|------|------|------|
|
||||
| POST | `/marketing/generate` | 生成营销文案 | 是 |
|
||||
| POST | `/marketing/keywords` | 生成关键词建议 | 是 |
|
||||
| POST | `/marketing/competitor-analysis` | 竞品分析 | 是 |
|
||||
|
||||
#### 生成文案
|
||||
```http
|
||||
POST /marketing/generate
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"product_name": "户外折叠椅",
|
||||
"description": "承重150kg，防水面料，带杯架和扶手",
|
||||
"category": "furniture",
|
||||
"price": "$25",
|
||||
"target": "US importers",
|
||||
"style": "professional",
|
||||
"language": "en",
|
||||
"count": 3
|
||||
}
|
||||
```
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
"Premium Outdoor Folding Chair - 150kg Load Capacity, Waterproof Fabric, Cup Holder & Armrests. Perfect for patios, camping, and events. FDA certified manufacturer.",
|
||||
"Heavy-Duty Folding Chair: 150kg capacity, waterproof, portable. Ideal for restaurants, events, outdoor venues. MOQ: 100pcs. FOB Shanghai.",
|
||||
"Upgrade your outdoor seating! Our folding chairs feature reinforced steel frame, waterproof fabric, and convenient cup holder. Bulk orders welcome."
|
||||
],
|
||||
"product": "户外折叠椅",
|
||||
"target": "US importers",
|
||||
"count": 3
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. 报价单 API (`/quotations`)
|
||||
|
||||
| 方法 | 路径 | 描述 | 认证 |
|
||||
|------|------|------|------|
|
||||
| POST | `/quotations` | 创建报价单 | 是 |
|
||||
| GET | `/quotations` | 获取报价单列表 | 是 |
|
||||
| GET | `/quotations/{id}` | 获取报价单详情 | 是 |
|
||||
| PATCH | `/quotations/{id}/status` | 更新报价单状态 | 是 |
|
||||
|
||||
#### 创建报价单
|
||||
```http
|
||||
POST /quotations
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"customer_id": "uuid",
|
||||
"title": "Quote for Outdoor Chairs",
|
||||
"currency": "USD",
|
||||
"payment_terms": "T/T 30% deposit",
|
||||
"delivery_terms": "FOB Shanghai",
|
||||
"lead_time": "25 days",
|
||||
"valid_until": "2026-06-08",
|
||||
"items": [
|
||||
{
|
||||
"product_name": "Outdoor Folding Chair",
|
||||
"description": "150kg capacity, waterproof",
|
||||
"quantity": 500,
|
||||
"unit_price": 12.5,
|
||||
"unit": "pcs"
|
||||
}
|
||||
],
|
||||
"discount": 0,
|
||||
"shipping": 0,
|
||||
"notes": "Sample quote"
|
||||
}
|
||||
```
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"customer_id": "uuid",
|
||||
"title": "Quote for Outdoor Chairs",
|
||||
"status": "draft",
|
||||
"currency": "USD",
|
||||
"subtotal": 6250,
|
||||
"total": 6250,
|
||||
"items": [...],
|
||||
"text": "QUOTATION\n\nDate: 2026-05-08...",
|
||||
"created_at": "2026-05-08T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. WhatsApp API (`/whatsapp`)
|
||||
|
||||
| 方法 | 路径 | 描述 | 认证 |
|
||||
|------|------|------|------|
|
||||
| GET | `/whatsapp/webhook` | Webhook 验证 | 否 |
|
||||
| POST | `/whatsapp/webhook` | Webhook 接收消息 | 否 |
|
||||
| POST | `/whatsapp/send` | 发送消息 | 是 |
|
||||
| GET | `/whatsapp/qr` | 获取二维码 | 是 |
|
||||
|
||||
#### Webhook 验证
|
||||
```http
|
||||
GET /whatsapp/webhook?hub.mode=subscribe&hub.challenge=STRING&hub.verify_token=TOKEN
|
||||
```
|
||||
|
||||
#### 发送消息
|
||||
```http
|
||||
POST /whatsapp/send
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"customer_id": "uuid",
|
||||
"message": "Thank you for your inquiry. Our price is $12.5/pc."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、错误响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "error_code",
|
||||
"detail": "具体错误描述",
|
||||
"timestamp": "2026-05-08T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
常见错误码：
|
||||
- `UNAUTHORIZED`: 未认证
|
||||
- `FORBIDDEN`: 无权限
|
||||
- `NOT_FOUND`: 资源不存在
|
||||
- `QUOTA_EXCEEDED`: 配额超限
|
||||
- `TIER_LIMITED`: 订阅等级限制
|
||||
- `VALIDATION_ERROR`: 参数校验失败
|
||||
|
||||
---
|
||||
|
||||
## 五、速率限制
|
||||
|
||||
| 级别 | 请求限制 |
|
||||
|------|---------|
|
||||
| 免费版 | 100 请求/分钟 |
|
||||
| Pro版 | 500 请求/分钟 |
|
||||
| 企业版 | 2000 请求/分钟 |
|
||||
|
||||
---
|
||||
|
||||
## 六、WebSocket (可选)
|
||||
|
||||
实时翻译进度和消息推送：
|
||||
|
||||
```
|
||||
wss://api.trademate.example.com/ws/translate
|
||||
```
|
||||
|
||||
连接需携带 Token 参数：
|
||||
```
|
||||
wss://api.trademate.example.com/ws/translate?token=<access_token>
|
||||
```
|
||||
@@ -0,0 +1,388 @@
|
||||
# 外贸小助手 (TradeMate) — 数据库设计文档
|
||||
|
||||
> 版本: v1.0
|
||||
> 创建日期: 2026-05-08
|
||||
|
||||
---
|
||||
|
||||
## 一、数据库概述
|
||||
|
||||
- **数据库类型**: PostgreSQL 15 + pgvector
|
||||
- **字符集**: UTF-8
|
||||
- **时区**: UTC (存储), 应用层转换
|
||||
|
||||
---
|
||||
|
||||
## 二、实体关系图
|
||||
|
||||
```
|
||||
┌────────────────┐ ┌────────────────┐
|
||||
│ users │ │ products │
|
||||
├────────────────┤ ├────────────────┤
|
||||
│ id (PK) │◄──────│ user_id (FK) │
|
||||
│ wechat_openid │ │ id (PK) │
|
||||
│ phone │ │ name │
|
||||
│ username │ │ name_en │
|
||||
│ password_hash │ │ description │
|
||||
│ tier │ │ category │
|
||||
│ is_active │ │ price │
|
||||
│ settings (JSON)│ │ keywords (JSON)│
|
||||
│ created_at │ │ specifications │
|
||||
└───────┬────────┘ └────────────────┘
|
||||
│
|
||||
│ 1:N
|
||||
▼
|
||||
┌────────────────┐ ┌────────────────┐
|
||||
│ customers │ │ quotations │
|
||||
├────────────────┤ ├────────────────┤
|
||||
│ id (PK) │ │ id (PK) │
|
||||
│ user_id (FK) │ │ user_id (FK) │
|
||||
│ name │ │ customer_id(FK)│
|
||||
│ company │ │ title │
|
||||
│ country │ │ status │
|
||||
│ phone │ │ currency │
|
||||
│ whatsapp_id │ │ subtotal │
|
||||
│ status │ │ total │
|
||||
│ last_contact_at│ │ ... │
|
||||
└───────┬────────┘ └────────────────┘
|
||||
│
|
||||
│ 1:N
|
||||
▼
|
||||
┌────────────────┐ ┌────────────────┐
|
||||
│ conversations │ │ quotation_items│
|
||||
├────────────────┤ ├────────────────┤
|
||||
│ id (PK) │ │ id (PK) │
|
||||
│ user_id (FK) │ │ quotation_id │
|
||||
│ customer_id(FK)│ │ product_name │
|
||||
│ channel │ │ quantity │
|
||||
│ status │ │ unit_price │
|
||||
│ message_count │ │ total_price │
|
||||
└───────┬────────┘ └────────────────┘
|
||||
│
|
||||
│ 1:N
|
||||
▼
|
||||
┌────────────────┐
|
||||
│ messages │
|
||||
├────────────────┤
|
||||
│ id (PK) │
|
||||
│ conversation_id│
|
||||
│ direction │
|
||||
│ content │
|
||||
│ content_translt│
|
||||
│ ai_suggestions │
|
||||
└────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、表结构定义
|
||||
|
||||
### 3.1 用户表 (users)
|
||||
|
||||
```sql
|
||||
CREATE TABLE users (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
wechat_openid VARCHAR(255) UNIQUE,
|
||||
phone VARCHAR(20) UNIQUE,
|
||||
username VARCHAR(100),
|
||||
password_hash VARCHAR(255),
|
||||
tier VARCHAR(50) DEFAULT 'free',
|
||||
is_active BOOLEAN DEFAULT true,
|
||||
settings JSONB DEFAULT '{"preferred_translate_provider": "auto", "reply_tone": "professional"}',
|
||||
created_at TIMESTAMP DEFAULT NOW(),
|
||||
updated_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
|
||||
CREATE INDEX idx_users_wechat ON users(wechat_openid);
|
||||
CREATE INDEX idx_users_phone ON users(phone);
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | UUID | 主键 |
|
||||
| wechat_openid | VARCHAR | 微信 OpenID (唯一) |
|
||||
| phone | VARCHAR | 手机号 (唯一) |
|
||||
| username | VARCHAR | 用户名 |
|
||||
| password_hash | VARCHAR | 密码 bcrypt 哈希 |
|
||||
| tier | VARCHAR | 订阅等级: free/pro/enterprise |
|
||||
| is_active | BOOLEAN | 账户状态 |
|
||||
| settings | JSONB | 用户偏好设置 |
|
||||
|
||||
---
|
||||
|
||||
### 3.2 产品表 (products)
|
||||
|
||||
```sql
|
||||
CREATE TABLE products (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
name VARCHAR(255) NOT NULL,
|
||||
name_en VARCHAR(255),
|
||||
description TEXT,
|
||||
description_en TEXT,
|
||||
category VARCHAR(100),
|
||||
price VARCHAR(50),
|
||||
price_unit VARCHAR(20) DEFAULT 'USD',
|
||||
moq VARCHAR(50),
|
||||
keywords JSONB DEFAULT '[]',
|
||||
specifications JSONB DEFAULT '{}',
|
||||
images JSONB DEFAULT '[]',
|
||||
is_active BOOLEAN DEFAULT true,
|
||||
created_at TIMESTAMP DEFAULT NOW(),
|
||||
updated_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
|
||||
CREATE INDEX idx_products_user ON products(user_id);
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | UUID | 主键 |
|
||||
| user_id | UUID | 所属用户 |
|
||||
| name | VARCHAR | 产品名称 (中文) |
|
||||
| name_en | VARCHAR | 产品英文名 |
|
||||
| description | TEXT | 产品描述 |
|
||||
| price | VARCHAR | 价格 |
|
||||
| moq | VARCHAR | 最小起订量 |
|
||||
| keywords | JSONB | 关键词列表 |
|
||||
|
||||
---
|
||||
|
||||
### 3.3 客户表 (customers)
|
||||
|
||||
```sql
|
||||
CREATE TABLE customers (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
name VARCHAR(255) NOT NULL,
|
||||
company VARCHAR(255),
|
||||
country VARCHAR(100),
|
||||
phone VARCHAR(50),
|
||||
email VARCHAR(255),
|
||||
whatsapp_id VARCHAR(255),
|
||||
source VARCHAR(100),
|
||||
tags JSONB DEFAULT '[]',
|
||||
notes TEXT,
|
||||
preference JSONB DEFAULT '{}',
|
||||
status VARCHAR(50) DEFAULT 'lead',
|
||||
last_contact_at TIMESTAMP,
|
||||
silence_started_at TIMESTAMP,
|
||||
next_followup_at TIMESTAMP,
|
||||
estimated_value VARCHAR(50),
|
||||
created_at TIMESTAMP DEFAULT NOW(),
|
||||
updated_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
|
||||
CREATE INDEX idx_customers_user ON customers(user_id);
|
||||
CREATE INDEX idx_customers_status ON customers(status);
|
||||
CREATE INDEX idx_customers_last_contact ON customers(last_contact_at);
|
||||
```
|
||||
|
||||
**status 枚举值**:
|
||||
- `lead`: 潜在客户
|
||||
- `negotiating`: 谈判中
|
||||
- `customer`: 已成交客户
|
||||
- `lost`: 丢失客户
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | UUID | 主键 |
|
||||
| user_id | UUID | 所属用户 |
|
||||
| name | VARCHAR | 客户姓名 |
|
||||
| whatsapp_id | VARCHAR | WhatsApp ID |
|
||||
| status | VARCHAR | 客户状态 |
|
||||
| last_contact_at | TIMESTAMP | 最后联系时间 |
|
||||
| silence_started_at | TIMESTAMP | 沉默开始时间 |
|
||||
| next_followup_at | TIMESTAMP | 下次跟进时间 |
|
||||
|
||||
---
|
||||
|
||||
### 3.4 对话表 (conversations)
|
||||
|
||||
```sql
|
||||
CREATE TABLE conversations (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
customer_id UUID NOT NULL REFERENCES customers(id) ON DELETE CASCADE,
|
||||
channel VARCHAR(50) DEFAULT 'whatsapp',
|
||||
topic VARCHAR(255),
|
||||
status VARCHAR(50) DEFAULT 'active',
|
||||
message_count INTEGER DEFAULT 0,
|
||||
last_message_at TIMESTAMP,
|
||||
created_at TIMESTAMP DEFAULT NOW(),
|
||||
updated_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
|
||||
CREATE INDEX idx_conversations_user ON conversations(user_id);
|
||||
CREATE INDEX idx_conversations_customer ON conversations(customer_id);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.5 消息表 (messages)
|
||||
|
||||
```sql
|
||||
CREATE TABLE messages (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
conversation_id UUID NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
|
||||
direction VARCHAR(20) NOT NULL,
|
||||
content TEXT NOT NULL,
|
||||
content_translated TEXT,
|
||||
content_type VARCHAR(50) DEFAULT 'text',
|
||||
ai_suggestions JSONB,
|
||||
selected_suggestion INTEGER,
|
||||
user_edited TEXT,
|
||||
status VARCHAR(50) DEFAULT 'sent',
|
||||
metadata JSONB DEFAULT '{}',
|
||||
created_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
|
||||
CREATE INDEX idx_messages_conversation ON messages(conversation_id);
|
||||
```
|
||||
|
||||
**direction 枚举值**:
|
||||
- `inbound`: 客户发来
|
||||
- `outbound`: 用户发出
|
||||
|
||||
---
|
||||
|
||||
### 3.6 报价单表 (quotations)
|
||||
|
||||
```sql
|
||||
CREATE TABLE quotations (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
customer_id UUID REFERENCES customers(id),
|
||||
title VARCHAR(255),
|
||||
status VARCHAR(50) DEFAULT 'draft',
|
||||
currency VARCHAR(10) DEFAULT 'USD',
|
||||
exchange_rate FLOAT,
|
||||
payment_terms VARCHAR(255),
|
||||
delivery_terms VARCHAR(255),
|
||||
lead_time VARCHAR(100),
|
||||
valid_until VARCHAR(100),
|
||||
subtotal FLOAT,
|
||||
discount FLOAT DEFAULT 0,
|
||||
shipping FLOAT DEFAULT 0,
|
||||
total FLOAT,
|
||||
notes TEXT,
|
||||
pdf_url TEXT,
|
||||
sent_at TIMESTAMP,
|
||||
created_at TIMESTAMP DEFAULT NOW(),
|
||||
updated_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
|
||||
CREATE INDEX idx_quotations_user ON quotations(user_id);
|
||||
CREATE INDEX idx_quotations_customer ON quotations(customer_id);
|
||||
CREATE INDEX idx_quotations_status ON quotations(status);
|
||||
```
|
||||
|
||||
**status 枚举值**:
|
||||
- `draft`: 草稿
|
||||
- `sent`: 已发送
|
||||
- `accepted`: 已接受
|
||||
- `rejected`: 已拒绝
|
||||
- `expired`: 已过期
|
||||
|
||||
---
|
||||
|
||||
### 3.7 报价单项表 (quotation_items)
|
||||
|
||||
```sql
|
||||
CREATE TABLE quotation_items (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
quotation_id UUID NOT NULL REFERENCES quotations(id) ON DELETE CASCADE,
|
||||
product_name VARCHAR(255) NOT NULL,
|
||||
description TEXT,
|
||||
quantity INTEGER NOT NULL,
|
||||
unit_price FLOAT NOT NULL,
|
||||
total_price FLOAT,
|
||||
unit VARCHAR(50) DEFAULT 'pcs'
|
||||
);
|
||||
|
||||
CREATE INDEX idx_quotation_items_quotation ON quotation_items(quotation_id);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.8 语料库表 (corpus_entries)
|
||||
|
||||
```sql
|
||||
CREATE TABLE corpus_entries (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
source_text TEXT NOT NULL,
|
||||
target_text TEXT NOT NULL,
|
||||
source_lang VARCHAR(20),
|
||||
target_lang VARCHAR(20),
|
||||
task_type VARCHAR(50) NOT NULL,
|
||||
domain VARCHAR(100) DEFAULT 'general',
|
||||
provider_used VARCHAR(50),
|
||||
quality_score FLOAT DEFAULT 0.5,
|
||||
user_edited BOOLEAN DEFAULT false,
|
||||
user_rating INTEGER,
|
||||
usage_count INTEGER DEFAULT 0,
|
||||
embedding VECTOR(768),
|
||||
metadata JSONB DEFAULT '{}',
|
||||
created_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
|
||||
CREATE INDEX idx_corpus_task ON corpus_entries(task_type);
|
||||
CREATE INDEX idx_corpus_domain ON corpus_entries(domain);
|
||||
CREATE INDEX idx_corpus_embedding ON corpus_entries USING ivfflat (embedding vector_cosine_ops);
|
||||
```
|
||||
|
||||
**task_type 枚举值**:
|
||||
- `translation`: 翻译
|
||||
- `reply_suggestion`: 回复建议
|
||||
- `marketing_copy`: 营销文案
|
||||
|
||||
---
|
||||
|
||||
## 四、pgvector 扩展
|
||||
|
||||
```sql
|
||||
CREATE EXTENSION IF NOT EXISTS vector;
|
||||
```
|
||||
|
||||
语料库表使用向量存储，支持语义相似度搜索：
|
||||
|
||||
```sql
|
||||
-- 查找相似翻译
|
||||
SELECT * FROM corpus_entries
|
||||
WHERE task_type = 'translation'
|
||||
ORDER BY embedding <=> query_embedding
|
||||
LIMIT 5;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、索引策略
|
||||
|
||||
| 表 | 索引 | 用途 |
|
||||
|---|------|------|
|
||||
| users | wechat_openid, phone | 登录查询 |
|
||||
| products | user_id | 用户产品列表 |
|
||||
| customers | user_id, status, last_contact_at | 客户列表、沉默检测 |
|
||||
| conversations | user_id, customer_id | 对话查询 |
|
||||
| messages | conversation_id | 消息历史 |
|
||||
| quotations | user_id, customer_id, status | 报价单管理 |
|
||||
| corpus_entries | task_type, domain, embedding | 语料检索 |
|
||||
|
||||
---
|
||||
|
||||
## 六、数据保留策略
|
||||
|
||||
| 数据类型 | 保留期限 | 原因 |
|
||||
|---------|---------|------|
|
||||
| 用户数据 | 永久 | 业务核心 |
|
||||
| 客户数据 | 永久 | 业务核心 |
|
||||
| 消息数据 | 2年 | 对话历史 |
|
||||
| 报价单数据 | 3年 | 订单追溯 |
|
||||
| 语料数据 | 永久 | AI训练 |
|
||||
| 日志数据 | 90天 | 调试审计 |
|
||||
|
||||
---
|
||||
|
||||
## 七、迁移脚本
|
||||
|
||||
使用 Alembic 进行数据库迁移，初始迁移见 `backend/alembic/versions/001_initial.py`。
|
||||
@@ -0,0 +1,250 @@
|
||||
# 外贸小助手 (TradeMate) — 产品设计文档
|
||||
|
||||
> 版本: v1.0
|
||||
> 创建日期: 2026-05-08
|
||||
> 状态: 初始设计
|
||||
|
||||
---
|
||||
|
||||
## 一、产品定位
|
||||
|
||||
### 1.1 一句话定义
|
||||
|
||||
> **微信里的外贸成交助理——帮不懂英文、不懂营销的中小企业，把客户询盘变成订单。**
|
||||
|
||||
### 1.2 目标用户
|
||||
|
||||
| 画像 | 特征 | 典型场景 |
|
||||
|------|------|---------|
|
||||
| **个体外贸SOHO** | 1-2人，什么都自己干 | 每天都在回WhatsApp消息，顾不上主动开发客户 |
|
||||
| **小型外贸公司老板** | 10-30人，团队没有专业营销 | 员工英文一般，发了开发信没人回复就不知道怎么继续 |
|
||||
| **工厂转型外贸** | 原来做内销，刚开阿里国际站 | 有产品优势，但不会写英文文案，不知道怎么跟老外沟通 |
|
||||
|
||||
### 1.3 核心洞察
|
||||
|
||||
外贸成交的本质是三个动作：
|
||||
```
|
||||
收到询盘 → 看懂意思 → 回复报价 → 跟进催单
|
||||
↑ ↑
|
||||
用户卡在这里 用户卡在这里
|
||||
（英文不好） （不知道怎么跟进）
|
||||
```
|
||||
|
||||
**我们只解决这三件事，别的都不做。**
|
||||
|
||||
---
|
||||
|
||||
## 二、功能设计
|
||||
|
||||
### 2.1 功能全景图
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ 外贸小助手 │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ 营销素材 │ │ 智能沟通 │ │ 客户跟进 │ │
|
||||
│ │ 工厂 │ │ 助手 │ │ 引擎 │ │
|
||||
│ ├──────────┤ ├──────────┤ ├──────────┤ │
|
||||
│ │ 开发信 │ │ 消息翻译 │ │ 沉默检测 │ │
|
||||
│ │ 产品文案 │ │ 回复建议 │ │ 跟进提醒 │ │
|
||||
│ │ 关键词 │ │ 一键发送 │ │ 话术推荐 │ │
|
||||
│ │ 竞品分析 │ │ 语气调整 │ │ 周期提醒 │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────┐ │
|
||||
│ │ 跨功能支撑: 报价单生成 / 汇率换算 │ │
|
||||
│ └─────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2.2 功能一：营销素材工厂（帮用户"有内容可发"）
|
||||
|
||||
#### 用户场景
|
||||
> "我想给美国客户发邮件推广我的户外折叠椅，但我不知道英文怎么写，也不知道怎么写才有吸引力。"
|
||||
|
||||
#### 交互流程
|
||||
|
||||
```
|
||||
[用户打开小程序]
|
||||
└─ 点击"营销素材"
|
||||
└─ 输入: "户外折叠椅，承重150kg，防水面料，带杯架和扶手"
|
||||
└─ 选择: ①英文开发信 ②WhatsApp开场白 ③产品描述 ④关键词建议
|
||||
└─ AI生成→用户左右滑动筛选→保存→一键复制
|
||||
|
||||
[用户过几天再来]
|
||||
└─ 点击"换一批" → AI 基于同样产品生成不同角度的话术
|
||||
└─ 点击"效果追踪" → 可以看到哪些文案被复制/发送了多少次
|
||||
```
|
||||
|
||||
#### 核心机制
|
||||
|
||||
- 每个用户有自己的**产品库**（首次输入后系统保存）
|
||||
- 同一个产品可以生成不同风格（正式/亲切/促销）
|
||||
- 不同目标国家生成适配当地习惯的文案
|
||||
- **关键**: AI 不是一次性生成，而是持续迭代——用户保存的文案越多，系统越懂用户的偏好风格
|
||||
|
||||
### 2.3 功能二：智能沟通助手（帮用户"看懂+回好"）
|
||||
|
||||
#### 用户场景
|
||||
> "客户在WhatsApp发了一大段英文，我大概能看懂一些，但不知道怎么回，怕写错了让客户觉得不专业。"
|
||||
|
||||
#### 交互流程
|
||||
|
||||
```
|
||||
[客户发来 WhatsApp 消息]
|
||||
└─ 系统自动翻译成中文（显示在客户消息下方）
|
||||
└─ 同时给出 3 个回复选项:
|
||||
① 快速报价（如果消息是询价）
|
||||
② 专业回复（通用商务场景）
|
||||
③ 亲切回复（如果客户是老客户）
|
||||
└─ 用户选择一个 → 自动填入对话输入框 → 用户可编辑 → 发送
|
||||
|
||||
[用户主动发起]
|
||||
└─ 打开小程序 → 输入中文 → 选择语气 → AI 翻译成英文
|
||||
└─ 支持: 文字转语音（方便用户确认发音）
|
||||
```
|
||||
|
||||
#### 核心机制
|
||||
|
||||
- **翻译质量领先**：结合 DeepL + OpenAI + 外贸术语库，翻译"MOQ、FOB、lead time"等术语准确
|
||||
- **回复建议有上下文**：基于聊天历史 + 产品库 + 客户画像，不是通用 ChatGPT 式回复
|
||||
- **用户微调记录**：用户每次编辑 AI 建议后再发送，系统记录差异，未来建议自动适配用户风格
|
||||
|
||||
#### 翻译 vs 回复建议 的边界
|
||||
|
||||
| 场景 | 做什么 | 用哪个引擎 |
|
||||
|------|--------|-----------|
|
||||
| 用户想看懂客户消息 | 翻译（直译，保留原意） | DeepL（准确） |
|
||||
| 用户想回复客户 | 生成回复建议（意译，优化表达） | OpenAI/Claude（生成质量高） |
|
||||
| 用户想写营销文案 | 生成创意内容 | Claude（写作最优） |
|
||||
| 用户需要正式报价 | 生成结构化报价单 | OpenAI（结构化能力强） |
|
||||
|
||||
### 2.4 功能三：客户跟进引擎（帮用户"不丢单"）
|
||||
|
||||
#### 用户场景
|
||||
> "上周报完价客户就没消息了，我也不知道该不该再发消息，发了怕烦到客户，不发怕被别人抢走。"
|
||||
|
||||
#### 交互流程
|
||||
|
||||
```
|
||||
[系统自动检测]
|
||||
└─ 客户沉默 3 天 → 推送提醒:
|
||||
"客户 Carlos (墨西哥) 已沉默3天，建议发送跟进消息"
|
||||
└─ 提供跟进话术（基于上次聊天内容定制）
|
||||
|
||||
└─ 客户沉默 7 天 → 升级提醒:
|
||||
"客户已沉默1周，建议发送限时优惠或新产品信息"
|
||||
└─ 提供促销话术 + 可选折扣模板
|
||||
|
||||
[用户主动查看]
|
||||
└─ 打开"客户"页面 → 按沉默天数排序
|
||||
└─ 每个客户显示: 最后联系时间、沉默天数、建议动作
|
||||
└─ 一键发送跟进消息
|
||||
```
|
||||
|
||||
#### 核心机制
|
||||
|
||||
- **沉默检测规则**：
|
||||
- 3天无回复 = 轻度沉默 → 跟进提醒
|
||||
- 7天无回复 = 中度沉默 → 升级提醒 + 提供优惠话术
|
||||
- 14天无回复 = 重度沉默 → 建议换话题（发新品/行业资讯/节日问候）
|
||||
- **行业基准对比**：跨用户匿名统计不同国家客户的回复率基线，帮助判断"这个客户是不是真的没意向"
|
||||
- **最佳发送时间**：基于历史数据推荐（如拉美客户下午3-5点回复率高）
|
||||
|
||||
### 2.5 跨功能支撑：报价单生成
|
||||
|
||||
#### 场景
|
||||
> "客户问价格了，我得赶紧报个价。但报价单要用英文写，还要算运费、汇率……"
|
||||
|
||||
#### 功能
|
||||
|
||||
```
|
||||
客户说 "How much for 500pcs FOB Shanghai?"
|
||||
|
||||
系统:
|
||||
- 识别出:FOB上海、500件、询价
|
||||
- 自动调取用户产品库里的价格（$12.5/pc）
|
||||
- 显示当前汇率（USD/CNY）
|
||||
- 生成报价草稿:
|
||||
"FOB Shanghai: $12.5/pc
|
||||
Total: $6,250
|
||||
Lead time: 25 days
|
||||
Payment: T/T 30% deposit"
|
||||
- 用户确认 → 生成正式报价单图片 → 一键发送
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、用户旅程
|
||||
|
||||
### 3.1 首次使用（30秒上手）
|
||||
|
||||
```
|
||||
1. 扫码打开小程序 → 微信授权登录
|
||||
2. 输入产品信息（中文）: "你主要卖什么？"
|
||||
└─ 示例: "户外折叠椅，主要出口欧美"
|
||||
3. 系统自动:
|
||||
├─ 生成 5 条开发信模板
|
||||
├─ 生成 5 条 WhatsApp 开场白
|
||||
└─ 保存产品到我的产品库
|
||||
4. 引导到"客户"页面 → 提示"可以导入或手动添加客户"
|
||||
5. 完成。全程 < 30 秒。
|
||||
```
|
||||
|
||||
### 3.2 日常使用
|
||||
|
||||
```
|
||||
早上:
|
||||
└─ 打开小程序 → 看"待跟进"列表 → 选择1-2个客户发跟进消息
|
||||
|
||||
白天:
|
||||
└─ WhatsApp 收到消息 → 切到小程序翻译 → 复制回复
|
||||
|
||||
晚上:
|
||||
└─ 打开小程序 → 看今日概览（回复了几个客户、几个沉默）→ 准备明天的跟进
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、数据模型概要
|
||||
|
||||
| 实体 | 核心字段 | 用途 |
|
||||
|------|---------|------|
|
||||
| 用户 | tier, 产品库 | 账户+订阅 |
|
||||
| 产品 | 名称, 描述, 价格, 规格, 关键词 | 用户自己的产品信息 |
|
||||
| 客户 | 姓名, 国家, WhatsApp, 来源, 标签 | 客户管理 |
|
||||
| 对话 | 消息, 翻译, 回复, 状态 | 沟通记录 |
|
||||
| 报价单 | 产品, 数量, 价格, 条款, 状态 | 报价管理 |
|
||||
| 语料条目 | 源文, 译文, 领域, 质量评分 | AI 训练数据 |
|
||||
|
||||
---
|
||||
|
||||
## 五、护城河策略
|
||||
|
||||
详见 `TECH_ARCHITECTURE.md` 第 5 章，核心三层：
|
||||
|
||||
1. **外贸垂直语料库**：用户每次使用产生的翻译/回复数据，积累成行业专属语料
|
||||
2. **用户产品知识库**：产品信息+客户偏好+历史报价，迁移成本极高
|
||||
3. **沉默客户模式算法**：跨用户行为数据产生的预测能力，网络效应
|
||||
|
||||
---
|
||||
|
||||
## 六、盈利模式
|
||||
|
||||
| 层级 | 价格 | 能力 |
|
||||
|------|------|------|
|
||||
| 免费版 | ¥0 | 1个产品、20次翻译/天、5个客户、基础回复建议 |
|
||||
| Pro版 | ¥99/月 | 10个产品、无限翻译、50个客户、跟进提醒、报价单 |
|
||||
| 企业版 | ¥399/月 | 无限产品、多人协作、品牌报价单、专属语料训练、API |
|
||||
|
||||
---
|
||||
|
||||
## 七、路线图
|
||||
|
||||
| 阶段 | 时间 | 功能 |
|
||||
|------|------|------|
|
||||
| MVP | 第1-4周 | 智能翻译+回复建议+基础营销素材+产品库 |
|
||||
| V2 | 第5-8周 | 沉默客户跟进+WhatsApp集成+报价单生成 |
|
||||
| V3 | 第9-12周 | 语料库训练+回复质量优化+多人协作 |
|
||||
| V4 | 第13-16周 | 跨用户A/B测试+预测算法+API开放 |
|
||||
@@ -0,0 +1,235 @@
|
||||
# 外贸小助手 (TradeMate) — 项目进度文档
|
||||
|
||||
> 版本: v1.0
|
||||
> 更新日期: 2026-05-08
|
||||
> 状态: MVP开发中
|
||||
|
||||
---
|
||||
|
||||
## 一、项目概述
|
||||
|
||||
**项目名称**: 外贸小助手 (TradeMate)
|
||||
**项目类型**: 微信小程序 + 后端API
|
||||
**目标用户**: 外贸SOHO、小型外贸公司、工厂转型外贸
|
||||
|
||||
---
|
||||
|
||||
## 二、功能实现总览
|
||||
|
||||
### 2.1 已完成功能 ✅
|
||||
|
||||
| 功能模块 | 后端API | 前端页面 | 状态 |
|
||||
|---------|---------|---------|------|
|
||||
| **用户认证** | /auth/register, login, refresh, me, settings | 登录页 | ✅ |
|
||||
| **智能翻译** | /translate, /reply, /extract, /feedback | 翻译页 | ✅ |
|
||||
| **回复建议** | /translate/reply (3种语气) | 翻译页 | ✅ |
|
||||
| **营销素材** | /marketing/generate, /keywords, /competitor-analysis | 营销页 | ✅ |
|
||||
| **客户管理** | /customers CRUD, /silent, /conversation | 客户页 | ✅ |
|
||||
| **沉默检测** | /customers/silent (3/7/14天) | 客户页 | ✅ |
|
||||
| **报价单** | /quotations CRUD, /status | 报价页 | ✅ |
|
||||
| **产品库** | /products CRUD | 产品页 | ✅ |
|
||||
| **汇率换算** | /exchange/convert, /rates | (待集成) | ✅ |
|
||||
| **推送通知** | /push/register, /send, /devices | (uni-push) | ✅ |
|
||||
| **WhatsApp** | /whatsapp/webhook, /send, /qr | (框架) | ✅ |
|
||||
| **定时任务** | Celery tasks | - | ✅ |
|
||||
|
||||
**前端页面**:
|
||||
- 登录页 (pages/login)
|
||||
- 首页仪表盘 (pages/index)
|
||||
- 翻译+回复 (pages/translate)
|
||||
- 客户管理 (pages/customers)
|
||||
- 营销素材 (pages/marketing)
|
||||
- 报价单 (pages/quotation)
|
||||
- 产品库 (pages/product)
|
||||
- 自定义TabBar
|
||||
|
||||
### 2.2 未完成功能 ❌
|
||||
|
||||
| 功能 | 优先级 | 说明 |
|
||||
|------|--------|------|
|
||||
| **微信登录** | 高 | 需配置微信开放平台OAuth |
|
||||
| **WhatsApp真实集成** | 高 | 需注册Meta Business，配置真实API |
|
||||
| **报价单PDF生成** | 中 | 需集成 weasyprint 库 |
|
||||
| **文字转语音(TTS)** | 中 | uni-app 有对应API |
|
||||
| **批量导入客户** | 中 | 需集成文件上传+xlsx解析 |
|
||||
| **Web管理后台** | 低 | 设计中有，未实现 |
|
||||
| **数据分析报表** | 低 | 首页数据目前为模拟 |
|
||||
| **多人协作/团队** | 低 | 企业版功能 |
|
||||
| **语料库训练** | 低 | V3功能，仅框架 |
|
||||
|
||||
### 2.3 缺失文档
|
||||
|
||||
- [x] 产品设计文档 (PRODUCT_DESIGN.md)
|
||||
- [x] 技术架构文档 (TECH_ARCHITECTURE.md)
|
||||
- [x] API设计文档 (API_DESIGN.md)
|
||||
- [x] 数据库设计文档 (DATABASE_SCHEMA.md)
|
||||
- [ ] 项目进度文档 (本文档) ✅
|
||||
|
||||
---
|
||||
|
||||
## 三、技术栈
|
||||
|
||||
### 3.1 后端
|
||||
|
||||
| 技术 | 版本 | 用途 |
|
||||
|------|------|------|
|
||||
| Python | 3.11+ | 运行环境 |
|
||||
| FastAPI | latest | Web框架 |
|
||||
| SQLAlchemy | 2.0+ | ORM |
|
||||
| PostgreSQL | 15 | 主数据库 |
|
||||
| pgvector | latest | 向量数据库 |
|
||||
| Redis | 7 | 缓存/队列 |
|
||||
| Celery | 5.0+ | 定时任务 |
|
||||
| AI Providers | - | DeepL/OpenAI/Claude |
|
||||
|
||||
### 3.2 前端
|
||||
|
||||
| 技术 | 版本 | 用途 |
|
||||
|------|------|------|
|
||||
| uni-app | 3.0+ | 跨端框架 |
|
||||
| Vue | 3.4+ | UI框架 |
|
||||
| Sass/SCSS | - | 样式预处理 |
|
||||
| uni-push | 2.0 | 推送服务 |
|
||||
|
||||
### 3.3 部署
|
||||
|
||||
| 技术 | 用途 |
|
||||
|------|------|
|
||||
| Docker | 容器化 |
|
||||
| Docker Compose | 编排 |
|
||||
| Nginx | 反向代理 |
|
||||
| Systemd | 进程管理 |
|
||||
|
||||
---
|
||||
|
||||
## 四、目录结构
|
||||
|
||||
```
|
||||
trade-assistant/
|
||||
├── docs/ # 设计文档
|
||||
│ ├── PRODUCT_DESIGN.md # 产品设计
|
||||
│ ├── TECH_ARCHITECTURE.md # 技术架构
|
||||
│ ├── API_DESIGN.md # API接口
|
||||
│ ├── DATABASE_SCHEMA.md # 数据库设计
|
||||
│ └── PROJECT_STATUS.md # 项目进度
|
||||
│
|
||||
├── backend/ # Python后端
|
||||
│ ├── app/
|
||||
│ │ ├── main.py # FastAPI入口
|
||||
│ │ ├── config.py # 配置
|
||||
│ │ ├── database.py # 数据库连接
|
||||
│ │ ├── celery_app.py # Celery配置
|
||||
│ │ ├── models/ # 数据模型
|
||||
│ │ │ ├── user.py # 用户+产品
|
||||
│ │ │ ├── customer.py # 客户+对话+消息
|
||||
│ │ │ ├── quotation.py # 报价单+明细
|
||||
│ │ │ └── corpus.py # 语料库
|
||||
│ │ ├── api/v1/ # REST API
|
||||
│ │ │ ├── auth.py # 认证
|
||||
│ │ │ ├── translate.py # 翻译
|
||||
│ │ │ ├── marketing.py # 营销
|
||||
│ │ │ ├── customer.py # 客户
|
||||
│ │ │ ├── quotation.py # 报价单
|
||||
│ │ │ ├── product.py # 产品
|
||||
│ │ │ ├── exchange.py # 汇率
|
||||
│ │ │ ├── push.py # 推送
|
||||
│ │ │ └── whatsapp.py # WhatsApp
|
||||
│ │ ├── services/ # 业务逻辑
|
||||
│ │ ├── ai/ # AI抽象层
|
||||
│ │ │ ├── router.py # 智能路由
|
||||
│ │ │ ├── trade_corpus.py # 语料库
|
||||
│ │ │ └── providers/ # 各引擎实现
|
||||
│ │ ├── core/ # 核心组件
|
||||
│ │ │ ├── security.py # JWT认证
|
||||
│ │ │ ├── exceptions.py # 异常处理
|
||||
│ │ │ └── middleware.py # 中间件
|
||||
│ │ └── workers/ # Celery任务
|
||||
│ │ └── tasks.py
|
||||
│ ├── alembic/ # 数据库迁移
|
||||
│ ├── requirements.txt
|
||||
│ ├── Dockerfile
|
||||
│ └── .env.example
|
||||
│
|
||||
├── uni-app/ # uni-app前端
|
||||
│ ├── src/
|
||||
│ │ ├── pages/ # 页面
|
||||
│ │ │ ├── login/ # 登录
|
||||
│ │ │ ├── index/ # 首页
|
||||
│ │ │ ├── translate/ # 翻译
|
||||
│ │ │ ├── customers/ # 客户
|
||||
│ │ │ ├── marketing/ # 营销
|
||||
│ │ │ ├── quotation/ # 报价单
|
||||
│ │ │ └── product/ # 产品库
|
||||
│ │ ├── components/ # 组件
|
||||
│ │ │ └── tabbar/ # 自定义TabBar
|
||||
│ │ ├── utils/ # 工具
|
||||
│ │ │ ├── api.js # API封装
|
||||
│ │ │ └── push.js # 推送服务
|
||||
│ │ ├── static/ # 静态资源
|
||||
│ │ ├── App.vue # 应用入口
|
||||
│ │ ├── main.js # Vue初始化
|
||||
│ │ └── pages.json # 页面配置
|
||||
│ ├── package.json
|
||||
│ └── vite.config.js
|
||||
│
|
||||
├── miniprogram/ # 微信小程序(原生-已弃用)
|
||||
│
|
||||
├── docker-compose.yml # Docker编排
|
||||
├── nginx/ # Nginx配置
|
||||
├── scripts/ # 运维脚本
|
||||
├── systemd/ # Systemd服务
|
||||
└── data/ # 数据目录
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、待办事项
|
||||
|
||||
### 5.1 高优先级 (MVP)
|
||||
|
||||
- [ ] 配置微信登录OAuth
|
||||
- [ ] 配置WhatsApp Cloud API真实环境
|
||||
- [ ] 集成PDF生成库 (weasyprint)
|
||||
- [ ] 添加批量客户导入功能
|
||||
|
||||
### 5.2 中优先级 (V2)
|
||||
|
||||
- [ ] 添加文字转语音(TTS)功能
|
||||
- [ ] 实现Web管理后台基础功能
|
||||
- [ ] 数据分析图表集成
|
||||
|
||||
### 5.3 低优先级 (V3+)
|
||||
|
||||
- [ ] 团队/多人协作功能
|
||||
- [ ] 语料库训练模型
|
||||
- [ ] API开放平台
|
||||
|
||||
---
|
||||
|
||||
## 六、部署说明
|
||||
|
||||
### 开发环境
|
||||
|
||||
```bash
|
||||
# 启动后端
|
||||
cd backend
|
||||
docker-compose up -d
|
||||
|
||||
# 启动前端
|
||||
cd uni-app
|
||||
npm install
|
||||
npm run dev:mp-weixin
|
||||
```
|
||||
|
||||
### 生产环境
|
||||
|
||||
详见 `scripts/deploy.sh` 和 systemd 配置
|
||||
|
||||
---
|
||||
|
||||
## 七、相关文档链接
|
||||
|
||||
- [产品设计](./PRODUCT_DESIGN.md)
|
||||
- [技术架构](./TECH_ARCHITECTURE.md)
|
||||
- [API设计](./API_DESIGN.md)
|
||||
- [数据库设计](./DATABASE_SCHEMA.md)
|
||||
@@ -0,0 +1,361 @@
|
||||
# 外贸小助手 (TradeMate) — 技术架构文档
|
||||
|
||||
> 版本: v1.0
|
||||
> 创建日期: 2026-05-08
|
||||
|
||||
---
|
||||
|
||||
## 一、系统架构总览
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
│ 客户端层 │
|
||||
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
||||
│ │ 微信小程序 │ │ Web后台 │ │ WhatsApp │ │
|
||||
│ │ (主入口) │ │ (管理用) │ │ 原生客户端 │ │
|
||||
│ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ │
|
||||
└─────────┼───────────────┼────────────────┼───────────┘
|
||||
│ HTTP/JSON │ HTTP/JSON │ WhatsApp
|
||||
│ │ │ Cloud API
|
||||
┌─────────┼───────────────┼────────────────┼───────────┐
|
||||
│ ┌┴──────────────┴────────────────┴┐ │
|
||||
│ │ API Gateway (FastAPI) │ │
|
||||
│ │ - 认证 (JWT + WeChat OAuth) │ │
|
||||
│ │ - 用户 tier 中间件 │ │
|
||||
│ │ - 配额控制中间件 │ │
|
||||
│ └────────────────┬─────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────────────┼─────────────────┐ │
|
||||
│ │ │ │ │
|
||||
│ ┌─────┴─────┐ ┌──────┴──────┐ ┌───────┴──────┐ │
|
||||
│ │ 业务服务 │ │ AI 服务 │ │ WhatsApp │ │
|
||||
│ │ │ │ 抽象层 │ │ 集成服务 │ │
|
||||
│ │ - 营销素材 │ │ - Provider │ │ - 消息收发 │ │
|
||||
│ │ - 翻译回复 │ │ - Router │ │ - Webhook │ │
|
||||
│ │ - 客户跟进 │ │ - 语料库 │ │ - 会话管理 │ │
|
||||
│ │ - 报价单 │ │ - 成本控制 │ │ │ │
|
||||
│ └─────┬─────┘ └──────┬──────┘ └──────┬───────┘ │
|
||||
│ │ │ │ │
|
||||
│ ┌─────┴─────────────────┴─────────────────┴──────┐ │
|
||||
│ │ 数据层 │ │
|
||||
│ │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │
|
||||
│ │ │PostgreSQL│ │ Redis │ │ 文件存储 │ │ │
|
||||
│ │ │+pgvector │ │ (缓存) │ │ (报价单PDF) │ │ │
|
||||
│ │ └──────────┘ └──────────┘ └──────────────┘ │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
└────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、技术栈选型
|
||||
|
||||
| 层级 | 技术 | 选型理由 |
|
||||
|------|------|---------|
|
||||
| 客户端 | 微信小程序 | 触达成本最低，中国外贸商家几乎100%使用微信 |
|
||||
| 后端 | FastAPI (Python 3.11+) | 异步性能好，类型安全，生态成熟 |
|
||||
| 主数据库 | PostgreSQL 15 + pgvector | 结构化数据 + 向量检索（语料库语义搜索） |
|
||||
| 缓存 | Redis 7 | 会话缓存、配额计数、任务队列 |
|
||||
| 任务队列 | Celery + Redis broker | 异步翻译、批量语料处理 |
|
||||
| AI Provider | DeepL + OpenAI + Claude + 本地模型 | 按场景路由，成本优化 |
|
||||
| WhatsApp | WhatsApp Cloud API | 官方API，合规稳定 |
|
||||
| 部署 | Docker + Docker Compose | 一键部署，环境一致 |
|
||||
|
||||
---
|
||||
|
||||
## 三、目录结构
|
||||
|
||||
```
|
||||
trade-assistant/
|
||||
├── docs/ # 设计文档
|
||||
│ ├── PRODUCT_DESIGN.md
|
||||
│ ├── TECH_ARCHITECTURE.md
|
||||
│ ├── API_DESIGN.md # API 接口设计
|
||||
│ └── DATABASE_SCHEMA.md # 数据库设计
|
||||
│
|
||||
├── backend/ # Python 后端
|
||||
│ ├── app/
|
||||
│ │ ├── main.py # FastAPI 入口
|
||||
│ │ ├── config.py # 配置管理
|
||||
│ │ ├── database.py # 数据库连接
|
||||
│ │ │
|
||||
│ │ ├── models/ # SQLAlchemy 数据模型
|
||||
│ │ │ ├── user.py
|
||||
│ │ │ ├── product.py
|
||||
│ │ │ ├── customer.py
|
||||
│ │ │ ├── conversation.py
|
||||
│ │ │ ├── quotation.py
|
||||
│ │ │ └── corpus.py
|
||||
│ │ │
|
||||
│ │ ├── api/v1/ # REST API 路由
|
||||
│ │ │ ├── auth.py # 认证
|
||||
│ │ │ ├── marketing.py # 营销素材
|
||||
│ │ │ ├── translate.py # 翻译与回复
|
||||
│ │ │ ├── customer.py # 客户管理
|
||||
│ │ │ ├── quotation.py # 报价单
|
||||
│ │ │ └── whatsapp.py # WhatsApp 集成
|
||||
│ │ │
|
||||
│ │ ├── services/ # 业务逻辑层
|
||||
│ │ │ ├── marketing.py # 营销素材生成
|
||||
│ │ │ ├── translation.py # 翻译+回复引擎
|
||||
│ │ │ ├── customer.py # 客户跟进引擎
|
||||
│ │ │ ├── quotation.py # 报价单服务
|
||||
│ │ │ └── whatsapp.py # WhatsApp 服务
|
||||
│ │ │
|
||||
│ │ ├── ai/ # AI 抽象层
|
||||
│ │ │ ├── base.py # Provider 接口
|
||||
│ │ │ ├── router.py # 智能路由+fallback
|
||||
│ │ │ ├── trade_corpus.py # 外贸语料库
|
||||
│ │ │ └── providers/ # 各引擎实现
|
||||
│ │ │ ├── openai.py
|
||||
│ │ │ ├── claude.py
|
||||
│ │ │ ├── deepl.py
|
||||
│ │ │ └── local.py
|
||||
│ │ │
|
||||
│ │ ├── core/ # 核心基础设施
|
||||
│ │ │ ├── security.py # JWT + 加密
|
||||
│ │ │ ├── exceptions.py # 异常处理
|
||||
│ │ │ └── middleware.py # 中间件
|
||||
│ │ │
|
||||
│ │ └── workers/ # Celery 任务
|
||||
│ │ └── tasks.py
|
||||
│ │
|
||||
│ ├── alembic/ # 数据库迁移
|
||||
│ ├── requirements.txt
|
||||
│ ├── Dockerfile
|
||||
│ └── .env.example
|
||||
│
|
||||
├── miniprogram/ # 微信小程序
|
||||
│ ├── app.js / app.json / app.wxss
|
||||
│ ├── pages/
|
||||
│ │ ├── index/ # 首页仪表盘
|
||||
│ │ ├── translate/ # 翻译+回复
|
||||
│ │ ├── customers/ # 客户管理
|
||||
│ │ ├── marketing/ # 营销素材
|
||||
│ │ └── quotation/ # 报价单
|
||||
│ ├── components/ # 通用组件
|
||||
│ └── utils/ # 工具函数
|
||||
│
|
||||
├── data/ # 数据存储
|
||||
│ ├── corpus/ # 外贸语料库文件
|
||||
│ └── models/ # 微调模型占位
|
||||
│
|
||||
├── scripts/ # 运维脚本
|
||||
├── docker-compose.yml
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、AI 服务架构（核心）
|
||||
|
||||
### 4.1 Provider 抽象层
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ AIRouter │
|
||||
│ │
|
||||
│ execute(task_type, method, *args, **kwargs) │
|
||||
│ │
|
||||
│ 1. 根据 task_type 获取优先级列表 │
|
||||
│ 2. 按优先级依次尝试 provider │
|
||||
│ 3. 失败自动 fallback 到下一个 │
|
||||
│ 4. 记录每次调用的 provider、token、耗时、成本 │
|
||||
│ 5. 将结果存入语料库（如果质量达标） │
|
||||
└──────────┬──────────┬──────────┬──────────┬──────────┘
|
||||
│ │ │ │
|
||||
┌──────┴──┐ ┌───┴────┐ ┌───┴────┐ ┌───┴──────┐
|
||||
│ OpenAI │ │ Claude │ │ DeepL │ │ Local │
|
||||
│ Provider│ │Provider│ │Provider│ │Provider │
|
||||
└─────────┘ └────────┘ └────────┘ └──────────┘
|
||||
```
|
||||
|
||||
### 4.2 路由规则
|
||||
|
||||
| 任务类型 | 主引擎 | Fallback | 成本策略 |
|
||||
|---------|--------|---------|---------|
|
||||
| 翻译（看懂） | DeepL | OpenAI → 本地 | 优先低成本 |
|
||||
| 回复建议 | OpenAI GPT-4o | Claude → 本地 | 质量优先 |
|
||||
| 营销文案 | Claude | OpenAI → 本地 | 质量优先 |
|
||||
| 结构化提取 | OpenAI GPT-4o | Claude | 结构化能力优先 |
|
||||
| 语料训练 | 本地（离线） | - | 零成本 |
|
||||
|
||||
### 4.3 语料库架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ TradeCorpus │
|
||||
│ │
|
||||
│ 收集: │
|
||||
│ ├─ 用户翻译记录（原文→译文，用户是否编辑过） │
|
||||
│ ├─ 用户选择的回复（用户从N个AI建议中选了哪个） │
|
||||
│ ├─ 用户点赞/点踩的反馈 │
|
||||
│ └─ 用户最终发出的版本（可能是AI建议+用户修改） │
|
||||
│ │
|
||||
│ 存储: │
|
||||
│ ├─ PostgreSQL (结构化: 源文, 译文, 领域, 评分) │
|
||||
│ └─ pgvector (语义向量, 用于相似翻译检索) │
|
||||
│ │
|
||||
│ 使用: │
|
||||
│ ├─ 运行时: 相似翻译召回 → 做 few-shot prompt │
|
||||
│ ├─ 离线: 训练专用翻译模型（用户量 >1万后启动） │
|
||||
│ └─ 质量评估: 持续评估各 provider 的质量分数 │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、护城河实现策略
|
||||
|
||||
### 5.1 外贸垂直语料库（数据壁垒）
|
||||
|
||||
**数据采集点**（在用户流程中无感埋点）：
|
||||
|
||||
```
|
||||
用户操作 → 系统记录
|
||||
────────────────────────────────────────
|
||||
用户输入中文要翻译 → 原文
|
||||
用户选择了某个回复建议 → 被选中的建议 + 未被选中的建议
|
||||
用户修改了AI建议再发送 → AI原文 + 用户修改版本
|
||||
用户点了赞/点踩 → 质量标签
|
||||
用户复制了某条营销文案 → 文案被使用的统计
|
||||
```
|
||||
|
||||
**语料库达到 10 万条后的效果**：
|
||||
- 翻译时从语料库检索相似度 >90% 的历史翻译，直接复用或做 few-shot
|
||||
- 回复建议不再是通用 prompt，而是"过去100个类似询盘的回复模式"
|
||||
- 新用户冷启动时直接受益于存量语料
|
||||
|
||||
### 5.2 用户产品知识库（迁移成本壁垒）
|
||||
|
||||
用户存入的数据是不可替代的资产：
|
||||
|
||||
```
|
||||
用户产品库:
|
||||
├─ 产品名称/描述（双语）
|
||||
├─ 价格表（不同客户不同价）
|
||||
├─ 规格参数
|
||||
├─ 产品图片
|
||||
└─ 关键词（多语言）
|
||||
|
||||
客户画像:
|
||||
├─ 基本信息（国家/公司/职位）
|
||||
├─ 沟通偏好（正式/亲切）
|
||||
├─ 历史价格
|
||||
├─ 付款习惯
|
||||
└─ 砍价风格
|
||||
|
||||
→ 换平台 = 所有数据重录
|
||||
→ 用户用得越久，走得越难
|
||||
```
|
||||
|
||||
### 5.3 沉默客户模式算法（网络效应）
|
||||
|
||||
```
|
||||
输入:
|
||||
- 本用户的客户沉默时长
|
||||
- 跨用户匿名统计的"不同国家客户回复率时间分布"
|
||||
- 历史成功跟进的话术模式
|
||||
|
||||
输出:
|
||||
- 最佳跟进时间
|
||||
- 最高回复率的话术类型
|
||||
- 客户"可能还有意向"的概率评分
|
||||
|
||||
网络效应:
|
||||
- 用户A的墨西哥客户跟进数据 → 改善用户B的墨西哥客户跟进建议
|
||||
- 用户越多，预测越准
|
||||
- 新用户直接获得"过去100个相似案例的最佳实践"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、配额与计费系统
|
||||
|
||||
### 6.1 计费计量点
|
||||
|
||||
```
|
||||
┌──────────────┬────────────┬───────────────┐
|
||||
│ 功能 │ 计量单位 │ 免费版限制 │
|
||||
├──────────────┼────────────┼───────────────┤
|
||||
│ 翻译 │ 字符数 │ 5000/天 │
|
||||
│ 回复建议 │ 请求次数 │ 20次/天 │
|
||||
│ 营销文案生成 │ 请求次数 │ 5次/天 │
|
||||
│ 报价单生成 │ 份数 │ 3份/天 │
|
||||
│ 客户管理 │ 客户数 │ 5个 │
|
||||
│ 跟进提醒 │ - │ 仅沉默检测 │
|
||||
└──────────────┴────────────┴───────────────┘
|
||||
```
|
||||
|
||||
### 6.2 实现架构
|
||||
|
||||
```
|
||||
用户请求 → tier middleware → quota middleware → 业务逻辑
|
||||
│ │
|
||||
↓ ↓
|
||||
User.tier Redis INCR user:daily_count
|
||||
控制功能可用性 检查是否超限
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、WhatsApp 集成架构
|
||||
|
||||
```
|
||||
WhatsApp User WhatsApp Cloud API TradeMate Backend
|
||||
│ │ │
|
||||
│ 发送消息 │ │
|
||||
│ ────────────────────────────────► │ │
|
||||
│ │ Webhook POST /webhook/whatsapp │
|
||||
│ │ ────────────────────────────────► │
|
||||
│ │ │
|
||||
│ │ 1. 验证 Webhook signature │
|
||||
│ │ 2. 解析消息内容 + 发送者信息 │
|
||||
│ │ 3. 调用翻译服务（用户可配置） │
|
||||
│ │ 4. 存储到 conversations 表 │
|
||||
│ │ 5. 检查是否触发沉默检测更新 │
|
||||
│ │ 6. 返回 200 OK │
|
||||
│ │ │
|
||||
│ 回复消息 │ POST /messages (通过 Cloud API) │
|
||||
│ ◄──────────────────────────────── │ ──── 用户在小程序确认回复后 ────► │
|
||||
│ │ │
|
||||
```
|
||||
|
||||
**注意**：WhatsApp Cloud API 要求企业通过 Meta Business 认证，初始阶段可以使用用户手动复制消息到 WhatsApp 的方式替代，降低启动门槛。
|
||||
|
||||
---
|
||||
|
||||
## 八、安全设计
|
||||
|
||||
| 维度 | 措施 |
|
||||
|------|------|
|
||||
| 认证 | JWT + 微信 OAuth + refresh token 轮换 |
|
||||
| API 安全 | 全站 HTTPS、请求签名校验、rate limiting |
|
||||
| 数据安全 | 密码 bcrypt 哈希、敏感配置环境变量注入 |
|
||||
| AI API Key | 仅服务端持有，不暴露给前端 |
|
||||
| 用户隔离 | 所有查询强制 user_id 过滤 |
|
||||
| WhatsApp | Webhook signature 验证、消息内容不落日志 |
|
||||
|
||||
---
|
||||
|
||||
## 九、部署架构
|
||||
|
||||
```
|
||||
开发环境: docker-compose up（单机）
|
||||
├─ backend:8000
|
||||
├─ postgres:5432
|
||||
├─ redis:6379
|
||||
└─ celery-worker
|
||||
|
||||
生产环境: 阿里云/腾讯云轻量服务器
|
||||
├─ Nginx 反代 + SSL
|
||||
├─ systemd 管理 backend + celery
|
||||
├─ PostgreSQL 走内网
|
||||
└─ Redis 走内网
|
||||
|
||||
关键指标:
|
||||
├─ API 响应: < 200ms (p95)
|
||||
├─ 翻译延迟: < 2s (p95)
|
||||
├─ 并发用户: 500+（单实例）
|
||||
└─ 可用性: 99.5%
|
||||
```
|
||||
Reference in New Issue
Block a user