siyu-bank/shensheshou
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: 以本地为准，上传全部并替换 GitHub

Browse Source
This commit is contained in:
卡若
2026-02-03 11:36:53 +08:00
parent 1219166526
commit b404bf546e
131 changed files with 37618 additions and 3930 deletions
Download Patch File Download Diff File Expand all files Collapse all files

146
开发文档/00_十目录索引.md Normal file
View File

@@ -0,0 +1,146 @@
# 神射手数据中台 - 十目录统一索引
> 📅 更新: 2026-01-31
> 🎯 基于 dev-template-project-manager skill 规范
> 📋 各板块子文档统一维护
---
## 📁 目录结构
```
开发文档/
├── 00_十目录索引.md ← 本文档（统一入口）
├── 00_项目核心文档.md # 项目总览
├── 01_开发进度文档.md # 进度跟踪
├── 02_提示词文档.md # 提示词存档
│
├── 1、需求/ # CFO + 产品负责人
│ ├── _智能展开.md # 需求引擎激活
│ ├── 业务需求.md # 业务需求文档
│ ├── 核心需求提取.md # 从项目提取的核心需求 ← 新增
│ └── 成本.md # 成本估算
│
├── 2、架构/ # CTO + 架构师
│ ├── _智能展开.md # 架构引擎激活
│ ├── 系统架构.md # 架构图
│ ├── 核心架构逻辑.md # 从项目提取的架构逻辑 ← 新增
│ └── 技术选型.md # 技术栈
│
├── 3、原型/ # UI/UX 设计师
│ ├── _智能展开.md # 原型引擎激活
│ ├── 页面结构.md # 从项目提取的页面结构 ← 新增
│ └── 原型设计规范.md # 设计规范
│
├── 4、前端/ # 前端主程
│ ├── _智能展开.md # 前端引擎激活
│ ├── 核心组件代码.md # 从项目提取的核心代码 ← 新增
│ └── 前端开发规范.md # 开发规范
│
├── 5、接口/ # API 架构师
│ ├── _智能展开.md # 接口引擎激活
│ ├── API清单与核心逻辑.md # 从项目提取的API逻辑 ← 新增
│ └── 接口定义规范.md # 接口规范
│
├── 6、后端/ # Python 架构师
│ ├── _智能展开.md # 后端引擎激活
│ ├── MongoDB连接器核心.md # 从项目提取的lib/mongodb逻辑 ← 新增
│ └── 后端开发规范.md # 开发规范
│
├── 7、数据库/ # DBA
│ ├── _智能展开.md # 数据库引擎激活
│ ├── ER与查询逻辑.md # 从项目提取的集合与查询 ← 新增
│ └── 数据库管理规范.md # 管理规范
│
├── 8、部署/ # DevOps
│ ├── _智能展开.md # 部署引擎激活
│ ├── 启动与部署脚本.md # 从项目提取的部署逻辑 ← 新增
│ └── 自动化部署流程.md # 部署流程
│
├── 9、手册/ # 技术文档专家
│ ├── _智能展开.md # 手册引擎激活
│ ├── 快速使用手册.md # 从项目提取的使用说明 ← 新增
│ └── 说明手册提示词.md # 手册模板
│
└── 10、项目管理/ # 高级 PM
├── _智能展开.md # 管理引擎激活
├── 执行表.md # 任务清单（链接.apm）
└── 项目管理提示词.md # 管理模板
```
---
## 🔗 跨目录联动
```mermaid
graph TB
A[1、需求] --> B[2、架构]
A --> C[3、原型]
B --> D[5、接口]
B --> E[7、数据库]
D --> F[4、前端]
D --> G[6、后端]
E --> G
F --> H[8、部署]
G --> H
H --> I[9、手册]
A --> J[10、项目管理]
B --> J
F --> J
G --> J
```
---
## 📋 快速指令
| 目录 | 激活指令 | 输出 |
|:---:|:---|:---|
| 1 | `@需求引擎 展开 [需求描述]` | 业务需求文档 |
| 2 | `@架构引擎 展开 [模块名]` | 系统架构图 |
| 3 | `@原型引擎 展开 [页面名]` | 页面结构 |
| 4 | `@前端引擎 展开 [组件名]` | React 组件代码 |
| 5 | `@接口引擎 展开 [API名]` | API 文档 |
| 6 | `@后端引擎 展开 [服务名]` | 后端代码 |
| 7 | `@数据库引擎 展开 [集合名]` | ER 图 |
| 8 | `@部署引擎 展开` | 部署脚本 |
| 9 | `@手册引擎 展开 [模块名]` | 用户手册 |
| 10 | `@项目管理 查看进度` | 执行表 |
---
## 📂 核心代码提取清单
| 目录 | 提取文件 | 核心逻辑 |
|:---|:---|:---|
| 1-需求 | PRD/对话记录 | 5大模块、用户资产数字化 |
| 2-架构 | .apm/docs/architecture.md | 四层架构、数据流向 |
| 3-原型 | app/ 路由结构 | 5模块+子页面 |
| 4-前端 | app/page.tsx, components/ | AI对话、卡片、布局 |
| 5-接口 | app/api/*/route.ts | 25个API、意图解析 |
| 6-后端 | lib/mongodb.ts | 连接池、查询、归一化 |
| 7-数据库 | KR.用户估值等 | 集合结构、字段映射 |
| 8-部署 | package.json, next.config | npm脚本、端口 |
| 9-手册 | SKILL.md | 快速开始、查询示例 |
| 10-管理 | .apm/execution-table.md | 31任务、里程碑 |
---
---
## 十、运行与端口
```bash
# 启动神射手
cd 神射手 && npm run dev -- -p 3001
# 端口说明
# 3001: 神射手前端（保留）
# 27017: MongoDB（保留）
# 8000: 卡若AI网关（保留）
# 3000、3002: 已关闭
```
---
*版本: v1.1 | 更新: 2026-01-31 | 维护: 卡若AI*

269
开发文档/00_项目核心文档.md Normal file
View File

@@ -0,0 +1,269 @@
# 神射手数据中台 - 项目核心文档
> 📅 最后更新：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*

190
开发文档/01_开发进度文档.md Normal file
View File

@@ -0,0 +1,190 @@
# 神射手数据中台 - 开发进度
> 📅 最后更新：2026-01-31 18:30
> 🎯 项目阶段：P3 执行
> 🟢 健康状态：正常
---
## 📈 进度摘要
| 指标 | 数值 |
|:---|:---|
| 总任务数 | 30 |
| 已完成 | 28 (93%) |
| 进行中 | 1 |
| 待开始 | 1 |
| 阻塞中 | 0 |
### 进度条
`[██████████████████░░] 93%`
---
## 🎯 当前里程碑
| 里程碑 | 目标日期 | 状态 | 交付物 |
|:---|:---|:---:|:---|
| M1 基础框架 | 01-29 | ✅ | Next.js项目+MongoDB连接 |
| M2 核心功能 | 01-30 | ✅ | 5大模块前端页面 |
| M3 真实数据 | 01-31 | ✅ | API对接真实数据库 |
| M4 外部集成 | 02-03 | 🔄 | 飞书/企微对接 |
| M5 正式上线 | 02-07 | ⏳ | 生产环境部署 |
---
## ⚠️ 当前风险/阻碍
| 问题 | 严重度 | 状态 | 处理方案 |
|:---|:---:|:---:|:---|
| 飞书机器人未配置 | 🟡 | 监控中 | 需配置环境变量 |
| API响应慢(大表) | 🟢 | 已缓解 | 使用$sample采样 |
---
## 状态说明
| 状态 | 含义 |
|:---:|:---|
| ✅ | Done - 已完成 |
| 🔄 | In Progress - 进行中 |
| ⏳ | Pending - 待开始 |
| ❌ | Blocked - 阻塞中 |
---
## P1 启动阶段
| 任务ID | 任务模块 | 具体行动 | 状态 | 交付物 |
|:---|:---|:---|:---:|:---|
| T001 | 项目初始化 | 创建Next.js项目 | ✅ | 项目结构 |
| T002 | 数据库连接 | MongoDB连接器 | ✅ | lib/mongodb.ts |
| T003 | AI对话API | 智能查询接口 | ✅ | /api/ai-chat |
---
## P2 开发阶段 - 数据概览
| 任务ID | 任务模块 | 具体行动 | 状态 | 交付物 |
|:---|:---|:---|:---:|:---|
| T004 | 首页 | AI对话+系统状态 | ✅ | app/page.tsx |
---
## P2 开发阶段 - 数据接入
| 任务ID | 任务模块 | 具体行动 | 状态 | 交付物 |
|:---|:---|:---|:---:|:---|
| T005 | 数据源管理 | 数据库列表+连接 | ✅ | /data-ingestion/sources |
| T006 | AI标签引擎 | 动态任务列表 | ✅ | /data-ingestion/ai-engine |
| T007 | 清洗规则 | 7条默认规则 | ✅ | /data-ingestion/cleaning |
| T008 | 任务调度 | 调度管理页 | ✅ | /data-ingestion/tasks |
| T009 | 数据血缘 | 动态节点API | ✅ | /data-ingestion/lineage |
---
## P2 开发阶段 - 标签画像
| 任务ID | 任务模块 | 具体行动 | 状态 | 交付物 |
|:---|:---|:---|:---:|:---|
| T010 | 标签管理 | 真实标签API | ✅ | /tag-portrait/tags |
| T011 | 用户画像 | 流量池统计 | ✅ | /tag-portrait/portrait |
| T012 | 人群圈选 | 按项目分类 | ✅ | /tag-portrait/crowd |
---
## P2 开发阶段 - AI Agent
| 任务ID | 任务模块 | 具体行动 | 状态 | 交付物 |
|:---|:---|:---|:---:|:---|
| T013 | 渠道配置 | 飞书/企微/微信 | ✅ | /ai-agent/channels |
| T014 | AI打标 | 提示词编辑 | ✅ | /ai-agent/smart-tag |
| T015 | AI清洗 | 规则配置 | ✅ | /ai-agent/data-cleaning |
| T016 | 智能报告 | 模板管理 | ✅ | /ai-agent/report |
---
## P2 开发阶段 - 数据市场
| 任务ID | 任务模块 | 具体行动 | 状态 | 交付物 |
|:---|:---|:---|:---:|:---|
| T017 | 流量包管理 | 导出CSV功能 | ✅ | /data-market/packages |
| T018 | API服务 | 13个端点文档 | ✅ | /data-market/api |
---
## P2 开发阶段 - 系统监控
| 任务ID | 任务模块 | 具体行动 | 状态 | 交付物 |
|:---|:---|:---|:---:|:---|
| T019 | 监控概览 | 真实API数据 | ✅ | /monitoring |
| T020 | 健康检查 | 服务状态 | ✅ | /monitoring/health |
| T021 | 告警中心 | 告警列表 | ✅ | /monitoring/alerts |
---
## P2 开发阶段 - API
| 任务ID | 任务模块 | 具体行动 | 状态 | 交付物 |
|:---|:---|:---|:---:|:---|
| T022 | 标签API | $sample采样优化 | ✅ | /api/tags |
| T023 | 流量池API | user_evaluation_score | ✅ | /api/traffic-packages |
| T024 | 人群圈选API | 按项目分类 | ✅ | /api/crowd-pools |
| T025 | 数据库结构API | 血缘节点生成 | ✅ | /api/database-structure |
| T026 | 渠道对接API | 飞书集成 | ✅ | /api/channels |
| T027 | 监控API | 健康/告警/指标 | ✅ | /api/monitoring |
---
## P3 执行阶段 - 项目管理
| 任务ID | 任务模块 | 具体行动 | 状态 | 交付物 |
|:---|:---|:---|:---:|:---|
| T028 | 项目管理工作区 | .apm目录 | ✅ | .apm/* |
| T029 | 架构图 | 系统架构文档 | ✅ | .apm/docs/architecture.md |
| T030 | 十目录展开 | skill格式+核心提取 | ✅ | 开发文档/1-10/*.md |
---
## P4 联调阶段
| 任务ID | 任务模块 | 具体行动 | 状态 | 交付物 |
|:---|:---|:---|:---:|:---|
| T031 | 飞书集成测试 | 环境变量配置 | ⏳ | 测试报告 |
---
## 📝 最近更新
- **2026-01-31 18:30** 用skill格式整理开发文档
- **2026-01-31 18:00** 新增渠道API和监控API
- **2026-01-31 17:30** 创建项目管理工作区
- **2026-01-31 16:30** 完成5大模块真实数据对接
- **2026-01-30 23:00** 完成核心功能开发
- **2026-01-29 20:00** 项目初始化
---
## 🔗 相关文档
- [项目状态](../.apm/project-state.md)
- [执行表](../.apm/execution-table.md)
- [对话记录](../.apm/conversation-log.md)
- [架构图](../.apm/docs/architecture.md)
---
## 任务统计
```
总计: 31 个任务
✅ Done: 28 个 (90%)
🔄 In Progress: 1 个
⏳ Pending: 2 个
❌ Blocked: 0 个
```
---
*版本: v1.4.0 | 更新: 2026-01-31 | 维护: 卡若AI*

276
开发文档/02_提示词文档.md Normal file
View File

@@ -0,0 +1,276 @@
# 神射手数据中台 - 提示词文档
> 📅 最后更新: 2026-01-31 18:30
> 🎯 记录每次对话的提示词和时间节点
> 📝 每次对话前查看历史提示词，了解上下文
---
## 一、提示词索引
| 时间 | 主题 | 关键词 |
|------|------|--------|
| 2026-01-31 18:30 | 项目检查运行+文档整理 | skill整理、项目运行、API验证 |
| 2026-01-31 17:30 | 项目管理工作区 | .apm、GitHub调研、架构图 |
| 2026-01-31 23:30 | 标签体系全面完善 | 用户画像、流量池分类、标签CRUD、清洗算法 |
| 2026-01-31 19:00 | 全量完善项目 | 卡若AI项目管理、文档更新、SKILL同步 |
| 2026-01-31 18:00 | 项目文档体系 | 文档、规则、记忆、UI优化 |
| 2026-01-31 17:00 | 功能开发完善 | 血缘可视化、渠道配置步骤 |
| 2026-01-31 16:00 | PRD需求开发 | AI标签引擎、人群圈选、API |
| 2026-01-30 | 数据库优化 | 索引、缓存、查询加速 |
| 2026-01-29 | 用户查询 | QQ查询、微博UID、手机号 |
---
## 二、详细提示词记录
### 2026-01-31 23:30 - 标签体系全面完善
**用户提示词:**
```
那个完善整个那个标签体系的这个包括用户画像里面都是要真实的数据，然后这里边的用户画像是可以直接创建用户画像的内容的，创建完之后它是直接分配给那个 SKR，然后来查询用户的那个生成用户的想要的有不标签的那个数据库，并且每一个用户他的流量。用户画像都可以点击进去，都可以看到详细的内容，这是一块，那第二块的话是关于流量池的这一些那个内容，流量池里面的话更多的是一个用户的一个标签，大白话一点的一个分类，并且每一个标签点击进去都是咱们 Mongo 数据库里面相对应的真实的一个标签。然后这个流量池里面的相应的人群就在咱们这里面有的所有的人群的一些真实的一个数据，那点击进去就是真实的人群的一个数据，然后更好的一个选择，然后这个圈选的流量池就由更多的一些流量池的，按这个流量池的种类进行分类。点击进去就是各个那个按标签和实际运营的热度，现在的一些那个流量池的一个内容，不要写人群圈，选这个就是流量池的一个内容，帮我把这一个整个的标签画下来，板块帮我按照这个完善一下，然后打通 skill 以及打通 Mango 的数据库来进行读取一下。按真实的情况来，内容更丰富一些，然后更真实一些，全部都要用真实的内容。那每个标签都可以选择，包括这个选择编辑删除的这一些，要有实际的一个作用更多的去完善，那包括标签管理，先进标签之后就是把这个标签管理弄到咱们的那个算法里面，并且把整个那个清洗标签的这个算法流程图也放到这里，这个标签管理的一个说明里面。把这些内容都统一的完善清楚。
```
**执行结果:**
- ✅ 用户画像API完善 - 支持真实数据查询、创建画像
- ✅ 用户画像页面重构 - 真实数据、创建功能、详情查看
- ✅ 流量池页面重构 - 按5大种类分类展示
- ✅ 标签管理页面增强 - 编辑删除功能、清洗算法流程图
- ✅ API新增PUT/DELETE方法支持CRUD
- ✅ 打通MongoDB真实数据
**功能清单:**
| 模块 | 功能 | 状态 |
|------|------|------|
| 用户画像 | 画像模板列表（从MongoDB动态加载） | ✅ |
| 用户画像 | 创建自定义画像（估值分/等级/省份/标签） | ✅ |
| 用户画像 | 用户列表分页（真实数据） | ✅ |
| 用户画像 | 用户详情查看 | ✅ |
| 用户画像 | 分配给SKR引擎 | ✅ |
| 流量池 | 价值分层（钻石/黄金/白银/青铜/潜力） | ✅ |
| 流量池 | 行为活跃（高频/沉默/流失） | ✅ |
| 流量池 | 地域分布（各省份） | ✅ |
| 流量池 | 数据来源（存客宝/点了码/微博/QQ） | ✅ |
| 流量池 | 生命周期（新用户/活跃/沉睡/流失） | ✅ |
| 标签管理 | 标签列表（按分类展示） | ✅ |
| 标签管理 | 创建标签（支持规则定义） | ✅ |
| 标签管理 | 编辑标签 | ✅ |
| 标签管理 | 删除标签（保护系统标签） | ✅ |
| 标签管理 | 清洗规则配置（7条规则） | ✅ |
| 标签管理 | 算法流程图（5步+RFM说明） | ✅ |
---
### 2026-01-31 19:00 - 全量完善项目
**用户提示词:**
```
已经建立完成了，你把这个上面的上一条，咱们的一个对话的那些需求全量把这个神射手的这个项目完善起来，全量的完善，然后用卡露 AI 的项目管理来完善整个边，完善整个开发文档，然后删除，完善完之后，嗯，分别把这些内容填写进去，一步一部分填写，能告诉我那个进度，把上面的所有的那个需求没完成的帮我把它完成掉
```
**执行结果:**
- 梳理全部对话历史需求
- 对比SKILL和前端路由
- 全量更新 `00_项目核心文档.md`
- 全量更新 `01_开发进度文档.md`
- 更新提示词文档
- 使用卡若AI项目管理规范
**完成进度:**
- ✅ 项目核心文档全量更新
- ✅ 开发进度文档全量更新
- ✅ 提示词文档更新
- ✅ SKILL文档待同步
- ✅ 系统监控模块已有
- ✅ 用户画像模板已有
---
### 2026-01-31 18:00 - 项目文档体系
**用户提示词:**
```
然后把这些数据库的整个的那个结构以及相应的那个结构都变成一个，一个这个项目的一个文档和一个文档，然后这个项目的文档每一次调取之后都需要是知道你要都需要调调那个读，以及读取完之后优化，也要优化到这个文档里面，然后把这个文档做的更清晰一些。我们对话中提到的几个，包括那个 AI 的这一个管家数据接入跟数据接入读取和数据分析，以及相应的那个数据查询的这一个管家的那个规则，包括这个用户资产数字化的规则都在这个项目里面。那每一次那个读取之前都要看一下数据库跟看一下这几张表，然后了解 SKU 的这个 AI SKU 的一个作用，然后再来每次读取都要看一下这些内容，然后再来更新迭代整个项目，以及项目的整个的目标运转目标都要更新迭代一下，然后把这个生成相应的几个文档。并且更新到科室的那个规则里面，这个项目的科室规则里面。整个那个都是以苹果毛玻璃的风格来设计，然后风格跟图标变得更丰富有趣一些，把整个界面变得更丰富有趣一些。后，并且设置一条咱们每一次对话的一些记忆的这一个功能，跟归那个优化这个功能都形成，都更新迭代到这个那个开发的那个文档里面，以及开发进度的文档里面，让整个项目能更通透的运转。并且修改成整个的那个开发文档，主要开发文档那个写入之前就先看一下开发文档的格式，然后按照他的要求写入进去修改这个规则进去，项目确保能有记忆、有步骤、有节奏的分布式的那个完成，并且新增相应的那个进度，项目管理写清楚。和落地规范写清楚，AI 打标签的这个功能就是输入提示词在数据库的允许范围内去做 AI 打标签的这么一个事情，它需要有一个输入提示词和编辑提示词的一个功能，把相应的功能帮我写进去，以及告诉我实时的一个进度跟实时的一个那个事情跟 AI 清洗是一样。需要配置清洗完的路，需要配置相应的规则。那智能报告也是一样，需要有一个配置规则的地方，每一个配置规则有一条默认的规则。另外一个记录的过程中，帮我把每一次那个对话的那个提示词，以及上面我们对话的所有的提示词，按时间节点都给我写一个提示词的一个文档，每一次都写入，按时间节点写入来完善这个提示词的一个文档，那么一次读取的时候也看一下这个上下的那个阶段。以及相应的那个执行时间，防止出错，那这个也都放到开发文档的进度里面
```
**执行结果:**
- 创建 `00_项目核心文档.md` - 数据库结构+AI规则
- 创建 `01_开发进度文档.md` - 项目管理与落地规范
- 创建 `02_提示词文档.md` - 本文档
- 待创建 Cursor规则文件
- 待优化 AI打标/清洗/报告的规则配置功能
- 待优化 UI毛玻璃风格
---
### 2026-01-31 17:00 - 功能开发完善
**用户提示词:**
```
继续
```
**执行结果:**
- 完成数据血缘可拖拉拽可视化
- 添加渠道配置详细步骤指南
- 8个节点 + 10条连接线
- 飞书/企微/微信/API完整配置步骤
---
### 2026-01-31 16:00 - PRD需求开发
**用户提示词:**
```
AI标签系统V1产品需求文档... 一个 AI 标签的系统整个的扭转是那个从数据源的管理，它是接入数据库之后就开始拆解符合的咱们的那个 AI 的那个中台的那个标签引擎...
```
**执行结果:**
- 创建 AI标签引擎页面 `/data-ingestion/ai-engine`
- 更新首页AI对话（思考过程+用户画像模板）
- 创建人群圈选页面（参考巨量引擎5步筛选）
- 更新智能报告（Skill执行+报告模板）
- 创建流量包发送（邮箱/飞书/微信）
- 创建API服务页面（13个端点）
---
### 2026-01-30 - 数据库优化
**关键提示词摘要:**
- 优化MongoDB查询性能
- 创建索引（qq、phone、uid）
- 4层缓存架构设计
- 断网自动切换本地模型
**执行结果:**
- 索引优化脚本
- 缓存机制设计
- 容灾备份方案
---
### 2026-01-29 - 用户查询
**关键提示词摘要:**
- 查询QQ号 28533368
- 查询手机号 13779954946
- 微博热点UID查询
- 2025年明星热度分析
**执行结果:**
- QQ关联手机号查询
- 用户画像完整输出
- 微博UID批量查询
- 明星数据分析报告
---
## 三、AI打标默认提示词
### 3.1 价值类打标
```
分析用户数据，根据RFM评分生成价值标签：
- RFM≥90: 高价值用户
- RFM≥70: 优质用户
- RFM≥50: 普通用户
- RFM<50: 待激活用户
- 近30天无活跃: 流失风险
```
### 3.2 行为类打标
```
分析用户行为数据，生成行为标签：
- 日活跃: 高频用户
- 周活跃: 活跃用户
- 月活跃: 普通用户
- 30天+未活跃: 沉默用户
- 首次访问: 新用户
```
### 3.3 偏好类打标
```
分析用户消费和行为数据，生成偏好标签：
- 电商消费≥5次/月: 电商活跃
- 社交互动≥10次/天: 社交达人
- 金融产品浏览: 金融偏好
- 游戏时长≥2h/天: 游戏玩家
```
---
## 四、AI清洗默认规则
### 4.1 手机号清洗
```
规则: 格式化为11位
- 去除空格、横杠
- 去除+86前缀
- 验证1[3-9]开头
- 无效手机号标记为null
```
### 4.2 姓名清洗
```
规则: 姓名脱敏
- 保留姓氏
- 中间名用*替代
- 示例: 张三 → 张*
```
### 4.3 地址清洗
```
规则: 标准化省市
- 提取省份名称
- 提取城市名称
- 去除"省""市"后缀
```
---
## 五、智能报告默认规则
### 5.1 日报规则
```
报告名称: 每日运营日报
生成时间: 每日23:59
包含章节:
- 核心指标（总用户、活跃用户、新增用户）
- 渠道消息（飞书、企微、微信消息量）
- AI查询统计（查询次数、响应时间）
- 异常告警
```
### 5.2 周报规则
```
报告名称: 周度数据质量报告
生成时间: 每周日00:00
包含章节:
- 质量概览
- 清洗统计（清洗量、去重量）
- 数据完整度
- 问题数据统计
```
### 5.3 月报规则
```
报告名称: 月度用户资产报告
生成时间: 每月1日08:00
包含章节:
- 资产总览
- 用户增长趋势
- RFM分布变化
- 流量池变化
- 标签覆盖率
- 下月预测
```
---
## 六、下次对话注意事项
1. **先读取文档**: 开始前读取 `00_项目核心文档.md` 和 `01_开发进度文档.md`
2. **确认当前任务**: 查看进度表中的🔄状态任务
3. **记录提示词**: 对话结束后更新本文档
4. **更新进度**: 完成任务后标记✅并填写日期

17
开发文档/10、项目管理/README.md Normal file
View File

@@ -0,0 +1,17 @@
# 10、项目管理
> 高级 PM | 执行表
## 本目录文档
| 文档 | 说明 |
|:---|:---|
| [_智能展开.md](./_智能展开.md) | 管理引擎激活 |
| [执行表.md](./执行表.md) | 任务清单（链接.apm） |
| [项目管理提示词.md](./项目管理提示词.md) | 管理模板 |
## 联动
- 上游: 1-需求、2-架构、4-前端、6-后端
- 主文档: `../../.apm/execution-table.md`
- 指令: `@项目管理 查看进度`

301
开发文档/10、项目管理/_智能展开.md Normal file
View File

@@ -0,0 +1,301 @@
# 📊 项目管理智能展开引擎 (PM Auto-Expand)
> **角色激活**: 将此文件拖入 AI，即刻激活 **高级项目经理 (PM)** 角色
> **核心能力**: 任务拆解、进度管理、风险控制、复盘总结
---
## 📋 一、快速启动指令
### 1.1 需求转任务
```
@项目管理引擎 请根据以下需求，拆解为可执行的项目计划：
【项目名称】：[项目名]
【核心功能】：[功能列表]
【开发周期】：[预期时间]
【团队规模】：[人数]
【里程碑】：[关键节点]
```
### 1.2 展开输出清单
| 输出项 | 说明 | 格式 |
|:---|:---|:---|
| 执行表 | 任务分解 + 状态 | 表格 |
| 甘特图 | 进度可视化 | Mermaid |
| 风险矩阵 | 风险识别与应对 | 表格 |
| 复盘模板 | 项目总结 | 结构化文档 |
---
## 📈 二、项目落地执行表
### 2.1 执行表模板
| 阶段 | 任务模块 | 具体行动 | 负责人 | 截止时间 | 状态 | 交付物 | 备注 |
|:---|:---|:---|:---|:---|:---:|:---|:---|
| **P1 启动** | 需求分析 | 确定 MVP 功能边界 | PM | T+3 | ✅ | 需求文档 | - |
| **P1 启动** | 技术选型 | 确定技术栈 | Tech Lead | T+3 | ✅ | 架构文档 | - |
| **P2 开发** | 数据库设计 | 设计集合结构 | 后端 | T+5 | 🔄 | ER 图 | - |
| **P2 开发** | 后端开发 | 实现核心 API | 后端 | T+15 | ⏳ | API 代码 | - |
| **P2 开发** | 前端开发 | 实现核心页面 | 前端 | T+15 | ⏳ | 前端代码 | - |
| **P3 联调** | 前后端联调 | 接口对接 | 全员 | T+18 | ⏳ | 联调通过 | - |
| **P4 测试** | 功能测试 | 测试核心流程 | QA | T+20 | ⏳ | 测试报告 | - |
| **P5 上线** | 部署发布 | 部署到生产环境 | DevOps | T+21 | ⏳ | 线上运行 | - |
**状态说明**: ✅ Done | 🔄 In Progress | ⏳ Pending | ❌ Blocked
### 2.2 里程碑定义
| 里程碑 | 时间点 | 完成标志 | 依赖 |
|:---|:---|:---|:---|
| M1 需求冻结 | T+3 | 需求文档签字确认 | - |
| M2 技术方案确定 | T+5 | 架构评审通过 | M1 |
| M3 开发完成 | T+15 | 代码 PR 合并 | M2 |
| M4 测试通过 | T+20 | Bug 归零 | M3 |
| M5 正式上线 | T+21 | 生产环境可访问 | M4 |
---
## 📊 三、进度可视化
### 3.1 甘特图模板
```mermaid
gantt
title 项目开发进度
dateFormat YYYY-MM-DD
section 启动阶段
需求分析 :done, a1, 2024-01-01, 3d
技术选型 :done, a2, after a1, 2d
section 开发阶段
数据库设计 :active, b1, after a2, 3d
后端开发 : b2, after b1, 10d
前端开发 : b3, after b1, 10d
section 联调测试
前后端联调 : c1, after b2, 3d
功能测试 : c2, after c1, 2d
section 上线
部署发布 : d1, after c2, 1d
里程碑: 正式上线 :milestone, m1, after d1, 0d
```
### 3.2 燃尽图数据结构
```javascript
// 燃尽图数据
const burndownData = {
totalTasks: 50,
dailyProgress: [
{ date: "01-01", remaining: 50, ideal: 50 },
{ date: "01-02", remaining: 48, ideal: 47 },
{ date: "01-03", remaining: 45, ideal: 44 },
// ...
]
};
```
---
## ⚠️ 四、风险管理
### 4.1 风险矩阵
| 风险点 | 可能性 | 影响 | 风险等级 | 应对策略 |
|:---|:---:|:---:|:---:|:---|
| 需求频繁变更 | 高 | 中 | 🟡 | 冻结需求版本，变更走审批 |
| 技术方案不可行 | 中 | 高 | 🟡 | 提前 POC 验证 |
| 核心人员离职 | 低 | 高 | 🟢 | 文档沉淀 + 备份人员 |
| 第三方服务不稳定 | 中 | 中 | 🟡 | 降级方案 + 多供应商 |
| 上线后 Bug 频发 | 中 | 高 | 🟡 | 完善测试 + 灰度发布 |
**风险等级**: 🔴 高危 | 🟡 中等 | 🟢 低风险
### 4.2 风险应对 SOP
```yaml
需求变更:
1. 评估影响范围
2. 计算工时变化
3. 与 PM 确认优先级
4. 更新执行表
5. 通知相关人员
技术卡点:
1. 描述问题现象
2. 列出已尝试方案
3. 寻求 Tech Lead 支持
4. 更新风险矩阵
5. 调整排期
人员变动:
1. 评估影响任务
2. 重新分配任务
3. 加速知识转移
4. 更新执行表
```
---
## 📝 五、复盘模板
### 5.1 项目复盘文档
```markdown
# [项目名称] 项目复盘报告
> 复盘时间：YYYY-MM-DD | 复盘人：卡若
---
## 一、项目概述
| 项目 | 说明 |
|:---|:---|
| 项目名称 | XXX |
| 项目周期 | YYYY-MM-DD ~ YYYY-MM-DD |
| 参与人员 | A, B, C |
| 最终状态 | ✅ 成功 / ⚠️ 部分完成 / ❌ 失败 |
---
## 二、目标与结果
| 目标 | 预期 | 实际 | 完成率 |
|:---|:---|:---|:---:|
| 功能上线 | 5 个 | 5 个 | 100% |
| 开发周期 | 21 天 | 25 天 | 84% |
| Bug 数量 | < 10 | 8 | ✅ |
---
## 三、过程回顾
### 3.1 做得好的地方 👍
1. 技术选型准确，没有踩坑
2. 文档先行，减少沟通成本
3. 每日站会，问题及时暴露
### 3.2 做得不好的地方 👎
1. 需求变更 3 次，影响进度
2. 测试环境不稳定，耽误 2 天
3. 部分接口文档缺失，联调效率低
---
## 四、经验教训
### 4.1 成功经验（可复制）
- **文档驱动开发**: 先写文档再写代码，效率提升 30%
- **每日站会**: 15 分钟快速同步，问题当天解决
### 4.2 失败教训（需避免）
- **需求未冻结就开发**: 导致返工 3 次
- **测试环境与生产不一致**: 上线后出现环境问题
---
## 五、改进行动
| 改进点 | 具体行动 | 负责人 | 截止时间 |
|:---|:---|:---|:---|
| 需求管理 | 引入需求变更审批流程 | PM | 下个项目 |
| 测试环境 | 搭建与生产一致的测试环境 | DevOps | T+7 |
| 接口文档 | 强制使用 OpenAPI 规范 | Tech Lead | 立即 |
---
## 六、数据存档
- 需求文档：[链接]
- 代码仓库：[链接]
- 部署文档：[链接]
- 测试报告：[链接]
```
---
## 🔄 六、自动化规则
### 6.1 执行表更新规则
```yaml
触发条件 → 自动更新
─────────────────────
"后端代码写完了" → 后端开发状态改为 ✅ Done
"遇到问题了" → 标记 ❌ Blocked，更新备注
"开始做 XX" → XX 任务状态改为 🔄 In Progress
"需求变了" → 新增任务到执行表，重新评估排期
```
### 6.2 提醒规则
```yaml
超时提醒:
- 任务超过截止时间 → 主动提醒负责人
- 连续 3 天无进展 → 标记为风险
状态检查:
- 每次对话结束 → 检查是否有状态变更
- 里程碑当天 → 确认交付物是否完成
```
---
## 🔗 七、跨目录联动
```mermaid
graph TB
A[1、需求] -->|功能清单| B[10、项目管理]
C[2-9 所有开发目录] -->|开发进度| B
B -->|复盘文档| D[知识库]
```
### 联动指令
```
@联动 需求→管理：将功能清单转化为执行任务
@联动 开发→管理：更新开发进度到执行表
@联动 管理→复盘：基于执行表生成复盘报告
```
---
## 🤖 八、AI 协作指令
| 指令 | 功能 | 示例 |
|:---|:---|:---|
| `@拆解任务` | 需求转执行任务 | `@拆解任务 用户中心模块` |
| `@更新进度` | 更新任务状态 | `@更新进度 后端开发完成` |
| `@甘特图` | 生成进度图 | `@甘特图 当前项目` |
| `@风险评估` | 评估项目风险 | `@风险评估 当前项目` |
| `@生成复盘` | 生成复盘报告 | `@生成复盘 私域银行v1.0` |
| `@站会纪要` | 生成站会纪要 | `@站会纪要 今日进展` |
---
## ⚠️ 九、注意事项
### 9.1 管理原则
```yaml
卡若管理风格:
- 结果导向：只看交付物，不看过程表演
- 数据说话：用数据而非感觉
- 拒绝形式主义：开会要有结论，文档要能执行
- PDCA 循环：计划-执行-检查-处理
```
### 9.2 常见问题
| 问题 | 解决方案 |
|:---|:---|
| 任务拆分太粗 | 每个任务不超过 2 天工作量 |
| 进度不透明 | 每日更新执行表 |
| 风险后知后觉 | 提前识别 + 定期评估 |
| 复盘流于形式 | 必须有具体改进行动 |
---
> **恭喜！** 你已完成整个开发模板的学习。现在回到 `AI开发引擎.md` 开始你的项目吧！

73
开发文档/10、项目管理/执行表.md Normal file
View File

@@ -0,0 +1,73 @@
# 神射手 - 执行表
> 📅 与 .apm/execution-table.md 同步 | 2026-01-31
> 📋 主文档: `../.apm/execution-table.md`
---
## 一、状态说明
| 状态 | 含义 |
|:---:|:---|
| ✅ | Done - 已完成 |
| 🔄 | In Progress - 进行中 |
| ⏳ | Pending - 待开始 |
| ❌ | Blocked - 阻塞中 |
---
## 二、进度摘要
| 指标 | 数值 |
|:---|:---|
| 总任务数 | 31 |
| 已完成 | 28 (90%) |
| 进行中 | 1 |
| 待开始 | 2 |
---
## 三、里程碑
| 里程碑 | 状态 | 交付物 |
|:---|:---:|:---|
| M1 基础框架 | ✅ | Next.js + MongoDB |
| M2 核心功能 | ✅ | 5大模块 |
| M3 真实数据 | ✅ | API对接 |
| M4 外部集成 | 🔄 | 飞书/企微 |
| M5 正式上线 | ⏳ | 生产部署 |
---
## 四、十目录任务映射
| 目录 | 对应任务 | 状态 |
|:---|:---|:---:|
| 1-需求 | 业务需求、用户故事 | ✅ |
| 2-架构 | 架构图、技术选型 | ✅ |
| 3-原型 | 页面结构 | ✅ |
| 4-前端 | 5大模块页面 | ✅ |
| 5-接口 | 25个API | ✅ |
| 6-后端 | MongoDB连接器 | ✅ |
| 7-数据库 | 集合结构、查询 | ✅ |
| 8-部署 | 启动脚本 | ✅ |
| 9-手册 | 使用手册 | ✅ |
| 10-管理 | 执行表、进度 | 🔄 |
---
## 五、联动指令
```
@项目管理 查看进度 → 读取 .apm/execution-table.md
@项目管理 更新进度 → 更新执行表
@项目管理 展开目录[N] → 展开对应目录子文档
```
---
## 六、关联文档
- [项目管理提示词.md](./项目管理提示词.md)
- [../../.apm/execution-table.md](../../.apm/execution-table.md)
- [../../.apm/project-state.md](../../.apm/project-state.md)

42
开发文档/10、项目管理/项目管理提示词.md Normal file
View File

@@ -0,0 +1,42 @@
# 神射手 - 项目管理提示词
> 📅 更新: 2026-01-31
---
## 一、管理规范
| 原则 | 说明 |
|:---|:---|
| 结果导向 | 只看交付物 |
| 数据说话 | 用数据而非感觉 |
| PDCA | 计划-执行-检查-处理 |
---
## 二、执行表
- **主文档**：`../../.apm/execution-table.md`
- **项目状态**：`../../.apm/project-state.md`
- **本目录**：`执行表.md` 为摘要
---
## 三、指令
| 指令 | 功能 |
|:---|:---|
| @项目管理 查看进度 | 读取执行表 |
| @项目管理 更新进度 | 更新任务状态 |
| @项目管理 展开目录[N] | 展开1-10目录 |
---
## 四、状态图例
| 状态 | 含义 |
|:---:|:---|
| ✅ | Done |
| 🔄 | In Progress |
| ⏳ | Pending |
| ❌ | Blocked |

18
开发文档/1、需求/README.md Normal file
View File

@@ -0,0 +1,18 @@
# 1、需求
> CFO + 产品负责人 | 业务需求文档
## 本目录文档
| 文档 | 说明 |
|:---|:---|
| [_智能展开.md](./_智能展开.md) | 需求引擎激活、五行框架 |
| [业务需求.md](./业务需求.md) | 业务需求文档 |
| [核心需求提取.md](./核心需求提取.md) | **从项目提取**：用户故事、MVP边界 |
| [成本.md](./成本.md) | 成本估算 |
| [技术需求.md](./技术需求.md) | 技术需求 |
## 联动
- 下游: 2-架构、3-原型、10-项目管理
- 指令: `@需求引擎 展开 [需求描述]`

298
开发文档/1、需求/_智能展开.md Normal file
View File

@@ -0,0 +1,298 @@
# 🎯 需求智能展开引擎 (Requirements Auto-Expand)
> **角色激活**: 将此文件拖入 AI，即刻激活 **CFO + 产品负责人** 双重角色
> **核心能力**: 需求拆解、成本测算、MVP 规划、用户故事生成
---
## 📋 一、快速启动指令
### 1.1 一句话需求展开
```
@需求引擎 请根据以下一句话需求，展开完整的需求文档：
【需求】：[用一句话描述你要做什么]
【预算】：[可选，开发预算]
【周期】：[可选，期望开发周期]
```
### 1.2 展开输出清单
| 输出项 | 说明 | 格式 |
|:---|:---|:---|
| 业务流程图 | 核心业务流程可视化 | Mermaid flowchart |
| 用户故事卡 | 按角色拆分的功能需求 | As a... I want... So that... |
| MVP 功能清单 | 优先级排序的功能列表 | 表格 + P0/P1/P2 标记 |
| 成本估算表 | API/服务器/人力成本 | 表格 + 公式 |
| 五行营销框架 | 金水木火土结构化分析 | 分层结构 |
---
## 🧠 二、智能拆解规则
### 2.1 五行营销框架 (卡若核心方法论)
```
┌─────────────────────────────────────────────────────────────┐
│ 五行营销需求框架 │
├─────────────────────────────────────────────────────────────┤
│ 🥇 金（目标）: 目标人群 / 流量来源 / 品牌定位 / 核心指标 │
│ ↓ │
│ 💧 水（流程）: 用户路径 / 转化漏斗 / 关键节点 / 触发条件 │
│ ↓ │
│ 🌳 木（落地）: 产品形态 / 功能清单 / MVP 边界 / 交付物 │
│ ↓ │
│ 🔥 火（分析）: 数据埋点 / 复盘指标 / 迭代方向 / 学习成长 │
│ ↓ │
│ 🌍 土（资源）: 技术资源 / 人力投入 / 预算分配 / 合作伙伴 │
└─────────────────────────────────────────────────────────────┘
```
### 2.2 云阿米巴需求检查点
```yaml
# 每个需求必须通过以下检查
流量入口检查:
- [ ] 是否有明确的流量获取方式？
- [ ] 流量池功能是否足够显眼？
分润显性化检查:
- [ ] 合作方能否一眼看到赚了多少钱？
- [ ] 分润计算逻辑是否清晰透明？
利益绑定检查:
- [ ] 是否分的是"不属于对方的钱"？
- [ ] 是否按创造价值分钱？
- [ ] 是否用流量+系统绑定合作方？
```
---
## 📊 三、需求文档模板
### 3.1 完整需求文档结构
```markdown
# [项目名称] 业务需求文档 v1.0
> 创建日期：YYYY-MM-DD | 负责人：卡若 | 状态：草稿/评审中/已确认
---
## 一、项目背景与目标 (金)
### 1.1 背景
[为什么做？解决什么问题？市场机会在哪？]
### 1.2 目标用户
| 用户角色 | 画像描述 | 核心痛点 | 使用场景 |
|:---|:---|:---|:---|
| 角色 A | 描述 | 痛点 | 场景 |
### 1.3 成功指标 (KPI)
| 指标 | 目标值 | 衡量方式 | 优先级 |
|:---|:---|:---|:---:|
| 日活用户 | X | 数据埋点 | P0 |
---
## 二、业务流程 (水)
### 2.1 核心流程图
[Mermaid flowchart]
### 2.2 用户旅程
[Mermaid journey]
---
## 三、功能清单 (木)
### 3.1 MVP 功能列表
| 模块 | 功能点 | 优先级 | 验收标准 | 依赖 |
|:---|:---|:---:|:---|:---|
| 用户模块 | 手机号登录 | P0 | 验证码正确可登录 | 短信服务 |
### 3.2 用户故事卡
**US-001: [功能名称]**
- **As a** [角色]
- **I want** [功能]
- **So that** [价值]
- **验收标准**：
- [ ] 条件 1
- [ ] 条件 2
---
## 四、数据与迭代 (火)
### 4.1 埋点清单
| 事件名 | 触发条件 | 携带参数 | 分析目的 |
|:---|:---|:---|:---|
### 4.2 迭代规划
| 版本 | 核心功能 | 预计时间 |
|:---|:---|:---|
---
## 五、资源与预算 (土)
### 5.1 成本估算
| 类型 | 明细 | 单价 | 数量 | 小计 |
|:---|:---|---:|:---:|---:|
| API 成本 | OpenAI GPT-4 | ¥0.1/次 | 10万次/月 | ¥10,000 |
### 5.2 团队分工
| 角色 | 负责人 | 职责范围 |
|:---|:---|:---|
---
## 附录
### A. 竞品分析
### B. 原始需求记录
### C. 变更历史
```
---
## 🔗 四、跨目录联动
### 4.1 下游联动
本目录确定后，自动触发以下目录更新：
```mermaid
graph LR
A[1、需求] -->|功能清单| B[2、架构]
A -->|用户故事| C[3、原型]
A -->|成本估算| D[8、部署]
A -->|KPI| E[10、项目管理]
```
### 4.2 联动指令
```
# 需求确定后，自动展开架构
@联动 需求→架构：基于 [需求文档.md] 生成系统架构
# 需求确定后，自动展开原型
@联动 需求→原型：基于 [用户故事] 生成页面结构
# 需求确定后，自动更新执行表
@联动 需求→管理：将功能清单转化为执行任务
```
---
## 🤖 五、AI 协作指令
### 5.1 角色设定
```yaml
角色: 产品合伙人 + CFO
风格: 大白话、结果导向、数据说话
输出: 必须包含 Mermaid 图 + 表格
检查: 每个需求必须通过云阿米巴检查点
```
### 5.2 指令集
| 指令 | 功能 | 示例 |
|:---|:---|:---|
| `@拆解需求` | 一句话展开完整需求 | `@拆解需求 做一个私域分销系统` |
| `@用户故事` | 生成用户故事卡片 | `@用户故事 登录注册模块` |
| `@流程图` | 生成业务流程图 | `@流程图 用户下单流程` |
| `@成本估算` | 生成成本明细表 | `@成本估算 日活1万的AI客服` |
| `@竞品分析` | 分析竞品功能 | `@竞品分析 [竞品URL]` |
| `@MVP边界` | 确定最小可行产品 | `@MVP边界 私域银行v1.0` |
---
## 📝 六、示例输出
### 6.1 业务流程图示例
```mermaid
flowchart TB
subgraph 流量端
A[抖音短视频] --> B[评论区引流]
B --> C[私域承接页]
end
subgraph 转化端
C --> D{用户登录}
D -->|新用户| E[注册绑定]
D -->|老用户| F[直接进入]
E --> F
F --> G[流量池展示]
end
subgraph 变现端
G --> H[场景获客]
H --> I[客资分发]
I --> J[分润结算]
J --> K[一键提现]
end
```
### 6.2 用户旅程示例
```mermaid
journey
title 合作方使用旅程
section 认知阶段
刷到短视频: 3: 合作方
点击主页链接: 4: 合作方
section 激活阶段
注册登录: 4: 合作方
开通流量池: 5: 合作方
section 变现阶段
查看今日收益: 5: 合作方
申请提现: 4: 合作方
到账确认: 5: 合作方
section 留存阶段
邀请新合作方: 4: 合作方
查看团队收益: 5: 合作方
```
### 6.3 成本估算示例
```markdown
## 私域银行 v1.0 成本估算
### 一次性成本
| 项目 | 金额 | 说明 |
|:---|---:|:---|
| 服务器配置 | ¥2,000 | 2核4G云服务器年费 |
| 域名+SSL | ¥100 | 年费 |
| **小计** | **¥2,100** | |
### 月度运营成本
| 项目 | 单价 | 预估用量 | 月成本 |
|:---|---:|:---:|---:|
| OpenAI API | ¥0.1/次 | 5万次 | ¥5,000 |
| 短信验证 | ¥0.05/条 | 1万条 | ¥500 |
| 对象存储 | ¥0.1/GB | 50GB | ¥5 |
| **小计** | | | **¥5,505** |
### ROI 测算
- 预期月收入：¥30,000 (30家合作方 × ¥1000/家)
- 预期月成本：¥5,505
- **毛利率**：81.7%
- **回本周期**：< 1个月
```
---
## ⚠️ 七、注意事项
### 7.1 常见陷阱
- ❌ 需求不明确就开始画原型
- ❌ 功能堆砌，没有 MVP 边界
- ❌ 忽略成本估算，盲目开发
- ❌ 没有成功指标，无法验收
### 7.2 最佳实践
- ✅ 先算账再动手（成本.md 先行）
- ✅ 功能做减法（MVP 原则）
- ✅ 用户故事驱动（避免自嗨需求）
- ✅ 数据埋点前置（火的分析能力）
---
> **下一步**: 需求确定后，拖入 `2、架构/_智能展开.md` 进行技术架构设计

74
开发文档/1、需求/业务需求.md Normal file
View File

@@ -0,0 +1,74 @@
# 神射手数据中台 - 业务需求
> 📅 更新: 2026-01-31 | 状态: 已确认
---
## 一、项目背景（金）
### 1.1 核心目标
- **产品定位**：用户资产数字化中台，整合20亿+用户数据
- **核心能力**：输入手机号/QQ/UID → 秒级返回用户画像
- **关键指标**：查询延迟 <500ms、数据覆盖率、标签准确率
### 1.2 目标用户
| 角色 | 画像 | 核心痛点 | 使用场景 |
|:---|:---|:---|:---|
| 运营人员 | 私域运营、营销 | 用户数据分散、查询慢 | 手机号查用户画像 |
| 营销人员 | 精准营销 | 人群圈选困难 | 按流量池选人、导出 |
| 数据分析师 | 数据洞察 | 多源数据难整合 | RFM分析、标签统计 |
| 系统管理员 | 运维 | 多平台对接 | 飞书/企微配置 |
---
## 二、业务流程（水）
### 2.1 核心流程
```
用户输入(手机/QQ/关键词) → 意图识别 → 跨库查询 → 画像合并 → 格式化输出
```
### 2.2 数据流向
```
数据源(KR_*) → AI标签引擎 → KR.用户估值 → 流量池分层 → 导出/发送
```
---
## 三、功能清单（木）
### 3.1 五大模块
| 模块 | 功能 | 优先级 | 验收标准 |
|:---|:---|:---:|:---|
| 数据概览 | AI对话、系统状态 | P0 | 输入手机号可查用户 |
| 数据接入 | 数据源、AI引擎、血缘 | P0 | 真实MongoDB连接 |
| 标签画像 | 标签、画像、人群圈选 | P0 | 按项目分类流量池 |
| AI Agent | 渠道、打标、清洗、报告 | P1 | 飞书/企微对接 |
| 数据市场 | 流量包、API服务 | P1 | 导出CSV、发送群 |
### 3.2 用户故事
- US-001: 手机号查询 → 秒级返回画像
- US-002: QQ号查询 → 关联手机+画像
- US-003: 人群圈选 → 项目→池→用户列表
- US-004: 流量包导出 → CSV下载
---
## 四、数据与迭代（火）
### 4.1 埋点
- AI对话次数、查询类型分布
- 各模块访问量
- API响应延迟
### 4.2 迭代规划
- v1.3: 真实数据对接 ✅
- v1.4: 外部集成（飞书/企微）✅
- v1.5: Redis缓存、性能优化
---
## 五、关联文档
- [核心需求提取.md](./核心需求提取.md)
- [成本.md](./成本.md)
- [技术需求.md](./技术需求.md)

41
开发文档/1、需求/成本.md Normal file
View File

@@ -0,0 +1,41 @@
# 神射手数据中台 - 成本分析
> 📅 更新: 2026-01-31
---
## 一、固定成本（月度）
| 类别 | 项目 | 单价/月 | 数量 | 小计 | 备注 |
|:---|:---|:---:|:---:|:---:|:---|
| 基建 | 云服务器 | 200 | 1 | 200 | 可选，本地开发为主 |
| 基建 | MongoDB | 0 | 1 | 0 | 本地Docker |
| 基建 | 域名+SSL | 10 | 1 | 10 | 年费均摊 |
| AI | LLM API | 500 | 1 | 500 | 可选，本地模型为主 |
| **合计** | | | | **710** | 轻量部署 |
---
## 二、变动成本
| 类别 | 项目 | 计费标准 | 预估 | 备注 |
|:---|:---|:---|:---|:---|
| 流量 | 公网带宽 | 按量 | 50/月 | 低流量 |
| 存储 | 对象存储 | 0.1/GB | 20/月 | 备份 |
| API | 第三方API | 按次 | 100/月 | 短信等 |
---
## 三、收益模型
| 类型 | 说明 | 预估 |
|:---|:---|:---|
| 内部使用 | 私域运营提效 | 无直接收入 |
| 数据服务 | 用户画像API调用 | 待定 |
| 流量包 | 导出/发送服务 | 待定 |
---
## 四、盈亏平衡
- **月度支出**：约 800 元（轻量部署）
- **回本**：内部工具，以提效为主

57
开发文档/1、需求/技术需求.md Normal file
View File

@@ -0,0 +1,57 @@
# 神射手数据中台 - 技术需求
> 📅 更新: 2026-01-31
---
## 一、开发规范
### 1.1 文档驱动
- 先读 `开发文档/00_项目核心文档.md`
- 新功能更新 `01_开发进度文档.md`
- 提示词写入 `02_提示词文档.md`
### 1.2 目录结构
- 严格遵守 1-10 目录结构
- 核心代码提取至各目录子文档
---
## 二、前端需求
| 项目 | 要求 |
|:---|:---|
| 框架 | Next.js 14 + React 18 |
| UI | Radix UI + TailwindCSS |
| 风格 | 苹果毛玻璃 (backdrop-blur) |
| 加载 | Skeleton 骨架屏 |
| 动画 | 路由转场、过渡效果 |
---
## 三、后端需求
| 项目 | 要求 |
|:---|:---|
| 数据库 | MongoDB (本地Docker) |
| 连接 | lib/mongodb.ts 连接池 |
| 查询 | $sample 采样优化大表 |
| 安全 | 参数化查询、无硬编码密钥 |
---
## 四、数据库需求
| 项目 | 要求 |
|:---|:---|
| 核心库 | KR.用户估值 |
| 多源 | KR_腾讯、KR_微博、KR_存客宝等 |
| 字段 | user_evaluation_score、unified_tags |
| 索引 | phone、qq、uid |
---
## 五、AI能力
- 意图识别：手机/QQ/状态/RFM/高价值
- 自然语言转查询
- 本地模型优先，断网切换

87
开发文档/1、需求/核心需求提取.md Normal file
View File

@@ -0,0 +1,87 @@
# 神射手 - 核心需求提取
> 📅 从项目代码与文档提取 | 2026-01-31
---
## 一、项目目标（金）
| 目标 | 描述 |
|:---|:---|
| 核心能力 | 输入手机号/QQ/UID → 秒级返回用户画像 |
| 数据规模 | 20亿+ 用户记录 |
| 业务价值 | 用户资产数字化、流量池管理、精准营销 |
---
## 二、五大模块需求（木）
| 模块 | 核心功能 | 验收标准 |
|:---|:---|:---|
| 数据概览 | AI对话、系统状态、数据统计 | 输入手机号可查用户 |
| 数据接入 | 数据源、AI引擎、清洗、任务、血缘 | 真实MongoDB连接 |
| 标签画像 | 标签、画像、人群圈选 | 按项目分类流量池 |
| AI Agent | 渠道、打标、清洗、报告 | 飞书/企微对接 |
| 数据市场 | 流量包、API服务 | 导出CSV、发送群 |
---
## 三、用户故事（从代码提取）
### US-001: 手机号查询
```
As a 运营人员
I want 输入11位手机号
So that 秒级获取用户画像（姓名、QQ、等级、标签）
验收: parseIntent 识别手机号 → queryFullProfile 跨库查询
```
### US-002: QQ号查询
```
As a 运营人员
I want 输入QQ号
So that 获取关联手机号及用户信息
验收: parseIntent 识别QQ → KR_腾讯.QQ+手机 → KR.用户估值
```
### US-003: 人群圈选
```
As a 营销人员
I want 按项目选择流量池
So that 查看真实用户列表
验收: /api/crowd-pools 按存客宝/点了码/微博/QQ分类
```
### US-004: 流量包导出
```
As a 运营人员
I want 点击下载按钮
So that 导出CSV格式用户数据
验收: /api/traffic-packages?action=export → 前端Blob下载
```
---
## 四、MVP边界
```yaml
已实现:
- AI对话（手机/QQ/状态/RFM/高价值）
- 5大模块前端页面
- 25个API端点
- MongoDB真实数据对接
- 飞书/企微渠道配置
待完善:
- 飞书机器人环境变量配置
- Redis缓存层
- 更多业务指标
```
---
## 五、关联文档
- [业务需求.md](./业务需求.md)
- [成本.md](./成本.md)
- [../2、架构/核心架构逻辑.md](../2、架构/核心架构逻辑.md)

18
开发文档/2、架构/README.md Normal file
View File

@@ -0,0 +1,18 @@
# 2、架构
> CTO + 架构师 | 系统架构图
## 本目录文档
| 文档 | 说明 |
|:---|:---|
| [_智能展开.md](./_智能展开.md) | 架构引擎激活 |
| [系统架构.md](./系统架构.md) | 系统架构 |
| [核心架构逻辑.md](./核心架构逻辑.md) | **从项目提取**：四层架构、数据流向 |
| [技术选型.md](./技术选型.md) | 技术栈 |
| [数据库.md](./数据库.md) | 数据库设计 |
## 联动
- 上游: 1-需求 | 下游: 3-原型、5-接口、7-数据库
- 指令: `@架构引擎 展开 [模块名]`

448
开发文档/2、架构/_智能展开.md Normal file
View File

@@ -0,0 +1,448 @@
# 🏗️ 架构智能展开引擎 (Architecture Auto-Expand)
> **角色激活**: 将此文件拖入 AI，即刻激活 **CTO + 系统架构师** 双重角色
> **核心能力**: 技术选型、系统设计、模块拆分、架构图生成
---
## 📋 一、快速启动指令
### 1.1 需求转架构
```
@架构引擎 请根据以下需求，生成完整的系统架构：
【项目名称】：[项目名]
【核心功能】：[一句话描述]
【预期规模】：日活[X]人 / 并发[X] / 数据量[X]
【技术偏好】：[有无特定要求，如：必须用Python]
【AI能力】：[是否需要 AI 功能]
```
### 1.2 展开输出清单
| 输出项 | 说明 | 格式 |
|:---|:---|:---|
| 技术选型表 | 前后端、数据库、部署工具 | 表格 + 理由 |
| 系统架构图 | C4 模型 / 分层架构 | Mermaid graph |
| 模块拆分 | 前后端模块职责 | 表格 |
| ER 图 | 核心数据模型 | Mermaid erDiagram |
| 部署架构 | 服务器拓扑 | Mermaid graph |
---
## 🧠 二、技术选型矩阵
### 2.1 卡若标准技术栈 (默认推荐)
```
┌─────────────────────────────────────────────────────────────────────┐
│ 卡若标准技术栈 │
├─────────────────────────────────────────────────────────────────────┤
│ 📱 前端层 │
│ ├── 框架: React / Next.js / Nuxt + Vue3 │
│ ├── UI: Shadcn UI + Tailwind CSS (iOS 风格) │
│ ├── 交互: 骨架屏 + 路由动画 (强制) │
│ └── 构建: Vite / Turbopack │
├─────────────────────────────────────────────────────────────────────┤
│ 🖥️ 后端层 │
│ ├── 语言: Python 3.10+ (首选) / Java (事务密集型) │
│ ├── 框架: FastAPI (异步) / Spring Boot │
│ ├── AI: LangChain / LlamaIndex + Gemini/OpenAI │
│ └── 验证: Pydantic + Type Hints (强制) │
├─────────────────────────────────────────────────────────────────────┤
│ 💾 数据层 │
│ ├── 业务库: MongoDB (首选) / MySQL (强事务) │
│ ├── 向量库: MongoDB Atlas Vector / ChromaDB / Pinecone │
│ ├── 缓存: Redis │
│ └── 文件: 阿里云 OSS / 腾讯 COS │
├─────────────────────────────────────────────────────────────────────┤
│ 🚀 部署层 │
│ ├── 服务器: 宝塔面板 / Docker + Docker Compose │
│ ├── 进程: PM2 (Node) / Gunicorn + Uvicorn (Python) │
│ ├── 网关: Nginx + 反向代理 │
│ └── CI/CD: GitHub Webhook 自动部署 │
└─────────────────────────────────────────────────────────────────────┘
```
### 2.2 技术选型决策树
```mermaid
flowchart TB
A[新项目] --> B{是否需要AI能力?}
B -->|是| C[Python FastAPI]
B -->|否| D{是否需要强事务?}
D -->|是| E[Java Spring Boot]
D -->|否| C
C --> F{数据规模?}
E --> F
F -->|小于100万| G[MongoDB 单机]
F -->|100万-1亿| H[MongoDB 副本集]
F -->|大于1亿| I[MongoDB 分片集群]
G --> J{是否需要向量检索?}
H --> J
I --> J
J -->|是| K[MongoDB Atlas Vector / ChromaDB]
J -->|否| L[纯 MongoDB]
K --> M[完成选型]
L --> M
```
---
## 📊 三、架构模板库
### 3.1 标准 Web 应用架构
```mermaid
graph TB
subgraph Client[客户端]
A1[H5/小程序]
A2[PC Web]
end
subgraph Gateway[网关层]
B1[Nginx]
B2[SSL/TLS]
B3[限流/防刷]
end
subgraph App[应用层]
C1[FastAPI 服务]
C2[认证中间件]
C3[业务路由]
end
subgraph Service[服务层]
D1[用户服务]
D2[流量池服务]
D3[分润服务]
D4[AI 服务]
end
subgraph Data[数据层]
E1[(MongoDB)]
E2[(Redis)]
E3[(向量库)]
E4[OSS]
end
subgraph External[外部服务]
F1[OpenAI/Gemini]
F2[短信服务]
F3[微信支付]
end
Client --> Gateway
Gateway --> App
App --> Service
Service --> Data
Service --> External
```
### 3.2 AI 增强型架构
```mermaid
graph TB
subgraph Input[输入层]
A1[用户问题]
A2[文档上传]
end
subgraph RAG[RAG 引擎]
B1[Embedding 服务]
B2[向量检索]
B3[上下文构建]
end
subgraph LLM[大模型层]
C1[Prompt 模板]
C2[LLM 调用]
C3[响应解析]
end
subgraph Output[输出层]
D1[结构化响应]
D2[流式输出]
end
Input --> B1
B1 --> E[(向量库)]
A1 --> B2
B2 --> E
B2 --> B3
B3 --> C1
C1 --> C2
C2 --> F[OpenAI/Gemini]
C2 --> C3
C3 --> Output
```
### 3.3 微服务架构 (大型项目)
```mermaid
graph TB
subgraph Gateway[API 网关]
G1[Kong/Nginx]
end
subgraph Services[微服务集群]
S1[用户服务<br/>:8001]
S2[订单服务<br/>:8002]
S3[支付服务<br/>:8003]
S4[AI服务<br/>:8004]
S5[通知服务<br/>:8005]
end
subgraph MQ[消息队列]
M1[RabbitMQ/Redis Stream]
end
subgraph DB[数据库集群]
D1[(用户库)]
D2[(订单库)]
D3[(向量库)]
end
Gateway --> Services
Services --> MQ
Services --> DB
S4 --> E[LLM API]
```
---
## 🔧 四、模块拆分规范
### 4.1 前端模块标准结构
```
/src
├── /app (or /pages) # 页面路由
│ ├── /scenarios # 场景获客
│ │ └── /new # 新建场景 (固定路径)
│ ├── /traffic # 流量池
│ └── /mine # 我的
├── /components # 通用组件
│ ├── /ui # Shadcn 基础组件
│ └── /business # 业务组件
├── /hooks # 自定义 Hooks
├── /lib # 工具函数
├── /styles # 全局样式
└── /types # TypeScript 类型
```
### 4.2 后端模块标准结构
```
/app
├── /routers # 路由层 (Controller)
│ ├── user.py
│ ├── traffic_pool.py
│ └── ai.py
├── /services # 服务层 (Business Logic)
│ ├── user_service.py
│ ├── traffic_service.py
│ └── ai_service.py
├── /models # 数据模型 (Pydantic)
│ ├── user.py
│ └── traffic_pool.py
├── /schemas # 请求/响应 Schema
├── /core # 核心配置
│ ├── config.py # 环境变量
│ ├── security.py # 认证鉴权
│ └── database.py # 数据库连接
├── /utils # 工具函数
└── main.py # 入口文件
```
---
## 🔗 五、跨目录联动
### 5.1 上下游关系
```mermaid
graph LR
A[1、需求] -->|功能清单| B[2、架构]
B -->|模块拆分| C[3、原型]
B -->|API设计| D[5、接口]
B -->|数据模型| E[7、数据库]
B -->|部署方案| F[8、部署]
```
### 5.2 联动指令
```
# 架构确定后，自动生成接口文档
@联动 架构→接口：基于模块拆分生成 API 清单
# 架构确定后，自动生成数据库设计
@联动 架构→数据库：基于数据模型生成 ER 图
# 架构确定后，自动生成部署方案
@联动 架构→部署：基于技术选型生成部署脚本
```
---
## 🤖 六、AI 协作指令
### 6.1 角色设定
```yaml
角色: CTO + 系统架构师
风格:
- 稳定优先，拒绝过度设计
- 实用主义，解决问题为先
- 安全第一，密钥绝不硬编码
输出: 必须包含架构图 (Mermaid) + 选型理由
检查: 必须通过安全检查清单
```
### 6.2 指令集
| 指令 | 功能 | 示例 |
|:---|:---|:---|
| `@技术选型` | 生成技术选型对比表 | `@技术选型 Python vs Java 对比` |
| `@架构图` | 生成系统架构图 | `@架构图 私域银行系统` |
| `@模块拆分` | 拆分前后端模块 | `@模块拆分 用户中心` |
| `@ER图` | 生成数据模型图 | `@ER图 流量池相关表` |
| `@性能评估` | 评估架构性能瓶颈 | `@性能评估 日活10万` |
| `@安全检查` | 检查架构安全风险 | `@安全检查 当前架构` |
---
## 🛡️ 七、安全规范检查清单
### 7.1 必须通过的检查
```yaml
代码安全:
- [ ] 敏感信息走环境变量 (.env)
- [ ] 禁止 os.system()，使用 subprocess
- [ ] 禁止硬编码 Token/密钥
- [ ] SQL/NoSQL 必须参数化查询
网络安全:
- [ ] 强制 HTTPS
- [ ] API 限流 (Rate Limit)
- [ ] CORS 白名单配置
- [ ] JWT Token 过期机制
数据安全:
- [ ] 密码必须 Hash (Argon2/bcrypt)
- [ ] 手机号/身份证加密存储
- [ ] 敏感操作记录审计日志
```
### 7.2 禁止清单
```python
# ❌ 绝对禁止
os.system("rm -rf /") # 系统命令注入
f"SELECT * FROM {table}" # SQL 注入
password = "123456" # 硬编码密码
api_key = "sk-xxx" # 硬编码密钥
# ✅ 正确做法
subprocess.run(["rm", "-rf", path], check=True) # 参数化命令
db.execute("SELECT * FROM users WHERE id = ?", [user_id]) # 参数化查询
password = os.getenv("DB_PASSWORD") # 环境变量
api_key = settings.OPENAI_API_KEY # 配置类
```
---
## 📝 八、架构文档模板
```markdown
# [项目名称] 系统架构文档 v1.0
> 创建日期：YYYY-MM-DD | 架构师：卡若 | 状态：草稿/已评审/已确认
---
## 一、技术选型
### 1.1 选型总览
| 层级 | 技术 | 版本 | 选型理由 |
|:---|:---|:---|:---|
| 前端框架 | React + Next.js | 14.x | SSR + App Router |
| UI 组件 | Shadcn UI | latest | iOS 风格 |
| 样式 | Tailwind CSS | 3.x | 原子化 CSS |
| 后端框架 | FastAPI | 0.100+ | 异步 + 类型安全 |
| 数据库 | MongoDB | 7.x | 文档型 + 向量索引 |
| 缓存 | Redis | 7.x | Session + 缓存 |
| AI 框架 | LangChain | 0.1.x | RAG + Agent |
### 1.2 版本要求
- Python: >= 3.10
- Node.js: >= 18.x
- MongoDB: >= 7.0
---
## 二、系统架构图
[Mermaid 架构图]
---
## 三、模块设计
### 3.1 前端模块
| 模块 | 路径 | 职责 | 依赖 |
|:---|:---|:---|:---|
### 3.2 后端模块
| 模块 | 服务 | 职责 | API 前缀 |
|:---|:---|:---|:---|
---
## 四、数据流设计
[Mermaid 序列图]
---
## 五、部署架构
[Mermaid 部署图]
---
## 六、安全设计
### 6.1 认证方案
### 6.2 数据加密
### 6.3 审计日志
---
## 附录
### A. 技术选型对比表
### B. 性能测试报告
### C. 安全评估报告
```
---
## ⚠️ 九、注意事项
### 9.1 常见陷阱
- ❌ 过度设计（小项目上微服务）
- ❌ 技术选型追新（不稳定版本）
- ❌ 忽略安全设计
- ❌ 没有考虑扩展性
### 9.2 最佳实践
- ✅ 先跑通再优化（MVP 原则）
- ✅ 技术栈统一（减少心智负担）
- ✅ 安全检查前置
- ✅ 文档与代码同步
---
> **下一步**: 架构确定后，拖入 `3、原型/_智能展开.md` 进行界面原型设计

48
开发文档/2、架构/技术选型.md Normal file
View File

@@ -0,0 +1,48 @@
# 神射手数据中台 - 技术选型
> 📅 更新: 2026-01-31
---
## 一、前端
| 项目 | 选型 | 说明 |
|:---|:---|:---|
| 框架 | Next.js 14 | App Router |
| UI | Radix UI | 组件库 |
| 样式 | TailwindCSS | 原子化 |
| 图表 | Recharts | 数据可视化 |
| 状态 | React Hooks | useState, useEffect |
| 风格 | 苹果毛玻璃 | backdrop-blur |
---
## 二、后端
| 项目 | 选型 | 说明 |
|:---|:---|:---|
| 运行时 | Node.js | Next.js API Routes |
| 数据库 | MongoDB | 本地Docker |
| 连接 | mongodb 驱动 | 连接池复用 |
| 网关 | FastAPI | 卡若AI Gateway |
---
## 三、数据库
| 项目 | 选型 | 说明 |
|:---|:---|:---|
| 主库 | MongoDB | localhost:27017 |
| 认证 | admin/admin123 | authSource=admin |
| 规模 | 26个KR_*库 | 20.13亿条 |
---
## 四、部署
| 项目 | 选型 | 说明 |
|:---|:---|:---|
| 开发 | npm run dev | 端口3001 |
| 构建 | next build | 生产构建 |
| 运行 | next start | 生产服务 |
| 容器 | Docker | MongoDB |

53
开发文档/2、架构/数据库.md Normal file
View File

@@ -0,0 +1,53 @@
# 神射手数据中台 - 数据库配置
> 📅 更新: 2026-01-31
> ⚠️ 敏感信息请使用环境变量
---
## 一、连接信息（本地开发）
| 项目 | 配置 |
|:---|:---|
| 地址 | localhost:27017 |
| 认证 | admin / admin123 |
| authSource | admin |
| 连接串 | mongodb://admin:admin123@localhost:27017/?authSource=admin |
---
## 二、环境变量
```bash
# .env.local
MONGODB_URI=mongodb://admin:admin123@localhost:27017/?authSource=admin
```
---
## 三、Docker启动
```bash
# 检查MongoDB容器
docker ps | grep mongo
# 容器名: datacenter_mongodb
# 端口: 0.0.0.0:27017->27017/tcp
```
---
## 四、核心集合
| 数据库 | 集合 | 用途 |
|:---|:---|:---|
| KR | 用户估值 | 统一画像 |
| KR_腾讯 | QQ+手机 | QQ↔手机 |
| KR_微博 | 微博uid+手机 | UID↔手机 |
| KR_存客宝 | 用户资产统一视图 | 存客宝用户 |
| KR_点了码 | 用户资产统一视图 | 点了码用户 |
---
## 五、关联文档
- [../7、数据库/ER与查询逻辑.md](../7、数据库/ER与查询逻辑.md)

69
开发文档/2、架构/核心架构逻辑.md Normal file
View File

@@ -0,0 +1,69 @@
# 神射手 - 核心架构逻辑
> 📅 从 .apm/docs/architecture.md 与代码提取 | 2026-01-31
---
## 一、四层架构
```
客户端层 → 网关层 → 服务层 → 数据层
```
### 1.1 客户端层
- 浏览器 (localhost:3001)
- 飞书机器人
- 企业微信
- API调用方
### 1.2 网关层
- **Next.js 14**: 前端 + /api/* 接口
- **卡若AI Gateway**: /feishu/*, /wecom/*
### 1.3 服务层（核心逻辑）
| 服务 | 核心函数 | 文件 |
|:---|:---|:---|
| 用户查询 | queryFullProfile, intelligentSearch | lib/mongodb.ts |
| AI对话 | parseIntent, handleQuery | app/api/ai-chat/route.ts |
| 标签统计 | $sample 采样 | app/api/tags/route.ts |
| 流量池 | user_evaluation_score 分桶 | app/api/traffic-packages/route.ts |
| 人群圈选 | getProjectPools, getPoolUsers | app/api/crowd-pools/route.ts |
### 1.4 数据层
- MongoDB localhost:27017
- 26个KR_*数据库
- 20.13亿条记录
---
## 二、数据流向
```
数据源(KR_*) → AI标签引擎 → KR.用户估值 → 流量池分层 → 导出/发送
```
### 2.1 核心集合
- **KR.用户估值**: 统一画像、user_evaluation_score
- **KR_腾讯.QQ+手机**: QQ↔手机
- **KR_微博.微博uid+手机**: UID↔手机
- **KR_存客宝.用户资产统一视图**: 流量池、unified_tags
---
## 三、关键设计决策
| 决策 | 原因 |
|:---|:---|
| $sample 采样 | 大表聚合超时，采样后按比例估算 |
| user_evaluation_score | 实际字段，非rfm_composite_score |
| 按项目分类人群 | 存客宝/点了码/微博/QQ 各自结构不同 |
| 连接池复用 | getMongoClient 全局缓存 |
---
## 四、关联文档
- [系统架构.md](./系统架构.md)
- [技术选型.md](./技术选型.md)
- [../.apm/docs/architecture.md](../../.apm/docs/architecture.md)

89
开发文档/2、架构/系统架构.md Normal file
View File

@@ -0,0 +1,89 @@
# 神射手数据中台 - 系统架构
> 📅 更新: 2026-01-31
---
## 一、四层架构
```
客户端层 → 网关层 → 服务层 → 数据层
```
### 1.1 客户端层
- 浏览器 (localhost:3001)
- 飞书机器人
- 企业微信
- API调用方
### 1.2 网关层
- **Next.js 14**：前端 + /api/* 接口
- **卡若AI Gateway**：/feishu/*, /wecom/*
### 1.3 服务层
- 用户查询：queryFullProfile, intelligentSearch
- AI对话：parseIntent, handleQuery
- 标签统计：$sample 采样
- 流量池：user_evaluation_score 分桶
- 人群圈选：按项目 getProjectPools
### 1.4 数据层
- MongoDB localhost:27017
- 26个KR_*数据库
- 20.13亿条记录
---
## 二、架构图
```mermaid
graph TB
subgraph 客户端
A[浏览器]
B[飞书]
C[企微]
end
subgraph 网关
D[Next.js :3001]
E[卡若AI Gateway :8000]
end
subgraph 服务
F[用户查询]
G[AI对话]
H[标签引擎]
I[流量池]
end
subgraph 数据
J[(MongoDB :27017)]
end
A --> D
B --> E
C --> E
D --> F
D --> G
D --> H
D --> I
E --> G
F --> J
G --> J
H --> J
I --> J
```
---
## 三、数据流向
```
数据源(KR_*) → AI标签引擎 → KR.用户估值 → 流量池分层 → 导出/发送
```
---
## 四、关联文档
- [核心架构逻辑.md](./核心架构逻辑.md)
- [技术选型.md](./技术选型.md)
- [数据库.md](./数据库.md)

16
开发文档/3、原型/README.md Normal file
View File

@@ -0,0 +1,16 @@
# 3、原型
> UI/UX 设计师 | 页面结构
## 本目录文档
| 文档 | 说明 |
|:---|:---|
| [_智能展开.md](./_智能展开.md) | 原型引擎激活 |
| [页面结构.md](./页面结构.md) | **从项目提取**：路由树、组件结构 |
| [原型设计规范.md](./原型设计规范.md) | 设计规范 |
## 联动
- 上游: 1-需求、2-架构 | 下游: 4-前端
- 指令: `@原型引擎 展开 [页面名]`

440
开发文档/3、原型/_智能展开.md Normal file
View File

@@ -0,0 +1,440 @@
# 🎨 原型智能展开引擎 (Prototype Auto-Expand)
> **角色激活**: 将此文件拖入 AI，即刻激活 **UI/UX 设计师** 角色
> **核心能力**: 页面结构、交互流程、iOS 风格规范、组件设计
---
## 📋 一、快速启动指令
### 1.1 需求转原型
```
@原型引擎 请根据以下需求，生成完整的原型设计：
【页面名称】：[页面名]
【核心功能】：[这个页面要完成什么]
【用户角色】：[谁会用这个页面]
【参考风格】：[可选：iOS/Android/Web/竞品截图]
```
### 1.2 展开输出清单
| 输出项 | 说明 | 格式 |
|:---|:---|:---|
| 页面结构图 | 信息架构 IA | Mermaid graph |
| 页面流程图 | 页面跳转逻辑 | Mermaid flowchart |
| 组件清单 | 每个页面用到的组件 | 表格 |
| 交互说明 | 点击/滑动/加载行为 | 文字描述 |
| iOS 规范 | 颜色/字体/间距 | Tailwind 类名 |
---
## 🎯 二、iOS 设计规范 (卡若标准)
### 2.1 设计系统
```
┌─────────────────────────────────────────────────────────────────────┐
│ 卡若 iOS 设计系统 │
├─────────────────────────────────────────────────────────────────────┤
│ 🎨 色彩体系 │
│ ├── 背景: #F2F2F7 (Grouped Background) │
│ ├── 卡片: #FFFFFF │
│ ├── 分割线: #C6C6C8 │
│ ├── 主色: #007AFF (System Blue) │
│ ├── 成功: #34C759 (System Green) │
│ ├── 警告: #FF9500 (System Orange) │
│ └── 危险: #FF3B30 (System Red) │
├─────────────────────────────────────────────────────────────────────┤
│ 📝 字体体系 │
│ ├── 首选: San Francisco / -apple-system │
│ ├── 中文: PingFang SC │
│ ├── 大标题: 34px / font-bold │
│ ├── 标题: 17px / font-semibold │
│ ├── 正文: 17px / font-normal │
│ ├── 副标题: 15px / text-gray-500 │
│ └── 说明: 13px / text-gray-400 │
├─────────────────────────────────────────────────────────────────────┤
│ 📐 间距体系 │
│ ├── 页面边距: 16px (px-4) │
│ ├── 卡片间距: 12px (gap-3) │
│ ├── 列表行高: 44px (h-11) │
│ └── 安全区域: env(safe-area-inset-*) │
├─────────────────────────────────────────────────────────────────────┤
│ 🔲 圆角体系 │
│ ├── 大卡片: 12px (rounded-xl) │
│ ├── 按钮: 10px (rounded-lg) │
│ ├── 输入框: 8px (rounded-md) │
│ └── 头像: 50% (rounded-full) │
├─────────────────────────────────────────────────────────────────────┤
│ 🌫️ 阴影体系 │
│ └── 柔和弥散: shadow-sm (0 1px 2px rgba(0,0,0,0.05)) │
└─────────────────────────────────────────────────────────────────────┘
```
### 2.2 Tailwind 快速配置
```javascript
// tailwind.config.js 卡若 iOS 风格配置
module.exports = {
theme: {
extend: {
colors: {
'ios-bg': '#F2F2F7',
'ios-card': '#FFFFFF',
'ios-separator': '#C6C6C8',
'ios-blue': '#007AFF',
'ios-green': '#34C759',
'ios-orange': '#FF9500',
'ios-red': '#FF3B30',
},
fontFamily: {
'ios': ['-apple-system', 'BlinkMacSystemFont', 'PingFang SC', 'sans-serif'],
},
},
},
}
```
---
## 📱 三、页面模板库
### 3.1 标准列表页
```
┌──────────────────────────────────────┐
│ ← 返回 标题 [操作按钮] │ ← Header (44px)
├──────────────────────────────────────┤
│ 🔍 搜索... │ ← SearchBar (可选)
├──────────────────────────────────────┤
│ │
│ ┌────────────────────────────────┐ │
│ │ 图标 标题 > │ │ ← ListItem (44px)
│ │ 副标题 │ │
│ └────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────┐ │
│ │ 图标 标题 > │ │
│ │ 副标题 │ │
│ └────────────────────────────────┘ │
│ │
├──────────────────────────────────────┤
│ 🏠首页 📊流量池 👤我的 │ ← TabBar (49px)
└──────────────────────────────────────┘
```
### 3.2 标准表单页
```
┌──────────────────────────────────────┐
│ ← 取消 填写信息 [保存] │ ← Header
├──────────────────────────────────────┤
│ │
│ 标签 │
│ ┌────────────────────────────────┐ │
│ │ 请输入... │ │ ← Input
│ └────────────────────────────────┘ │
│ │
│ 标签 │
│ ┌────────────────────────────────┐ │
│ │ 请选择 ∨ │ │ ← Select
│ └────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────┐ │
│ │ 确认提交 │ │ ← Button
│ └────────────────────────────────┘ │
│ │
└──────────────────────────────────────┘
```
### 3.3 数据展示页 (分润看板)
```
┌──────────────────────────────────────┐
│ ← 返回 我的收益 │
├──────────────────────────────────────┤
│ │
│ ┌────────────────────────────────┐ │
│ │ 今日收益 │ │
│ │ ¥ 1,234.56 │ │ ← 大字金额
│ │ 累计: ¥12,345.67 │ │
│ │ [立即提现] │ │
│ └────────────────────────────────┘ │
│ │
│ 收益明细 查看全部 >│
│ ┌────────────────────────────────┐ │
│ │ 用户A下单 +¥12.50 10:30 │ │
│ │ 用户B下单 +¥8.00 09:15 │ │
│ │ ... │ │
│ └────────────────────────────────┘ │
│ │
└──────────────────────────────────────┘
```
---
## 🔄 四、交互规范 (强制)
### 4.1 加载状态
```yaml
# 强制规则：严禁白屏和 Spinner
数据加载中:
方案: Skeleton 骨架屏
组件: van-skeleton / Shadcn Skeleton
时机: 数据请求开始 → 数据返回
图片加载中:
方案: 灰色占位 + 渐显
失败: 显示默认占位图
按钮加载中:
方案: 禁用 + loading 状态
文案: "提交中..." / "加载中..."
```
### 4.2 转场动画
```yaml
# 强制规则：所有路由切换必须有动画
前进 (Push):
动画: 从右向左滑入
时长: 300ms
缓动: ease-out
后退 (Pop):
动画: 从左向右滑出
时长: 300ms
缓动: ease-in
Modal 弹出:
动画: 从下向上滑入 + 背景遮罩渐显
时长: 250ms
```
### 4.3 反馈机制
```yaml
操作成功:
方案: Toast (顶部或中间)
图标: ✓ 绿色
时长: 1.5s
操作失败:
方案: Toast + 震动 (移动端)
图标: ✗ 红色
时长: 2s
加载中:
方案: Loading 遮罩 (阻断操作)
文案: "处理中..."
```
---
## 🔗 五、跨目录联动
### 5.1 上下游关系
```mermaid
graph LR
A[1、需求] -->|用户故事| B[3、原型]
C[2、架构] -->|模块拆分| B
B -->|页面结构| D[4、前端]
B -->|交互需求| E[5、接口]
```
### 5.2 联动指令
```
# 原型确定后，自动生成前端代码
@联动 原型→前端：基于 [页面结构] 生成 React 组件
# 原型确定后，自动识别接口需求
@联动 原型→接口：基于 [交互说明] 识别需要的 API
```
---
## 🤖 六、AI 协作指令
### 6.1 角色设定
```yaml
角色: UI/UX 设计师
风格:
- iOS 原生风格优先
- 极简、高效、流量入口显眼
- 分润数据必须醒目
输出: 必须包含页面结构图 + Tailwind 类名
检查: 必须包含骨架屏和转场动画说明
```
### 6.2 指令集
| 指令 | 功能 | 示例 |
|:---|:---|:---|
| `@页面结构` | 生成信息架构 | `@页面结构 我的钱包页面` |
| `@页面流程` | 生成页面跳转图 | `@页面流程 用户注册到下单` |
| `@组件清单` | 列出页面组件 | `@组件清单 流量池列表页` |
| `@交互说明` | 描述交互细节 | `@交互说明 下拉刷新` |
| `@iOS样式` | 生成 Tailwind 类 | `@iOS样式 列表卡片` |
| `@骨架屏` | 设计骨架屏结构 | `@骨架屏 首页` |
---
## 📝 七、原型文档模板
```markdown
# [页面名称] 原型设计文档 v1.0
> 创建日期：YYYY-MM-DD | 设计师：卡若 | 状态：草稿/已评审
---
## 一、页面信息
| 项目 | 说明 |
|:---|:---|
| 页面路径 | /xxx/xxx |
| 页面类型 | 列表页/详情页/表单页/弹窗 |
| 用户角色 | 合作方/管理员/游客 |
| 入口来源 | 从哪些页面可以进入 |
---
## 二、页面结构
### 2.1 布局示意
[ASCII 布局图]
### 2.2 组件清单
| 区域 | 组件 | 说明 | 交互 |
|:---|:---|:---|:---|
---
## 三、交互说明
### 3.1 加载状态
[骨架屏设计]
### 3.2 用户操作
| 操作 | 触发条件 | 响应行为 | 跳转页面 |
|:---|:---|:---|:---|
### 3.3 转场动画
[动画说明]
---
## 四、样式规范
### 4.1 Tailwind 类名
[关键组件的类名]
### 4.2 自定义样式
[如有特殊样式]
---
## 附录
### A. 竞品参考截图
### B. 设计稿链接
```
---
## 📊 八、示例输出
### 8.1 页面结构图示例
```mermaid
graph TB
subgraph App[私域银行 App]
subgraph Tab1[首页]
A1[Banner 轮播]
A2[快捷入口]
A3[最新动态]
end
subgraph Tab2[流量池]
B1[搜索栏]
B2[筛选标签]
B3[流量池列表]
end
subgraph Tab3[我的]
C1[用户信息卡]
C2[收益概览]
C3[功能菜单]
end
end
Tab1 --> D[场景详情]
Tab2 --> E[流量池详情]
Tab3 --> F[钱包/提现]
Tab3 --> G[设备管理]
```
### 8.2 页面流程图示例
```mermaid
flowchart TB
A[启动 App] --> B{已登录?}
B -->|否| C[登录页]
B -->|是| D[首页]
C --> C1[手机号输入]
C1 --> C2[验证码输入]
C2 --> D
D --> E[流量池]
D --> F[我的]
E --> E1[流量池详情]
E1 --> E2[开启流量池]
F --> F1[我的收益]
F1 --> F2[申请提现]
F2 --> F3[提现成功]
```
### 8.3 组件样式示例
```jsx
// iOS 风格列表项
<div className="bg-white px-4 py-3 flex items-center justify-between
active:bg-gray-100 transition-colors">
<div className="flex items-center gap-3">
<div className="w-10 h-10 rounded-full bg-ios-blue/10
flex items-center justify-center">
<Icon className="w-5 h-5 text-ios-blue" />
</div>
<div>
<p className="text-[17px] font-medium text-gray-900">标题文字</p>
<p className="text-[13px] text-gray-500">副标题说明</p>
</div>
</div>
<ChevronRight className="w-5 h-5 text-gray-300" />
</div>
```
---
## ⚠️ 九、注意事项
### 9.1 常见陷阱
- ❌ 直接抄 Android Material Design
- ❌ 使用 Spinner 代替骨架屏
- ❌ 页面切换无动画
- ❌ 忽略安全区域适配
### 9.2 最佳实践
- ✅ 严格遵循 iOS HIG
- ✅ 所有数据加载用 Skeleton
- ✅ 所有路由切换有 Transition
- ✅ 金额/收益必须醒目显示
---
> **下一步**: 原型确定后，拖入 `4、前端/_智能展开.md` 进行前端代码开发

58
开发文档/3、原型/原型设计规范.md Normal file
View File

@@ -0,0 +1,58 @@
# 神射手数据中台 - 原型设计规范
> 📅 更新: 2026-01-31
---
## 一、设计原则
| 原则 | 说明 |
|:---|:---|
| 极简 | 苹果毛玻璃风格 |
| 高效 | 流量入口显眼、数据清晰 |
| 一致 | 5大模块统一布局 |
---
## 二、界面规范
### 2.1 页面路径
| 模块 | 路径 | 说明 |
|:---|:---|:---|
| 首页 | / | AI对话 |
| 数据接入 | /data-ingestion/* | 5个子页 |
| 标签画像 | /tag-portrait/* | 3个子页 |
| AI Agent | /ai-agent/* | 4个子页 |
| 数据市场 | /data-market/* | 2个子页 |
| 系统监控 | /monitoring/* | 3个子页 |
### 2.2 导航结构
- 左侧：5大模块 + 系统监控
- 顶部：标题、刷新
- 内容区：卡片式布局
### 2.3 交互规范
- 加载：Skeleton 骨架屏
- 转场：淡入淡出
- 反馈：Toast 提示
---
## 三、UI规范（苹果毛玻璃）
```css
/* 页面背景 */
bg-gradient-to-br from-slate-50 via-blue-50/30 to-purple-50/20
/* 卡片 */
bg-white/80 backdrop-blur border-slate-200/60 rounded-xl shadow-lg
/* 按钮 */
bg-gradient-to-r from-blue-500 to-purple-500
```
---
## 四、关联文档
- [页面结构.md](./页面结构.md)
- [../4、前端/前端开发规范.md](../4、前端/前端开发规范.md)

88
开发文档/3、原型/页面结构.md Normal file
View File

@@ -0,0 +1,88 @@
# 神射手 - 页面结构
> 📅 从 app/ 路由提取 | 2026-01-31
---
## 一、路由树
```
/ # 首页 - 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/ # 智能报告
│ └── chat/ # 对话（已移除到首页）
├── data-market/ # 数据市场
│ ├── packages/ # 流量包管理
│ └── api/ # API服务
├── monitoring/ # 系统监控
│ ├── health/ # 健康检查
│ ├── alerts/ # 告警中心
│ └── business/ # 业务指标
└── overview/ # 概览（如有）
```
---
## 二、页面组件结构
### 2.1 首页 (app/page.tsx)
```
Layout
├── Header (神射手 用户资产数字化中台)
├── AI对话区
│ ├── 输入框
│ ├── 思考过程 (thinking)
│ └── 用户画像卡片 (UserPortrait)
├── 模块导航 (5个卡片)
└── 系统状态 (2.01B 可查询)
```
### 2.2 人群圈选 (tag-portrait/crowd)
```
项目列表 → 流量池列表 → 用户表格
├── 面包屑导航
├── 项目卡片 (存客宝/点了码/微博/QQ)
├── 流量池/标签列表
├── 用户表格 (分页)
└── 保存为流量包 弹窗
```
### 2.3 数据血缘 (data-ingestion/lineage)
```
可拖拽画布
├── 数据源节点 (Source)
├── 转换节点 (Transform)
├── 目标节点 (Target)
└── 连接线 (Connection)
```
---
## 三、UI规范
```css
/* 苹果毛玻璃 */
background: from-slate-50 via-blue-50/30 to-purple-50/20
card: bg-white/80 backdrop-blur shadow-lg rounded-xl
button: bg-gradient-to-r from-blue-500 to-purple-500
```
---
## 四、关联文档
- [原型设计规范.md](./原型设计规范.md)
- [../4、前端/核心组件代码.md](../4、前端/核心组件代码.md)

16
开发文档/4、前端/README.md Normal file
View File

@@ -0,0 +1,16 @@
# 4、前端
> 前端主程 | 组件代码
## 本目录文档
| 文档 | 说明 |
|:---|:---|
| [_智能展开.md](./_智能展开.md) | 前端引擎激活、iOS风格 |
| [核心组件代码.md](./核心组件代码.md) | **从项目提取**：AI对话、毛玻璃样式 |
| [前端开发规范.md](./前端开发规范.md) | 开发规范 |
## 联动
- 上游: 3-原型、5-接口 | 下游: 8-部署
- 指令: `@前端引擎 展开 [组件名]`

723
开发文档/4、前端/_智能展开.md Normal file
View File

@@ -0,0 +1,723 @@
# ⚛️ 前端智能展开引擎 (Frontend Auto-Expand)
> **角色激活**: 将此文件拖入 AI，即刻激活 **前端技术专家** 角色
> **核心能力**: React 组件、Tailwind 样式、iOS 风格、性能优化
---
## 📋 一、快速启动指令
### 1.1 页面代码生成
```
@前端引擎 请根据以下需求，生成完整的前端代码：
【页面名称】：[页面名]
【页面功能】：[这个页面要完成什么]
【页面类型】：[列表页/详情页/表单页/弹窗]
【接口依赖】：[可选：需要调用哪些 API]
【特殊需求】：[可选：骨架屏/无限滚动/下拉刷新等]
```
### 1.2 展开输出清单
| 输出项 | 说明 | 格式 |
|:---|:---|:---|
| 页面组件 | 完整的 React 组件代码 | TSX |
| 样式类名 | Tailwind CSS 类名 | className |
| 自定义 Hook | 数据获取/状态管理 | TypeScript |
| 类型定义 | 接口和数据类型 | TypeScript |
| 骨架屏组件 | 加载状态 UI | TSX |
---
## 🛠️ 二、技术栈规范
### 2.1 卡若标准前端栈
```
┌─────────────────────────────────────────────────────────────────────┐
│ 卡若前端技术栈 │
├─────────────────────────────────────────────────────────────────────┤
│ 🏗️ 框架层 │
│ ├── React 18+ (首选) / Vue 3 + Nuxt │
│ ├── Next.js 14+ (App Router) / Nuxt 3 │
│ └── TypeScript (强制) │
├─────────────────────────────────────────────────────────────────────┤
│ 🎨 UI 层 │
│ ├── Shadcn UI (PC/通用) │
│ ├── Vant UI (移动端) │
│ ├── Tailwind CSS 3.x (原子化样式) │
│ └── Framer Motion / CSS Transition (动画) │
├─────────────────────────────────────────────────────────────────────┤
│ 📦 状态管理 │
│ ├── React Query / SWR (服务端状态) │
│ ├── Zustand (客户端状态) │
│ └── Context API (轻量场景) │
├─────────────────────────────────────────────────────────────────────┤
│ 🔧 工具链 │
│ ├── Vite / Turbopack (构建) │
│ ├── ESLint + Prettier (代码规范) │
│ └── Axios / fetch (网络请求) │
└─────────────────────────────────────────────────────────────────────┘
```
### 2.2 目录结构规范
```
/src
├── /app # 页面路由 (Next.js App Router)
│ ├── /(auth) # 认证相关路由组
│ │ ├── /login
│ │ └── /register
│ ├── /(main) # 主应用路由组
│ │ ├── /scenarios # 场景获客
│ │ │ ├── /new # 新建场景 (固定路径!)
│ │ │ └── /[id] # 场景详情
│ │ ├── /traffic # 流量池
│ │ └── /mine # 我的
│ ├── /api # API 路由
│ └── layout.tsx # 根布局
│
├── /components # 组件库
│ ├── /ui # Shadcn 基础组件
│ │ ├── button.tsx
│ │ ├── skeleton.tsx # 骨架屏 (必须!)
│ │ └── ...
│ ├── /business # 业务组件
│ │ ├── UserCard.tsx
│ │ ├── TrafficPoolItem.tsx
│ │ └── ...
│ └── /layout # 布局组件
│ ├── Header.tsx
│ ├── TabBar.tsx
│ └── PageContainer.tsx
│
├── /hooks # 自定义 Hooks
│ ├── useAuth.ts
│ ├── useTrafficPool.ts
│ └── usePagination.ts
│
├── /lib # 工具库
│ ├── api.ts # API 封装
│ ├── utils.ts # 工具函数
│ └── constants.ts # 常量
│
├── /styles # 样式
│ └── globals.css # 全局样式 + Tailwind
│
└── /types # 类型定义
├── api.d.ts
└── business.d.ts
```
---
## 🎨 三、iOS 风格组件库
### 3.1 页面容器
```tsx
// components/layout/PageContainer.tsx
interface PageContainerProps {
children: React.ReactNode;
title?: string;
showBack?: boolean;
rightAction?: React.ReactNode;
loading?: boolean;
}
export function PageContainer({
children,
title,
showBack = true,
rightAction,
loading = false,
}: PageContainerProps) {
return (
<div className="min-h-screen bg-ios-bg">
{/* iOS 风格 Header */}
<header className="sticky top-0 z-50 h-11 bg-white/80 backdrop-blur-xl
border-b border-ios-separator flex items-center px-4">
{showBack && (
<button onClick={() => router.back()} className="text-ios-blue">
<ChevronLeft className="w-6 h-6" />
</button>
)}
<h1 className="flex-1 text-center text-[17px] font-semibold">
{title}
</h1>
<div className="w-10">{rightAction}</div>
</header>
{/* 内容区域 */}
<main className="pb-safe">
{loading ? <PageSkeleton /> : children}
</main>
</div>
);
}
```
### 3.2 iOS 列表项
```tsx
// components/ui/ListItem.tsx
interface ListItemProps {
icon?: React.ReactNode;
title: string;
subtitle?: string;
value?: string | React.ReactNode;
arrow?: boolean;
onClick?: () => void;
}
export function ListItem({
icon,
title,
subtitle,
value,
arrow = true,
onClick,
}: ListItemProps) {
return (
<div
onClick={onClick}
className="bg-white px-4 py-3 flex items-center justify-between
active:bg-gray-100 transition-colors cursor-pointer"
>
<div className="flex items-center gap-3">
{icon && (
<div className="w-8 h-8 rounded-lg bg-ios-blue/10
flex items-center justify-center text-ios-blue">
{icon}
</div>
)}
<div>
<p className="text-[17px] text-gray-900">{title}</p>
{subtitle && (
<p className="text-[13px] text-gray-500 mt-0.5">{subtitle}</p>
)}
</div>
</div>
<div className="flex items-center gap-2">
{value && (
<span className="text-[15px] text-gray-500">{value}</span>
)}
{arrow && <ChevronRight className="w-5 h-5 text-gray-300" />}
</div>
</div>
);
}
```
### 3.3 骨架屏组件 (强制使用)
```tsx
// components/ui/skeleton.tsx
import { cn } from "@/lib/utils";
interface SkeletonProps {
className?: string;
}
// 基础骨架
export function Skeleton({ className }: SkeletonProps) {
return (
<div
className={cn(
"animate-pulse rounded-md bg-gray-200",
className
)}
/>
);
}
// 列表项骨架
export function ListItemSkeleton() {
return (
<div className="bg-white px-4 py-3 flex items-center gap-3">
<Skeleton className="w-10 h-10 rounded-full" />
<div className="flex-1">
<Skeleton className="h-4 w-24 mb-2" />
<Skeleton className="h-3 w-32" />
</div>
</div>
);
}
// 卡片骨架
export function CardSkeleton() {
return (
<div className="bg-white rounded-xl p-4 m-4">
<Skeleton className="h-6 w-1/3 mb-4" />
<Skeleton className="h-10 w-1/2 mb-2" />
<Skeleton className="h-4 w-2/3" />
</div>
);
}
// 页面骨架
export function PageSkeleton() {
return (
<div className="space-y-4 p-4">
<CardSkeleton />
<div className="space-y-1">
{[...Array(5)].map((_, i) => (
<ListItemSkeleton key={i} />
))}
</div>
</div>
);
}
```
### 3.4 金额展示组件 (云阿米巴核心)
```tsx
// components/business/MoneyDisplay.tsx
interface MoneyDisplayProps {
amount: number;
label?: string;
size?: 'sm' | 'md' | 'lg';
trend?: 'up' | 'down' | 'none';
}
export function MoneyDisplay({
amount,
label,
size = 'md',
trend = 'none',
}: MoneyDisplayProps) {
const sizeClasses = {
sm: 'text-xl',
md: 'text-3xl',
lg: 'text-4xl',
};
const trendColors = {
up: 'text-ios-green',
down: 'text-ios-red',
none: 'text-gray-900',
};
return (
<div className="text-center">
{label && (
<p className="text-[13px] text-gray-500 mb-1">{label}</p>
)}
<p className={cn(
'font-bold tabular-nums',
sizeClasses[size],
trendColors[trend]
)}>
<span className="text-base mr-1">¥</span>
{amount.toLocaleString('zh-CN', {
minimumFractionDigits: 2,
maximumFractionDigits: 2,
})}
</p>
</div>
);
}
```
---
## 🔄 四、交互规范代码
### 4.1 路由转场动画
```tsx
// app/template.tsx - 全局转场动画
'use client';
import { motion } from 'framer-motion';
export default function Template({ children }: { children: React.ReactNode }) {
return (
<motion.div
initial={{ x: 20, opacity: 0 }}
animate={{ x: 0, opacity: 1 }}
exit={{ x: -20, opacity: 0 }}
transition={{ duration: 0.3, ease: 'easeOut' }}
>
{children}
</motion.div>
);
}
```
### 4.2 下拉刷新
```tsx
// hooks/usePullRefresh.ts
import { useState, useCallback } from 'react';
export function usePullRefresh(onRefresh: () => Promise<void>) {
const [refreshing, setRefreshing] = useState(false);
const handleRefresh = useCallback(async () => {
setRefreshing(true);
try {
await onRefresh();
} finally {
setRefreshing(false);
}
}, [onRefresh]);
return { refreshing, handleRefresh };
}
```
### 4.3 无限滚动
```tsx
// hooks/useInfiniteScroll.ts
import { useEffect, useRef, useCallback } from 'react';
export function useInfiniteScroll(
onLoadMore: () => void,
hasMore: boolean,
loading: boolean
) {
const observerRef = useRef<IntersectionObserver | null>(null);
const loadMoreRef = useCallback(
(node: HTMLDivElement | null) => {
if (loading) return;
if (observerRef.current) observerRef.current.disconnect();
observerRef.current = new IntersectionObserver((entries) => {
if (entries[0].isIntersecting && hasMore) {
onLoadMore();
}
});
if (node) observerRef.current.observe(node);
},
[loading, hasMore, onLoadMore]
);
return loadMoreRef;
}
```
---
## 🔗 五、API 调用规范
### 5.1 统一请求封装
```typescript
// lib/api.ts
import axios from 'axios';
import { toast } from 'sonner';
const api = axios.create({
baseURL: process.env.NEXT_PUBLIC_API_URL,
timeout: 10000,
});
// 请求拦截
api.interceptors.request.use((config) => {
const token = localStorage.getItem('token');
if (token) {
config.headers.Authorization = `Bearer ${token}`;
}
return config;
});
// 响应拦截
api.interceptors.response.use(
(response) => {
const { code, message, data } = response.data;
if (code !== 200) {
toast.error(message || '请求失败');
return Promise.reject(new Error(message));
}
return data;
},
(error) => {
if (error.response?.status === 401) {
// Token 过期，跳转登录
window.location.href = '/login';
}
toast.error('网络错误，请稍后重试');
return Promise.reject(error);
}
);
export { api };
```
### 5.2 React Query 封装
```typescript
// hooks/useTrafficPool.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { api } from '@/lib/api';
// 获取流量池列表
export function useTrafficPools(page = 1, pageSize = 20) {
return useQuery({
queryKey: ['trafficPools', page, pageSize],
queryFn: () => api.get('/api/v1/traffic-pools', {
params: { page, pageSize }
}),
});
}
// 创建流量池
export function useCreateTrafficPool() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: (data: CreateTrafficPoolDTO) =>
api.post('/api/v1/traffic-pools', data),
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['trafficPools'] });
toast.success('创建成功');
},
});
}
```
---
## 📱 六、页面模板
### 6.1 列表页模板
```tsx
// app/(main)/traffic/page.tsx
'use client';
import { useState } from 'react';
import { PageContainer } from '@/components/layout/PageContainer';
import { ListItem } from '@/components/ui/ListItem';
import { ListItemSkeleton } from '@/components/ui/skeleton';
import { useTrafficPools } from '@/hooks/useTrafficPool';
import { useInfiniteScroll } from '@/hooks/useInfiniteScroll';
export default function TrafficPoolPage() {
const [page, setPage] = useState(1);
const { data, isLoading, hasMore } = useTrafficPools(page);
const loadMoreRef = useInfiniteScroll(
() => setPage((p) => p + 1),
hasMore,
isLoading
);
return (
<PageContainer title="流量池" showBack={false}>
{/* 搜索栏 */}
<div className="sticky top-11 z-40 bg-ios-bg px-4 py-2">
<input
type="search"
placeholder="搜索流量池..."
className="w-full h-9 px-4 bg-gray-200 rounded-lg
text-[15px] placeholder:text-gray-400"
/>
</div>
{/* 列表区域 */}
<div className="mt-2">
{isLoading && !data ? (
// 首次加载：显示骨架屏
[...Array(10)].map((_, i) => <ListItemSkeleton key={i} />)
) : (
// 数据列表
<>
{data?.list.map((item) => (
<ListItem
key={item.id}
icon={<Pool className="w-4 h-4" />}
title={item.name}
subtitle={`${item.count} 条流量`}
value={`¥${item.revenue}`}
onClick={() => router.push(`/traffic/${item.id}`)}
/>
))}
{/* 加载更多触发器 */}
<div ref={loadMoreRef} className="h-10 flex items-center justify-center">
{isLoading && <span className="text-gray-400">加载中...</span>}
{!hasMore && <span className="text-gray-400">没有更多了</span>}
</div>
</>
)}
</div>
</PageContainer>
);
}
```
### 6.2 表单页模板
```tsx
// app/(main)/scenarios/new/page.tsx
'use client';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { PageContainer } from '@/components/layout/PageContainer';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { useCreateScenario } from '@/hooks/useScenario';
const schema = z.object({
name: z.string().min(2, '名称至少2个字符'),
description: z.string().optional(),
});
type FormData = z.infer<typeof schema>;
export default function NewScenarioPage() {
const { mutate, isPending } = useCreateScenario();
const {
register,
handleSubmit,
formState: { errors },
} = useForm<FormData>({
resolver: zodResolver(schema),
});
const onSubmit = (data: FormData) => {
mutate(data);
};
return (
<PageContainer
title="新建场景"
rightAction={
<button
onClick={handleSubmit(onSubmit)}
disabled={isPending}
className="text-ios-blue font-medium disabled:opacity-50"
>
{isPending ? '保存中...' : '保存'}
</button>
}
>
<form className="p-4 space-y-6">
{/* 场景名称 */}
<div>
<label className="text-[13px] text-gray-500 mb-2 block">
场景名称
</label>
<Input
{...register('name')}
placeholder="请输入场景名称"
className="h-11"
/>
{errors.name && (
<p className="text-ios-red text-[13px] mt-1">
{errors.name.message}
</p>
)}
</div>
{/* 场景描述 */}
<div>
<label className="text-[13px] text-gray-500 mb-2 block">
场景描述
</label>
<textarea
{...register('description')}
placeholder="请输入场景描述（可选）"
className="w-full h-24 px-3 py-2 bg-white border border-gray-200
rounded-lg text-[15px] resize-none"
/>
</div>
</form>
</PageContainer>
);
}
```
---
## 🔗 七、跨目录联动
### 7.1 上下游关系
```mermaid
graph LR
A[3、原型] -->|页面结构| B[4、前端]
C[5、接口] -->|API定义| B
B -->|联调需求| C
B -->|部署资源| D[8、部署]
```
### 7.2 联动指令
```
# 基于原型生成组件
@联动 原型→前端：基于 [页面结构] 生成 React 组件代码
# 基于接口生成 Hook
@联动 接口→前端：基于 [API文档] 生成 React Query Hook
# 生成完整页面
@联动 全量：基于 [需求+原型+接口] 生成完整页面代码
```
---
## 🤖 八、AI 协作指令
### 8.1 角色设定
```yaml
角色: 前端技术专家
风格:
- iOS 原生风格，像素级还原
- TypeScript 强类型
- 组件化、Hook 化
输出: 必须包含完整可运行代码
检查: 必须包含骨架屏、类型定义、错误处理
```
### 8.2 指令集
| 指令 | 功能 | 示例 |
|:---|:---|:---|
| `@生成页面` | 生成完整页面代码 | `@生成页面 流量池列表` |
| `@生成组件` | 生成单个组件 | `@生成组件 用户信息卡片` |
| `@生成Hook` | 生成自定义 Hook | `@生成Hook 分页加载` |
| `@生成类型` | 生成 TypeScript 类型 | `@生成类型 用户信息` |
| `@样式优化` | 优化 Tailwind 类名 | `@样式优化 [代码片段]` |
| `@性能优化` | 分析性能问题 | `@性能优化 列表渲染` |
---
## ⚠️ 九、注意事项
### 9.1 强制规则
```yaml
必须做:
- [ ] 所有数据加载使用 Skeleton 骨架屏
- [ ] 所有路由切换有转场动画
- [ ] 所有组件使用 TypeScript
- [ ] 所有 API 调用封装在 Hook 中
- [ ] 所有表单使用 react-hook-form + zod
禁止做:
- [ ] 使用 Spinner/Loading 代替骨架屏
- [ ] 硬编码 API 地址
- [ ] 使用 any 类型
- [ ] 在组件中直接调用 fetch
```
### 9.2 常见问题
| 问题 | 解决方案 |
|:---|:---|
| 首屏白屏 | 添加 Skeleton 骨架屏 |
| 页面闪烁 | 添加路由转场动画 |
| 类型报错 | 完善 TypeScript 类型定义 |
| 性能问题 | 使用 React.memo / useMemo |
---
> **下一步**: 前端开发完成后，拖入 `5、接口/_智能展开.md` 进行 API 联调

63
开发文档/4、前端/前端开发规范.md Normal file
View File

@@ -0,0 +1,63 @@
# 神射手数据中台 - 前端开发规范
> 📅 更新: 2026-01-31
---
## 一、技术栈
| 项目 | 选型 |
|:---|:---|
| 框架 | Next.js 14 + React 18 |
| UI | Radix UI |
| 样式 | TailwindCSS |
| 图表 | Recharts |
| 状态 | React Hooks |
---
## 二、视觉规范（苹果毛玻璃）
| 元素 | 类名 |
|:---|:---|
| 页面背景 | `from-slate-50 via-blue-50/30 to-purple-50/20` |
| 卡片 | `bg-white/80 backdrop-blur rounded-xl shadow-lg` |
| 按钮 | `from-blue-500 to-purple-500` |
| 分割线 | `border-slate-200/60` |
---
## 三、交互规范
| 要求 | 实现 |
|:---|:---|
| 骨架屏 | Skeleton 组件，严禁 Spinner |
| 转场 | 路由切换动画 |
| 数据加载 | useEffect + fetch |
---
## 四、目录结构
```
app/
├── page.tsx # 首页
├── data-ingestion/ # 数据接入
├── tag-portrait/ # 标签画像
├── ai-agent/ # AI Agent
├── data-market/ # 数据市场
├── monitoring/ # 系统监控
└── api/ # API 路由
components/
└── ui/ # Radix 组件
lib/
└── mongodb.ts # MongoDB 连接
```
---
## 五、关联文档
- [核心组件代码.md](./核心组件代码.md)
- [../3、原型/原型设计规范.md](../3、原型/原型设计规范.md)

119
开发文档/4、前端/核心组件代码.md Normal file
View File

@@ -0,0 +1,119 @@
# 神射手 - 核心组件代码
> 📅 从 app/ 与 components/ 提取 | 2026-01-31
---
## 一、首页AI对话核心逻辑
### 1.1 状态与API调用 (app/page.tsx)
```tsx
// 核心状态
const [query, setQuery] = useState("")
const [loading, setLoading] = useState(false)
const [messages, setMessages] = useState<ChatMessage[]>([])
const [aiStatus, setAiStatus] = useState<AIStatus | null>(null)
// 获取AI状态
useEffect(() => {
fetch("/api/ai-chat")
.then(res => res.json())
.then(data => {
setAiStatus(data)
setStats({ totalUsers: data.database?.totalUsers, ... })
})
}, [])
// 发送查询
const handleSend = async () => {
setLoading(true)
const res = await fetch("/api/ai-chat", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ message: query })
})
const data = await res.json()
// 添加 thinking 消息
setMessages(prev => [...prev, { role: "thinking", content: data.thinking }])
// 添加回复 + portrait
setMessages(prev => [...prev, { role: "assistant", content: data.response, portrait: data.portrait }])
setLoading(false)
}
```
### 1.2 用户画像卡片渲染
```tsx
// UserPortrait 卡片结构
{msg.portrait && (
<Card className="bg-white/80 backdrop-blur">
<CardHeader>
<CardTitle>👤 用户画像</CardTitle>
</CardHeader>
<CardContent>
<div className="grid grid-cols-2 gap-2 text-sm">
{msg.portrait.name && <span>姓名: {msg.portrait.name}</span>}
{msg.portrait.phone && <span>手机: {msg.portrait.phone}</span>}
{msg.portrait.qq && <span>QQ: {msg.portrait.qq}</span>}
{msg.portrait.level && <span>等级: {msg.portrait.level}</span>}
{msg.portrait.province && <span>地区: {msg.portrait.province}</span>}
</div>
</CardContent>
</Card>
)}
```
---
## 二、通用模式
### 2.1 动态数据加载
```tsx
// 各页面通用模式
const [data, setData] = useState([])
const [loading, setLoading] = useState(true)
useEffect(() => {
fetch('/api/xxx')
.then(res => res.json())
.then(data => {
if (data.success) setData(data.xxx)
})
.finally(() => setLoading(false))
}, [])
```
### 2.2 苹果毛玻璃样式
```tsx
// 页面容器
className="min-h-screen bg-gradient-to-br from-slate-50 via-blue-50/30 to-purple-50/20"
// 卡片
className="bg-white/80 backdrop-blur border-slate-200/60 rounded-xl shadow-lg"
// 按钮
className="bg-gradient-to-r from-blue-500 to-purple-500 hover:from-blue-600 hover:to-purple-600"
```
---
## 三、关键组件路径
| 组件 | 路径 | 用途 |
|:---|:---|:---|
| Card | @/components/ui/card | 卡片容器 |
| Button | @/components/ui/button | 按钮 |
| Badge | @/components/ui/badge | 标签 |
| Input | @/components/ui/input | 输入框 |
| Dialog | @/components/ui/dialog | 弹窗 |
| Select | @/components/ui/select | 下拉选择 |
---
## 四、关联文档
- [前端开发规范.md](./前端开发规范.md)
- [../3、原型/页面结构.md](../3、原型/页面结构.md)

102
开发文档/5、接口/API清单与核心逻辑.md Normal file
View File

@@ -0,0 +1,102 @@
# 神射手 - API清单与核心逻辑
> 📅 从 app/api/ 提取 | 2026-01-31
---
## 一、API清单 (25个)
| 路由 | 方法 | 功能 | 核心逻辑 |
|:-----|:-----|:-----|:---------|
| /api/ai-chat | GET/POST | AI对话 | parseIntent → queryFullProfile |
| /api/data-sources | GET | 数据源列表 | listDatabases + 统计 |
| /api/tags | GET | 标签统计 | $sample 采样 |
| /api/portrait | GET | 用户画像 | queryFullProfile |
| /api/traffic-packages | GET/POST | 流量池/导出 | user_evaluation_score 分桶 |
| /api/crowd-pools | GET | 人群圈选 | 按项目 getProjectPools |
| /api/database-structure | GET | 血缘节点 | listDatabases + 生成节点 |
| /api/channels | GET/POST | 渠道对接 | 转发到 Gateway |
| /api/monitoring | GET | 系统监控 | serverStatus + 健康检查 |
| /api/ai-tagging | GET/POST | AI打标 | - |
| /api/cleaning-rules | GET/POST | 清洗规则 | - |
| /api/users | GET | 用户列表 | - |
| /api/search | POST | 智能搜索 | intelligentSearch |
---
## 二、AI对话意图解析 (核心逻辑)
```typescript
// app/api/ai-chat/route.ts
function parseIntent(message: string): { type: string; query?: string } {
// 手机号: 1[3-9]\d{9}
const phoneMatch = message.match(/(\+?86)?1[3-9]\d{9}/g)
if (phoneMatch) return { type: "query_phone", query: phoneMatch[0] }
// QQ号
const qqMatch = message.match(/(?:qq)?[：:\s]*(\d{5,11})/i)
if (qqMatch) return { type: "query_qq", query: qqMatch[1] }
// 系统状态
if (msg.includes("状态") || msg.includes("统计")) return { type: "system_status" }
// RFM分析
if (msg.includes("rfm") || msg.includes("估值")) return { type: "rfm_analysis" }
// 高价值用户
if (msg.includes("高价值") || msg.includes("top")) return { type: "high_value_users" }
return { type: "search", query: message }
}
```
---
## 三、流量池分桶逻辑
```typescript
// app/api/traffic-packages/route.ts
const scoreRange = {
diamond: { $gte: 3000 },
gold: { $gte: 2000, $lt: 3000 },
silver: { $gte: 1000, $lt: 2000 },
bronze: { $gte: 500, $lt: 1000 },
potential: { $lt: 500 }
}
// 使用 $sample 采样
const stats = await collection.aggregate([
{ $sample: { size: 100000 } },
{ $match: { user_evaluation_score: { $exists: true, $gt: 0 } } },
{ $bucket: { groupBy: '$user_evaluation_score', boundaries: [0, 500, 1000, 2000, 3000, 10000] } }
], { maxTimeMS: 15000 })
```
---
## 四、人群圈选逻辑
```typescript
// app/api/crowd-pools/route.ts
// 项目定义
const PROJECTS = {
ckb: { db: 'KR_存客宝', coll: '用户资产统一视图', by: 'traffic_pool.pool_name' },
dlm: { db: 'KR_点了码', coll: '用户资产统一视图', by: '角色标签' },
weibo: { db: 'KR_微博', coll: '微博uid+手机' },
qq: { db: 'KR_腾讯', coll: 'QQ+手机', by: '省份' }
}
// 获取池内用户
const users = await collection.find({ [field]: poolId })
.skip((page - 1) * limit)
.limit(limit)
.project({ phone: 1, name: 1, ... })
.toArray()
```
---
## 五、关联文档
- [接口定义规范.md](./接口定义规范.md)
- [../6、后端/MongoDB连接器核心.md](../6、后端/MongoDB连接器核心.md)

17
开发文档/5、接口/README.md Normal file
View File

@@ -0,0 +1,17 @@
# 5、接口
> API 架构师 | API 文档
## 本目录文档
| 文档 | 说明 |
|:---|:---|
| [_智能展开.md](./_智能展开.md) | 接口引擎激活、RESTful |
| [API清单与核心逻辑.md](./API清单与核心逻辑.md) | **从项目提取**：25API、意图解析 |
| [接口定义规范.md](./接口定义规范.md) | 接口规范 |
| [存客宝对接规范.md](./存客宝对接规范.md) | 存客宝API |
## 联动
- 上游: 1-需求、2-架构 | 下游: 4-前端、6-后端、7-数据库
- 指令: `@接口引擎 展开 [API名]`

587
开发文档/5、接口/_智能展开.md Normal file
View File

@@ -0,0 +1,587 @@
# 🔌 接口智能展开引擎 (API Auto-Expand)
> **角色激活**: 将此文件拖入 AI，即刻激活 **API 架构师** 角色
> **核心能力**: RESTful 设计、接口文档、错误码、认证鉴权
---
## 📋 一、快速启动指令
### 1.1 功能转接口
```
@接口引擎 请根据以下功能需求，生成完整的 API 接口文档：
【模块名称】：[模块名]
【核心功能】：[功能描述]
【用户角色】：[谁会调用这些接口]
【特殊需求】：[可选：分页/鉴权/文件上传等]
```
### 1.2 展开输出清单
| 输出项 | 说明 | 格式 |
|:---|:---|:---|
| 接口清单 | 所有 API 列表 | 表格 |
| 详细文档 | 每个接口的详细定义 | Markdown |
| 请求示例 | cURL / JSON 示例 | 代码块 |
| 响应示例 | 成功/失败响应 | JSON |
| 时序图 | 接口调用流程 | Mermaid |
---
## 📐 二、接口设计规范
### 2.1 URL 命名规范
```yaml
# 基础规则
前缀: /api/v1
资源名: 复数名词，小写，中划线分隔
嵌套: 最多两层
# 示例
✅ 正确:
- GET /api/v1/users # 用户列表
- GET /api/v1/users/:id # 用户详情
- POST /api/v1/users # 创建用户
- PUT /api/v1/users/:id # 更新用户
- DELETE /api/v1/users/:id # 删除用户
- GET /api/v1/users/:id/orders # 用户的订单列表
❌ 错误:
- GET /api/v1/getUser # 动词命名
- GET /api/v1/User # 大写
- GET /api/v1/user_list # 下划线
```
### 2.2 HTTP 方法规范
| 方法 | 用途 | 幂等 | 示例 |
|:---:|:---|:---:|:---|
| GET | 查询资源 | ✅ | 获取用户信息 |
| POST | 创建资源 | ❌ | 创建订单 |
| PUT | 全量更新 | ✅ | 更新用户资料 |
| PATCH | 部分更新 | ✅ | 修改密码 |
| DELETE | 删除资源 | ✅ | 删除文章 |
### 2.3 统一响应格式
```typescript
// 成功响应
interface SuccessResponse<T> {
code: 200;
message: "success";
data: T;
timestamp: number;
}
// 分页响应
interface PaginatedResponse<T> {
code: 200;
message: "success";
data: {
list: T[];
total: number;
page: number;
pageSize: number;
totalPages: number;
};
timestamp: number;
}
// 错误响应
interface ErrorResponse {
code: number; // 非 200
message: string; // 错误描述
data: null;
timestamp: number;
traceId?: string; // 可选：追踪 ID
}
```
### 2.4 状态码规范
```yaml
# HTTP 状态码
200: 成功
201: 创建成功
204: 删除成功（无返回体）
400: 请求参数错误
401: 未认证（Token 无效/过期）
403: 无权限
404: 资源不存在
429: 请求过于频繁
500: 服务器内部错误
# 业务状态码（在 response.code 中）
200: 成功
1001: 参数校验失败
1002: 业务逻辑错误
2001: 用户不存在
2002: 密码错误
2003: 验证码错误
3001: 余额不足
3002: 提现失败
```
---
## 🔐 三、认证鉴权规范
### 3.1 JWT Token 方案
```yaml
# Token 结构
Header:
alg: HS256
typ: JWT
Payload:
sub: user_id # 用户 ID
exp: timestamp # 过期时间
iat: timestamp # 签发时间
role: "user" # 用户角色
# 传递方式
Header: Authorization: Bearer <token>
# Token 刷新
Access Token: 2小时
Refresh Token: 7天
```
### 3.2 认证流程
```mermaid
sequenceDiagram
participant Client
participant API
participant Auth
participant DB
Client->>API: POST /api/v1/auth/login
API->>DB: 验证用户名密码
DB-->>API: 用户信息
API->>Auth: 生成 Token
Auth-->>API: Access + Refresh Token
API-->>Client: {accessToken, refreshToken, expiresIn}
Note over Client,API: 后续请求
Client->>API: GET /api/v1/users/me<br/>Authorization: Bearer <token>
API->>Auth: 验证 Token
Auth-->>API: 用户信息
API-->>Client: 用户数据
Note over Client,API: Token 过期
Client->>API: POST /api/v1/auth/refresh<br/>{refreshToken}
API->>Auth: 验证 Refresh Token
Auth-->>API: 新 Access Token
API-->>Client: {accessToken, expiresIn}
```
---
## 📄 四、接口文档模板
### 4.1 单接口模板
```markdown
## 接口：[接口名称]
### 基本信息
| 项目 | 说明 |
|:---|:---|
| URL | `/api/v1/xxx` |
| Method | `POST` |
| 认证 | 需要 Bearer Token |
| 权限 | user / admin |
### 请求参数
#### Headers
| 参数 | 类型 | 必填 | 说明 |
|:---|:---|:---:|:---|
| Authorization | string | ✅ | Bearer Token |
| Content-Type | string | ✅ | application/json |
#### Body
| 参数 | 类型 | 必填 | 说明 | 示例 |
|:---|:---|:---:|:---|:---|
| name | string | ✅ | 名称 | "流量池A" |
| count | number | ❌ | 数量 | 100 |
### 响应
#### 成功响应 (200)
```json
{
"code": 200,
"message": "success",
"data": {
"id": "xxx",
"name": "流量池A"
},
"timestamp": 1678888888
}
```
#### 错误响应
| code | message | 说明 |
|:---:|:---|:---|
| 1001 | 参数校验失败 | 检查必填字段 |
| 2001 | 流量池已存在 | 名称重复 |
### 请求示例
```bash
curl -X POST 'https://api.example.com/api/v1/traffic-pools' \
-H 'Authorization: Bearer xxx' \
-H 'Content-Type: application/json' \
-d '{"name": "流量池A"}'
```
```
### 4.2 模块接口清单模板
```markdown
# [模块名称] 接口文档
## 接口清单
| 序号 | 接口名称 | Method | URL | 认证 | 说明 |
|:---:|:---|:---:|:---|:---:|:---|
| 1 | 获取列表 | GET | /api/v1/xxx | ✅ | 分页查询 |
| 2 | 获取详情 | GET | /api/v1/xxx/:id | ✅ | 单条查询 |
| 3 | 创建 | POST | /api/v1/xxx | ✅ | 新增 |
| 4 | 更新 | PUT | /api/v1/xxx/:id | ✅ | 全量更新 |
| 5 | 删除 | DELETE | /api/v1/xxx/:id | ✅ | 软删除 |
## 详细接口
### 1. 获取列表
[详细文档...]
### 2. 获取详情
[详细文档...]
```
---
## 📊 五、常用接口模板
### 5.1 用户认证模块
```yaml
# 登录
POST /api/v1/auth/login
Body: { mobile, code }
Response: { accessToken, refreshToken, expiresIn, user }
# 刷新 Token
POST /api/v1/auth/refresh
Body: { refreshToken }
Response: { accessToken, expiresIn }
# 获取当前用户
GET /api/v1/auth/me
Response: { id, mobile, nickname, avatar, ... }
# 登出
POST /api/v1/auth/logout
Response: { }
```
### 5.2 CRUD 模块
```yaml
# 列表查询（分页）
GET /api/v1/resources?page=1&pageSize=20&keyword=xxx
Response: { list, total, page, pageSize, totalPages }
# 详情查询
GET /api/v1/resources/:id
Response: { id, ... }
# 创建
POST /api/v1/resources
Body: { ... }
Response: { id, ... }
# 更新
PUT /api/v1/resources/:id
Body: { ... }
Response: { id, ... }
# 删除
DELETE /api/v1/resources/:id
Response: { }
```
### 5.3 文件上传
```yaml
# 上传单个文件
POST /api/v1/upload
Content-Type: multipart/form-data
Body: { file }
Response: { url, filename, size, mimeType }
# 上传多个文件
POST /api/v1/upload/batch
Content-Type: multipart/form-data
Body: { files[] }
Response: { files: [{ url, filename, size }] }
```
### 5.4 分润相关（云阿米巴核心）
```yaml
# 获取收益概览
GET /api/v1/earnings/overview
Response: {
today: 123.45,
thisMonth: 1234.56,
total: 12345.67,
withdrawable: 1000.00
}
# 获取收益明细
GET /api/v1/earnings/records?page=1&startDate=xxx&endDate=xxx
Response: { list: [{ id, amount, type, description, createdAt }], ... }
# 申请提现
POST /api/v1/withdrawals
Body: { amount, accountType, accountNo }
Response: { id, amount, status, estimatedTime }
# 获取提现记录
GET /api/v1/withdrawals?page=1
Response: { list: [{ id, amount, status, createdAt }], ... }
```
---
## 🔗 六、跨目录联动
### 6.1 上下游关系
```mermaid
graph LR
A[1、需求] -->|功能清单| B[5、接口]
C[2、架构] -->|模块设计| B
B -->|API定义| D[4、前端]
B -->|API实现| E[6、后端]
B -->|数据结构| F[7、数据库]
```
### 6.2 联动指令
```
# 基于需求生成接口
@联动 需求→接口：基于 [功能清单] 生成 API 接口文档
# 接口文档转前端 Hook
@联动 接口→前端：基于 [API文档] 生成 React Query Hook
# 接口文档转后端路由
@联动 接口→后端：基于 [API文档] 生成 FastAPI 路由代码
# 接口文档转数据库
@联动 接口→数据库：基于 [请求响应] 生成 MongoDB Schema
```
---
## 🔌 七、存客宝接口对接
### 7.1 快速对接
本目录包含 `存客宝对接规范.md`，用于对接存客宝系统。
**核心功能**：
- 线索上报（手机号/微信号）
- 用户画像追踪
- 标签管理
### 7.2 对接指令
```
# 生成存客宝对接代码
@存客宝对接 生成 [TypeScript/Python] 客户端
# 生成线索上报服务
@存客宝对接 生成线索上报 Service
# 生成留资表单
@存客宝对接 生成留资表单组件
```
### 7.3 配置要求
```yaml
必须配置:
- apiKey: 存客宝分配的接口密钥（联系卡若获取）
环境变量:
- CKB_API_KEY=your_api_key
- CKB_BASE_URL=https://ckbapi.quwanzhi.com
```
### 7.4 签名算法要点
```
1. 移除字段：sign、apiKey、portrait
2. 移除空值：null、''
3. 按键名排序：ASCII 升序
4. 拼接值：只取值，无分隔符
5. 两次MD5：先对拼接串，再对结果+apiKey
```
详细规范见：`存客宝对接规范.md`
---
## 🤖 八、AI 协作指令
### 8.1 角色设定
```yaml
角色: API 架构师
风格:
- RESTful 规范
- 简洁、统一、容错
- 安全优先
输出: 必须包含完整接口文档 + 示例
检查: 必须包含错误码、认证说明
```
### 8.2 指令集
| 指令 | 功能 | 示例 |
|:---|:---|:---|
| `@生成接口` | 生成模块接口文档 | `@生成接口 用户模块` |
| `@接口详情` | 生成单个接口详细文档 | `@接口详情 用户登录` |
| `@时序图` | 生成接口调用时序图 | `@时序图 下单流程` |
| `@错误码` | 生成错误码清单 | `@错误码 订单模块` |
| `@Mock数据` | 生成 Mock 响应数据 | `@Mock数据 用户列表` |
| `@Postman` | 生成 Postman Collection | `@Postman 全部接口` |
| `@存客宝对接` | 生成存客宝对接代码 | `@存客宝对接 TypeScript客户端` |
---
## 📝 八、示例输出
### 8.1 流量池模块接口文档
```markdown
# 流量池模块 API 文档
## 接口清单
| # | 接口 | Method | URL | 认证 |
|:---:|:---|:---:|:---|:---:|
| 1 | 获取流量池列表 | GET | /api/v1/traffic-pools | ✅ |
| 2 | 获取流量池详情 | GET | /api/v1/traffic-pools/:id | ✅ |
| 3 | 创建流量池 | POST | /api/v1/traffic-pools | ✅ |
| 4 | 更新流量池 | PUT | /api/v1/traffic-pools/:id | ✅ |
| 5 | 删除流量池 | DELETE | /api/v1/traffic-pools/:id | ✅ |
| 6 | 开启/关闭流量池 | PATCH | /api/v1/traffic-pools/:id/status | ✅ |
---
## 1. 获取流量池列表
### 基本信息
- **URL**: `/api/v1/traffic-pools`
- **Method**: `GET`
- **认证**: 需要
### 请求参数 (Query)
| 参数 | 类型 | 必填 | 说明 | 默认值 |
|:---|:---|:---:|:---|:---|
| page | number | ❌ | 页码 | 1 |
| pageSize | number | ❌ | 每页数量 | 20 |
| keyword | string | ❌ | 搜索关键词 | - |
| status | string | ❌ | 状态筛选 | - |
### 成功响应
```json
{
"code": 200,
"message": "success",
"data": {
"list": [
{
"id": "tp_001",
"name": "抖音本地生活",
"description": "厦门本地餐饮流量",
"count": 1234,
"revenue": 5678.90,
"status": "active",
"createdAt": "2024-01-01T00:00:00Z"
}
],
"total": 100,
"page": 1,
"pageSize": 20,
"totalPages": 5
},
"timestamp": 1678888888
}
```
```
### 8.2 接口调用时序图
```mermaid
sequenceDiagram
participant App as 小程序
participant API as 后端API
participant DB as MongoDB
participant AI as AI服务
App->>API: GET /api/v1/traffic-pools
API->>API: 验证 Token
API->>DB: 查询流量池列表
DB-->>API: 流量池数据
API-->>App: {code: 200, data: {list: [...]}}
App->>API: POST /api/v1/traffic-pools/:id/analyze
API->>AI: 调用 AI 分析
AI-->>API: 分析结果
API->>DB: 保存分析结果
DB-->>API: 保存成功
API-->>App: {code: 200, data: {analysis: ...}}
```
---
## ⚠️ 九、注意事项
### 9.1 安全规范
```yaml
必须做:
- [ ] 所有接口走 HTTPS
- [ ] 敏感接口限流 (Rate Limit)
- [ ] 参数必须校验
- [ ] 响应脱敏（手机号、身份证等）
禁止做:
- [ ] GET 请求传递敏感信息
- [ ] 在 URL 中暴露内部 ID
- [ ] 返回过多不必要字段
```
### 9.2 版本管理
```yaml
# 版本号在 URL 中
/api/v1/xxx # 当前版本
/api/v2/xxx # 新版本（重大变更）
# 兼容性原则
- 新增字段：向后兼容，可直接发布
- 删除字段：先标记废弃，下个大版本删除
- 修改字段：新建接口，保留旧接口
```
---
> **下一步**: 接口定义完成后，拖入 `6、后端/_智能展开.md` 进行后端开发

803
开发文档/5、接口/存客宝对接规范.md Normal file
View File

@@ -0,0 +1,803 @@
# 🔗 存客宝接口对接规范 (CunKeBao API Standard)
> **用途**: 所有项目对接存客宝系统的统一规范
> **版本**: v1.0
> **适用场景**: 线索上报、用户画像、流量池管理
---
## 📋 一、快速对接指南
### 1.1 对接前准备
```yaml
必须获取:
- apiKey: 存客宝分配的接口密钥（每个任务/场景唯一）
接口地址:
- 生产环境: https://ckbapi.quwanzhi.com/v1/api/scenarios
- 测试环境: [按需配置]
请求格式:
- Content-Type: application/json (推荐)
- 备选: application/x-www-form-urlencoded
- 编码: UTF-8
```
### 1.2 一分钟接入
```javascript
// 最简调用示例
const response = await fetch('https://ckbapi.quwanzhi.com/v1/api/scenarios', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
apiKey: 'YOUR_API_KEY',
timestamp: Math.floor(Date.now() / 1000),
phone: '13800000000',
sign: generateSign(params) // 见签名算法
})
});
```
---
## 🔐 二、签名算法（核心）
### 2.1 签名生成流程图
```
┌─────────────────────────────────────────────────────────────────────┐
│ 签名生成流程 │
├─────────────────────────────────────────────────────────────────────┤
│ Step 1: 准备参数 │
│ └── 收集所有请求参数（含 apiKey, timestamp, 业务参数） │
│ │
│ Step 2: 移除特殊字段 │
│ └── 移除: sign, apiKey, portrait │
│ │
│ Step 3: 移除空值 │
│ └── 移除: null, ''（空字符串） │
│ │
│ Step 4: 按键名排序 │
│ └── ASCII 升序排序（a→z） │
│ │
│ Step 5: 拼接参数值 │
│ └── 只取值，顺序拼接，无分隔符 │
│ │
│ Step 6: 第一次 MD5 │
│ └── firstMd5 = MD5(拼接字符串) │
│ │
│ Step 7: 第二次 MD5 │
│ └── sign = MD5(firstMd5 + apiKey) │
└─────────────────────────────────────────────────────────────────────┘
```
### 2.2 签名规则详解
```yaml
# 签名规则
不参与签名的字段:
- sign: 签名本身不参与
- apiKey: 不参与拼接，只在最后一步参与二次MD5
- portrait: 整个画像对象不参与（避免复杂度）
空值处理:
- null 值字段: 不参与签名
- 空字符串 '': 不参与签名
排序规则:
- 按参数名（键名）ASCII 升序
- 例如: name, phone, source, timestamp
拼接规则:
- 只取值，不取键
- 顺序直接拼接，无分隔符
- 例如: "张三13800000000微信广告1710000000"
MD5 规则:
- 使用小写 MD5
- 两次 MD5: 先对拼接字符串，再对结果+apiKey
```
### 2.3 签名代码实现
#### TypeScript/JavaScript 实现
```typescript
/**
* 存客宝签名生成器
* @description 生成符合存客宝接口规范的签名
* @param params 请求参数（不含sign）
* @param apiKey 接口密钥
* @returns 签名字符串（小写MD5）
*/
function generateCKBSign(params: Record<string, any>, apiKey: string): string {
// Step 1: 复制参数，移除特殊字段
const signParams = { ...params };
delete signParams.sign;
delete signParams.apiKey;
delete signParams.portrait;
// Step 2: 移除空值
Object.keys(signParams).forEach(key => {
if (signParams[key] === null || signParams[key] === '') {
delete signParams[key];
}
});
// Step 3: 按键名排序
const sortedKeys = Object.keys(signParams).sort();
// Step 4: 拼接参数值
const stringToSign = sortedKeys.map(key => signParams[key]).join('');
// Step 5: 第一次 MD5
const firstMd5 = md5(stringToSign);
// Step 6: 第二次 MD5（拼接 apiKey）
const sign = md5(firstMd5 + apiKey);
return sign;
}
// 使用示例
const params = {
apiKey: 'YOUR_API_KEY',
timestamp: Math.floor(Date.now() / 1000),
phone: '13800000000',
name: '张三',
source: '微信广告'
};
const sign = generateCKBSign(params, params.apiKey);
params.sign = sign;
```
#### Python 实现
```python
"""
存客宝签名生成器
"""
import hashlib
from typing import Dict, Any
def generate_ckb_sign(params: Dict[str, Any], api_key: str) -> str:
"""
生成存客宝接口签名
Args:
params: 请求参数（不含sign）
api_key: 接口密钥
Returns:
签名字符串（小写MD5）
"""
# Step 1: 复制参数，移除特殊字段
sign_params = {k: v for k, v in params.items()
if k not in ['sign', 'apiKey', 'portrait']}
# Step 2: 移除空值
sign_params = {k: v for k, v in sign_params.items()
if v is not None and v != ''}
# Step 3: 按键名排序
sorted_keys = sorted(sign_params.keys())
# Step 4: 拼接参数值
string_to_sign = ''.join(str(sign_params[k]) for k in sorted_keys)
# Step 5: 第一次 MD5
first_md5 = hashlib.md5(string_to_sign.encode('utf-8')).hexdigest()
# Step 6: 第二次 MD5
sign = hashlib.md5((first_md5 + api_key).encode('utf-8')).hexdigest()
return sign
# 使用示例
import time
params = {
'apiKey': 'YOUR_API_KEY',
'timestamp': int(time.time()),
'phone': '13800000000',
'name': '张三',
'source': '微信广告'
}
sign = generate_ckb_sign(params, params['apiKey'])
params['sign'] = sign
```
#### PHP 实现
```php
<?php
/**
* 存客宝签名生成器
*
* @param array $params 请求参数（不含sign）
* @param string $apiKey 接口密钥
* @return string 签名字符串（小写MD5）
*/
function generateCKBSign(array $params, string $apiKey): string {
// Step 1: 移除特殊字段
unset($params['sign'], $params['apiKey'], $params['portrait']);
// Step 2: 移除空值
$params = array_filter($params, function($value) {
return !is_null($value) && $value !== '';
});
// Step 3: 按键名排序
ksort($params);
// Step 4: 拼接参数值
$stringToSign = implode('', array_values($params));
// Step 5: 第一次 MD5
$firstMd5 = md5($stringToSign);
// Step 6: 第二次 MD5
$sign = md5($firstMd5 . $apiKey);
return $sign;
}
// 使用示例
$params = [
'apiKey' => 'YOUR_API_KEY',
'timestamp' => time(),
'phone' => '13800000000',
'name' => '张三',
'source' => '微信广告'
];
$sign = generateCKBSign($params, $params['apiKey']);
$params['sign'] = $sign;
```
---
## 📤 三、请求参数规范
### 3.1 鉴权字段（必填）
| 字段名 | 类型 | 必填 | 说明 |
|:---|:---|:---:|:---|
| `apiKey` | string | ✅ | 存客宝分配的接口密钥 |
| `sign` | string | ✅ | 签名值（见签名算法） |
| `timestamp` | int | ✅ | 秒级时间戳，与服务器时间差 ≤ 5分钟 |
### 3.2 主标识字段（至少传一个）
| 字段名 | 类型 | 必填 | 说明 |
|:---|:---|:---:|:---|
| `wechatId` | string | 二选一 | 微信号，优先作为主标识 |
| `phone` | string | 二选一 | 手机号，wechatId 为空时用作主标识 |
### 3.3 基础信息字段（可选）
| 字段名 | 类型 | 必填 | 说明 | 示例 |
|:---|:---|:---:|:---|:---|
| `name` | string | ❌ | 客户姓名 | "张三" |
| `source` | string | ❌ | 线索来源 | "抖音直播间" |
| `remark` | string | ❌ | 备注信息 | "通过H5落地页留资" |
| `tags` | string | ❌ | 微信标签（逗号分隔） | "高意向,电商,女装" |
| `siteTags` | string | ❌ | 站内标签（逗号分隔） | "新客,VIP" |
### 3.4 用户画像字段（可选）
```typescript
interface Portrait {
/**
* 画像类型
* 0-浏览 1-点击 2-下单/购买 3-注册 4-互动
*/
type?: 0 | 1 | 2 | 3 | 4;
/**
* 画像来源
* 0-本站 1-老油条 2-老坑爹
*/
source?: 0 | 1 | 2;
/**
* 画像明细数据（任意键值对）
*/
sourceData?: {
age?: number;
gender?: string;
city?: string;
productId?: string;
pageUrl?: string;
[key: string]: any;
};
/**
* 画像备注，最大100字符
*/
remark?: string;
/**
* 去重唯一ID
* 相同 uniqueId 在半小时内会合并统计
* 建议格式: {来源}_{用户标识}_{时间戳}_{序号}
*/
uniqueId?: string;
}
```
#### 画像类型说明
| 值 | 类型 | 说明 | 适用场景 |
|:---:|:---|:---|:---|
| 0 | 浏览 | 用户浏览了页面或内容 | 页面访问、商品浏览 |
| 1 | 点击 | 用户点击了某个元素 | 按钮点击、广告点击 |
| 2 | 下单/购买 | 用户完成了购买行为 | 订单提交、支付完成 |
| 3 | 注册 | 用户完成了注册 | 账号注册、会员注册 |
| 4 | 互动 | 用户进行了互动行为 | 点赞、评论、分享 |
---
## 📥 四、响应格式规范
### 4.1 统一响应结构
```typescript
interface CKBResponse<T = any> {
code: number; // 200=成功，其他=失败
message: string; // 提示信息
data: T | null; // 业务数据
}
```
### 4.2 成功响应
```json
// 新增成功
{ "code": 200, "message": "新增成功", "data": "13800000000" }
// 已存在
{ "code": 200, "message": "已存在", "data": "13800000000" }
```
### 4.3 错误响应
| code | message | 说明 | 处理建议 |
|:---:|:---|:---|:---|
| 400 | apiKey不能为空 | 缺少 apiKey | 检查参数 |
| 400 | sign不能为空 | 缺少签名 | 检查签名生成 |
| 400 | timestamp不能为空 | 缺少时间戳 | 添加时间戳 |
| 400 | 请求已过期 | 时间戳超过5分钟 | 同步服务器时间 |
| 401 | 无效的apiKey | apiKey 错误 | 检查 apiKey |
| 401 | 签名验证失败 | 签名错误 | 检查签名算法 |
| 500 | 系统错误 | 服务端异常 | 联系技术支持 |
---
## 📝 五、完整请求示例
### 5.1 基础线索上报
```json
{
"apiKey": "YOUR_API_KEY",
"timestamp": 1710000000,
"phone": "13800000000",
"name": "张三",
"source": "微信广告",
"remark": "通过H5落地页留资",
"tags": "高意向,电商",
"sign": "a1b2c3d4e5f6..."
}
```
### 5.2 带微信号的线索上报
```json
{
"apiKey": "YOUR_API_KEY",
"timestamp": 1710000000,
"wechatId": "wxid_abcdefg123",
"phone": "13800000001",
"name": "李四",
"source": "小程序落地页",
"tags": "中意向,直播",
"sign": "a1b2c3d4e5f6..."
}
```
### 5.3 带用户画像的线索上报
```json
{
"apiKey": "YOUR_API_KEY",
"timestamp": 1710000000,
"phone": "13800000002",
"name": "王五",
"source": "百度推广",
"portrait": {
"type": 1,
"source": 0,
"sourceData": {
"age": 28,
"gender": "female",
"city": "上海",
"productId": "P12345",
"pageUrl": "https://example.com/product/123"
},
"remark": "点击了立即咨询按钮",
"uniqueId": "site_13800000002_1710000000_001"
},
"sign": "a1b2c3d4e5f6..."
}
```
---
## 🛠️ 六、封装工具类
### 6.1 TypeScript 完整封装
```typescript
/**
* 存客宝 API 客户端
* @description 封装存客宝接口调用，自动处理签名
*/
import crypto from 'crypto';
interface CKBConfig {
apiKey: string;
baseUrl?: string;
}
interface LeadData {
phone?: string;
wechatId?: string;
name?: string;
source?: string;
remark?: string;
tags?: string;
siteTags?: string;
portrait?: {
type?: 0 | 1 | 2 | 3 | 4;
source?: 0 | 1 | 2;
sourceData?: Record<string, any>;
remark?: string;
uniqueId?: string;
};
}
interface CKBResponse<T = any> {
code: number;
message: string;
data: T;
}
export class CunKeBaoClient {
private apiKey: string;
private baseUrl: string;
constructor(config: CKBConfig) {
this.apiKey = config.apiKey;
this.baseUrl = config.baseUrl || 'https://ckbapi.quwanzhi.com';
}
/**
* 生成 MD5
*/
private md5(str: string): string {
return crypto.createHash('md5').update(str, 'utf8').digest('hex');
}
/**
* 生成签名
*/
private generateSign(params: Record<string, any>): string {
// 复制参数，移除特殊字段
const signParams = { ...params };
delete signParams.sign;
delete signParams.apiKey;
delete signParams.portrait;
// 移除空值
Object.keys(signParams).forEach(key => {
if (signParams[key] === null || signParams[key] === '') {
delete signParams[key];
}
});
// 按键名排序
const sortedKeys = Object.keys(signParams).sort();
// 拼接参数值
const stringToSign = sortedKeys.map(key => signParams[key]).join('');
// 两次 MD5
const firstMd5 = this.md5(stringToSign);
return this.md5(firstMd5 + this.apiKey);
}
/**
* 上报线索
* @param data 线索数据
*/
async reportLead(data: LeadData): Promise<CKBResponse<string>> {
const timestamp = Math.floor(Date.now() / 1000);
const params: Record<string, any> = {
apiKey: this.apiKey,
timestamp,
...data,
};
// 生成签名
params.sign = this.generateSign(params);
// 发送请求
const response = await fetch(`${this.baseUrl}/v1/api/scenarios`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(params),
});
return response.json();
}
/**
* 上报用户画像
* @param identifier 用户标识（phone 或 wechatId）
* @param portrait 画像数据
*/
async reportPortrait(
identifier: { phone?: string; wechatId?: string },
portrait: LeadData['portrait']
): Promise<CKBResponse<string>> {
return this.reportLead({
...identifier,
portrait,
});
}
}
// ============ 使用示例 ============
// 初始化客户端
const ckb = new CunKeBaoClient({
apiKey: 'YOUR_API_KEY',
});
// 上报线索
await ckb.reportLead({
phone: '13800000000',
name: '张三',
source: '微信广告',
tags: '高意向,电商',
});
// 上报带画像的线索
await ckb.reportLead({
phone: '13800000001',
name: '李四',
source: '抖音直播',
portrait: {
type: 1, // 点击
sourceData: {
productId: 'P12345',
pageUrl: 'https://example.com/product',
},
uniqueId: 'site_13800000001_' + Date.now(),
},
});
```
### 6.2 Python 完整封装
```python
"""
存客宝 API 客户端
封装存客宝接口调用，自动处理签名
"""
import hashlib
import time
import requests
from typing import Optional, Dict, Any
from dataclasses import dataclass, asdict
@dataclass
class Portrait:
"""用户画像"""
type: int = 0 # 0-浏览 1-点击 2-下单 3-注册 4-互动
source: int = 0 # 0-本站 1-老油条 2-老坑爹
sourceData: Optional[Dict[str, Any]] = None
remark: Optional[str] = None
uniqueId: Optional[str] = None
class CunKeBaoClient:
"""存客宝 API 客户端"""
def __init__(self, api_key: str, base_url: str = "https://ckbapi.quwanzhi.com"):
self.api_key = api_key
self.base_url = base_url
def _md5(self, s: str) -> str:
"""生成 MD5"""
return hashlib.md5(s.encode('utf-8')).hexdigest()
def _generate_sign(self, params: Dict[str, Any]) -> str:
"""生成签名"""
# 复制参数，移除特殊字段
sign_params = {k: v for k, v in params.items()
if k not in ['sign', 'apiKey', 'portrait']}
# 移除空值
sign_params = {k: v for k, v in sign_params.items()
if v is not None and v != ''}
# 按键名排序
sorted_keys = sorted(sign_params.keys())
# 拼接参数值
string_to_sign = ''.join(str(sign_params[k]) for k in sorted_keys)
# 两次 MD5
first_md5 = self._md5(string_to_sign)
return self._md5(first_md5 + self.api_key)
def report_lead(
self,
phone: Optional[str] = None,
wechat_id: Optional[str] = None,
name: Optional[str] = None,
source: Optional[str] = None,
remark: Optional[str] = None,
tags: Optional[str] = None,
site_tags: Optional[str] = None,
portrait: Optional[Portrait] = None
) -> Dict[str, Any]:
"""
上报线索
Args:
phone: 手机号
wechat_id: 微信号
name: 客户姓名
source: 线索来源
remark: 备注
tags: 微信标签（逗号分隔）
site_tags: 站内标签（逗号分隔）
portrait: 用户画像
Returns:
API 响应
"""
params = {
'apiKey': self.api_key,
'timestamp': int(time.time()),
}
# 添加可选参数
if phone:
params['phone'] = phone
if wechat_id:
params['wechatId'] = wechat_id
if name:
params['name'] = name
if source:
params['source'] = source
if remark:
params['remark'] = remark
if tags:
params['tags'] = tags
if site_tags:
params['siteTags'] = site_tags
if portrait:
params['portrait'] = asdict(portrait)
# 生成签名
params['sign'] = self._generate_sign(params)
# 发送请求
response = requests.post(
f"{self.base_url}/v1/api/scenarios",
json=params,
headers={'Content-Type': 'application/json'}
)
return response.json()
# ============ 使用示例 ============
# 初始化客户端
ckb = CunKeBaoClient(api_key='YOUR_API_KEY')
# 上报线索
result = ckb.report_lead(
phone='13800000000',
name='张三',
source='微信广告',
tags='高意向,电商'
)
# 上报带画像的线索
result = ckb.report_lead(
phone='13800000001',
name='李四',
source='抖音直播',
portrait=Portrait(
type=1, # 点击
sourceData={
'productId': 'P12345',
'pageUrl': 'https://example.com/product'
},
uniqueId=f'site_13800000001_{int(time.time())}'
)
)
```
---
## ❓ 七、常见问题 (FAQ)
### Q1: 签名验证失败怎么排查？
**A**: 按以下步骤排查：
1. 确认 apiKey 正确
2. 确认 timestamp 在 5 分钟内
3. 确认移除了 sign、apiKey、portrait 字段
4. 确认移除了空值字段
5. 确认按键名排序
6. 确认 MD5 是小写
### Q2: portrait 字段是否必传？
**A**: 不是必传。只有需要记录用户画像时才传递。
### Q3: uniqueId 的作用是什么？
**A**: 防止重复记录。相同 uniqueId 的画像数据在半小时内会合并统计。
### Q4: phone 和 wechatId 必须传哪个？
**A**: 至少传一个。wechatId 优先作为主标识。
### Q5: 时间戳超时怎么处理？
**A**: 确保服务器时间准确，或使用 NTP 同步时间。
---
## 🔗 八、与开发模板联动
### 8.1 在项目中使用
```
1. 复制本文件中的工具类到项目 lib/ckb.ts
2. 配置 apiKey 到环境变量
3. 在需要的地方调用 ckb.reportLead()
```
### 8.2 联动指令
```
# 生成存客宝对接代码
@联动 存客宝→后端：生成线索上报 Service
# 生成前端表单
@联动 存客宝→前端：生成留资表单组件
```
---
## 📞 九、技术支持
- **接口问题**: 联系存客宝技术支持
- **apiKey 申请**: 联系卡若（微信 28533368）
---
> **更新日志**:
> - v1.0 (2026-01-18): 初始版本，支持线索上报和用户画像

44
开发文档/5、接口/接口定义规范.md Normal file
View File

@@ -0,0 +1,44 @@
# 神射手数据中台 - 接口定义规范
> 📅 更新: 2026-01-31
---
## 一、统一响应
```typescript
// 成功
{ success: true, data: {...} }
// 失败
{ success: false, error: "错误信息" }
```
---
## 二、核心API
| 路由 | 方法 | 说明 |
|:---|:---|:---|
| /api/ai-chat | GET/POST | AI对话 |
| /api/data-sources | GET | 数据源 |
| /api/tags | GET | 标签 |
| /api/traffic-packages | GET/POST | 流量池 |
| /api/crowd-pools | GET | 人群圈选 |
| /api/monitoring | GET | 系统监控 |
---
## 三、请求规范
| 项目 | 要求 |
|:---|:---|
| Content-Type | application/json |
| 分页 | page=1, limit=20 |
| 动作 | action=xxx (如 pools, export) |
---
## 四、关联文档
- [API清单与核心逻辑.md](./API清单与核心逻辑.md)
- [存客宝对接规范.md](./存客宝对接规范.md)

131
开发文档/6、后端/MongoDB连接器核心.md Normal file
View File

@@ -0,0 +1,131 @@
# 神射手 - MongoDB连接器核心
> 📅 从 lib/mongodb.ts 提取 | 2026-01-31
---
## 一、连接配置
```typescript
// lib/mongodb.ts
const MONGODB_URI = process.env.MONGODB_URI ||
'mongodb://admin:admin123@localhost:27017/?authSource=admin'
const DB_NAMES = {
KR: 'KR',
KR_腾讯: 'KR_腾讯',
KR_微博: 'KR_微博',
KR_京东: 'KR_京东',
KR_存客宝: 'KR_存客宝',
KR_点了码: 'KR_点了码'
}
```
---
## 二、核心函数
### 2.1 连接池
```typescript
let cachedClient: MongoClient | null = null
export async function getMongoClient(): Promise<MongoClient> {
if (cachedClient) return cachedClient
const client = new MongoClient(MONGODB_URI, {
maxPoolSize: 10,
minPoolSize: 2,
maxIdleTimeMS: 60000,
serverSelectionTimeoutMS: 5000,
})
await client.connect()
cachedClient = client
return client
}
```
### 2.2 手机号归一化
```typescript
function normalizePhone(phone: string): string[] {
const cleaned = phone.replace(/\D/g, '')
const variants: string[] = []
if (cleaned.startsWith('86') && cleaned.length === 13) {
const base = cleaned.slice(2)
variants.push(base, `+86${base}`, `86${base}`, cleaned)
} else if (cleaned.length === 11 && cleaned.startsWith('1')) {
variants.push(cleaned, `+86${cleaned}`, `86${cleaned}`)
} else {
variants.push(phone, cleaned)
}
return [...new Set(variants)]
}
```
### 2.3 跨库查询用户画像
```typescript
export async function queryFullProfile(phone: string) {
const client = await getMongoClient()
const phoneVariants = normalizePhone(phone)
const query = { $or: phoneVariants.map(p => ({ phone: p })) }
const [valuation, qqPhone, ckbAsset] = await Promise.all([
client.db('KR').collection('用户估值').findOne(query),
client.db('KR_腾讯').collection('QQ+手机').findOne(query),
client.db('KR_存客宝').collection('用户资产统一视图').findOne(query).catch(() => null)
])
return { valuation, qqPhone, ckbAsset }
}
```
### 2.4 智能搜索（QQ→手机→画像）
```typescript
export async function intelligentSearch(query: string) {
// QQ号: 先查 KR_腾讯 获取手机号，再查 KR.用户估值
if (/^\d{5,11}$/.test(query)) {
const qqDoc = await client.db('KR_腾讯').collection('QQ+手机').findOne({
$or: [{ qq: query }, { qq: parseInt(query) }]
})
if (qqDoc?.phone) {
return queryFullProfile(qqDoc.phone)
}
}
// 手机号: 直接 queryFullProfile
// 关键词: name/city/province 模糊搜索
}
```
---
## 三、接口定义
```typescript
interface UserValuationDoc {
phone?: string
phone_masked?: string
name?: string
user_level?: string
user_evaluation_score?: number
province?: string
city?: string
tags?: string[]
}
interface QQPhoneDoc {
qq: string
phone?: string
手机号?: string
省份?: string
运营商?: string
}
```
---
## 四、关联文档
- [后端开发规范.md](./后端开发规范.md)
- [../7、数据库/ER与查询逻辑.md](../7、数据库/ER与查询逻辑.md)

16
开发文档/6、后端/README.md Normal file
View File

@@ -0,0 +1,16 @@
# 6、后端
> Python 架构师 | 后端代码
## 本目录文档
| 文档 | 说明 |
|:---|:---|
| [_智能展开.md](./_智能展开.md) | 后端引擎激活 |
| [MongoDB连接器核心.md](./MongoDB连接器核心.md) | **从项目提取**：连接池、跨库查询 |
| [后端开发规范.md](./后端开发规范.md) | 开发规范 |
## 联动
- 上游: 5-接口、7-数据库 | 下游: 8-部署
- 指令: `@后端引擎 展开 [服务名]`

484
开发文档/6、后端/_智能展开.md Normal file
View File

@@ -0,0 +1,484 @@
# 🐍 后端智能展开引擎 (Backend Auto-Expand)
> **角色激活**: 将此文件拖入 AI，即刻激活 **Python 架构师** 角色
> **核心能力**: FastAPI 开发、AI 集成、异步编程、安全规范
---
## 📋 一、快速启动指令
### 1.1 接口转代码
```
@后端引擎 请根据以下接口定义，生成完整的后端代码：
【模块名称】：[模块名]
【接口清单】：[接口列表或文档链接]
【AI需求】：[是否需要 AI 能力]
【特殊需求】：[可选：缓存/消息队列/定时任务等]
```
### 1.2 展开输出清单
| 输出项 | 说明 | 文件 |
|:---|:---|:---|
| Router | 路由定义 | `routers/xxx.py` |
| Schema | 请求/响应模型 | `schemas/xxx.py` |
| Service | 业务逻辑 | `services/xxx.py` |
| Model | 数据模型 | `models/xxx.py` |
| 测试用例 | 单元测试 | `tests/test_xxx.py` |
---
## 🛠️ 二、技术栈规范
### 2.1 卡若标准后端栈
```
┌─────────────────────────────────────────────────────────────────────┐
│ 卡若后端技术栈 │
├─────────────────────────────────────────────────────────────────────┤
│ 🐍 语言与框架 │
│ ├── Python 3.10+ (强制) │
│ ├── FastAPI 0.100+ (异步 Web 框架) │
│ ├── Pydantic v2 (数据校验) │
│ └── Uvicorn/Gunicorn (ASGI 服务器) │
├─────────────────────────────────────────────────────────────────────┤
│ 🤖 AI 能力 │
│ ├── LangChain 0.1+ (Agent/Chain) │
│ ├── OpenAI / Gemini API (LLM) │
│ └── ChromaDB / MongoDB Vector (向量检索) │
├─────────────────────────────────────────────────────────────────────┤
│ 💾 数据层 │
│ ├── Motor (异步 MongoDB) │
│ ├── Redis (缓存/Session) │
│ └── SQLAlchemy (可选，强事务场景) │
├─────────────────────────────────────────────────────────────────────┤
│ 🔧 工具链 │
│ ├── Poetry / pip (依赖管理) │
│ ├── Black + Ruff (代码格式化) │
│ ├── pytest (测试) │
│ └── loguru (日志) │
└─────────────────────────────────────────────────────────────────────┘
```
### 2.2 目录结构规范
```
/app
├── /routers # 路由层 (Controller)
│ ├── __init__.py
│ ├── auth.py # 认证路由
│ ├── user.py # 用户路由
│ └── traffic_pool.py # 流量池路由
│
├── /schemas # Pydantic 模型 (DTO)
│ ├── __init__.py
│ ├── base.py # 基础响应模型
│ ├── user.py
│ └── traffic_pool.py
│
├── /services # 业务逻辑层
│ ├── __init__.py
│ ├── user_service.py
│ ├── traffic_service.py
│ └── ai_service.py # AI 相关服务
│
├── /models # 数据库模型
│ ├── __init__.py
│ └── user.py
│
├── /core # 核心配置
│ ├── __init__.py
│ ├── config.py # 环境变量配置
│ ├── security.py # JWT/认证
│ ├── database.py # 数据库连接
│ └── deps.py # 依赖注入
│
├── /utils # 工具函数
│ ├── __init__.py
│ └── helpers.py
│
├── /tests # 测试
│ └── test_user.py
│
├── main.py # 入口文件
└── requirements.txt # 依赖清单
```
---
## 📝 三、代码模板
### 3.1 配置文件 (config.py)
```python
# app/core/config.py
from pydantic_settings import BaseSettings
from functools import lru_cache
class Settings(BaseSettings):
"""应用配置 - 从环境变量读取"""
# 应用配置
APP_NAME: str = "私域银行"
DEBUG: bool = False
# 数据库配置
MONGODB_URL: str
REDIS_URL: str
# JWT 配置
JWT_SECRET: str
JWT_ALGORITHM: str = "HS256"
JWT_EXPIRE_HOURS: int = 2
# AI 配置
OPENAI_API_KEY: str = ""
GEMINI_API_KEY: str = ""
class Config:
env_file = ".env"
@lru_cache()
def get_settings() -> Settings:
return Settings()
settings = get_settings()
```
### 3.2 统一响应模型 (schemas/base.py)
```python
# app/schemas/base.py
from typing import TypeVar, Generic, Optional
from pydantic import BaseModel
from datetime import datetime
T = TypeVar("T")
class Response(BaseModel, Generic[T]):
"""统一响应格式"""
code: int = 200
message: str = "success"
data: Optional[T] = None
timestamp: int = int(datetime.now().timestamp())
class PaginatedData(BaseModel, Generic[T]):
"""分页数据"""
list: list[T]
total: int
page: int
page_size: int
total_pages: int
class PaginatedResponse(Response[PaginatedData[T]], Generic[T]):
"""分页响应"""
pass
```
### 3.3 路由模板 (routers/xxx.py)
```python
# app/routers/traffic_pool.py
from fastapi import APIRouter, Depends, HTTPException
from typing import Optional
from app.schemas.base import Response, PaginatedResponse
from app.schemas.traffic_pool import (
TrafficPoolCreate,
TrafficPoolUpdate,
TrafficPoolResponse
)
from app.services.traffic_service import TrafficPoolService
from app.core.deps import get_current_user
router = APIRouter(prefix="/traffic-pools", tags=["流量池"])
@router.get("", response_model=PaginatedResponse[TrafficPoolResponse])
async def get_traffic_pools(
page: int = 1,
page_size: int = 20,
keyword: Optional[str] = None,
current_user = Depends(get_current_user),
service: TrafficPoolService = Depends()
):
"""获取流量池列表"""
return await service.get_list(
user_id=current_user.id,
page=page,
page_size=page_size,
keyword=keyword
)
@router.post("", response_model=Response[TrafficPoolResponse])
async def create_traffic_pool(
data: TrafficPoolCreate,
current_user = Depends(get_current_user),
service: TrafficPoolService = Depends()
):
"""创建流量池"""
result = await service.create(user_id=current_user.id, data=data)
return Response(data=result)
```
### 3.4 服务层模板 (services/xxx.py)
```python
# app/services/traffic_service.py
from typing import Optional
from motor.motor_asyncio import AsyncIOMotorDatabase
from bson import ObjectId
from app.schemas.traffic_pool import TrafficPoolCreate, TrafficPoolUpdate
from app.core.database import get_database
class TrafficPoolService:
"""流量池服务 - 业务逻辑层"""
def __init__(self):
self.db: AsyncIOMotorDatabase = get_database()
self.collection = self.db.traffic_pools
async def get_list(
self,
user_id: str,
page: int = 1,
page_size: int = 20,
keyword: Optional[str] = None
):
"""获取流量池列表（分页）"""
# 构建查询条件
query = {"user_id": user_id, "is_deleted": False}
if keyword:
query["name"] = {"$regex": keyword, "$options": "i"}
# 查询总数
total = await self.collection.count_documents(query)
# 分页查询
cursor = self.collection.find(query) \
.sort("created_at", -1) \
.skip((page - 1) * page_size) \
.limit(page_size)
items = await cursor.to_list(length=page_size)
return {
"list": items,
"total": total,
"page": page,
"page_size": page_size,
"total_pages": (total + page_size - 1) // page_size
}
async def create(self, user_id: str, data: TrafficPoolCreate):
"""创建流量池"""
doc = {
**data.model_dump(),
"user_id": user_id,
"is_deleted": False,
"created_at": datetime.utcnow(),
"updated_at": datetime.utcnow(),
}
result = await self.collection.insert_one(doc)
doc["_id"] = result.inserted_id
return doc
```
---
## 🤖 四、AI 集成模板
### 4.1 AI 服务封装
```python
# app/services/ai_service.py
from langchain_openai import ChatOpenAI
from langchain_google_genai import ChatGoogleGenerativeAI
from langchain.prompts import ChatPromptTemplate
from langchain.schema import HumanMessage
import asyncio
from app.core.config import settings
class AIService:
"""AI 服务 - 封装 LLM 调用"""
def __init__(self):
# 初始化 LLM（根据配置选择）
if settings.GEMINI_API_KEY:
self.llm = ChatGoogleGenerativeAI(
model="gemini-pro",
google_api_key=settings.GEMINI_API_KEY,
temperature=0.7
)
else:
self.llm = ChatOpenAI(
model="gpt-3.5-turbo",
api_key=settings.OPENAI_API_KEY,
temperature=0.7
)
async def chat(self, message: str, system_prompt: str = None) -> str:
"""简单对话"""
messages = []
if system_prompt:
messages.append(("system", system_prompt))
messages.append(("human", message))
prompt = ChatPromptTemplate.from_messages(messages)
chain = prompt | self.llm
# 异步调用
response = await chain.ainvoke({})
return response.content
async def analyze_traffic_pool(self, pool_data: dict) -> dict:
"""分析流量池数据（AI 增强）"""
system_prompt = """你是一个私域运营专家，请分析以下流量池数据：
- 给出流量质量评分（1-100）
- 给出优化建议（3条）
- 预测下周转化率
请用 JSON 格式返回。"""
result = await self.chat(
message=f"流量池数据：{pool_data}",
system_prompt=system_prompt
)
return result
```
### 4.2 向量检索服务
```python
# app/services/vector_service.py
from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import MongoDBAtlasVectorSearch
from pymongo import MongoClient
from app.core.config import settings
class VectorService:
"""向量检索服务"""
def __init__(self):
self.embeddings = OpenAIEmbeddings(
api_key=settings.OPENAI_API_KEY
)
self.client = MongoClient(settings.MONGODB_URL)
self.collection = self.client.knowledge_base.documents
self.vector_store = MongoDBAtlasVectorSearch(
collection=self.collection,
embedding=self.embeddings,
index_name="vector_index",
text_key="content",
embedding_key="embedding"
)
async def search(self, query: str, k: int = 5) -> list:
"""语义搜索"""
results = self.vector_store.similarity_search(query, k=k)
return [{"content": doc.page_content, "metadata": doc.metadata}
for doc in results]
async def add_documents(self, documents: list[dict]):
"""添加文档到向量库"""
texts = [doc["content"] for doc in documents]
metadatas = [doc.get("metadata", {}) for doc in documents]
self.vector_store.add_texts(texts=texts, metadatas=metadatas)
```
---
## 🔐 五、安全规范
### 5.1 安全检查清单
```yaml
强制规则:
- [ ] 所有密钥走环境变量 (.env)
- [ ] 禁止 os.system()，使用 subprocess
- [ ] 所有数据库操作参数化
- [ ] 所有函数必须 Type Hints
- [ ] 所有业务逻辑必须中文注释
禁止清单:
- os.system("any command")
- f"SELECT * FROM {table}"
- password = "hardcoded"
- api_key = "sk-xxx"
- eval() / exec()
```
### 5.2 JWT 认证
```python
# app/core/security.py
from datetime import datetime, timedelta
from jose import jwt, JWTError
from passlib.context import CryptContext
from app.core.config import settings
pwd_context = CryptContext(schemes=["argon2"], deprecated="auto")
def create_access_token(user_id: str) -> str:
"""创建 JWT Token"""
expire = datetime.utcnow() + timedelta(hours=settings.JWT_EXPIRE_HOURS)
payload = {
"sub": user_id,
"exp": expire,
"iat": datetime.utcnow()
}
return jwt.encode(payload, settings.JWT_SECRET, algorithm=settings.JWT_ALGORITHM)
def verify_token(token: str) -> str:
"""验证 Token，返回 user_id"""
try:
payload = jwt.decode(token, settings.JWT_SECRET, algorithms=[settings.JWT_ALGORITHM])
return payload.get("sub")
except JWTError:
return None
def hash_password(password: str) -> str:
"""密码哈希"""
return pwd_context.hash(password)
def verify_password(plain: str, hashed: str) -> bool:
"""验证密码"""
return pwd_context.verify(plain, hashed)
```
---
## 🔗 六、跨目录联动
```mermaid
graph LR
A[5、接口] -->|API定义| B[6、后端]
C[7、数据库] -->|Schema| B
B -->|部署需求| D[8、部署]
B -->|测试用例| E[10、项目管理]
```
### 联动指令
```
@联动 接口→后端：基于 [API文档] 生成 FastAPI 代码
@联动 数据库→后端：基于 [ER图] 生成 Pydantic 模型
@联动 后端→部署：生成 requirements.txt 和启动脚本
```
---
## 🤖 七、AI 协作指令
| 指令 | 功能 | 示例 |
|:---|:---|:---|
| `@生成路由` | 生成 Router 代码 | `@生成路由 用户模块` |
| `@生成服务` | 生成 Service 代码 | `@生成服务 流量池CRUD` |
| `@生成AI服务` | 生成 AI 集成代码 | `@生成AI服务 智能客服` |
| `@安全检查` | 检查代码安全问题 | `@安全检查 [代码片段]` |
---
> **下一步**: 后端开发完成后，拖入 `7、数据库/_智能展开.md` 进行数据库设计

48
开发文档/6、后端/后端开发规范.md Normal file
View File

@@ -0,0 +1,48 @@
# 神射手数据中台 - 后端开发规范
> 📅 更新: 2026-01-31
---
## 一、技术栈
| 项目 | 选型 |
|:---|:---|
| 运行时 | Node.js (Next.js API Routes) |
| 数据库 | MongoDB |
| 连接 | lib/mongodb.ts |
---
## 二、代码规范
| 要求 | 说明 |
|:---|:---|
| 连接池 | getMongoClient 全局缓存 |
| 查询 | 参数化，无硬编码 |
| 大表 | $sample 采样 |
| 超时 | maxTimeMS: 10000 |
---
## 三、目录结构
```
app/api/
├── ai-chat/route.ts # AI对话
├── data-sources/route.ts # 数据源
├── tags/route.ts # 标签
├── traffic-packages/route.ts
├── crowd-pools/route.ts
├── monitoring/route.ts
└── ...
lib/
└── mongodb.ts # 连接器
```
---
## 四、关联文档
- [MongoDB连接器核心.md](./MongoDB连接器核心.md)
- [../7、数据库/ER与查询逻辑.md](../7、数据库/ER与查询逻辑.md)

145
开发文档/7、数据库/ER与查询逻辑.md Normal file
View File

@@ -0,0 +1,145 @@
# 神射手 - ER与查询逻辑
> 📅 从 MongoDB 与代码提取 | 2026-01-31
---
## 一、核心集合ER
### 1.1 KR.用户估值（统一画像）
```yaml
集合: 用户估值
文档数: 1436万
索引: phone, name, email
字段:
phone: string # 手机号（多种格式）
phone_masked: string # 脱敏手机 134****0001
name: string # 姓名
user_level: string # 用户等级 S/A/B/C/D
user_evaluation_score: number # 估值分 0-5000+
province: string # 省份
city: string # 城市
source_channels: array # 数据来源 ['KR_手机']
unified_tags: array # 统一标签
traffic_pool: object # { pool_name: '黄金池' }
rfm_scores: object # { R, F, M }
```
### 1.2 KR_腾讯.QQ+手机
```yaml
集合: QQ+手机
文档数: 7.05亿
索引: phone, qq
字段:
qq: string # QQ号
phone: string # 手机号
手机号: string # 同 phone
QQ号评分: number
手机号评分: number
省份: string
运营商: string
```
### 1.3 KR_存客宝.用户资产统一视图
```yaml
集合: 用户资产统一视图
文档数: 21.6万
字段:
phone_masked: string
unified_tags: array # ['白银级用户', '存客宝用户']
traffic_pool: object # { pool_name: '白银池' }
rfm_scores: object # { user_level: '白银' }
```
### 1.4 KR_点了码.用户资产统一视图
```yaml
集合: 用户资产统一视图
文档数: 1000
字段:
角色标签: string # 商户/用户
用户等级: string
phone: string
name: string
```
---
## 二、关键查询逻辑
### 2.1 手机号查询（多格式匹配）
```javascript
db.用户估值.findOne({
$or: [
{ phone: "13800138000" },
{ phone: "+8613800138000" },
{ phone: "8613800138000" }
]
})
```
### 2.2 QQ→手机→画像
```javascript
// 1. QQ查手机
db.getCollection('QQ+手机').findOne({ qq: "28533368" })
// 2. 手机查画像
db.用户估值.findOne({ phone: "138xxx" })
```
### 2.3 流量池分桶（采样）
```javascript
db.用户估值.aggregate([
{ $sample: { size: 100000 } },
{ $match: { user_evaluation_score: { $exists: true, $gt: 0 } } },
{ $bucket: {
groupBy: '$user_evaluation_score',
boundaries: [0, 500, 1000, 2000, 3000, 10000],
default: 'other',
output: { count: { $sum: 1 } }
}}
], { maxTimeMS: 15000 })
```
### 2.4 人群圈选（按项目）
```javascript
// 存客宝: 按流量池名
db.getCollection('用户资产统一视图').find({ 'traffic_pool.pool_name': '黄金池' })
// 点了码: 按角色标签
db.getCollection('用户资产统一视图').find({ 角色标签: '商户' })
// QQ: 按省份
db.getCollection('QQ+手机').find({ 省份: '福建' })
```
---
## 三、字段映射
| 业务字段 | MongoDB字段 | 多库别名 |
|:---|:---|:---|
| 手机号 | phone, mobile, tel | 手机号 |
| 姓名 | name, cname | 姓名 |
| QQ | qq | - |
| 估值分 | user_evaluation_score | - |
| 等级 | user_level | 用户等级 |
| 省份 | province | 省份 |
---
## 四、关联文档
- [数据库管理规范.md](./数据库管理规范.md)
- [../6、后端/MongoDB连接器核心.md](../6、后端/MongoDB连接器核心.md)

16
开发文档/7、数据库/README.md Normal file
View File

@@ -0,0 +1,16 @@
# 7、数据库
> DBA | ER 图
## 本目录文档
| 文档 | 说明 |
|:---|:---|
| [_智能展开.md](./_智能展开.md) | 数据库引擎激活 |
| [ER与查询逻辑.md](./ER与查询逻辑.md) | **从项目提取**：集合结构、分桶逻辑 |
| [数据库管理规范.md](./数据库管理规范.md) | 管理规范 |
## 联动
- 上游: 2-架构、5-接口 | 下游: 6-后端
- 指令: `@数据库引擎 展开 [集合名]`

364
开发文档/7、数据库/_智能展开.md Normal file
View File

@@ -0,0 +1,364 @@
# 💾 数据库智能展开引擎 (Database Auto-Expand)
> **角色激活**: 将此文件拖入 AI，即刻激活 **DBA** 角色
> **核心能力**: MongoDB 设计、向量索引、ER 图、查询优化
---
## 📋 一、快速启动指令
### 1.1 需求转数据库
```
@数据库引擎 请根据以下需求，生成完整的数据库设计：
【模块名称】：[模块名]
【核心实体】：[主要数据对象]
【AI需求】：[是否需要向量检索]
【数据规模】：[预估数据量]
```
### 1.2 展开输出清单
| 输出项 | 说明 | 格式 |
|:---|:---|:---|
| ER 图 | 实体关系图 | Mermaid erDiagram |
| 集合设计 | MongoDB 集合结构 | JSON Schema |
| 索引策略 | 索引定义 | MongoDB 命令 |
| 向量配置 | 向量索引（如需） | Atlas 配置 |
| 查询示例 | 常用查询 | MongoDB 聚合 |
---
## 🛠️ 二、数据库选型
### 2.1 卡若数据库策略
```
┌─────────────────────────────────────────────────────────────────────┐
│ 数据库选型策略 │
├─────────────────────────────────────────────────────────────────────┤
│ 📦 MongoDB (首选) │
│ ├── 适用：业务数据、用户数据、日志数据 │
│ ├── 优势：灵活 Schema、内置向量索引、JSON 原生 │
│ └── 部署：Atlas 云服务 / 自建副本集 │
├─────────────────────────────────────────────────────────────────────┤
│ 🔍 向量能力 │
│ ├── MongoDB Atlas Vector Search (推荐) │
│ ├── ChromaDB (轻量本地) │
│ └── Pinecone (大规模云端) │
├─────────────────────────────────────────────────────────────────────┤
│ 💰 MySQL (可选) │
│ ├── 适用：强事务场景（资金流水、订单） │
│ └── 部署：腾讯云 CDB │
├─────────────────────────────────────────────────────────────────────┤
│ ⚡ Redis │
│ ├── 适用：缓存、Session、限流计数 │
│ └── 部署：云 Redis / 自建 │
└─────────────────────────────────────────────────────────────────────┘
```
---
## 📊 三、集合设计规范
### 3.1 命名规范
```yaml
集合命名:
格式: 复数、小写、下划线分隔
示例:
✅ users, traffic_pools, order_records
❌ User, trafficPool, OrderRecord
字段命名:
格式: 小写、下划线分隔
示例:
✅ user_id, created_at, is_deleted
❌ userId, createdAt, isDeleted
特殊字段:
_id: 主键（MongoDB 自动生成）
created_at: 创建时间
updated_at: 更新时间
is_deleted: 软删除标记
```
### 3.2 核心集合模板
#### users (用户表)
```javascript
{
_id: ObjectId,
mobile: "15880802661", // 手机号（加密存储）
password_hash: "xxx", // 密码哈希
nickname: "卡若",
avatar: "https://...",
role: "user", // user/admin/partner
status: "active", // active/disabled
// 云阿米巴字段
inviter_id: ObjectId, // 邀请人 ID
team_count: 0, // 团队人数
total_earnings: 0.00, // 累计收益
withdrawable: 0.00, // 可提现金额
// 元数据
created_at: ISODate,
updated_at: ISODate,
last_login_at: ISODate,
is_deleted: false
}
// 索引
db.users.createIndex({ mobile: 1 }, { unique: true })
db.users.createIndex({ inviter_id: 1 })
db.users.createIndex({ created_at: -1 })
```
#### traffic_pools (流量池)
```javascript
{
_id: ObjectId,
user_id: ObjectId, // 所属用户
name: "抖音本地生活",
description: "厦门本地餐饮流量",
// 统计数据
total_count: 1234, // 总流量数
today_count: 56, // 今日新增
conversion_rate: 0.05, // 转化率
// 向量字段（AI 检索）
embedding: [0.1, 0.2, ...], // 1536 维向量
// 状态
status: "active", // active/paused/deleted
// 元数据
created_at: ISODate,
updated_at: ISODate,
is_deleted: false
}
// 索引
db.traffic_pools.createIndex({ user_id: 1 })
db.traffic_pools.createIndex({ status: 1 })
db.traffic_pools.createIndex({ created_at: -1 })
```
#### earnings (收益记录)
```javascript
{
_id: ObjectId,
user_id: ObjectId,
// 收益信息
amount: 12.50, // 金额（精确到分）
type: "order_commission", // 收益类型
source_id: ObjectId, // 来源 ID
source_type: "order", // 来源类型
// 描述
description: "用户 A 下单佣金",
// 元数据
created_at: ISODate
}
// 索引
db.earnings.createIndex({ user_id: 1, created_at: -1 })
db.earnings.createIndex({ type: 1 })
```
---
## 🔍 四、向量索引配置
### 4.1 MongoDB Atlas Vector Search
```javascript
// 创建向量索引（Atlas UI 或 API）
{
"mappings": {
"dynamic": true,
"fields": {
"embedding": {
"type": "knnVector",
"dimensions": 1536,
"similarity": "cosine"
}
}
}
}
```
### 4.2 向量搜索查询
```javascript
// 语义搜索
db.knowledge_base.aggregate([
{
"$vectorSearch": {
"index": "vector_index",
"path": "embedding",
"queryVector": [0.1, 0.2, ...], // 查询向量
"numCandidates": 100,
"limit": 10
}
},
{
"$project": {
"content": 1,
"score": { "$meta": "vectorSearchScore" }
}
}
])
```
---
## 📈 五、常用查询模板
### 5.1 分页查询
```javascript
// 流量池列表（分页 + 搜索）
db.traffic_pools.aggregate([
{ $match: { user_id: ObjectId("xxx"), is_deleted: false } },
{ $match: { name: { $regex: "关键词", $options: "i" } } },
{ $sort: { created_at: -1 } },
{ $facet: {
data: [{ $skip: 0 }, { $limit: 20 }],
total: [{ $count: "count" }]
}}
])
```
### 5.2 统计查询
```javascript
// 用户收益统计
db.earnings.aggregate([
{ $match: { user_id: ObjectId("xxx") } },
{ $group: {
_id: null,
today: { $sum: { $cond: [
{ $gte: ["$created_at", ISODate("今天")] },
"$amount", 0
]}},
this_month: { $sum: { $cond: [
{ $gte: ["$created_at", ISODate("本月1日")] },
"$amount", 0
]}},
total: { $sum: "$amount" }
}}
])
```
---
## 📊 六、ER 图模板
```mermaid
erDiagram
User ||--o{ TrafficPool : owns
User ||--o{ Earning : has
User ||--o{ Withdrawal : requests
User ||--o{ User : invites
TrafficPool ||--o{ TrafficItem : contains
TrafficPool {
ObjectId _id
ObjectId user_id
string name
array embedding "Vector[1536]"
int total_count
string status
}
User {
ObjectId _id
string mobile
string nickname
ObjectId inviter_id
float total_earnings
float withdrawable
}
Earning {
ObjectId _id
ObjectId user_id
float amount
string type
datetime created_at
}
Withdrawal {
ObjectId _id
ObjectId user_id
float amount
string status
datetime created_at
}
```
---
## 🔗 七、跨目录联动
```mermaid
graph LR
A[5、接口] -->|数据结构| B[7、数据库]
C[6、后端] -->|Model| B
B -->|备份策略| D[8、部署]
```
### 联动指令
```
@联动 接口→数据库：基于 [请求响应] 生成集合设计
@联动 数据库→后端：基于 [集合设计] 生成 Pydantic 模型
```
---
## 🤖 八、AI 协作指令
| 指令 | 功能 | 示例 |
|:---|:---|:---|
| `@生成集合` | 生成集合结构 | `@生成集合 订单模块` |
| `@生成ER图` | 生成关系图 | `@生成ER图 用户相关` |
| `@生成索引` | 生成索引策略 | `@生成索引 流量池集合` |
| `@生成查询` | 生成聚合查询 | `@生成查询 用户收益统计` |
| `@向量配置` | 生成向量索引 | `@向量配置 知识库` |
---
## ⚠️ 九、注意事项
### 9.1 安全规范
```yaml
必须做:
- [ ] 敏感字段加密存储（手机号、身份证）
- [ ] 密码必须 Hash（Argon2）
- [ ] 所有查询参数化
- [ ] 定期备份
禁止做:
- [ ] 明文存储密码
- [ ] 在日志中打印敏感数据
- [ ] 直接拼接查询条件
```
### 9.2 性能优化
```yaml
索引原则:
- 查询字段必建索引
- 复合索引注意顺序
- 避免过多索引
查询优化:
- 避免 $where 和 $regex（无索引）
- 大数据量用游标分批处理
- 统计查询加缓存
```
---
> **下一步**: 数据库设计完成后，拖入 `8、部署/_智能展开.md` 进行部署配置

40
开发文档/7、数据库/数据库管理规范.md Normal file
View File

@@ -0,0 +1,40 @@
# 神射手数据中台 - 数据库管理规范
> 📅 更新: 2026-01-31
---
## 一、连接规范
| 项目 | 配置 |
|:---|:---|
| 地址 | localhost:27017 |
| 认证 | admin / admin123 |
| 环境变量 | MONGODB_URI |
---
## 二、查询规范
| 场景 | 方案 |
|:---|:---|
| 大表聚合 | $sample 采样 |
| 超时控制 | maxTimeMS: 10000 |
| 手机号 | normalizePhone 多格式 |
| 跨库 | Promise.all 并行 |
---
## 三、核心集合
| 集合 | 索引 | 用途 |
|:---|:---|:---|
| KR.用户估值 | phone, name | 统一画像 |
| KR_腾讯.QQ+手机 | phone, qq | QQ↔手机 |
| KR_微博.微博uid+手机 | phone, uid | UID↔手机 |
---
## 四、关联文档
- [ER与查询逻辑.md](./ER与查询逻辑.md)
- [../2、架构/数据库.md](../2、架构/数据库.md)

42
开发文档/8、部署/Next.js自动化部署流程.md Normal file
View File

@@ -0,0 +1,42 @@
# 神射手 - Next.js 自动化部署流程
> 📅 更新: 2026-01-31
---
## 一、本地开发
```bash
cd /Users/karuo/Documents/开发/2、私域银行/神射手
pnpm dev # 端口 3117
# 或 ./scripts/start.sh --kill（带端口冲突检查）
# 访问 http://localhost:3117
```
---
## 二、生产构建
```bash
npm run build
npm run start
# 默认端口 3000
```
---
## 三、Webhook 自动化部署（宝塔）
1. GitHub Webhook → 宝塔服务器
2. 触发脚本：git pull → npm install → npm run build → pm2 restart
3. 详见：`基于 GitHub Webhook 与宝塔面板的自动化部署流程文档.md`
---
## 四、端口说明
| 端口 | 服务 | 说明 |
|:---:|:---|:---|
| 3117 | 神射手 | 本地开发（见 端口登记.md）|
| 27017 | MongoDB | Docker |
| 8000 | 卡若AI网关 | Docker |

17
开发文档/8、部署/README.md Normal file
View File

@@ -0,0 +1,17 @@
# 8、部署
> DevOps | 部署脚本
## 本目录文档
| 文档 | 说明 |
|:---|:---|
| [_智能展开.md](./_智能展开.md) | 部署引擎激活 |
| [启动与部署脚本.md](./启动与部署脚本.md) | **从项目提取**：npm脚本、端口 |
| [Next.js自动化部署流程.md](./Next.js自动化部署流程.md) | 部署流程 |
| [基于 GitHub Webhook 与宝塔面板的自动化部署流程文档.md](./基于%20GitHub%20Webhook%20与宝塔面板的自动化部署流程文档.md) | Webhook 部署 |
## 联动
- 上游: 4-前端、6-后端 | 下游: 9-手册
- 指令: `@部署引擎 展开`

41
开发文档/8、部署/WEBHOOK部署的提示词.md Normal file
View File

@@ -0,0 +1,41 @@
# 神射手 - Webhook 部署提示词
> 📅 更新: 2026-01-31
---
## 一、神射手 Webhook 配置
| 项目 | 配置 |
|:---|:---|
| 仓库 | 神射手 Git 仓库 |
| 分支 | main |
| 脚本 | git pull → npm install → npm run build → pm2 reload |
---
## 二、脚本模板
```bash
#!/bin/bash
cd /www/wwwroot/神射手
git pull origin main
npm install
npm run build
pm2 reload shensheshou
echo "神射手部署完成"
```
---
## 三、前提条件
- Node.js 18+
- MongoDB 运行
- PM2 已安装
- 端口 3001 可用
---
## 四、关联文档
- [基于 GitHub Webhook 与宝塔面板的自动化部署流程文档.md](./基于%20GitHub%20Webhook%20与宝塔面板的自动化部署流程文档.md)

390
开发文档/8、部署/_智能展开.md Normal file
View File

@@ -0,0 +1,390 @@
# 🚀 部署智能展开引擎 (Deployment Auto-Expand)
> **角色激活**: 将此文件拖入 AI，即刻激活 **DevOps 运维专家** 角色
> **核心能力**: 自动化部署、CI/CD、Docker、服务器配置
---
## 📋 一、快速启动指令
### 1.1 项目转部署
```
@部署引擎 请根据以下项目信息，生成完整的部署方案：
【项目名称】：[项目名]
【技术栈】：[前端/后端技术]
【服务器】：[宝塔/Docker/云服务]
【域名】：[可选：域名信息]
【特殊需求】：[可选：负载均衡/SSL等]
```
### 1.2 展开输出清单
| 输出项 | 说明 | 格式 |
|:---|:---|:---|
| 部署架构图 | 服务器拓扑 | Mermaid |
| 环境配置 | .env 模板 | 文本 |
| 部署脚本 | Shell 脚本 | Bash |
| Nginx 配置 | 反向代理 | Nginx conf |
| CI/CD 配置 | 自动化流程 | YAML/Shell |
---
## 🛠️ 二、部署方案选型
### 2.1 卡若标准部署栈
```
┌─────────────────────────────────────────────────────────────────────┐
│ 部署技术栈 │
├─────────────────────────────────────────────────────────────────────┤
│ 🖥️ 服务器管理 │
│ ├── 宝塔面板 (首选，可视化) │
│ ├── Docker + Docker Compose (容器化) │
│ └── 云服务器：阿里云 / 腾讯云 / 轻量应用 │
├─────────────────────────────────────────────────────────────────────┤
│ 🌐 Web 服务 │
│ ├── Nginx (反向代理 + SSL) │
│ ├── PM2 (Node.js 进程管理) │
│ └── Gunicorn + Uvicorn (Python ASGI) │
├─────────────────────────────────────────────────────────────────────┤
│ 🔄 CI/CD │
│ ├── GitHub Webhook (自动部署) │
│ ├── GitHub Actions (可选) │
│ └── 宝塔 Webhook 插件 │
├─────────────────────────────────────────────────────────────────────┤
│ 📊 监控 │
│ ├── PM2 日志 / journalctl │
│ ├── 宝塔监控面板 │
│ └── Sentry (错误追踪) │
└─────────────────────────────────────────────────────────────────────┘
```
---
## 📝 三、部署配置模板
### 3.1 环境变量模板 (.env)
```bash
# .env.production
# 应用配置
APP_NAME=私域银行
APP_ENV=production
DEBUG=false
PORT=8000
# 数据库
MONGODB_URL=mongodb://user:pass@host:27017/dbname
REDIS_URL=redis://:password@host:6379/0
# JWT
JWT_SECRET=your-super-secret-key-change-in-production
JWT_ALGORITHM=HS256
JWT_EXPIRE_HOURS=2
# AI 配置
OPENAI_API_KEY=sk-xxx
GEMINI_API_KEY=xxx
# 第三方服务
SMS_ACCESS_KEY=xxx
SMS_SECRET_KEY=xxx
OSS_BUCKET=xxx
```
### 3.2 Nginx 配置
```nginx
# /etc/nginx/sites-available/project.conf
# 前端
server {
listen 80;
server_name example.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name example.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
# 前端静态文件
location / {
root /www/wwwroot/project/frontend/dist;
try_files $uri $uri/ /index.html;
# 缓存静态资源
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
expires 30d;
add_header Cache-Control "public, immutable";
}
}
# 后端 API 代理
location /api {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket 支持
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
```
### 3.3 部署脚本 (deploy.sh)
```bash
#!/bin/bash
# deploy.sh - 自动部署脚本
set -e
PROJECT_DIR="/www/wwwroot/project"
BACKEND_DIR="$PROJECT_DIR/backend"
FRONTEND_DIR="$PROJECT_DIR/frontend"
echo "🚀 开始部署..."
# 1. 拉取最新代码
cd $PROJECT_DIR
git pull origin main
# 2. 后端部署
echo "📦 部署后端..."
cd $BACKEND_DIR
source venv/bin/activate
pip install -r requirements.txt --quiet
sudo systemctl restart project-backend
# 3. 前端部署
echo "🎨 部署前端..."
cd $FRONTEND_DIR
npm install --silent
npm run build
# 4. 重载 Nginx
sudo nginx -t && sudo nginx -s reload
echo "✅ 部署完成！"
```
### 3.4 Systemd 服务配置
```ini
# /etc/systemd/system/project-backend.service
[Unit]
Description=Project Backend Service
After=network.target
[Service]
Type=simple
User=www
Group=www
WorkingDirectory=/www/wwwroot/project/backend
Environment="PATH=/www/wwwroot/project/backend/venv/bin"
EnvironmentFile=/www/wwwroot/project/backend/.env
ExecStart=/www/wwwroot/project/backend/venv/bin/gunicorn \
-w 4 \
-k uvicorn.workers.UvicornWorker \
-b 127.0.0.1:8000 \
main:app
Restart=always
RestartSec=3
[Install]
WantedBy=multi-user.target
```
---
## 🔄 四、CI/CD 配置
### 4.1 GitHub Webhook 自动部署
```bash
# webhook_handler.sh - Webhook 处理脚本
#!/bin/bash
cd /www/wwwroot/project
git pull origin main
bash deploy.sh >> /var/log/deploy.log 2>&1
```
### 4.2 宝塔 Webhook 配置
```
1. 安装宝塔 Webhook 插件
2. 添加 Webhook：
- 名称：project-deploy
- 执行脚本：/www/wwwroot/project/deploy.sh
3. 获取 Webhook URL
4. 在 GitHub 仓库设置中添加 Webhook
```
### 4.3 部署流程图
```mermaid
sequenceDiagram
participant Dev as 开发者
participant GitHub
participant Server as 服务器
participant Nginx
Dev->>GitHub: git push
GitHub->>Server: Webhook 触发
Server->>Server: git pull
Server->>Server: pip install
Server->>Server: npm build
Server->>Server: systemctl restart
Server->>Nginx: nginx reload
Nginx-->>Dev: 部署完成
```
---
## 🐳 五、Docker 部署方案
### 5.1 Dockerfile (后端)
```dockerfile
# backend/Dockerfile
FROM python:3.11-slim
WORKDIR /app
# 安装依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# 复制代码
COPY . .
# 启动命令
CMD ["gunicorn", "-w", "4", "-k", "uvicorn.workers.UvicornWorker", "-b", "0.0.0.0:8000", "main:app"]
```
### 5.2 docker-compose.yml
```yaml
version: '3.8'
services:
backend:
build: ./backend
ports:
- "8000:8000"
env_file:
- ./backend/.env
depends_on:
- mongodb
- redis
restart: always
frontend:
build: ./frontend
ports:
- "3000:3000"
restart: always
mongodb:
image: mongo:7
volumes:
- mongo_data:/data/db
restart: always
redis:
image: redis:7-alpine
restart: always
nginx:
image: nginx:alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf
- ./certs:/etc/nginx/certs
depends_on:
- backend
- frontend
restart: always
volumes:
mongo_data:
```
---
## 🔗 六、跨目录联动
```mermaid
graph LR
A[6、后端] -->|技术栈| B[8、部署]
C[4、前端] -->|构建产物| B
D[7、数据库] -->|备份策略| B
B -->|运维手册| E[9、手册]
```
---
## 🤖 七、AI 协作指令
| 指令 | 功能 | 示例 |
|:---|:---|:---|
| `@生成部署脚本` | 生成 Shell 脚本 | `@生成部署脚本 Python+React` |
| `@生成Nginx` | 生成 Nginx 配置 | `@生成Nginx 反向代理` |
| `@生成Docker` | 生成 Docker 配置 | `@生成Docker 全栈项目` |
| `@生成CI/CD` | 生成自动化流程 | `@生成CI/CD GitHub Webhook` |
| `@环境检查` | 检查服务器环境 | `@环境检查 Python+Node` |
---
## ⚠️ 八、注意事项
### 8.1 安全规范
```yaml
必须做:
- [ ] 密钥走环境变量，不提交代码
- [ ] 开启 HTTPS
- [ ] 配置防火墙
- [ ] 定期备份数据库
禁止做:
- [ ] 在代码中硬编码密钥
- [ ] 开放不必要端口
- [ ] root 用户运行服务
```
### 8.2 常用命令
```bash
# 查看服务状态
systemctl status project-backend
# 查看日志
journalctl -u project-backend -f
# 重启服务
systemctl restart project-backend
# Nginx 测试配置
nginx -t
# Docker 常用
docker-compose up -d
docker-compose logs -f
docker-compose restart
```
---
> **下一步**: 部署完成后，拖入 `9、手册/_智能展开.md` 编写用户手册

88
开发文档/8、部署/启动与部署脚本.md Normal file
View File

@@ -0,0 +1,88 @@
# 神射手 - 启动与部署脚本
> 📅 从 package.json 与项目配置提取 | 2026-01-31
---
## 一、开发环境启动
### 1.1 前置条件
```bash
# 1. MongoDB 运行
docker ps | grep mongo
# datacenter_mongodb Up 0.0.0.0:27017->27017/tcp
# 2. Node.js 环境
node -v # v20+
npm -v # 或 pnpm
```
### 1.2 启动命令
```bash
# 进入项目目录
cd /Users/karuo/Documents/开发/2、私域银行/神射手
# 安装依赖（首次）
npm install
# 或 pnpm install
# 启动开发服务器（默认 3000，指定 3001）
npm run dev -- -p 3001
# 访问
open http://localhost:3001
```
### 1.3 package.json 脚本
```json
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "next lint"
}
}
```
---
## 二、生产构建
```bash
# 构建
npm run build
# 启动生产服务（默认 3000）
npm run start
```
---
## 三、环境变量
```bash
# .env.local（可选）
MONGODB_URI=mongodb://admin:admin123@localhost:27017/?authSource=admin
GATEWAY_URL=http://localhost:8000 # 卡若AI网关
```
---
## 四、端口说明
| 服务 | 端口 | 说明 |
|:---|:---:|:---|
| 神射手前端 | 3001 | Next.js dev |
| MongoDB | 27017 | Docker |
| 卡若AI网关 | 8000 | FastAPI |
---
## 五、关联文档
- [Next.js自动化部署流程.md](./Next.js自动化部署流程.md)
- [../9、手册/快速使用手册.md](../9、手册/快速使用手册.md)

103
开发文档/8、部署/基于 GitHub Webhook 与宝塔面板的自动化部署流程文档.md Normal file
View File

@@ -0,0 +1,103 @@
I. 概述
本流程文档旨在指导您如何通过 GitHub 的 Webhook 功能，实现代码提交后自动同步到宝塔面板服务器，从而完成网站内容的自动化部署。这将极大地提高您的开发效率，减少手动部署带来的重复劳动和潜在错误。
II. 前提条件
在开始配置之前，请确保您已具备以下条件：
1. GitHub 账号：并已拥有一个托管项目代码的仓库。
2. 宝塔面板服务器：一台已安装宝塔面板的 Linux 服务器，并确保已安装 Nginx/Apache、PHP 和 Git 环境。
3. 项目代码：您的网站或应用代码已完整地托管在 GitHub 仓库中。
4. Composer (如果项目是 PHP)：PHP 项目需要确保服务器上安装了 Composer，用于管理项目依赖。
III. 流程概览
以下是自动化部署的整个流程图：
```mermaid
graph TD
A[提交代码到GitHub] --> B{GitHub Webhook};
B --> C[发送Payload到宝塔面板];
C --> D[宝塔面板接收通知];
D --> E[触发部署脚本];
E --> F[执行 git pull];
F --> G[执行 composer install (可选)];
G --> H[清理网站缓存 (可选)];
H --> I[网站内容自动更新];
```
流程说明：
当您将代码提交（Push）到 GitHub 仓库后，GitHub 会通过预设的 Webhook 向您的宝塔面板服务器发送一个通知（Payload）。宝塔面板接收到这个通知后，会触发一个预设的部署脚本，该脚本通常会执行 git pull 拉取最新代码，并可能运行 composer install 安装依赖，以及清理网站缓存等操作。最终，您的网站内容将自动更新到最新版本。
IV. 具体配置步骤
A. GitHub 仓库配置
5. 选择或创建项目仓库：
登录您的 GitHub 账号，选择或创建一个您需要自动部署的项目仓库。
6. 配置 Webhook：
这是实现自动触发部署的关键。
* 进入您的 GitHub 仓库页面，点击顶部的 Settings（设置）。
* 在左侧导航栏中，点击 Webhooks。
* 点击 Add webhook（添加 Webhook）。
* 填写以下信息：
* Payload URL：这个 URL 需要从宝塔面板中获取。请暂时留空，我们将在后面的宝塔面板配置步骤中获取并填回。
* Content type：选择 `application/json`。
* Secret (可选，但强烈推荐)：设置一个随机且复杂的字符串作为密钥。这个密钥用于验证请求是否真的来自 GitHub，增强安全性。例如：`your_github_webhook_secret_123`。请务必牢记这个密钥，稍后宝塔面板中会用到。
* Which events would you like to trigger this webhook?：选择 `Just the push event.`（仅推送事件）。这意味着只有当您向仓库推送代码时，Webhook 才会触发。
* Active：确保此选项被勾选。
* 点击 Add webhook 完成添加。
B. 宝塔面板服务器配置
7. 登录宝塔面板：
使用您的账号密码登录到宝塔面板。
8. 确保服务器环境：
确认您的服务器已安装 Nginx (或 Apache)、PHP (版本需与项目兼容，例如 PHP 7.4) 和 Git。如果 Git 未安装，您可以通过宝塔面板的"软件商店"进行安装。
9. 创建或选择网站：
在宝塔面板中，进入 网站 菜单，创建或选择您要部署代码的网站。确保网站的根目录（运行目录）与您的项目部署路径一致。
10. 设置 Git 部署：
宝塔面板提供了便捷的 Git 部署功能。
* 在网站列表中，找到对应的网站，点击右侧的 设置。
* 在网站设置窗口中，找到 Git 选项卡，点击进入。
* 启用 Git 部署：打开 Git 部署功能。
* 选择平台：选择 `Github`。
* 项目地址：填写您的 GitHub 仓库的 HTTPS 地址。例如：`https://github.com/your-username/your-repo-name.git`。
* 分支：填写您希望自动部署的分支名称，通常是 `main` 或 `master`。
* Token：填写您在 GitHub Webhook 配置中设置的 `Secret` 密钥。
* 项目部署目录：宝塔会自动填写网站的根目录，请确保它是您项目代码实际要部署的路径。
* 部署类型：选择 `拉取`。
* 部署完成后执行的命令 (最重要)：这是自动化部署的核心。当代码拉取完成后，宝塔会执行这些命令。您可以根据您的项目类型填写相应的命令。
* PHP 项目示例命令（请根据您的项目实际情况调整）：
```bash
# 进入项目部署目录 (宝塔会自动切换到此目录，但为了保险可以再cd一次)
cd /www/wwwroot/your_website_directory/
# 拉取最新代码
git pull
# 安装/更新 Composer 依赖 (如果您的项目使用Composer)
composer install --no-dev --optimize-autoloader
# 清理框架缓存 (如果使用框架，如Laravel, Symfony等)
# 例如 Laravel:
# php artisan cache:clear
# php artisan view:clear
# php artisan config:clear
# php artisan migrate --force # 数据库迁移，请谨慎使用！
# 刷新权限 (有时需要)
# chown -R www:www .
# chmod -R 755 .
# chmod -R 777 storage bootstrap/cache # 给予某些目录写入权限
```
请根据您的项目实际情况，选择并修改适合的命令。
* Webhook URL：在您配置完上述信息并保存后，宝塔面板会为您生成一个 `WebHook地址`。复制这个 URL。
11. 返回 GitHub 配置 Webhook：
* 回到 GitHub 仓库的 Webhook 设置页面。
* 编辑您之前创建的 Webhook。
* 将刚刚从宝塔面板复制的 WebHook地址 粘贴到 Payload URL 字段中。
* 点击 Update webhook 保存。
V. 常见问题与排查
- Webhook 接收失败：
* 检查 GitHub Webhook 设置中的 Payload URL 是否正确，是否与宝塔面板生成的 URL 一致。
* 检查 Secret 密钥是否在 GitHub 和宝塔面板中设置一致。
* 检查服务器防火墙或安全组，确保 GitHub 的请求可以到达宝塔面板的 8888 端口（或其他自定义的宝塔面板端口）。
* 查看 GitHub Webhook 的 Recent Deliveries，检查是否有红色感叹号，并查看具体错误信息。
- 部署命令执行失败：
* 查看宝塔面板中网站的 日志，或在 计划任务 中查看 Git 部署的日志，可以找到具体的错误信息。
* 确认部署命令中的 PHP 版本、Composer 路径等是否正确。
* 检查项目依赖是否已正确安装，或 composer install 命令是否正确。
* 检查文件和目录的权限，确保 www 用户（Nginx/Apache 运行用户）对项目目录有读写权限。
- 代码未更新：
* 检查 git pull 命令是否执行成功。
* 如果使用了缓存，确保缓存清理命令正确执行。
VI. 注意事项
- 安全性：`Secret` 密钥非常重要，请妥善保管，不要泄露。
- 分支管理：建议只对生产环境或主分支（如 `main` 或 `production`）进行自动部署，开发分支可以手动部署或使用单独的测试环境。
- 环境区分：生产环境和开发环境应严格区分，避免将开发中的不稳定代码直接部署到生产环境。
- 备份：在进行任何部署操作之前，务必定期备份您的网站代码和数据库。

49
开发文档/8、部署/项目程序提示词.md Normal file
View File

@@ -0,0 +1,49 @@
# 神射手 - 项目程序提示词
> 📅 更新: 2026-01-31
---
## 一、神射手部署信息
| 项目 | 配置 |
|:---|:---|
| 路径 | /Users/karuo/Documents/开发/2、私域银行/神射手 |
| 端口 | 3001（开发） |
| 启动 | npm run dev -- -p 3001 |
| 构建 | npm run build |
| 生产 | npm run start |
---
## 二、环境检查
```bash
# MongoDB
docker ps | grep mongo
# 端口
lsof -i :3001
# 依赖
npm install
```
---
## 三、Webhook 脚本（神射手）
```bash
#!/bin/bash
cd /path/to/神射手
git pull origin main
npm install
npm run build
pm2 reload shensheshou
```
---
## 四、关联文档
- [启动与部署脚本.md](./启动与部署脚本.md)
- [Next.js自动化部署流程.md](./Next.js自动化部署流程.md)

18
开发文档/9、手册/README.md Normal file
View File

@@ -0,0 +1,18 @@
# 9、手册
> 技术文档专家 | 用户手册
## 本目录文档
| 文档 | 说明 |
|:---|:---|
| [_智能展开.md](./_智能展开.md) | 手册引擎激活 |
| [快速使用手册.md](./快速使用手册.md) | **从项目提取**：查询示例、FAQ |
| [说明手册提示词.md](./说明手册提示词.md) | 手册模板 |
| [使用手册提示词.md](./使用手册提示词.md) | 使用手册模板 |
| [落地方案提示词.md](./落地方案提示词.md) | 落地方案 |
## 联动
- 上游: 8-部署
- 指令: `@手册引擎 展开 [模块名]`

290
开发文档/9、手册/_智能展开.md Normal file
View File

@@ -0,0 +1,290 @@
# 📚 手册智能展开引擎 (Manual Auto-Expand)
> **角色激活**: 将此文件拖入 AI，即刻激活 **技术文档专家 + 内容运营** 角色
> **核心能力**: 用户手册、FAQ、营销文案、落地方案
---
## 📋 一、快速启动指令
### 1.1 功能转手册
```
@手册引擎 请根据以下功能，生成完整的用户手册：
【产品名称】：[产品名]
【目标用户】：[小白/合作方/管理员]
【核心功能】：[主要功能列表]
【输出类型】：[用户手册/FAQ/营销文案]
```
### 1.2 展开输出清单
| 输出项 | 说明 | 格式 |
|:---|:---|:---|
| 用户手册 | 傻瓜式操作指南 | Markdown |
| FAQ | 常见问题解答 | Q&A 格式 |
| 营销文案 | ISSMAX 结构 | 朋友圈/公众号 |
| 落地方案 | 商业计划 | PPT 大纲 |
---
## ✍️ 二、文档风格规范
### 2.1 卡若风格（大白话）
```yaml
核心原则:
- 价值先行：先说能赚多少钱，再说怎么操作
- 傻瓜式：Step 1, 2, 3 清晰分步
- 图文并茂：每个步骤配截图
- 禁止术语：不说"分布式"，说"数据自动同步"
话术转换:
❌ "基于分布式架构的数据同步机制"
✅ "账目自动同步，谁也改不了"
❌ "调用 API 接口获取数据"
✅ "点击刷新按钮，数据自动更新"
❌ "用户认证授权流程"
✅ "输入手机号，收到验证码，填上就能登录"
```
### 2.2 ISSMAX 营销结构（卡若专属）
```
I - Interest (兴趣): 自问自答引发共鸣
S - Story (故事): 真实案例/数据
S - Share (干货): 可执行的方法论
M - Model (模型): 核心概念/产品
A - Action (行动): 立即可做的事
X - Xfission (裂变): 分享激励
```
---
## 📝 三、用户手册模板
### 3.1 完整手册结构
```markdown
# [产品名称] 使用手册
> 让你轻松赚钱的私域工具 | 版本 1.0
---
## 📌 一分钟了解
**这是什么？**
一句话：帮你自动分钱的私域系统。
**能帮你什么？**
- ✅ 自动统计流量来源
- ✅ 自动计算分润
- ✅ 一键提现到微信
**谁在用？**
已有 XXX 位合作方使用，累计分润 XXX 万元。
---
## 🚀 快速开始 (3分钟上手)
### Step 1: 登录系统
1. 打开小程序/网页
2. 点击「手机号登录」
3. 输入手机号，获取验证码
4. 填写验证码，点击「登录」
> 💡 **小贴士**: 验证码 60 秒有效，没收到请检查手机信号
### Step 2: 开通流量池
1. 进入「流量池」页面
2. 点击右上角「+」
3. 填写流量池名称
4. 点击「立即开通」
> ✅ **恭喜**: 你的流量池已开通，开始赚钱吧！
### Step 3: 查看收益
1. 进入「我的」页面
2. 点击「我的收益」
3. 查看今日/本月/累计收益
---
## 💰 核心功能详解
### 功能一：流量池管理
[详细说明 + 截图]
### 功能二：收益统计
[详细说明 + 截图]
### 功能三：一键提现
[详细说明 + 截图]
---
## ❓ 常见问题 (FAQ)
### Q1: 收益什么时候到账？
**A**: 提现申请后，1-3 个工作日内到账微信零钱。
### Q2: 提现有手续费吗？
**A**: 100元以上免手续费，100元以下收取 1 元。
### Q3: 忘记密码怎么办？
**A**: 点击登录页「忘记密码」，用手机号重置即可。
---
## 📞 联系我们
- **客服微信**: 28533368
- **客服电话**: 15880802661
- **工作时间**: 周一至周五 9:00-18:00
---
> 💡 **还有问题？** 扫码加入用户群，随时答疑！
```
---
## 📢 四、营销文案模板
### 4.1 ISSMAX 结构示例
```markdown
# [标题：引发好奇]
## I - 兴趣 (自问自答)
你有没有想过，为什么别人做私域能月入10万，而你累死累活才赚几千？
问题不在你不努力，而在你没有系统。
## S - 故事 (真实案例)
去年，厦门一个餐饮老板老张，每天忙到凌晨，月收入才3万。
后来他接入了我们的「云阿米巴」系统：
- 第一个月：自动获客 200+，分润 1.2 万
- 第三个月：团队扩展到 10 人，月分润 5 万
- 半年后：躺赚被动收入，月均 8 万
他只做了一件事：**让系统帮他分钱**。
## S - 干货 (方法论)
我总结了「3 步绑定合作方」的方法：
1. **流量验证**: 先用 7 天免费流量证明效果
2. **系统交付**: 一键开通私域系统，0 学习成本
3. **现金分润**: 每单实时到账，让合作方看到钱
关键点：不占股，分现钱，让利益看得见。
## M - 模型 (核心产品)
这就是我独创的「云阿米巴」模式：
- ✅ 不占你的股
- ✅ 分的是增量收益
- ✅ 用流量+系统绑定合作
## A - 行动 (立即可做)
本周，我们开放 10 个免费测试名额。
扫码加微信 28533368，发送「测试」即可申请。
## X - 裂变 (分享激励)
转发本文到朋友圈，截图发给我，送你：
📚《私域运营100问》电子书
💰 额外 7 天免费流量池
```
---
## 📊 五、落地方案模板
### 5.1 商业计划书大纲
```markdown
# [项目名称] 商业落地方案
## 一、市场背景
- 行业规模：XX 亿
- 增长趋势：年增 XX%
- 痛点分析：XXX
## 二、产品介绍
- 核心功能
- 差异化优势
- 技术壁垒
## 三、商业模式
- 收入来源
- 定价策略
- 成本结构
## 四、运营计划
- 获客渠道
- 转化策略
- 留存方案
## 五、团队介绍
- 核心成员
- 分工协作
## 六、财务预测
- 收入预测
- 成本预测
- 盈亏平衡点
## 七、融资需求
- 融资金额
- 资金用途
- 预期回报
```
---
## 🔗 六、跨目录联动
```mermaid
graph LR
A[1、需求] -->|功能清单| B[9、手册]
C[3、原型] -->|页面截图| B
D[8、部署] -->|运维文档| B
B -->|交付物| E[10、项目管理]
```
---
## 🤖 七、AI 协作指令
| 指令 | 功能 | 示例 |
|:---|:---|:---|
| `@生成手册` | 生成用户手册 | `@生成手册 流量池功能` |
| `@生成FAQ` | 生成常见问题 | `@生成FAQ 提现模块` |
| `@生成文案` | 生成营销文案 | `@生成文案 ISSMAX结构` |
| `@话术优化` | 技术术语翻译 | `@话术优化 [技术文档]` |
| `@生成方案` | 生成落地方案 | `@生成方案 私域银行` |
---
## ⚠️ 八、注意事项
### 8.1 文档原则
```yaml
必须做:
- [ ] 每个步骤配截图
- [ ] 使用大白话
- [ ] 价值前置
- [ ] 提供联系方式
禁止做:
- [ ] 使用技术术语
- [ ] 长篇大论无重点
- [ ] 只说功能不说价值
```
---
> **下一步**: 手册完成后，拖入 `10、项目管理/_智能展开.md` 进行项目管理

50
开发文档/9、手册/使用手册提示词.md Normal file
View File

@@ -0,0 +1,50 @@
# 神射手 - 使用手册提示词
> 📅 更新: 2026-01-31
---
## 一、受众与风格
| 项目 | 说明 |
|:---|:---|
| 受众 | 运营、营销、数据分析人员 |
| 风格 | 大白话、步骤清晰、图文并茂 |
| 原则 | 价值先行，再说操作 |
---
## 二、神射手快速上手
### Step 1: 启动
```bash
cd 神射手
npm run dev -- -p 3001
```
访问 http://localhost:3001
### Step 2: AI 查询
- 输入手机号：如 `13800138000`
- 输入 QQ 号：如 `28533368 qq`
- 输入「状态」：查看系统统计
### Step 3: 人群圈选
- 数据接入 → 标签画像 → 人群圈选
- 选择项目（存客宝/点了码/微博/QQ）
- 选择流量池 → 查看用户列表
---
## 三、常见问题
| 问题 | 解法 |
|:---|:---|
| 端口被占用 | 换端口 `npm run dev -- -p 3002` |
| MongoDB 连接失败 | 检查 `docker ps \| grep mongo` |
| 查询超时 | 大表已用 $sample 采样优化 |
---
## 四、关联文档
- [快速使用手册.md](./快速使用手册.md)
- [../00_项目核心文档.md](../00_项目核心文档.md)

106
开发文档/9、手册/快速使用手册.md Normal file
View File

@@ -0,0 +1,106 @@
# 神射手 - 快速使用手册
> 📅 从 SKILL.md 与项目提取 | 2026-01-31
---
## 一、快速开始
### 1.1 启动项目
```bash
cd /Users/karuo/Documents/开发/2、私域银行/神射手
npm run dev -- -p 3001
```
### 1.2 访问地址
- 前端: http://localhost:3001
- API: http://localhost:3001/api/ai-chat
---
## 二、AI对话使用
### 2.1 支持的查询类型
| 输入示例 | 返回 |
|:---|:---|
| `13800138000` | 用户画像（姓名、QQ、等级、地区） |
| `28533368 qq` | QQ关联手机号及用户信息 |
| `状态` / `统计` | 系统状态、总用户数、延迟 |
| `RFM分析` | 用户价值分析 |
| `高价值用户` | Top N 高估值用户 |
### 2.2 示例
```
用户: 13407000001
AI: [思考过程] 识别为手机号查询...
[用户画像卡片]
姓名: xxx
手机: 134****0001
等级: A
估值分: 2227
```
---
## 三、各模块使用
### 3.1 数据概览
- 首页输入框直接输入查询
- 点击模块卡片进入对应功能
### 3.2 数据接入
- 数据源: 查看26个KR_*数据库连接状态
- AI引擎: 查看标签引擎任务
- 数据血缘: 拖拽查看数据流向
### 3.3 标签画像
- 标签: 查看/创建标签
- 用户画像: 选择画像模板
- 人群圈选: 项目→流量池→用户列表
### 3.4 AI Agent
- 渠道配置: 飞书/企微/微信配置步骤
- AI打标: 配置打标规则
- 智能报告: 配置报告模板
### 3.5 数据市场
- 流量包: 创建/下载/发送
- API服务: 查看13个API端点
---
## 四、API调用示例
```bash
# 获取系统状态
curl http://localhost:3001/api/ai-chat
# 查询用户
curl -X POST http://localhost:3001/api/ai-chat \
-H "Content-Type: application/json" \
-d '{"message":"13800138000"}'
# 健康检查
curl "http://localhost:3001/api/monitoring?action=health"
```
---
## 五、常见问题
| 问题 | 解决 |
|:---|:---|
| 端口被占用 | 换端口 `npm run dev -- -p 3002` |
| MongoDB连接失败 | 检查 `docker ps`，确认27017 |
| 飞书未配置 | 配置 .env 中 FEISHU_* 变量 |
---
## 六、关联文档
- [说明手册提示词.md](./说明手册提示词.md)
- [../00_项目核心文档.md](../00_项目核心文档.md)

32
开发文档/9、手册/落地方案提示词.md Normal file
View File

@@ -0,0 +1,32 @@
# 神射手 - 落地方案提示词
> 📅 更新: 2026-01-31
---
## 一、神射手落地复盘模板
```markdown
## 神射手数据中台落地复盘
**目标&结果**：目标完成5大模块真实数据对接，实际完成率95%。
**过程**：
- 数据概览：AI对话、系统状态 ✅
- 数据接入：数据源、AI引擎、血缘 ✅
- 标签画像：标签、画像、人群圈选 ✅
- AI Agent：渠道、打标、清洗、报告 ✅
- 数据市场：流量包、API服务 ✅
**反思**：大表查询需 $sample 采样，飞书需配置环境变量。
**执行**：完善飞书配置，引入 Redis 缓存。
```
---
## 二、输出格式
- **结构**：目标→过程→反思→执行
- **数据**：引用真实统计（如 20.13亿用户）
- **行动**：具体可执行项

38
开发文档/9、手册/说明手册提示词.md Normal file
View File

@@ -0,0 +1,38 @@
# 神射手 - 说明手册提示词
> 📅 更新: 2026-01-31
---
## 一、系统概述
- **定位**：用户资产数字化中台
- **能力**：手机号/QQ/UID 秒级查询用户画像
- **规模**：20亿+ 用户、26个KR_*数据库
---
## 二、架构说明
| 项目 | 说明 |
|:---|:---|
| 前端 | Next.js 14 + Radix UI + TailwindCSS |
| 后端 | Next.js API Routes + MongoDB |
| 数据库 | MongoDB localhost:27017 |
| 网关 | 卡若AI FastAPI :8000 |
---
## 三、接口与数据
- **API**：25个端点，见 `5、接口/API清单与核心逻辑.md`
- **集合**：KR.用户估值、KR_腾讯.QQ+手机 等，见 `7、数据库/ER与查询逻辑.md`
---
## 四、配置与环境
```bash
MONGODB_URI=mongodb://admin:admin123@localhost:27017/?authSource=admin
GATEWAY_URL=http://localhost:8000
```

346
开发文档/AI开发引擎.md Normal file
View File

@@ -0,0 +1,346 @@
# 🚀 AI 开发引擎 (AI Development Engine) v2.0
> **核心定位**: 这是整个开发模板的"大脑"，一个基于多智能体协作的智能开发中台。
> **使用方式**: 将此文件拖入 AI 对话框，即可激活"全栈架构师"角色，自动拆解项目并联动所有目录。
> **项目管理 Skill**: 本模板内置 `dev-template-project-manager` Skill，自动管理项目进度、任务拆解、对话上下文存储。
---
## 🎯 项目管理 Skill 集成
本开发模板内置了 **项目管理专家 Skill** (`.cursor/skills/dev-template-project-manager/`)，提供：
| 能力 | 说明 |
|:---|:---|
| 📊 **项目进度管理** | 执行表、甘特图、燃尽图 |
| 📋 **需求任务拆解** | 自动将需求转化为可执行任务 |
| 💾 **对话上下文存储** | 跨对话保持项目状态 |
| 📝 **提示词库管理** | 存储和复用常用提示词 |
| 🔗 **文档联动更新** | 变更自动同步到相关文档 |
**快速开始**：
```
@项目管理 初始化项目工作区
【项目名称】：[项目名]
【项目描述】：[一句话描述]
【预期周期】：[开发周期]
```
详见 `.cursor/skills/dev-template-project-manager/SKILL.md`
---
## 🎯 引擎功能矩阵
```
┌─────────────────────────────────────────────────────────────────────────┐
│ AI 开发引擎 (总控) │
├─────────────────────────────────────────────────────────────────────────┤
│ 📥 输入层 │ 🧠 处理层 │ 📤 输出层 │
│ ───────────── │ ───────────── │ ───────────── │
│ · 需求描述 │ · 需求拆解引擎 │ · 完整项目文档 │
│ · 竞品/截图 │ · 架构设计引擎 │ · 代码框架 │
│ · 预算/时间 │ · 代码生成引擎 │ · 部署脚本 │
│ │ · 文档生成引擎 │ · 使用手册 │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## 🏗️ 一、快速启动：一键展开项目
### 1.1 极速启动指令
将以下内容复制到 AI 对话框，替换 `[项目描述]` 即可自动展开整个项目：
```
@AI引擎 请根据以下需求，自动展开完整项目文档：
【项目名称】：[填写项目名]
【核心功能】：[用一句话描述核心功能]
【目标用户】：[谁会用这个产品]
【预期规模】：[日活/并发/数据量]
【时间预算】：[开发周期]
【技术偏好】：[有无特定技术栈要求]
请按照 1-10 目录结构，逐一生成所有文档。
```
### 1.2 展开输出清单
AI 将自动生成以下全套文档：
| 序号 | 目录 | 自动生成内容 | 联动文件 |
|:---:|:---|:---|:---|
| 1 | 需求 | 业务流程图、用户故事、MVP 功能清单 | `业务需求.md` `成本.md` |
| 2 | 架构 | 系统架构图、技术选型表、模块拆分 | `系统架构.md` `技术选型.md` |
| 3 | 原型 | 页面结构、交互流程、UI 规范 | `原型设计规范.md` |
| 4 | 前端 | 组件树、页面代码、样式系统 | `前端开发规范.md` |
| 5 | 接口 | API 列表、请求响应示例、错误码 | `接口定义规范.md` |
| 6 | 后端 | 服务拆分、业务流程、AI 集成 | `后端开发规范.md` |
| 7 | 数据库 | ER 图、集合设计、索引策略 | `数据库管理规范.md` |
| 8 | 部署 | 部署脚本、CI/CD 配置、运维手册 | `项目程序提示词.md` |
| 9 | 手册 | 用户手册、FAQ、营销文案 | `使用手册提示词.md` |
| 10 | 管理 | 甘特图、执行表、风险矩阵 | `项目管理提示词.md` |
---
## 🧠 二、多智能体协作架构 (DocAgent)
基于最新 AI 研究成果，本引擎采用多智能体协作模式：
```mermaid
graph TB
subgraph Orchestrator[🎯 编排器]
O[任务分发与协调]
end
subgraph Agents[🤖 智能体矩阵]
A1[📖 Reader<br/>需求理解]
A2[🔍 Searcher<br/>上下文检索]
A3[✍️ Writer<br/>内容生成]
A4[✅ Verifier<br/>质量校验]
end
subgraph Output[📤 输出层]
D1[需求文档]
D2[架构文档]
D3[代码框架]
D4[部署脚本]
end
O --> A1
A1 --> A2
A2 --> A3
A3 --> A4
A4 --> Output
A4 -->|不通过| A3
```
### 智能体职责说明
| 智能体 | 角色 | 职责 | 对应目录 |
|:---:|:---|:---|:---|
| 📖 Reader | 需求分析师 | 理解输入、提取关键信息 | 1、需求 |
| 🔍 Searcher | 架构师 | 检索最佳实践、技术选型 | 2、架构 |
| ✍️ Writer | 全栈工程师 | 生成代码、文档、配置 | 3-8 目录 |
| ✅ Verifier | QA 工程师 | 校验一致性、安全性 | 9、10 目录 |
---
## ⚡ 三、智能展开指令集
### 3.1 按阶段展开
```
# 阶段一：需求与架构（战略层）
@AI引擎 展开阶段一：
- 生成业务流程图 (Mermaid)
- 生成用户故事卡片
- 生成技术选型对比表
- 生成系统架构图
# 阶段二：设计与接口（战术层）
@AI引擎 展开阶段二：
- 生成页面结构树
- 生成 API 接口文档
- 生成 ER 图
- 生成组件设计图
# 阶段三：编码与部署（执行层）
@AI引擎 展开阶段三：
- 生成前端代码框架
- 生成后端代码框架
- 生成部署脚本
- 生成运维手册
```
### 3.2 按目录单独展开
```
# 单独展开某个目录
@AI引擎 展开目录[N]：[项目上下文]
# 示例：
@AI引擎 展开目录5：为私域银行项目生成完整 API 接口文档
```
### 3.3 跨目录联动展开
```
# 联动展开（自动保持一致性）
@AI引擎 联动展开：
- 基于 [需求文档] 更新 [架构文档]
- 基于 [架构文档] 生成 [接口文档]
- 基于 [接口文档] 生成 [前端代码]
- 基于 [接口文档] 生成 [后端代码]
```
---
## 🔧 四、核心规则与约束
### 4.1 卡若风格规则
```yaml
# 输出风格
语言: 大白话，直击要点
结构: 结论→原因→步骤
可视化: 必须包含 Mermaid 图表
代码: 必须中文注释
# 技术规范
前端: React + Shadcn UI + Tailwind CSS + iOS 风格
后端: Python FastAPI + Type Hints + 异步优先
数据库: MongoDB 优先（含向量索引）
部署: Webhook 自动化 + 宝塔/Docker
# 安全规范
禁止: 硬编码密钥、os.system()、rm -rf
强制: 参数化查询、Type Hints、骨架屏
```
### 4.2 云阿米巴商业规则
```yaml
# 核心逻辑
分钱原则: 分不属于对方的钱
价值绑定: 按创造价值分钱
流量锁定: 用稳定流量 + 便捷私域体系绑定合作方
# 产品规则
流量池: 页面必须有流量入口
分润显示: 让合作方一眼看到赚了多少钱
一键提现: 降低操作门槛
```
---
## 📊 五、输出模板库
### 5.1 需求文档模板
```markdown
# [项目名称] 需求文档 v1.0
## 一、项目背景
[为什么做这个项目？解决什么痛点？]
## 二、目标用户
| 用户角色 | 核心诉求 | 使用场景 |
|:---|:---|:---|
## 三、功能清单 (MVP)
| 功能模块 | 子功能 | 优先级 | 验收标准 |
|:---|:---|:---:|:---|
## 四、业务流程
[Mermaid 流程图]
## 五、成功指标
- [ ] 核心指标 1
- [ ] 核心指标 2
```
### 5.2 架构文档模板
```markdown
# [项目名称] 系统架构 v1.0
## 一、技术选型
| 层级 | 技术 | 选型理由 |
|:---|:---|:---|
## 二、系统架构图
[Mermaid C4/架构图]
## 三、模块拆分
| 模块 | 职责 | 依赖 |
|:---|:---|:---|
## 四、数据流
[Mermaid 序列图]
```
### 5.3 API 文档模板
```markdown
# [项目名称] API 文档 v1.0
## 接口：[接口名称]
- **URL**: `/api/v1/xxx`
- **Method**: `POST`
- **Auth**: Bearer Token
### Request
| 参数 | 类型 | 必填 | 说明 |
|:---|:---|:---:|:---|
### Response
{
"code": 200,
"message": "success",
"data": { }
}
### 错误码
| code | message | 处理建议 |
|:---:|:---|:---|
```
---
## 🔄 六、自动更新机制
### 6.1 文档同步规则
```
触发条件 → 自动更新动作
─────────────────────────
需求变更 → 更新架构文档、接口文档、前后端代码
接口变更 → 更新前端调用、后端实现、API 文档
数据库变更 → 更新 ER 图、后端 Model、接口文档
部署配置变更 → 更新运维手册、启动脚本
```
### 6.2 版本控制
```yaml
# 文档版本规则
major.minor.patch
│ │ └── 小修小补（错别字、格式）
│ └──────── 功能迭代（新增接口、字段）
└────────────── 架构变更（技术栈、模块重构）
```
---
## 🎮 七、快捷指令速查表
| 指令 | 功能 | 示例 |
|:---|:---|:---|
| `@全量展开` | 展开所有 1-10 目录 | `@全量展开 私域银行项目` |
| `@展开[N]` | 展开指定目录 | `@展开5 生成 API 文档` |
| `@联动更新` | 基于变更同步文档 | `@联动更新 接口新增了 /api/v1/withdraw` |
| `@生成代码` | 生成代码框架 | `@生成代码 前端登录页面` |
| `@生成图表` | 生成 Mermaid 图 | `@生成图表 用户下单流程` |
| `@复盘总结` | 生成项目复盘 | `@复盘总结 Q1 迭代` |
---
## 📎 附录：目录索引
| 目录 | 智能展开文件 | 角色 |
|:---|:---|:---|
| 1、需求 | `_智能展开.md` | CFO + 产品负责人 |
| 2、架构 | `_智能展开.md` | CTO + 架构师 |
| 3、原型 | `_智能展开.md` | UI/UX 设计师 |
| 4、前端 | `_智能展开.md` | 前端主程 |
| 5、接口 | `_智能展开.md` | API 架构师 |
| 6、后端 | `_智能展开.md` | Python 架构师 |
| 7、数据库 | `_智能展开.md` | DBA |
| 8、部署 | `_智能展开.md` | DevOps 运维 |
| 9、手册 | `_智能展开.md` | 技术文档专家 |
| 10、项目管理 | `_智能展开.md` | 高级 PM |
---
> **使用提示**: 本文件是"总控"，每个目录下的 `_智能展开.md` 是"分控"。可以单独使用某个目录的智能展开，也可以用本文件一键展开全部。

BIN
开发文档/AI开发流程.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.0 MiB

BIN
开发文档/AI标签系统V1产品需求文档 (2).docx Normal file
View File

Binary file not shown.

BIN
开发文档/《神射手数据中台》产品需求文档 (PRD) V1.1.docx Normal file
View File

Binary file not shown.

466
开发文档/代码核心提取器.md Normal file
View File

@@ -0,0 +1,466 @@
# 🔬 代码核心提取器 (Code Core Extractor)
> **角色激活**: 将此文件拖入 AI，即刻激活 **代码分析专家** 角色
> **核心能力**: 分析项目结构、提取核心代码、精简无关文件、生成核心文档
---
## 🎯 一、快速启动指令
### 1.1 一键提取核心
```
@代码提取器 请分析以下项目，提取核心代码：
【项目路径】：[项目根目录路径]
【项目类型】：[前端/后端/全栈]
【技术栈】：[React/Vue/FastAPI/等]
【提取目标】：[理解架构/二次开发/代码审计/学习参考]
```
### 1.2 展开输出清单
| 输出项 | 说明 | 存放位置 |
|:---|:---|:---|
| 项目架构图 | 模块关系可视化 | `_核心代码/架构图.md` |
| 核心文件清单 | 关键文件列表 | `_核心代码/文件清单.md` |
| 核心代码摘要 | 关键代码片段 | `_核心代码/代码摘要.md` |
| 数据流图 | 数据流转逻辑 | `_核心代码/数据流.md` |
| 删除建议 | 可删除的无关文件 | `_核心代码/清理建议.md` |
---
## 🧠 二、分析流程
### 2.1 五步分析法
```
┌─────────────────────────────────────────────────────────────────────┐
│ 代码核心提取流程 │
├─────────────────────────────────────────────────────────────────────┤
│ Step 1: 🔍 扫描项目结构 │
│ ├── 识别项目类型（前端/后端/全栈） │
│ ├── 识别技术栈（框架/语言/依赖） │
│ └── 生成目录树 │
├─────────────────────────────────────────────────────────────────────┤
│ Step 2: 📊 识别核心模块 │
│ ├── 入口文件（main.py/index.ts/App.tsx） │
│ ├── 路由配置（router/routes） │
│ ├── 核心业务逻辑（services/controllers） │
│ └── 数据模型（models/schemas） │
├─────────────────────────────────────────────────────────────────────┤
│ Step 3: 🔗 分析依赖关系 │
│ ├── 模块间调用关系 │
│ ├── 数据流向 │
│ └── 第三方依赖 │
├─────────────────────────────────────────────────────────────────────┤
│ Step 4: ✂️ 提取核心代码 │
│ ├── 提取关键函数/类 │
│ ├── 保留核心注释 │
│ └── 去除冗余代码 │
├─────────────────────────────────────────────────────────────────────┤
│ Step 5: 🗑️ 标记可删除文件 │
│ ├── 测试文件（可选保留） │
│ ├── 配置示例文件 │
│ ├── 文档/注释文件 │
│ └── 构建产物/缓存 │
└─────────────────────────────────────────────────────────────────────┘
```
---
## 📁 三、核心文件识别规则
### 3.1 前端项目核心文件
```yaml
必须保留:
入口文件:
- main.ts / main.tsx / index.tsx
- App.tsx / App.vue
- _app.tsx (Next.js)
- nuxt.config.ts (Nuxt)
路由配置:
- router/index.ts
- app/layout.tsx (Next.js App Router)
- pages/_app.tsx
核心页面:
- pages/*.tsx
- app/**/page.tsx
- views/*.vue
核心组件:
- components/ui/* (基础组件)
- components/business/* (业务组件)
状态管理:
- store/*.ts
- hooks/use*.ts
API调用:
- api/*.ts
- services/*.ts
- lib/api.ts
可以删除:
- __tests__/
- *.test.ts / *.spec.ts
- .storybook/
- docs/
- examples/
- node_modules/
- .next/ / dist/ / build/
- *.md (非核心文档)
```
### 3.2 后端项目核心文件
```yaml
必须保留:
入口文件:
- main.py / app.py
- __init__.py (包入口)
- manage.py (Django)
路由/控制器:
- routers/*.py
- controllers/*.py
- views.py (Django)
- urls.py
业务逻辑:
- services/*.py
- core/*.py
- utils/*.py (核心工具)
数据模型:
- models/*.py
- schemas/*.py
- entities/*.py
配置:
- config.py / settings.py
- core/config.py
数据库:
- database.py
- migrations/ (结构参考)
可以删除:
- tests/
- __pycache__/
- *.pyc
- .pytest_cache/
- docs/
- examples/
- venv/ / .venv/
- *.egg-info/
```
### 3.3 全栈项目核心文件
```yaml
必须保留:
前端: (参考 3.1)
后端: (参考 3.2)
共享:
- types/*.ts (类型定义)
- shared/*.ts
- constants/*.ts
配置:
- package.json
- requirements.txt / pyproject.toml
- docker-compose.yml
- .env.example
可以删除:
- 所有测试文件
- 所有构建产物
- IDE 配置 (.vscode/ .idea/)
- Git 钩子 (.husky/)
- CI/CD 配置 (可选)
```
---
## 📝 四、输出模板
### 4.1 核心代码目录结构
```
📁 _核心代码/
│
├── 📄 README.md ← 项目概述 + 快速理解指南
├── 📄 架构图.md ← Mermaid 架构图
├── 📄 文件清单.md ← 核心文件列表 + 说明
├── 📄 代码摘要.md ← 关键代码片段
├── 📄 数据流.md ← 数据流转说明
├── 📄 清理建议.md ← 可删除文件列表
│
├── 📁 入口/ ← 入口文件副本
├── 📁 路由/ ← 路由配置副本
├── 📁 业务逻辑/ ← 核心 Service 副本
├── 📁 数据模型/ ← Model/Schema 副本
└── 📁 工具函数/ ← 核心 Utils 副本
```
### 4.2 架构图模板
```markdown
# [项目名] 系统架构
## 模块依赖图
[Mermaid graph TB]
## 数据流图
[Mermaid sequenceDiagram]
## 目录结构
[树形结构]
```
### 4.3 文件清单模板
```markdown
# [项目名] 核心文件清单
## 一、入口文件
| 文件 | 路径 | 说明 | 重要度 |
|:---|:---|:---|:---:|
| main.py | /app/main.py | FastAPI 入口 | ⭐⭐⭐ |
## 二、路由配置
...
## 三、业务逻辑
...
## 四、数据模型
...
## 五、依赖关系
[哪个文件依赖哪个文件]
```
### 4.4 代码摘要模板
```markdown
# [项目名] 核心代码摘要
## 1. 入口文件 (main.py)
### 核心逻辑
[代码片段 + 中文注释]
### 关键点
- 要点1
- 要点2
---
## 2. 用户服务 (user_service.py)
### 核心函数
[代码片段]
### 业务逻辑说明
...
```
### 4.5 清理建议模板
```markdown
# [项目名] 文件清理建议
## 一、建议删除（无影响）
| 文件/目录 | 原因 | 大小 |
|:---|:---|---:|
| __pycache__/ | Python 缓存 | 2.3MB |
| node_modules/ | 依赖包 | 500MB |
| .next/ | 构建产物 | 150MB |
## 二、可选删除（按需保留）
| 文件/目录 | 原因 | 保留场景 |
|:---|:---|:---|
| tests/ | 测试文件 | 需要运行测试时保留 |
| docs/ | 文档 | 需要查阅文档时保留 |
## 三、必须保留（勿删）
| 文件/目录 | 原因 |
|:---|:---|
| .env.example | 环境变量模板 |
| requirements.txt | 依赖清单 |
## 四、清理命令
```bash
# 一键清理无用文件
rm -rf __pycache__ .pytest_cache .next dist build
rm -rf node_modules # 可重新 npm install
```
```
---
## 🤖 五、AI 协作指令
### 5.1 分析指令
| 指令 | 功能 | 示例 |
|:---|:---|:---|
| `@分析项目` | 全面分析项目结构 | `@分析项目 /path/to/project` |
| `@提取核心` | 提取核心代码到 _核心代码/ | `@提取核心 当前项目` |
| `@架构图` | 生成架构图 | `@架构图 模块依赖` |
| `@数据流` | 分析数据流向 | `@数据流 用户下单` |
| `@文件清单` | 列出核心文件 | `@文件清单 后端` |
### 5.2 清理指令
| 指令 | 功能 | 示例 |
|:---|:---|:---|
| `@清理建议` | 生成可删除文件列表 | `@清理建议 当前项目` |
| `@瘦身` | 执行文件清理 | `@瘦身 删除测试文件` |
| `@精简` | 提取最小可运行代码 | `@精简 只保留核心` |
### 5.3 组合指令
```
# 完整分析 + 提取 + 清理
@全量分析 [项目路径]
→ 自动执行：分析 → 提取核心 → 生成清理建议
# 快速理解项目
@快速理解 [项目路径]
→ 输出：架构图 + 入口文件说明 + 核心逻辑
# 准备二次开发
@二开准备 [项目路径]
→ 输出：核心代码 + 扩展点 + 修改建议
```
---
## 📊 六、分析输出示例
### 6.1 架构图示例
```mermaid
graph TB
subgraph 前端[前端 Next.js]
A1[pages/] --> A2[components/]
A2 --> A3[hooks/]
A3 --> A4[lib/api.ts]
end
subgraph 后端[后端 FastAPI]
B1[main.py] --> B2[routers/]
B2 --> B3[services/]
B3 --> B4[models/]
B4 --> B5[(MongoDB)]
end
A4 -->|API 调用| B2
```
### 6.2 核心代码摘要示例
```python
# === 入口文件: main.py ===
# 核心作用：FastAPI 应用入口，注册路由和中间件
from fastapi import FastAPI
from app.routers import user, traffic_pool # 核心路由
from app.core.config import settings # 配置
app = FastAPI(title=settings.APP_NAME)
# 注册路由 - 这是核心！
app.include_router(user.router, prefix="/api/v1")
app.include_router(traffic_pool.router, prefix="/api/v1")
# === 理解要点 ===
# 1. 所有 API 都在 /api/v1 前缀下
# 2. 业务逻辑在 services/ 目录
# 3. 数据模型在 models/ 目录
```
---
## ⚠️ 七、注意事项
### 7.1 分析规则
```yaml
必须做:
- [ ] 先扫描整体结构，再深入分析
- [ ] 保留所有核心业务逻辑
- [ ] 保留关键注释和文档
- [ ] 生成清晰的依赖关系图
禁止做:
- [ ] 删除 .env.example（配置模板）
- [ ] 删除 requirements.txt/package.json
- [ ] 删除数据库迁移文件（结构参考）
- [ ] 未经确认直接删除文件
```
### 7.2 安全提醒
```yaml
敏感文件处理:
- .env 文件：提取结构，不提取值
- 密钥文件：标记位置，不复制内容
- 数据库文件：只提取 Schema，不提取数据
```
---
## 🔗 八、与其他模块联动
```mermaid
graph LR
A[代码核心提取器] -->|架构理解| B[2、架构]
A -->|接口提取| C[5、接口]
A -->|数据模型| D[7、数据库]
A -->|部署分析| E[8、部署]
```
### 联动指令
```
# 提取后自动生成架构文档
@联动 提取→架构：基于核心代码生成架构文档
# 提取后自动生成接口文档
@联动 提取→接口：基于路由代码生成 API 文档
# 提取后自动分析数据库
@联动 提取→数据库：基于 Model 生成 ER 图
```
---
## 🚀 九、快速使用流程
```
1️⃣ 打开项目目录
↓
2️⃣ 拖入此文件到 AI 对话框
↓
3️⃣ 输入：@全量分析 [项目路径]
↓
4️⃣ AI 自动执行：
- 扫描项目结构
- 识别核心文件
- 提取关键代码
- 生成架构图
- 输出清理建议
↓
5️⃣ 在 _核心代码/ 目录查看结果
↓
6️⃣ 根据清理建议删除无关文件
```
---
> **目标**: 让你在 5 分钟内理解任何项目的核心架构，快速上手二次开发！

39
开发文档/开发文档.md
View File

@@ -1,39 +0,0 @@
## 2025-08-08 菜单同步 + 用户画像数据与接口完善
- 完成内容：
- 同步左侧导航与底部菜单，统一为【首页 / 数据中台 / 画像 / AI智能助手】，去除“搜索”入口，避免与首页内置搜索重复。
- 新增 /api/users 接口（GET/POST），支持 q、tags、status、rfmMin、rfmMax、page、pageSize 与 id 详情查询。
- 新增 lib/mock-users.ts：批量生成中文姓名、邮箱、手机号、标签、动态时间（基于当前时间）与 RFM 分数的模拟用户数据。
- 新增 Skeleton 组件与 moments-sync 编辑页 loading.tsx 作为 Suspense Fallback，避免 useSearchParams 构建报错。
- 补齐 Toast / Toaster 组件的导出与实现，修复构建失败。
- 将“搜索入口”迁移并固定在首页；修复 /api/users 导出/导入冲突，稳定构建。
- 首页搜索功能：在 app/page.tsx 中集成 UserSearch 组件，提供状态筛选、RFM区间筛选与实时搜索
- 用户列表组件：components/home/user-list.tsx 完整实现，包含加载态、错误态、空态处理
- 筛选组件：components/home/user-search.tsx 提供状态多选、RFM滑块筛选
- API接口：app/api/users/route.ts 简化实现，仅依赖 lib/mock-users.ts
- 数据层：lib/mock-users.ts 生成120条真实感用户数据，支持多条件查询与分页
- UI组件：补齐 Slider 组件，修复 useDebounce 导出问题
- 变更文件：
- app/page.tsx（新增首页搜索与指标卡片）
- components/home/user-search.tsx（新增：状态/RFM过滤 + 绑定首页搜索框）
- components/home/user-list.tsx（新增：表格列表）
- app/api/users/route.ts（精简重写：仅依赖 lib/mock-users 导出）
- lib/mock-users.ts（统一导出 queryUsers/addUser/getUserById，时间全部相对“当前时间”生成）
- 接口与数据：
- GET /api/users?id= 返回单体详情；GET /api/users 返回列表与分页；POST /api/users 新增一个用户（服务内内存态）。
- 完成度：
- 本轮任务完成度：100%
- 用户画像模块整体完成度：90%（已具备真实感数据与筛选能力，待接入真实库）
- 全项目：70%
- 下一步计划：
1. 接入真实数据库（Neon/Supabase/MySQL），并加上索引与分页游标；
2. 画像页联动更多筛选项与批量导出；
3. 详情页增加 AI 洞察与行动建议（AI SDK），联动 RFM；
4. 对齐路由处的 loading 骨架风格，完善可用性与无障碍。
1) 数据库对接（Neon/Supabase/MySQL）保留接口契约不变；
2) 画像页接入上述接口的分页与高级筛选，补齐批量导出；
3) 详情页接入 AI SDK 生成洞察与跟进建议（RFM联动）。

143
开发文档/标签管理系统开发文档.md
View File

@@ -1,143 +0,0 @@
# 标签管理系统开发文档
## 1. 系统概述
标签管理系统是用户数据资产中台的核心组件之一，用于管理和组织用户标签体系，支持用户画像的构建和应用。系统包括标签管理、标签规则引擎等功能模块，为企业提供完整的用户标签生命周期管理能力。
## 2. 系统架构
### 2.1 总体架构
标签管理系统采用前后端分离架构，前端使用 React + Next.js 开发，后端使用 Node.js + MySQL 开发。系统主要包括以下几个部分：
- 标签管理：负责标签的创建、编辑、删除等基础管理功能
- 标签规则引擎：负责标签生成规则的定义和执行
- 标签分析：提供标签使用情况的统计和分析功能
- 标签关系图谱：展示标签之间的关联关系
### 2.2 数据模型
#### 标签表 (tags)
| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| id | varchar(36) | 主键，标签ID |
| name | varchar(100) | 标签名称 |
| category | varchar(50) | 标签分类 |
| type | enum | 标签类型：系统、自定义、衍生 |
| source | varchar(100) | 数据来源 |
| coverage | decimal(5,2) | 覆盖率 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |
#### 标签规则表 (tag_rules)
| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| id | varchar(36) | 主键，规则ID |
| name | varchar(100) | 规则名称 |
| description | text | 规则描述 |
| target_tag_id | varchar(36) | 目标标签ID |
| condition | text | 规则条件 |
| sql | text | SQL语句 |
| status | enum | 状态：活跃、非活跃、草稿 |
| priority | int | 优先级 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |
#### 规则执行历史表 (rule_executions)
| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| id | varchar(36) | 主键，执行ID |
| rule_id | varchar(36) | 规则ID |
| execution_time | datetime | 执行时间 |
| duration | int | 执行耗时（秒） |
| status | enum | 状态：成功、失败、执行中 |
| affected_users | int | 影响用户数 |
| executed_by | varchar(50) | 执行人 |
| log | text | 执行日志 |
#### 用户标签关联表 (user_tags)
| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| user_id | varchar(36) | 用户ID |
| tag_id | varchar(36) | 标签ID |
| created_at | datetime | 创建时间 |
| rule_execution_id | varchar(36) | 规则执行ID |
## 3. 功能模块
### 3.1 标签管理
标签管理模块提供标签的基础管理功能，包括：
- 标签列表：展示所有标签，支持搜索、筛选和排序
- 标签创建：创建新标签，设置标签名称、分类、类型等信息
- 标签编辑：修改标签信息
- 标签删除：删除不需要的标签
- 标签分析：展示标签的使用情况和分布情况
- 标签关系图谱：展示标签之间的关联关系
### 3.2 标签规则引擎
标签规则引擎负责标签生成规则的定义和执行，包括：
- 规则列表：展示所有规则，支持搜索、筛选和排序
- 规则创建：创建新规则，设置规则名称、描述、目标标签、条件等信息
- 规则编辑：修改规则信息
- 规则执行：手动执行规则，为符合条件的用户打标签
- 规则调度：设置规则的自动执行计划
- 执行历史：查看规则的执行历史和结果
## 4. 开发流程
### 4.1 标签管理模块开发
1. 创建标签管理页面 (app/tag-management/page.tsx)
2. 实现标签列表展示功能
3. 实现标签创建、编辑、删除功能
4. 实现标签分类分布图表 (components/tag-management/tag-category-chart.tsx)
5. 实现标签使用统计图表 (components/tag-management/tag-usage-stats.tsx)
6. 实现标签关系图谱 (components/tag-management/tag-relationship-graph.tsx)
### 4.2 标签规则引擎开发
1. 创建标签规则引擎页面 (app/tag-rules/page.tsx)
2. 实现规则列表展示功能
3. 实现规则创建、编辑、删除功能
4. 实现规则编辑器 (components/tag-rules/rule-editor.tsx)
5. 实现规则执行历史查看功能 (components/tag-rules/rule-execution-history.tsx)
## 5. 接口设计
### 5.1 标签管理接口
- GET /api/tags - 获取标签列表
- POST /api/tags - 创建标签
- GET /api/tags/:id - 获取标签详情
- PUT /api/tags/:id - 更新标签
- DELETE /api/tags/:id - 删除标签
- GET /api/tags/stats - 获取标签统计信息
- GET /api/tags/relationships - 获取标签关系图谱数据
### 5.2 标签规则引擎接口
- GET /api/tag-rules - 获取规则列表
- POST /api/tag-rules - 创建规则
- GET /api/tag-rules/:id - 获取规则详情
- PUT /api/tag-rules/:id - 更新规则
- DELETE /api/tag-rules/:id - 删除规则
- POST /api/tag-rules/:id/execute - 执行规则
- GET /api/tag-rules/executions - 获取规则执行历史
- GET /api/tag-rules/executions/:id - 获取规则执行详情
## 6. 后续计划
1. 实现标签规则的自动调度功能
2. 增加标签导入导出功能
3. 增加标签权限管理功能
4. 增加标签版本管理功能
5. 增加标签质量评估功能
6. 增加标签推荐功能

312
开发文档/模板使用说明书.md Normal file
View File

@@ -0,0 +1,312 @@
# 🎯 全能开发模板 - 智能开发中台 v2.0
> **核心理念**: 这不是一堆文档，而是一套 **"AI 驱动的虚拟团队"**
> **使用心法**: **"拖入即激活"** - 把文件拖入 AI 对话框，AI 瞬间变身该领域专家
> **最新技术**: 融合 DocAgent 多智能体协作 + RAG 文档检索 + 自动化工作流
> **内置 Skill**: 项目管理专家 Skill，自动管理进度、任务、对话上下文
---
## 🆕 内置项目管理 Skill
本模板内置了 **项目管理专家 Skill** (`.cursor/skills/dev-template-project-manager/`)：
```
📁 .cursor/skills/dev-template-project-manager/
├── 📄 SKILL.md ← 主技能文件（AI 自动读取）
├── 📄 workflow.md ← 工作流详解
├── 📄 templates.md ← 文档模板库
├── 📄 commands.md ← 完整指令参考
└── 📄 integration.md ← 与开发模板集成指南
```
**核心功能**：
- 📊 项目进度管理（执行表、甘特图）
- 📋 需求自动拆解为任务
- 💾 对话上下文跨会话存储
- 📝 提示词库管理
- 🔗 文档联动自动更新
**快速激活**：每次使用开发模板时，AI 会自动读取此 Skill 并激活项目管理能力。
---
## 🚀 一、极速启动 (30秒上手)
### 方式一：一键全量展开
1. 打开 `AI开发引擎.md`
2. 拖入 AI 对话框
3. 输入你的项目需求
4. AI 自动生成 1-10 全套文档
```
@AI引擎 请展开项目：
【项目名称】：私域银行 v2.0
【核心功能】：流量池管理、分润计算、一键提现
【预期规模】：日活 1 万
```
### 方式二：单目录精准展开
1. 进入对应目录（如 `4、前端`）
2. 打开 `_智能展开.md`
3. 拖入 AI 对话框
4. AI 变身该领域专家
---
## 🗂️ 二、目录全景图
```
📁 开发模板/
│
├── 📄 AI开发引擎.md ← 🧠 总控：一键展开全部
├── 📄 代码核心提取器.md ← 🔬 分析项目、提取核心、清理文件
├── 📄 模板使用说明书.md ← 📖 你正在看的这个
│
├── 📁 1、需求/ ← 💰 CFO + 产品负责人
│ ├── _智能展开.md ← 🔮 智能展开提示词
│ ├── 业务需求.md
│ ├── 技术需求.md
│ └── 成本.md
│
├── 📁 2、架构/ ← 🏗️ CTO + 架构师
│ ├── _智能展开.md
│ ├── 系统架构.md
│ └── 技术选型.md
│
├── 📁 3、原型/ ← 🎨 UI/UX 设计师
│ ├── _智能展开.md
│ └── 原型设计规范.md
│
├── 📁 4、前端/ ← ⚛️ 前端技术专家
│ ├── _智能展开.md
│ └── 前端开发规范.md
│
├── 📁 5、接口/ ← 🔌 API 架构师
│ ├── _智能展开.md
│ └── 接口定义规范.md
│
├── 📁 6、后端/ ← 🐍 Python 架构师
│ ├── _智能展开.md
│ └── 后端开发规范.md
│
├── 📁 7、数据库/ ← 💾 DBA
│ ├── _智能展开.md
│ └── 数据库管理规范.md
│
├── 📁 8、部署/ ← 🚀 DevOps 运维
│ ├── _智能展开.md
│ └── 项目程序提示词.md
│
├── 📁 9、手册/ ← 📚 技术文档专家
│ ├── _智能展开.md
│ └── 使用手册提示词.md
│
└── 📁 10、项目管理/ ← 📊 高级 PM
├── _智能展开.md
└── 项目管理提示词.md
```
---
## 🎮 三、核心操作指南
### 3.1 按场景选择入口
| 我要做什么 | 使用哪个文件 | AI 会帮我 |
|:---|:---|:---|
| **新项目启动** | `AI开发引擎.md` | 一键生成全套文档 |
| **分析现有项目** | `代码核心提取器.md` | 提取核心代码、清理无关文件 |
| **算账/定功能** | `1、需求/_智能展开.md` | 成本估算、MVP 边界 |
| **技术选型** | `2、架构/_智能展开.md` | 架构图、技术栈对比 |
| **画页面** | `3、原型/_智能展开.md` | 页面结构、iOS 规范 |
| **写前端代码** | `4、前端/_智能展开.md` | React 组件、Tailwind |
| **定义接口** | `5、接口/_智能展开.md` | API 文档、错误码 |
| **写后端代码** | `6、后端/_智能展开.md` | FastAPI、AI 集成 |
| **设计数据库** | `7、数据库/_智能展开.md` | ER 图、向量索引 |
| **部署上线** | `8、部署/_智能展开.md` | 脚本、CI/CD |
| **写用户手册** | `9、手册/_智能展开.md` | 傻瓜式文档、营销文案 |
| **管理项目** | `10、项目管理/_智能展开.md` | 甘特图、执行表 |
### 3.2 联动组合拳
不要只用一个文件，学会**组合**使用：
**场景：我要做一个 AI 客服功能**
```
第一步（定钱）: 拖入 1、需求/_智能展开.md
→ 问："加这个功能要多少 API 成本？"
第二步（定架构）: 拖入 2、架构/_智能展开.md
→ 问："用 LangChain 还是原生 API？"
第三步（定接口）: 拖入 5、接口/_智能展开.md
→ 指令："@生成接口 AI 对话模块"
第四步（落地）: 拖入 10、项目管理/_智能展开.md
→ 指令："把这个功能拆解成任务"
```
---
## 🔮 四、智能展开指令速查表
### 4.1 全局指令
| 指令 | 功能 | 在哪用 |
|:---|:---|:---|
| `@全量展开 [项目]` | 一键生成 1-10 全套文档 | AI开发引擎 |
| `@展开[N] [内容]` | 展开指定目录 | AI开发引擎 |
| `@联动更新` | 基于变更同步所有文档 | AI开发引擎 |
| `@全量分析 [路径]` | 分析项目、提取核心代码 | 代码核心提取器 |
| `@清理建议` | 生成可删除文件列表 | 代码核心提取器 |
| `@快速理解 [路径]` | 快速理解项目架构 | 代码核心提取器 |
### 4.2 各目录专属指令
| 目录 | 常用指令 |
|:---|:---|
| 1、需求 | `@拆解需求` `@用户故事` `@成本估算` `@MVP边界` |
| 2、架构 | `@技术选型` `@架构图` `@模块拆分` `@安全检查` |
| 3、原型 | `@页面结构` `@页面流程` `@iOS样式` `@骨架屏` |
| 4、前端 | `@生成页面` `@生成组件` `@生成Hook` `@样式优化` |
| 5、接口 | `@生成接口` `@接口详情` `@时序图` `@Mock数据` |
| 6、后端 | `@生成路由` `@生成服务` `@生成AI服务` `@安全检查` |
| 7、数据库 | `@生成集合` `@生成ER图` `@生成索引` `@向量配置` |
| 8、部署 | `@生成部署脚本` `@生成Nginx` `@生成Docker` |
| 9、手册 | `@生成手册` `@生成FAQ` `@生成文案` `@话术优化` |
| 10、管理 | `@拆解任务` `@更新进度` `@甘特图` `@生成复盘` |
---
## 🏛️ 五、核心规则（必读）
### 5.1 卡若风格规则
```yaml
输出风格:
语言: 大白话，直击要点
结构: 结论→原因→步骤
可视化: 必须包含 Mermaid 图表
代码: 必须中文注释
技术规范:
前端: React + Shadcn UI + Tailwind CSS + iOS 风格
后端: Python FastAPI + Type Hints + 异步优先
数据库: MongoDB 优先（含向量索引）
部署: Webhook 自动化 + 宝塔/Docker
安全红线:
禁止: 硬编码密钥、os.system()、rm -rf
强制: 参数化查询、Type Hints、骨架屏
```
### 5.2 云阿米巴商业规则
```yaml
分钱原则: 分不属于对方的钱
价值绑定: 按创造价值分钱
流量锁定: 用稳定流量 + 便捷私域体系绑定合作方
产品规则:
- 页面必须有流量入口
- 分润数据必须醒目显示
- 提现操作必须简单一键
```
---
## 🔄 六、文档自生长机制
### 6.1 更新规则
```
触发条件 → 自动更新动作
─────────────────────────
需求变更 → 更新架构、接口、前后端、执行表
接口变更 → 更新前端调用、后端实现、API 文档
数据库变更 → 更新 ER 图、后端 Model
代码完成 → 更新执行表状态为 ✅
```
### 6.2 同步指令
```
# 确定了数据库结构后
@联动 数据库→后端：基于 ER 图生成 Pydantic 模型
# 完成了后端开发后
@联动 后端→执行表：更新后端任务状态为完成
# 需求变更后
@联动 需求→全量：基于新需求更新所有相关文档
```
---
## 📊 七、权限与责任
| 目录 | 维护责任人 | 谁不能乱动 |
|:---|:---|:---|
| 1、需求 / 10、管理 | **卡若 (老板/PM)** | 开发人员（只读） |
| 2、架构 / 5、接口 | **架构师** | 非技术人员 |
| 4、前端 / 6、后端 | **对应开发** | 非本岗位人员 |
| 8、部署 | **运维/核心开发** | **所有人**（涉及密钥） |
---
## 🧠 八、最新 AI 技术融合
### 8.1 多智能体协作 (DocAgent)
本模板采用多智能体协作架构：
```
📖 Reader (需求理解) → 🔍 Searcher (上下文检索)
→ ✍️ Writer (内容生成) → ✅ Verifier (质量校验)
```
### 8.2 RAG 文档增强
- 支持 Gemini File Search 全托管 RAG
- MongoDB Atlas Vector Search 向量检索
- 自动从代码/文档/历史中提取上下文
### 8.3 自动化工作流
- GitHub Webhook 自动触发部署
- 文档变更自动同步
- 代码生成自动包含测试
---
## 💡 九、使用技巧
### 9.1 高效使用建议
1. **先读后写**: 开始新模块前，先读相关目录的现有文档
2. **指令明确**: 使用 `@指令` 格式，AI 响应更精准
3. **上下文传递**: 在复杂任务中，把前一步的输出作为下一步的输入
4. **及时更新**: 每次变更后要求 AI 同步更新相关文档
### 9.2 常见问题
| 问题 | 解决方案 |
|:---|:---|
| AI 输出不符合规范 | 明确提醒"请按照卡若风格" |
| 文档不同步 | 使用 `@联动更新` 指令 |
| 代码风格不统一 | 检查是否使用了 `_智能展开.md` |
| 缺少图表 | 明确要求"请用 Mermaid 画图" |
---
## 📞 十、联系与支持
- **问题反馈**: 微信 28533368
- **模板更新**: 关注 GitHub 仓库
- **使用交流**: 扫码加入用户群
---
> **总结**: 这套模板是你的 **"数字化外脑"**，把卡若的经验固化成 Prompt，让 AI 能随时按你的标准干活。用好它，你就是一支队伍。🚀

BIN
开发文档/神射手数据中台_PRD_V1.1_扩展版 (1).docx Normal file
View File

Binary file not shown.

141
开发文档/需求文档.md
View File

@@ -1,141 +0,0 @@
产品需求文档 (PRD): "神射手" 用户资产数字中台 V1.3
1. 项目概述
- 项目名称: "神射手" 用户资产数字中台 (对应 @神射手 项目)
- 目标: 构建一个统一、灵活、高性能的用户数据中心，汇聚来自**多个异构源系统**（如截图所示 众多数据库，以及未来可能接入的其他内外部系统）的用户相关信息，形成 360 度用户视图。该平台通过 API 服务 (api/ 目录) 赋能其他业务系统（如“存客宝”），并可能包含内置管理界面 (app/ 等目录)。
- 核心挑战: 处理源系统**数据结构差异巨大**、**字段繁多且命名不一**的问题（如 所有数据库所有字段.csv 所反映），将这些**多样化的数据**有效整合为统一的“用户资产”。
- 核心价值: 打破数据孤岛，沉淀用户资产，提升数据驱动能力。通过标准化的服务层 (services/ 目录) 和 API 接口，支持精细化运营和个性化用户分析。
2. 项目目标
- 数据汇聚: 实现对各源数据库（覆盖截图中的 MySQL 库等）及其他渠道用户数据的统一接入和存储。
- Schema 灵活性: 支持存储结构各异的数据，能动态适应不同来源、包含大量**非标准化字段**的数据。
- 高性能查询: 实现对单个用户信息的毫秒级查询响应，**即使在数据模型复杂、数据量巨大的情况下**。
- 统一用户资产视图: 将来自不同源系统、**各种不同字段**的数据，通过映射和关联，**统一成可理解、可使用的“用户资产”格式**，存储在中台数据库中。
- 快速迭代: 采用模块化架构，支持业务需求的快速变化。
- 统一服务: 提供稳定、标准的 API 接口 (api/ 路由驱动)，供内部系统调用。
- 赋能应用: 使“存客宝”等应用能利用中台数据自定义用户分群、构建流量池规则。
- 支持分析: 提供基础的用户画像分析能力，支持基于全量用户数据的查询和探索。
3. 功能需求
- 3.1 数据接入 (Ingestion)
- 数据源适配: 需要开发或配置数据同步/ETL 工具，能够连接不同的源数据库（如 MySQL）和 API，定期或实时抽取数据。
- API 端点: 提供 /api/ingest (或类似) 接口，用于接收实时推送的数据。
- 服务层处理 (**services/IngestionService**):
- 接收原始数据（包含来源 source 和 源ID source_user_id）。
- 核心步骤：数据映射与转换 - 根据预定义的 **数据字典和映射规则**（见 3.2.1），对原始数据进行初步处理：
- 识别关键字段（如姓名、手机、邮箱等）。
- 标准化某些字段值（如日期格式、地址格式）。
- 生成或关联全局唯一 userId（涉及身份识别逻辑）。
- 准备写入数据库的文档结构。
- 历史数据迁移: 需要制定计划，将源系统中的存量数据批量导入中台。
- 3.2 数据存储与结构 (Storage & Schema)
- 数据库选型: **强烈推荐文档数据库 (如 MongoDB)**。理由：其灵活的 Schema 是处理源系统字段多样性（Caihong 中众多 shua_ 表，SG_ 库中各异的结构）的最佳方式，可以直接存储源系统的原始字段结构，避免了在关系型数据库中创建超宽表或大量关联表的复杂性。
- 数据模型 (示例):
{
"userId": "global-unique-id-xyz", // 中台统一用户ID
"core_profile": { // 提取的核心/标准化字段
"name": "...",
"mobile": "...", // 脱敏存储
"email": "...",
// ... 其他核心字段
},
"unified_tags": ["高价值客户", "医疗行业", "辽宁负责人"], // 统一标签
"unified_attributes": { // 统一计算属性
"lifetime_value": 15000,
"last_active_days": 15
},
"source_profiles": [ // 存储各来源的详细档案
{
"source": "caihong_shua_users", // 来源标识 (更具体)
"source_user_id": "user_id_in_shua_users_table",
"original_data": { // 保留原始字段，无需所有字段都映射
"username": "...",
"level": 3,
"register_time": "...",
// ... shua_users 表中的所有字段
},
"ingestion_timestamp": "..."
},
{
"source": "sg_enterprise_directory",
"source_record_id": "record_id_in_sg_enterprise", // 源记录ID
// 可能基于 企业名称+负责人 关联到 userId
"original_data": {
"企业名称": "沈阳东北制药总厂",
"负责人": "张三", // 假设这个负责人也是中台的一个用户
"联系人": "李四",
"职位": "厂长",
"行政区划": "210106",
"地址": "沈阳市铁西区重工南街37号",
"区号": "024",
// ... SG_企业名录 中的所有字段
},
"ingestion_timestamp": "..."
},
// ... 其他来源 (SG_人才库, SG_投资, 抖音, 微信等)
],
"createdAt": "...", // 中台记录创建时间
"updatedAt": "..." // 中台记录更新时间
}
- 3.2.1 数据字典与映射规则:
- 核心产出: 需要基于对 所有数据库所有字段.csv 及各源系统的分析，创建一份详细的**数据字典**。
- 内容:
- 定义中台的核心字段 (core_profile) 及其含义。
- 定义统一标签 (unified_tags) 和统一属性 (unified_attributes) 的生成规则。
- 建立**源系统字段**到**中台字段（核心字段或保留在 ****original_data**** 中）的映射关系**。
- 标识出 PII（个人身份信息）字段，明确其处理方式（存储、加密、脱敏、访问控制）。
- 标识出可用于**身份识别 (Identity Resolution)** 的关键字段（如手机号、邮箱、身份证号、微信 unionid 等）。
- 实现: 映射规则可以在 services/IngestionService 中通过代码实现，或配置在外部规则引擎中。
- 3.3 数据查询 (Querying)
- API 端点 (**api/****):** 提供丰富的查询 API。
- 服务层逻辑 (**services/QueryService****):** 封装数据库查询逻辑。
- 查询能力:
- 基础查询: 按 userId, core_profile.email, core_profile.mobile 等快速获取用户。
- 关联查询: 按 source_profiles.source + source_profiles.source_user_id 查询。
- 复杂分析查询: 支持基于 core_profile, unified_tags, unified_attributes 以及 source_profiles.original_data **内部任意字段**的组合查询。例如：
- 查询 source_profiles.source 为 'sg_enterprise_directory' 且 original_data.负责人 为 '张三' 的所有用户。
- 查询 unified_tags 包含 '高价值客户' 且 source_profiles 中存在 source='caihong_shua_orders' 记录的用户。
- 性能: 必须为 userId, 核心字段, 以及 source_profiles 中经常用于查询的字段（如 source, source_user_id, original_data 内的关键业务字段）**建立数据库索引**。
- 3.4 数据服务 (API Distribution)
- (与 V1.2 类似) 提供标准 API，重点强化查询 API 的过滤能力，满足存客宝等应用需求。
- 3.5 (可能) 管理界面 (Management UI)
- (与 V1.2 类似) 提供界面用于查看统一后的用户视图、搜索用户、可能包含基础的数据质量监控。
- 3.6 与存客宝 (**cunkebao 0420**) 集成场景
- 存客宝调用中台 API，获取 **经过整合和关联的全维度用户数据**，包括核心信息、统一标签、以及来自 Caihong, SG_* 等所有源系统的详细档案信息，用于构建复杂的流量池规则和执行精准营销。
- 3.7 (重点) 身份识别与合并 (Identity Resolution)
- 必要性: 由于数据来自不同系统，必须有机制识别哪些记录属于同一个自然人。
- 策略: 需要在 services/ 中实现，基于数据字典中标识的关键字段（手机、邮箱、身份证等），采用确定性匹配（完全一致）和模糊匹配（相似度算法）相结合的方式，将不同 source_profiles 关联到同一个 userId。这是一个持续优化的过程。
- 3.8 分析支持
- 中台 API 应能支持 BI 工具或数据分析平台进行数据查询和提取。
- (可选) 提供数据导出功能，将处理整合后的用户数据导出为宽表或其他格式，供离线分析使用。
4. 非功能性需求
- (与 V1.2 类似：性能、可扩展性、灵活性、可用性)
- 4.5 安全性:
- 严禁存储明文密码或高度敏感凭证。 对于截图中可能存在的密码或敏感数据，在接入中台时必须**丢弃**或进行**不可逆的哈希处理**（如果中台需要校验密码，但这通常应由源系统或统一认证中心负责）。
- 严格遵守数据字典中定义的 PII 处理规则（加密、脱敏、访问控制）。
- API 访问控制要做到字段级别。
5. 数据库选型推荐
- 首选: **MongoDB**。其灵活的文档模型、强大的查询能力（支持嵌套文档查询和索引）、成熟的生态和良好的水平扩展性，非常适合应对当前描述的复杂数据源整合需求。
6. 开放问题与后续步骤
- 启动核心任务： **立即开始分析 ****所有数据库所有字段.csv**** 和各源数据库结构，着手制定 V1.0 的数据字典和映射规则。** 这是项目成功的关键。
- 详细设计身份识别 (Identity Resolution) 的具体算法和流程。
- 确定数据库部署方案（云服务 Atlas? 自建?）。
- 与存客宝团队详细对接 API 需求，特别是复杂查询场景。
- 确定管理界面的范围和优先级。
- 制定历史数据迁移方案和数据质量校验计划。