# 神射手数据中台 - 项目核心文档

> 📅 最后更新：2026-01-31 18:30
> 🎯 项目阶段：P3 执行
> 🟢 健康状态：正常

---

## 📊 项目概览

| 项目 | 信息 |
|:---|:---|
| 项目名称 | 神射手数据中台 |
| 项目描述 | 用户资产数字化中台，整合20亿+用户数据的查询、标签、画像和流量池管理 |
| 开始日期 | 2026-01-29 |
| 目标日期 | 2026-02-07 |
| 当前阶段 | P3 执行 |
| 负责人 | 卡若AI |
| 前端路径 | `/Users/karuo/Documents/开发/2、私域银行/神射手` |
| 后端Skill | `/Users/karuo/Documents/个人/卡若AI/04_卡火（火）/_团队成员/火炬/神射手/SKILL.md` |

---

## 🔧 技术栈

```yaml
前端:
  框架: Next.js 14
  UI库: Radix UI + TailwindCSS
  图表: Recharts
  状态: React Hooks (useState, useEffect)
  风格: 苹果毛玻璃 (backdrop-blur + bg-white/80)

后端:
  数据库: MongoDB (Docker localhost:27017)
  认证: admin / admin123
  API: Next.js API Routes (25个端点)
  网关: 卡若AI FastAPI Gateway

数据规模:
  总数据库: 26个KR_*库
  总用户数: 20.13亿条
  总容量: 222GB
```

---

## 📁 项目结构

```
神射手/
├── app/                          # Next.js App Router
│   ├── page.tsx                  # 首页 - AI对话
│   ├── data-ingestion/           # 数据接入模块
│   │   ├── sources/              # 数据源管理
│   │   ├── ai-engine/            # AI标签引擎
│   │   ├── cleaning/             # 清洗规则
│   │   ├── tasks/                # 任务调度
│   │   └── lineage/              # 数据血缘
│   ├── tag-portrait/             # 标签画像模块
│   │   ├── tags/                 # 标签管理
│   │   ├── portrait/             # 用户画像
│   │   └── crowd/                # 人群圈选
│   ├── ai-agent/                 # AI Agent模块
│   │   ├── channels/             # 渠道配置
│   │   ├── smart-tag/            # AI打标
│   │   ├── data-cleaning/        # AI清洗
│   │   └── report/               # 智能报告
│   ├── data-market/              # 数据市场模块
│   │   ├── packages/             # 流量包管理
│   │   └── api/                  # API服务
│   ├── monitoring/               # 系统监控模块
│   └── api/                      # API路由 (25个)
├── lib/
│   └── mongodb.ts                # MongoDB连接器
├── components/                   # 公共组件
├── .apm/                         # 项目管理工作区
│   ├── project-state.md          # 项目状态
│   ├── execution-table.md        # 执行表
│   ├── conversation-log.md       # 对话记录
│   └── docs/architecture.md      # 架构图
└── 开发文档/                      # 开发文档
    ├── 00_项目核心文档.md         # 本文档
    ├── 01_开发进度文档.md         # 进度跟踪
    └── 02_提示词文档.md           # 提示词存档
```

---

## 🌐 API清单 (25个端点)

### 核心API

| 路由 | 方法 | 功能 | 状态 |
|:-----|:-----|:-----|:----:|
| `/api/ai-chat` | GET/POST | AI智能对话、系统状态 | ✅ |
| `/api/data-sources` | GET/POST | 数据源管理、连接测试 | ✅ |
| `/api/tags` | GET/POST | 标签统计、标签创建 | ✅ |
| `/api/portrait` | GET/POST | 用户画像、人群分布 | ✅ |
| `/api/traffic-packages` | GET/POST | 流量池、流量包导出 | ✅ |
| `/api/crowd-pools` | GET | 人群圈选按项目 | ✅ |
| `/api/database-structure` | GET | 数据库结构、血缘节点 | ✅ |
| `/api/monitoring` | GET | 系统监控、健康检查 | ✅ |
| `/api/channels` | GET/POST | 渠道对接、飞书集成 | ✅ |

### 辅助API

| 路由 | 方法 | 功能 |
|:-----|:-----|:-----|
| `/api/users` | GET | 用户列表查询 |
| `/api/search` | POST | 多条件搜索 |
| `/api/ai-tagging` | GET/POST | AI打标引擎 |
| `/api/cleaning-rules` | GET/POST | 清洗规则管理 |
| `/api/system-status` | GET | 系统状态 |
| `/api/rfm/*` | GET/POST | RFM分析系列 |

---

## 🗄️ 数据库结构

### 核心集合

| 集合 | 数据库 | 文档数 | 用途 |
|:-----|:-------|-------:|:-----|
| 用户估值 | KR | 1436万 | 统一画像、RFM评分 |
| QQ+手机 | KR_腾讯 | 7.05亿 | QQ↔手机关联 |
| 微博uid+手机 | KR_微博 | 2.17亿 | 微博UID↔手机 |
| 用户资产统一视图 | KR_存客宝 | 21.6万 | 存客宝用户 |
| 用户资产统一视图 | KR_点了码 | 1000 | 点了码用户 |

