# 🚀 客户报备管理系统 - 完整启动指南

## 📦 项目包含

1. **后端服务** (Node.js + Express + MySQL)
2. **前端界面** (React + Ant Design 5)

## ⚡ 快速启动（5步）

### 1️⃣ 安装后端依赖

```bash
# 在项目根目录
npm install
```

### 2️⃣ 配置数据库

编辑 `.env` 文件，设置MySQL密码：

```env
DB_PASSWORD=你的MySQL密码
```

### 3️⃣ 初始化数据库

```bash
npm run init-db
```

### 4️⃣ 启动后端服务

```bash
npm run dev
```

后端运行在：http://localhost:3000

### 5️⃣ 启动前端界面

打开**新的终端窗口**：

```bash
cd client
npm install
npm run dev
```

前端运行在：http://localhost:3001

## 🎯 访问系统

### 方式1：使用前端界面（推荐）

访问：**http://localhost:3001**

默认账号：
- 管理员：`admin` / `admin123`
- 销售1：`sales001` / `123456`
- 销售2：`sales002` / `123456`
- 经理：`manager001` / `123456`

### 方式2：使用简单界面

访问：http://localhost:3000

### 方式3：直接调用 API

```bash
# 登录获取 Token
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'
```

## 📁 项目结构

```
customer-crm/
├── 📁 后端 (根目录)
│   ├── src/
│   │   ├── controllers/     # 业务逻辑
│   │   ├── middleware/      # 中间件
│   │   ├── routes/          # 路由
│   │   ├── config/          # 配置
│   │   └── utils/           # 工具
│   ├── scripts/             # 数据库脚本
│   └── public/              # 静态文件
│
└── 📁 前端 (client/)
    ├── src/
    │   ├── pages/           # 页面组件
    │   ├── components/      # 公共组件
    │   └── utils/           # 工具函数
    └── package.json
```

## 🎨 功能模块

### ✅ 已实现功能

| 模块 | 功能 |
|------|------|
| 🔐 用户认证 | 登录、JWT、权限控制 |
| 📊 工作台 | 数据统计、到期提醒 |
| 👥 客户管理 | 列表、报备、查重、详情、跟进 |
| 🏊 公海池 | 客户领取、释放、筛选 |
| ✅ 审批流程 | 延期申请、协同跟进、审批处理 |
| 📈 统计报表 | 团队统计、来源分析、可视化 |
| ⏰ 自动任务 | 保护期检查、到期提醒 |

## 🔧 常用命令

### 后端命令

```bash
npm run dev          # 开发模式（热重载）
npm start            # 生产模式
npm run init-db      # 初始化数据库
npm run test-data    # 创建测试数据
npm run clean-db     # 清空数据库
```

### 前端命令

```bash
cd client
npm run dev          # 开发模式
npm run build        # 构建生产版本
npm run preview      # 预览构建结果
```

## 🎯 测试流程

### 1. 创建测试数据

```bash
npm run test-data
```

这将创建：
- ✅ 3个测试用户
- ✅ 25个测试客户（含公海池）
- ✅ 跟进记录

### 2. 测试登录

使用以下账号登录前端界面：
- 销售：`sales001` / `123456`
- 经理：`manager001` / `123456`

### 3. 测试核心功能

1. **报备客户**
   - 进入"客户管理" → "报备客户"
   - 输入客户信息
   - 查看实时查重功能

2. **查看客户列表**
   - 搜索、筛选
   - 查看客户详情
   - 添加跟进记录

3. **公海池**
   - 查看公海池客户
   - 领取客户

4. **审批流程**
   - 提交延期申请
   - 切换经理账号审批

5. **统计报表**（经理账号）
   - 查看团队统计
   - 查看来源分析

## 📊 角色权限

| 功能 | 销售 | 经理 | 总监 | 管理员 |
|------|:----:|:----:|:----:|:------:|
| 报备客户 | ✅ | ✅ | ✅ | ✅ |
| 查看自己客户 | ✅ | ✅ | ✅ | ✅ |
| 查看团队客户 | ❌ | ✅ | ✅ | ✅ |
| 领取公海客户 | ✅ | ✅ | ✅ | ✅ |
| 提交审批 | ✅ | ✅ | ✅ | ✅ |
| 审批处理 | ❌ | ✅ | ✅ | ✅ |
| 团队统计 | ❌ | ✅ | ✅ | ✅ |
| 用户管理 | ❌ | ❌ | ❌ | ✅ |

## 🐛 故障排除

### 后端启动失败

**问题1：数据库连接失败**
```
解决：检查 .env 中的数据库配置
     确保 MySQL 服务已启动
```

**问题2：端口被占用**
```bash
# 查找占用端口的进程
lsof -i :3000

# 杀死进程
kill -9 PID
```

### 前端启动失败

**问题1：依赖安装失败**
```bash
# 清理缓存重新安装
cd client
rm -rf node_modules package-lock.json
npm install
```

**问题2：API 请求失败**
```
解决：确保后端服务在 http://localhost:3000 运行
     检查浏览器控制台 Network 标签
```

### 登录问题

**Token 过期**
```
解决：清除浏览器 localStorage
     或重新登录
```

## 📱 端口说明

| 服务 | 端口 | 用途 |
|------|------|------|
| 后端 API | 3000 | 提供 RESTful API |
| 前端界面 | 3001 | React 开发服务器 |

## 🔒 安全建议

生产环境部署前，请修改：

1. **JWT Secret**
```env
JWT_SECRET=修改为强随机字符串
```

2. **数据库密码**
```env
DB_PASSWORD=使用强密码
```

3. **管理员密码**
```bash
# 首次登录后立即修改
```

## 🚀 生产部署

### 后端部署

```bash
# 使用 PM2
pm2 start src/server.js --name customer-crm
pm2 save
pm2 startup
```

### 前端部署

```bash
# 构建
cd client
npm run build

# 构建产物在 ../public/admin
# 配置 Nginx 指向该目录
```

### Nginx 配置

```nginx
server {
    listen 80;
    server_name your-domain.com;

    # 前端静态文件
    location /admin {
        root /path/to/public;
        try_files $uri $uri/ /admin/index.html;
    }

    # API 代理
    location /api {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}
```

## 📚 相关文档

- [README.md](README.md) - 完整项目文档
- [QUICKSTART.md](QUICKSTART.md) - 快速启动指南
- [INSTALL.md](INSTALL.md) - 详细安装说明
- [API_EXAMPLES.md](API_EXAMPLES.md) - API 调用示例
- [CLIENT_README.md](CLIENT_README.md) - 前端开发文档

## 🎉 开始使用

现在您可以：

1. ✅ 访问 http://localhost:3001
2. ✅ 使用 `admin` / `admin123` 登录
3. ✅ 体验完整的客户报备管理系统！

有问题随时查看文档或提交 Issue。

---

**祝您使用愉快！** 🎊