TradeMate Dev
c6206787da
项目结构: - backend/ Python FastAPI 后端 - uni-app/ uni-app跨端前端 - docs/ 设计文档 - docker-compose.yml Docker编排 - nginx/scripts/systemd 运维配置 已完成功能: - 用户认证 (JWT) - 智能翻译 + 回复建议 - 营销素材生成 - 客户管理 + 沉默检测 - 报价单管理 - 产品库管理 - 汇率换算 - 推送通知 (uni-push) - WhatsApp Webhook框架 - Celery定时任务
352 lines
7.5 KiB
Markdown
352 lines
7.5 KiB
Markdown
# 外贸小助手 (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>
|
||
``` |