alai-dev/trade-assistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 修复 H5 底部导航覆盖 + 更新项目进度文档

Browse Source 
## H5 底部导航修复 (Bug #10)
- 精简 App.vue，移除重复 tabbar，仅保留全局样式
- uni-page 设置 height: calc(100% - 50px) + overflow-y: auto
- 内容区域精确停在底部导航上方，独立滚动不再叠加
- 恢复 custom-tab-bar 组件

## 项目进度文档
- PROGRESS.md 更新至 10 个 Bug 修复
- 新增 H5 底部导航修复记录
- 新增历史变更条目
This commit is contained in:
TradeMate Dev
2026-05-12 20:24:42 +08:00
parent 69e164dcae
commit 7b62c2f8b4
125 changed files with 19725 additions and 728 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/TECH_ARCHITECTURE.md
+215 -4
View File
@@ -1,7 +1,8 @@
# 外贸小助手 (TradeMate) — 技术架构文档
> 版本: v1.0
> 创建日期: 2026-05-08
> 版本: v1.1
> 创建日期: 2026-05-10
> 更新: 新增客户健康度看板、AI跟进助手、市场机会分析三大模块
---
@@ -34,6 +35,8 @@
│ │ - 翻译回复 │ │ - Router │ │ - Webhook │ │
│ │ - 客户跟进 │ │ - 语料库 │ │ - 会话管理 │ │
│ │ - 报价单 │ │ - 成本控制 │ │ │ │
│ │ - 健康度 │ │ - 市场分析 │ │ │ │
│ │ - 跟进引擎 │ │ - 跟进策略 │ │ │ │
│ └─────┬─────┘ └──────┬──────┘ └──────┬───────┘ │
│ │ │ │ │
│ ┌─────┴─────────────────┴─────────────────┴──────┐ │
@@ -99,6 +102,9 @@ trade-assistant/
│ │ │ ├── marketing.py # 营销素材生成
│ │ │ ├── translation.py # 翻译+回复引擎
│ │ │ ├── customer.py # 客户跟进引擎
│ │ │ ├── customer_health.py # 客户健康度评分 (新增)
│ │ │ ├── followup_engine.py # AI跟进策略引擎 (新增)
│ │ │ ├── market_analysis.py # 市场机会分析 (新增)
│ │ │ ├── quotation.py # 报价单服务
│ │ │ └── whatsapp.py # WhatsApp 服务
│ │ │
@@ -325,7 +331,212 @@ WhatsApp User WhatsApp Cloud API TradeMate
---
## 八、安全设计
## 八、V2 新增模块架构
### 8.1 客户健康度看板
#### 评分模型
```
输入 → 多维度特征提取 → 加权评分 → 等级输出 → 行动建议
```
**评分维度与权重**:
| 维度 | 权重 | 数据源 | 计算方式 |
|------|------|--------|---------|
| 响应趋势 | 25% | messages | 近7天平均回复时长 vs 前7天，趋势上升加分 |
| 情感轨迹 | 20% | messages | AI分析最近3条客户消息情感极性（正面/负面/中性） |
| 询盘深度 | 20% | messages | 是否包含MOQ/认证/FOB/证书等成交信号关键词 |
| 沉默天数 | 20% | customers | 归一化得分: 1天=100, 14天+=0 |
| 商业价值 | 15% | quotations | 历史成交金额 + 当前在谈金额 |
**等级输出**:
| 分数区间 | 等级 | 颜色 | 建议动作 |
|---------|------|------|---------|
| 80-100 | 活跃 | 🟢 绿 | 保持正常跟进 |
| 50-79 | 需关注 | 🟡 黄 | 3天内安排跟进 |
| 0-49 | 高危 | 🔴 红 | 立即跟进，提供优惠或新产品信息 |
#### 技术实现
- **无需新模型**: 使用现有 `messages`、`customers`、`quotations` 表
- **轻量计算**: 无需 ML 模型，规则引擎即可，同步计算 < 50ms
- **异步更新**: Celery 定时任务每小时更新一次评分缓存到 Redis
- **API**: `GET /api/v1/customers/{id}/health` — 单个客户健康度
- **API**: `GET /api/v1/customers/health-overview` — 全量概览
### 8.2 AI 智能跟进引擎
#### 架构
```
┌────────────────────────────────────────────────────────────┐
│ FollowupEngine │
│ │
│ 1. 状态评估 │
│ └─ 读客户健康度 → 判断是否到跟进时机 │
│ │
│ 2. 策略选择 │
│ ├─ 沉默 3-5 天 → 温和提醒（"Just checking in"） │
│ ├─ 沉默 6-10 天 → 价值提供（"新品/行业资讯"） │
│ ├─ 沉默 11+ 天 → 重新激活（"限时优惠/调查问卷"） │
│ └─ 客户有回复但未成交 → 促进决策（"成功案例/限时"） │
│ │
│ 3. 内容生成 │
│ └─ AI 基于客户画像+产品库+历史对话生成个性化内容 │
│ │
│ 4. 渠道推荐 │
│ ├─ 历史互动中 WhatsApp 回复率>60% → WhatsApp │
│ ├─ 客户来自展会/邮件 → Email │
│ └─ 紧急/高价商机 → 建议电话 │
│ │
│ 5. 效果追踪 │
│ └─ 跟进后监控客户反应 → 更新策略模型 │
└────────────────────────────────────────────────────────────┘
```
#### 技术实现
- **跟进策略**: 基于规则的策略选择器（可扩展为强化学习）
- **内容生成**: 复用现有 AI 营销素材能力，注入客户上下文
- **渠道路由**: 基于 `customer.preference.channel` 和历史回复率
- **定时任务**: Celery beat 每 6 小时轮检所有客户
- **通知推送**: 检测到跟进时机 → 写入 notifications → PushService 推送
#### 数据模型
```python
class FollowupStrategy(Base):
"""跟进策略模板"""
__tablename__ = "followup_strategies"
id: UUID (PK)
user_id: UUID (nullable — null = 系统策略)
name: str # 策略名称
trigger_conditions: JSONB # 触发条件: {health_score_max, silence_days_min, ...}
channel: str # 推荐渠道
ai_prompt_template: str # AI提示词模板
min_interval_hours: int # 最短间隔
is_active: bool
success_count: int # 成功率统计
created_at: datetime
```
```python
class FollowupLog(Base):
"""跟进记录"""
__tablename__ = "followup_logs"
id: UUID (PK)
user_id: UUID
customer_id: UUID (FK)
strategy_id: UUID (FK → followup_strategies)
health_score_before: float # 跟进前健康分
suggested_content: Text # AI建议内容
actual_content: Text # 用户实际发送内容
channel: str # 使用的渠道
was_sent: bool # 是否已发送
customer_replied: bool # 客户是否回复
replied_within_hours: int # 回复间隔
created_at: datetime
```
### 8.3 智能市场机会分析
#### 架构
```
┌────────────────────────────────────────────────────────────┐
│ MarketAnalysisService │
│ │
│ 1. 市场趋势分析 │
│ └─ 调取 UN COMTRADE / ITC TradeMap API → 目标国进口趋势 │
│ │
│ 2. 客户发现 │
│ └─ Google Custom Search → B2B平台/行业黄页 → 潜在客户列表 │
│ │
│ 3. 竞争情报 │
│ └─ AI 分析竞品定价/卖点/市场定位 │
│ │
│ 4. 策略报告 │
│ └─ AI 综合生成: 市场选择→进入策略→风险提示→行动清单 │
└────────────────────────────────────────────────────────────┘
```
#### 数据源集成
| 数据源 | 集成方式 | 费率 |
|--------|---------|------|
| UN COMTRADE API | REST API (https://comtrade.un.org/api/) | 免费, 需注册 |
| ITC TradeMap | SOAP/REST (https://www.trademap.org/) | 免费基础查询 |
| Google Custom Search | JSON API (100次/天免费) | 免费~$5/1000次 |
| SerpAPI | Google搜索结果结构化 | $50/月 起 |
| AI 自有知识 | 已有模型知识 | 免费 |
**核心原则**: 所有数据源有免费层，上线初期零数据采购成本。
#### API 设计
```
POST /api/v1/market-analysis/opportunity
输入: { product_name, description, category, target_markets? }
输出: {
recommended_markets: [{ country, growth_rate, entry_strategy }],
potential_clients: [{ name, source, description }],
competitive_landscape: "分析文本",
strategy_report: "完整策略报告"
}
GET /api/v1/market-analysis/reports
列表用户历史报告
GET /api/v1/market-analysis/reports/{id}
获取报告详情
```
#### 关键设计决策
- **异步生成**: 报告生成可能需要 30-60 秒，使用 Celery 异步任务
- **缓存策略**: 相同产品+市场的报告缓存 7 天
- **渐进式展示**: 前端先显示 loading，各个模块完成后逐步展示（趋势数据先出 → 客户发现 → 报告）
- **用户引导**: 首次使用后提示"保存到产品库"或"一键生成开发信"
---
## 九、护城河策略（V2 更新）
V1 有三层护城河，V2 增加两层：
### 第 4 层: 客户健康度数据集
```
用户每日查看健康度 → 记录评分变化 → 验证建议有效性 → 优化评分模型
↓
跨用户匿名统计 → 行业基准对比
"你的客户健康度分布 vs 同行业用户的分布"
```
网络效应: 用户越多，行业基准越准，评分越有价值。
### 第 5 层: AI跟进策略知识库
```
每次跟进记录:
├─ 客户状态（评分/沉默天数/阶段）
├─ 跟进策略（时机/内容/渠道）
├─ 结果（回复/未回复/成交）
└─ 用户反馈
→ 积累到 1000+ 条后:
├─ 分析"什么策略在什么场景下最有效"
├─ 自动优化策略选择器
└─ 新用户直接受益于"过去1000次跟进的最佳实践"
```
---
## 十一、安全设计
| 维度 | 措施 |
|------|------|
@@ -338,7 +549,7 @@ WhatsApp User WhatsApp Cloud API TradeMate
---
## 九、部署架构
## 十二、部署架构
```
开发环境: docker-compose up（单机）