# 客户报备管理系统 (Customer Registration CRM)

## 📋 项目简介

基于 Node.js + Express + MySQL 的企业级客户报备管理系统，实现标准化客户报备流程，防止销售撞单抢单，实现客户资源公司化、流程规范化、管理可视化。

### 核心功能

- ✅ **客户报备与查重** - 支持精确匹配和模糊匹配，防止重复报备
- ✅ **保护期管理** - 默认30天保护期，自动到期提醒
- ✅ **公海池管理** - 客户释放、领取，限制每日领取次数
- ✅ **审批流程** - 延期申请、强制释放、协同跟进
- ✅ **数据报表** - 个人仪表盘、团队统计、来源分析
- ✅ **角色权限** - 销售、销售经理、销售总监、系统管理员
- ✅ **自动化任务** - 定时检查保护期到期、自动提醒

## 🚀 快速开始

### 环境要求

- Node.js >= 14.x
- MySQL >= 5.7
- npm 或 yarn

### 安装步骤

1. **克隆项目**
```bash
cd /Users/ly/CodeBuddy/20260114134435
```

2. **安装依赖**
```bash
npm install
```

3. **配置环境变量**
```bash
cp .env.example .env
```

编辑 `.env` 文件，配置数据库连接信息：
```env
PORT=3000
NODE_ENV=development

DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=customer_crm

JWT_SECRET=your_jwt_secret_key_change_this_in_production
JWT_EXPIRES_IN=7d

DEFAULT_PROTECTION_DAYS=30
MAX_DAILY_LEADS=5
SIMILARITY_THRESHOLD=0.8
```

4. **初始化数据库**
```bash
npm run init-db
```

这将自动创建数据库表结构，并生成默认管理员账号：
- 用户名：`admin`
- 密码：`admin123`

5. **启动服务**

开发环境（带热重载）：
```bash
npm run dev
```

生产环境：
```bash
npm start
```

6. **访问系统**

打开浏览器访问：http://localhost:3000

API 基础路径：http://localhost:3000/api

## 📚 API 文档

### 认证接口

#### 用户登录
```http
POST /api/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin123"
}
```

响应：
```json
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "uuid",
      "username": "admin",
      "real_name": "系统管理员",
      "role": "admin"
    }
  }
}
```

#### 获取当前用户信息
```http
GET /api/auth/me
Authorization: Bearer {token}
```

### 客户管理接口

#### 客户查重
```http
GET /api/customers/check-duplicate?customer_name=测试公司
Authorization: Bearer {token}
```

#### 创建客户报备
```http
POST /api/customers
Authorization: Bearer {token}
Content-Type: application/json

{
  "customer_name": "XX有限公司",
  "industry": "互联网/软件",
  "region": "北京",
  "contact_person": "张三",
  "contact_phone": "13800138000",
  "demand_description": "需要CRM系统",
  "source": "转介绍"
}
```

#### 获取客户列表
```http
GET /api/customers?page=1&limit=20&status=following&keyword=测试
Authorization: Bearer {token}
```

参数说明：
- `page`: 页码（默认1）
- `limit`: 每页数量（默认20）
- `status`: 客户状态（following/won/lost/released）
- `keyword`: 搜索关键词

#### 获取客户详情
```http
GET /api/customers/{customer_id}
Authorization: Bearer {token}
```

#### 添加跟进记录
```http
POST /api/customers/followup
Authorization: Bearer {token}
Content-Type: application/json

{
  "customer_id": "uuid",
  "followup_type": "call",
  "content": "电话沟通，客户表示有兴趣",
  "next_plan": "下周上门拜访"
}
```

### 公海池接口

#### 获取公海池客户
```http
GET /api/pool/customers?page=1&limit=20&industry=互联网
Authorization: Bearer {token}
```

#### 领取客户
```http
POST /api/pool/claim
Authorization: Bearer {token}
Content-Type: application/json

{
  "customer_id": "uuid"
}
```

#### 释放客户到公海池
```http
POST /api/pool/release
Authorization: Bearer {token}
Content-Type: application/json

{
  "customer_id": "uuid",
  "release_reason": "客户暂无需求"
}
```

### 审批流程接口

#### 创建审批申请
```http
POST /api/approvals
Authorization: Bearer {token}
Content-Type: application/json

{
  "type": "extension",
  "customer_id": "uuid",
  "reason": "客户决策周期较长，需要延长跟进时间",
  "extension_days": 15
}
```

审批类型：
- `extension`: 延期申请
- `force_release`: 强制释放
- `collaboration`: 协同跟进

