# 🏗️ 神射手系统架构图

> 📅 更新: 2026-01-31
> 🎯 版本: v1.3.0

---

## 一、系统总览

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           神射手数据中台 v1.3                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│  │  数据概览   │    │  数据接入   │    │  标签画像   │    │  AI Agent   │  │
│  │  首页AI对话 │    │  数据源管理 │    │  标签管理   │    │  渠道配置   │  │
│  │  数据统计   │    │  AI标签引擎 │    │  用户画像   │    │  AI打标     │  │
│  │             │    │  清洗规则   │    │  人群圈选   │    │  AI清洗     │  │
│  │             │    │  任务调度   │    │  流量池     │    │  智能报告   │  │
│  │             │    │  数据血缘   │    │             │    │             │  │
│  └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘  │
│                                                                             │
│  ┌─────────────┐                                                            │
│  │  数据市场   │                                                            │
│  │  API服务    │                                                            │
│  │  流量包管理 │                                                            │
│  └─────────────┘                                                            │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 二、技术架构

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              客户端层                                        │
├─────────────────────────────────────────────────────────────────────────────┤
│  浏览器 (Web)     │   飞书机器人    │   企业微信    │   API调用方           │
└────────┬──────────┴────────┬────────┴───────┬───────┴──────────┬────────────┘
         │                   │                │                  │
         ▼                   ▼                ▼                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              网关层                                          │
├─────────────────────────────────────────────────────────────────────────────┤
│  Next.js 14 (localhost:3001)          │  FastAPI Gateway (卡若AI)          │
│  - 前端页面                            │  - /feishu/events                   │
│  - /api/* 接口                         │  - /wecom/callback                  │
│  - SSR渲染                             │  - /shensheshou/*                   │
└────────┬────────────────────────────────┴──────────────────────┬────────────┘
         │                                                       │
         ▼                                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              服务层                                          │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌───────────────────┐    ┌───────────────────┐    ┌───────────────────┐   │
│  │   用户查询服务     │    │   标签引擎服务     │    │   AI对话服务      │   │
│  │   - 手机号查询     │    │   - RFM计算        │    │   - 意图识别      │   │
│  │   - QQ号查询       │    │   - 用户分级       │    │   - 数据拆解      │   │
│  │   - 智能搜索       │    │   - 标签生成       │    │   - 画像输出      │   │
│  └───────────────────┘    └───────────────────┘    └───────────────────┘   │
│                                                                             │
│  ┌───────────────────┐    ┌───────────────────┐    ┌───────────────────┐   │
│  │   流量池服务       │    │   数据清洗服务     │    │   报告生成服务    │   │
│  │   - 人群圈选       │    │   - 手机号格式化   │    │   - 日报/周报     │   │
│  │   - 流量包管理     │    │   - 数据去重       │    │   - AI分析报告    │   │
│  │   - 导出功能       │    │   - 质量评估       │    │   - 模板管理      │   │
│  └───────────────────┘    └───────────────────┘    └───────────────────┘   │
│                                                                             │
└────────┬────────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              数据层                                          │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                        MongoDB (localhost:27017)                     │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐       │   │
│  │  │   KR    │ │KR_腾讯  │ │KR_微博  │ │KR_京东  │ │KR_存客宝│ ...  │   │
│  │  │ 4.7GB  │ │ 62.5GB │ │ 18.7GB │ │ 20.1GB │ │ 0.44GB │       │   │
│  │  │用户估值│ │QQ+手机 │ │UID+手机│ │ 消费  │ │用户资产│       │   │
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘       │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  总计: 26个数据库 | 20.13亿条记录 | 222GB存储                               │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 三、数据流向

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  数据源     │ ──▶ │  AI标签引擎 │ ──▶ │  用户估值   │ ──▶ │  流量池     │
│  KR_腾讯    │     │  字段拆解   │     │  RFM计算    │     │  人群分层   │
│  KR_微博    │     │  数据清洗   │     │  等级划分   │     │  标签筛选   │
│  KR_京东    │     │  标签生成   │     │  画像合并   │     │  流量包输出 │
│  KR_存客宝  │     │             │     │             │     │             │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
       │                   │                   │                   │
       │                   │                   │                   │
       ▼                   ▼                   ▼                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              KR.用户估值 (核心表)                            │
├─────────────────────────────────────────────────────────────────────────────┤
│  phone          │  user_evaluation_score  │  unified_tags  │  traffic_pool │
│  phone_masked   │  rfm_scores             │  source_channels│  user_level   │
│  name           │  data_quality           │  merge_evidence │  created_at   │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 四、API架构

```
/api/
├── ai-chat/              # AI智能对话
│   ├── GET  → 获取状态
│   └── POST → 发送查询
│
├── data-sources/         # 数据源管理
│   ├── GET  → 列表+统计
│   └── POST → 连接测试
│
├── tags/                 # 标签服务
│   └── GET  → 标签统计
│
├── portrait/             # 用户画像
│   └── GET  → 画像查询
│
├── traffic-packages/     # 流量池
│   ├── GET  → 池统计
│   └── POST → 创建流量包
│
├── crowd-pools/          # 人群圈选
│   └── GET  → 项目/池/用户
│
├── database-structure/   # 数据库结构
│   └── GET  → 血缘数据
│
└── monitoring/           # 系统监控
    └── GET  → 健康状态
```

---

## 五、GitHub参考项目

### 5.1 Tracardi CDP
- **仓库**: github.com/tracardi/tracardi
- **星数**: 621+
- **技术**: Python + FastAPI + Elasticsearch
- **可借鉴**:
  - Profile合并算法
  - 事件处理工作流
  - 插件架构设计

### 5.2 Crowd.dev
- **仓库**: github.com/CrowdDotDev/crowd.dev
- **星数**: 3.3k+
- **技术**: TypeScript + PostgreSQL
- **可借鉴**:
  - 社区数据整合
  - 活跃度计算
  - 成员画像

### 5.3 借鉴要点

| 功能 | 参考项目 | 核心代码 |
|------|----------|----------|
| 用户合并 | Tracardi | profile/merger.py |
| 事件追踪 | Tracardi | domain/event.py |
| 标签计算 | Tracardi | process/tagging.py |
| 活跃度 | Crowd.dev | services/member.ts |

---

## 六、优化方向

### 6.1 性能优化
```yaml
当前问题:
  - 大表查询慢 (>10s)
  - 内存占用高

解决方案:
  - $sample采样 ✅ 已实施
  - 索引优化
  - 分页查询
  - 缓存层
```

### 6.2 架构优化
```yaml
计划:
  - 引入Redis缓存热点数据
  - 分离读写库
  - 增加消息队列(RabbitMQ)
```

---

## 七、部署架构

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              生产环境                                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌───────────────────┐    ┌───────────────────┐    ┌───────────────────┐   │
│  │   Nginx反向代理   │ ──▶│   Next.js服务     │ ──▶│   MongoDB集群     │   │
│  │   SSL证书         │    │   PM2进程管理     │    │   Docker容器      │   │
│  │   负载均衡        │    │   端口:3001       │    │   端口:27017      │   │
│  └───────────────────┘    └───────────────────┘    └───────────────────┘   │
│         │                                                                   │
│         ▼                                                                   │
│  ┌───────────────────┐                                                      │
│  │   FastAPI网关     │                                                      │
│  │   飞书/企微回调   │                                                      │
│  │   端口:8000       │                                                      │
│  └───────────────────┘                                                      │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```