# 存客宝（Cunkebao）项目分析报告

## 📋 项目概述

**项目名称**: 存客宝管理系统
**版本**: 3.0.0
**技术栈**: React 18 + TypeScript + Vite + Zustand + Ant Design Mobile
**项目类型**: 移动端微信营销管理系统（PWA应用）

## 🏗️ 技术架构

### 核心技术栈

- **前端框架**: React 18.2.0
- **开发语言**: TypeScript 5.4.5
- **构建工具**: Vite 7.0.5
- **状态管理**: Zustand 5.0.6
- **路由管理**: React Router DOM 6.20.0
- **UI组件库**:
  - Ant Design Mobile 5.39.1（移动端）
  - Ant Design 5.13.1（部分桌面端组件）
- **HTTP客户端**: Axios 1.6.7
- **图表库**: ECharts 5.6.0 + echarts-for-react
- **样式方案**: SCSS + PostCSS (px转rem)
- **工具库**:
  - dayjs（日期处理）
  - crypto-js（加密）
  - react-window（虚拟列表）

### 项目结构

```
Cunkebao/
├── src/
│   ├── api/              # API请求封装
│   │   ├── request.ts    # 主请求封装（带防抖、拦截器）
│   │   ├── request2.ts   # 备用请求封装
│   │   └── common.ts    # 通用API
│   ├── components/       # 公共组件库
│   │   ├── Layout/      # 布局组件
│   │   ├── Upload/      # 文件上传组件（图片、视频、音频等）
│   │   ├── Selection/   # 选择器组件（账号、设备、群组、好友等）
│   │   ├── InfiniteList/# 无限滚动列表
│   │   └── ...
│   ├── pages/           # 页面组件
│   │   ├── mobile/      # 移动端页面
│   │   │   ├── home/    # 首页
│   │   │   ├── workspace/# 工作台（核心业务）
│   │   │   ├── scenarios/# 场景管理
│   │   │   ├── mine/    # 我的（个人中心）
│   │   │   └── test/    # 测试页面
│   │   ├── login/       # 登录页
│   │   ├── guide/       # 设备绑定引导
│   │   └── iframe/      # 内嵌页面
│   ├── router/          # 路由配置
│   │   ├── config.ts    # 路由配置和权限定义
│   │   ├── index.tsx    # 路由主入口
│   │   └── module/      # 模块化路由
│   ├── store/           # 状态管理
│   │   ├── module/      # Store模块（user, app, settings）
│   │   ├── createPersistStore.ts # 持久化Store创建器
│   │   └── persistUtils.ts # 持久化工具
│   ├── utils/           # 工具函数
│   │   ├── apiUrl.ts    # API地址配置
│   │   ├── common.ts    # 通用工具
│   │   ├── env.ts       # 环境变量
│   │   └── ...
│   └── styles/          # 全局样式
├── public/              # 静态资源
├── vite.config.ts       # Vite配置
└── package.json         # 项目依赖
```

## 🎯 核心业务功能

### 1. 工作台（Workspace）- 核心营销功能

#### 1.1 群发推送（Group Push）
- **功能**: 批量向微信群发送消息
- **特性**:
  - 支持选择设备、群组、内容
  - 任务列表管理（查看、编辑、删除、复制、启用/禁用）
  - 任务详情查看

#### 1.2 自动建群（Group Create）
- **功能**: 自动化创建微信群
- **特性**:
  - 设备选择
  - 流量池选择
  - 群主/管理员设置
  - 群组列表管理

#### 1.3 自动点赞（Auto Like）
- **功能**: 自动点赞朋友圈
- **特性**:
  - 任务创建和管理
  - 执行记录查看

#### 1.4 朋友圈同步（Moments Sync）
- **功能**: 同步朋友圈内容
- **特性**:
  - 任务创建
  - 同步记录管理

#### 1.5 自动拉群（Auto Group）
- **功能**: 自动将用户拉入群组
- **特性**:
  - 设备选择
  - 流量池选择
  - 群组配置

#### 1.6 流量分发（Traffic Distribution）
- **功能**: 智能分配用户流量
- **特性**:
  - 渠道管理
  - 分发规则配置
  - 分发记录查看

#### 1.7 AI助手（AI Assistant）
- **功能**: AI智能营销助手
- **特性**:
  - AI知识库管理
  - 智能分析和推荐

### 2. 场景管理（Scenarios）

#### 2.1 场景列表
- 展示所有营销场景

#### 2.2 计划管理（Plan）
- **功能**: 创建和管理营销计划
- **特性**:
  - 多步骤表单（基础设置、消息设置、好友设置、群组设置、分发设置）
  - 计划列表查看
  - 计划详情和编辑

### 3. 我的（Mine）- 个人中心

#### 3.1 设备管理
- 微信设备绑定和管理
- 设备状态监控

#### 3.2 微信号管理
- 微信账号管理
- 账号状态查看

#### 3.3 流量池管理（Traffic Pool）
- **功能**: 用户群体管理
- **特性**:
  - 流量池创建（基本信息、人群筛选、用户列表）
  - RFM分析
  - 标签筛选
  - 自定义条件
  - 方案推荐

#### 3.4 内容管理（Content）
- **功能**: 营销内容库
- **特性**:
  - 内容创建和编辑
  - 素材管理（图片、视频、文字等）

#### 3.5 设置
- 账户设置
- 安全设置
- 应用设置
- 关于页面

## 🔐 权限管理

### 路由权限系统