#### 获取待审批列表
```http
GET /api/approvals/pending?page=1&limit=20
Authorization: Bearer {token}
```

#### 处理审批
```http
POST /api/approvals/{approval_id}/process
Authorization: Bearer {token}
Content-Type: application/json

{
  "status": "approved",
  "result_comment": "同意延期"
}
```

### 统计报表接口

#### 个人仪表盘
```http
GET /api/stats/dashboard
Authorization: Bearer {token}
```

#### 团队统计
```http
GET /api/stats/team?start_date=2024-01-01&end_date=2024-01-31&period=day
Authorization: Bearer {token}
```

#### 客户来源分析
```http
GET /api/stats/source-analysis
Authorization: Bearer {token}
```

## 🎭 角色权限说明

### 销售（sales）
- 报备客户
- 查看和管理自己的客户
- 添加跟进记录
- 从公海池领取客户
- 提交延期申请

### 销售经理（sales_manager）
- 销售的所有权限
- 查看团队所有客户
- 审批延期申请
- 强制释放客户
- 查看团队统计报表

### 销售总监（sales_director）
- 销售经理的所有权限
- 查看部门所有客户
- 查看更高级别的统计报表

### 系统管理员（admin）
- 所有权限
- 用户管理
- 系统配置

## 🗄️ 数据库设计

### 主要数据表

- **users** - 用户表
- **customers** - 客户报备表
- **followup_records** - 跟进记录表
- **pool_claim_records** - 公海池领取记录表
- **approvals** - 审批流程表
- **operation_logs** - 操作日志表
- **attachments** - 附件表

## ⏰ 定时任务

系统包含以下自动化任务：

1. **保护期检查** - 每小时执行
   - 自动释放到期的客户到公海池

2. **到期提醒** - 每天 09:00 执行
   - 提醒3天后到期的客户
   - 提醒1天后到期的客户

## 🔒 安全性

- JWT Token 认证
- 密码 bcrypt 加密
- 角色权限控制
- 数据权限隔离
- 操作日志完整记录
- SQL 注入防护（参数化查询）

## 🛠️ 技术栈

- **后端框架**: Express.js
- **数据库**: MySQL
- **认证**: JWT (jsonwebtoken)
- **密码加密**: bcryptjs
- **定时任务**: node-cron
- **日期处理**: moment
- **字符串相似度**: string-similarity

## 📦 项目结构

```
customer-crm/
├── src/
│   ├── config/
│   │   └── database.js          # 数据库配置
│   ├── controllers/
│   │   ├── authController.js    # 认证控制器
│   │   ├── customerController.js # 客户管理控制器
│   │   ├── poolController.js    # 公海池控制器
│   │   ├── approvalController.js # 审批流程控制器
│   │   └── statsController.js   # 统计报表控制器
│   ├── middleware/
│   │   ├── auth.js              # 认证中间件
│   │   └── logger.js            # 日志中间件
│   ├── routes/
│   │   └── index.js             # 路由配置
│   ├── utils/
│   │   └── scheduler.js         # 定时任务
│   └── server.js                # 服务器入口
├── scripts/
│   └── initDatabase.js          # 数据库初始化脚本
├── public/
│   └── index.html               # 前端页面
├── package.json
├── .env.example
└── README.md
```

## 🔧 配置说明

### 业务配置

在 `.env` 文件中可配置：

- `DEFAULT_PROTECTION_DAYS`: 默认保护期天数（默认30天）
- `MAX_DAILY_LEADS`: 每日最大领取客户数（默认5个）
- `SIMILARITY_THRESHOLD`: 客户名称相似度阈值（默认0.8）

### 定时任务配置

在 `src/utils/scheduler.js` 中可修改定时任务执行时间。

## 🐛 常见问题

### 数据库连接失败
检查 `.env` 文件中的数据库配置是否正确，确保 MySQL 服务已启动。

### JWT Token 过期
重新登录获取新的 Token。

### 领取客户失败
检查是否达到每日领取上限，或客户是否已被其他人领取。

## 📝 开发计划

### 第一期（MVP）✅
- [x] 客户报备与查重
- [x] 30天保护期管理
- [x] 基础公海池
- [x] 个人客户列表
- [x] 团队报备统计

### 第二期规划
- [ ] 微信/钉钉通知集成
- [ ] 更丰富的数据报表
- [ ] 移动端 App
- [ ] 与主流 CRM 系统集成
- [ ] 客户标签系统
- [ ] 智能客户分配

## 📄 许可证

MIT License

## 👥 贡献

欢迎提交 Issue 和 Pull Request！

## 📧 联系方式

如有问题，请提交 Issue 或联系开发团队。

---

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