### 字段映射

```yaml
KR.用户估值:
  phone: '+8613407000001'           # 手机号
  phone_masked: '134****0001'       # 脱敏手机
  name: '姓名'                      # 姓名
  user_evaluation_score: 2227       # 估值分 (0-5000+)
  user_level: 'A'                   # 用户等级
  province: '广东'                  # 省份
  city: '深圳'                      # 城市
  source_channels: ['KR_手机']     # 数据来源
  unified_tags: ['高价值', '活跃']  # 统一标签
  traffic_pool: {pool_name: '黄金池'} # 流量池

KR_腾讯.QQ+手机:
  qq: '3520685418'                  # QQ号
  phone: '18879944144'              # 手机号
  QQ号评分: 100                     # QQ评分
  手机号评分: 470                   # 手机评分
  省份: '广西'                      # 省份
  运营商: '移动'                    # 运营商
```

---

## 🏷️ AI标签体系

### 标签分类

| 分类 | 标签示例 | 生成方式 |
|:-----|:---------|:---------|
| 价值标签 | S/A/B/C/D级用户 | RFM自动计算 |
| 行为标签 | 高频活跃、流失风险 | 行为分析 |
| 渠道标签 | 微信渠道、抖音渠道 | 数据来源 |
| 地域标签 | 一线城市、厦门本地 | 地址解析 |

### RFM评分规则

```
综合评分 = R×0.3 + F×0.3 + M×0.4

等级划分 (基于 user_evaluation_score):
├── 钻石池: ≥3000分
├── 黄金池: 2000-2999分
├── 白银池: 1000-1999分
├── 青铜池: 500-999分
└── 潜力池: <500分
```

---

## 🔗 外部集成

### 飞书机器人

```yaml
网关路径: /Users/karuo/Documents/个人/卡若AI/_共享模块/deploy/gateway/routers/feishu.py

API端点:
  - GET  /feishu/test          # 连接测试
  - GET  /feishu/chats         # 获取群列表
  - POST /feishu/send_message  # 发送消息
  - POST /feishu/send_minutes  # 发送会议纪要
  - POST /feishu/webhook       # 事件回调

环境变量:
  FEISHU_APP_ID: cli_xxxxx
  FEISHU_APP_SECRET: xxxxx
  FEISHU_VERIFICATION_TOKEN: xxxxx
```

### 企业微信

```yaml
网关路径: gateway/routers/wecom.py

API端点:
  - POST /wecom/callback       # 消息回调

环境变量:
  WECOM_CORP_ID: wwxxxxx
  WECOM_AGENT_ID: 1000002
  WECOM_SECRET: xxxxx
```

---

## 🚀 快速启动

```bash
# 1. 确认MongoDB运行
docker ps | grep mongo

# 2. 启动开发服务器（端口 3117）
cd /Users/karuo/Documents/开发/2、私域银行/神射手
pnpm dev   # 或 ./scripts/start.sh --kill（带端口冲突检查）

# 3. 访问
http://localhost:3117

# 4. 测试API
curl http://localhost:3117/api/ai-chat
curl http://localhost:3117/api/monitoring?action=health
```

---

## 📚 相关文档

| 文档 | 路径 | 用途 |
|:-----|:-----|:-----|
| **十目录索引** | `00_十目录索引.md` | 统一入口、跨目录联动 |
| 开发进度 | `01_开发进度文档.md` | 进度跟踪、任务管理 |
| 提示词存档 | `02_提示词文档.md` | 对话历史、提示词模板 |
| 项目状态 | `.apm/project-state.md` | 项目总览 |
| 执行表 | `.apm/execution-table.md` | 任务清单 |
| 架构图 | `.apm/docs/architecture.md` | 系统架构 |
| 后端Skill | `卡若AI/04_卡火/火炬/神射手/SKILL.md` | 后端能力 |
| Cursor规则 | `.cursor/rules/shensheshou.mdc` | 对话规范 |

### 十目录子文档（按 skill 规范）

| 目录 | 核心子文档 | 内容 |
|:---|:---|:---|
| 1-需求 | 核心需求提取.md | 用户故事、MVP边界 |
| 2-架构 | 核心架构逻辑.md | 四层架构、数据流向 |
| 3-原型 | 页面结构.md | 路由树、组件结构 |
| 4-前端 | 核心组件代码.md | AI对话、毛玻璃样式 |
| 5-接口 | API清单与核心逻辑.md | 25API、意图解析 |
| 6-后端 | MongoDB连接器核心.md | 连接池、跨库查询 |
| 7-数据库 | ER与查询逻辑.md | 集合结构、分桶逻辑 |
| 8-部署 | 启动与部署脚本.md | npm脚本、端口 |
| 9-手册 | 快速使用手册.md | 查询示例、FAQ |
| 10-管理 | 执行表.md | 任务映射、联动 |

---

*版本: v1.4.0 | 更新: 2026-01-31 | 维护: 卡若AI*