项目实现了基于角色的权限控制（RBAC）：

- **管理员（admin）**: 拥有所有路由访问权限
- **普通用户（user）**: 基础功能访问权限
- **访客（guest）**: 仅登录页访问权限

权限检查通过 `PermissionRoute` 组件实现，支持：
- 路由级别的权限控制
- 动态参数路由匹配
- 自动重定向到登录页

## 📦 状态管理

### Zustand Store架构

项目使用 Zustand 进行状态管理，并实现了完整的持久化功能：

#### 1. User Store (`user.ts`)
- **存储内容**: 用户信息、登录状态、token
- **持久化**: localStorage
- **功能**: 登录、登出、用户信息管理

#### 2. App Store (`app.ts`)
- **存储内容**: 应用状态、主题、调试模式
- **持久化**: localStorage

#### 3. Settings Store (`settings.ts`)
- **存储内容**: 应用设置、语言、时区
- **持久化**: localStorage

### 持久化特性

- ✅ 数据压缩
- ✅ 数据加密
- ✅ TTL支持（自动过期）
- ✅ 批量操作
- ✅ 存储监控
- ✅ 数据迁移
- ✅ 备份恢复

## 🌐 API架构

### 请求封装特点

1. **统一拦截器**:
   - 请求拦截：自动添加Authorization token
   - 响应拦截：统一错误处理和401跳转

2. **防抖机制**:
   - 默认1秒防抖间隔
   - 可自定义防抖时间
   - 防止重复请求

3. **错误处理**:
   - 统一Toast提示
   - 401自动跳转登录
   - 网络异常处理

## 🎨 UI/UX设计

### 设计特点

1. **移动端优先**: 使用 Ant Design Mobile 组件库
2. **响应式设计**: 支持不同屏幕尺寸
3. **PWA支持**: 可安装为移动应用
4. **主题定制**: 支持主题切换
5. **虚拟列表**: 使用 react-window 优化长列表性能

### 组件库

- **选择器组件**: 账号、设备、群组、好友、内容、流量池选择
- **上传组件**: 图片、视频、音频、文件上传
- **布局组件**: 固定布局、导航栏、底部栏
- **图表组件**: ECharts集成

## 🔧 开发工具链

### 代码质量

- **ESLint**: 代码检查
- **Prettier**: 代码格式化
- **TypeScript**: 类型安全

### 构建优化

- **代码分割**:
  - vendor（React核心）
  - ui（UI组件库）
  - utils（工具库）
  - charts（图表库）
- **压缩**: esbuild压缩
- **源码映射**: 生产环境关闭

### 开发体验

- **热更新**: Vite HMR
- **路径别名**: `@/` 指向 `src/`
- **环境变量**: 支持 `.env` 配置

## 📱 PWA特性

- **Manifest配置**: 支持安装为移动应用
- **Service Worker**: 离线支持（通过vite-pwa）
- **更新通知**: `UpdateNotification` 组件

## 🔍 项目特点

### 优势

1. ✅ **模块化架构**: 清晰的目录结构和组件划分
2. ✅ **类型安全**: 完整的TypeScript支持
3. ✅ **状态管理**: Zustand + 持久化，轻量高效
4. ✅ **权限系统**: 完善的RBAC权限控制
5. ✅ **组件复用**: 丰富的公共组件库
6. ✅ **性能优化**: 代码分割、虚拟列表、防抖节流
7. ✅ **移动端优化**: PWA支持、响应式设计

### 可改进点

1. ⚠️ **测试覆盖**: 缺少单元测试和集成测试
2. ⚠️ **文档完善**: 部分模块缺少详细文档
3. ⚠️ **错误边界**: React错误边界处理可以加强
4. ⚠️ **国际化**: 目前仅支持中文，可扩展i18n

## 📊 代码统计

- **页面数量**: 20+ 个主要页面
- **组件数量**: 30+ 个公共组件
- **路由数量**: 50+ 个路由配置
- **Store模块**: 3个核心Store

## 🚀 部署配置

- **构建命令**: `pnpm build`
- **预览命令**: `pnpm preview`
- **开发服务器**: `pnpm dev` (端口3000)
- **输出目录**: `dist/`
- **宝塔面板（静态发布脚本 `master.py`）**
  - **默认面板主机（最新）**: `43.139.27.93`；未设置 `BT_PANEL_URL` 时默认访问 `https://43.139.27.93:9988`
  - **默认站点根目录**: `/www/wwwroot/auto-devlop/ckb-operation`（可用环境变量 `DEPLOY_BASE_PATH` / `DEPLOY_BASE_PATH_PROD` / `DEPLOY_BASE_PATH_DEV` 覆盖）
  - **常用环境变量**: `BT_PANEL_URL`、`BT_API_KEY`、`DEPLOY_HOST`（覆盖默认 IP）、`BT_UPLOAD_CHUNK_MB`（上传分块，默认 4MB）

## 📝 总结

存客宝是一个功能完善的微信营销管理系统，主要面向移动端用户。项目采用现代化的技术栈，架构清晰，代码组织良好。核心功能包括：

1. **自动化营销**: 群发、建群、点赞、朋友圈同步等
2. **流量管理**: 流量池、流量分发、用户筛选
3. **内容管理**: 内容库、素材管理
4. **设备管理**: 微信设备绑定和监控
5. **AI辅助**: AI助手和知识库

项目整体质量较高，具有良好的可维护性和扩展性。适合作为企业级微信营销管理平台使用。
