270 lines
8.6 KiB
Markdown
270 lines
8.6 KiB
Markdown
# 神射手数据中台 - 项目核心文档
|
||
|
||
> 📅 最后更新：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*
|