# 安装指南

## 📋 前置要求

在开始安装之前，请确保您的系统已安装：

1. **Node.js** (版本 >= 14.x)
   ```bash
   node --version  # 检查版本
   ```

2. **MySQL** (版本 >= 5.7)
   ```bash
   mysql --version  # 检查版本
   ```

3. **npm** 或 **yarn**
   ```bash
   npm --version  # 检查版本
   ```

## 🚀 安装步骤

### 1. 准备项目目录

确认您在项目目录中：
```bash
cd /Users/ly/CodeBuddy/20260114134435
```

### 2. 安装依赖包

```bash
npm install
```

这将安装所有必需的 Node.js 依赖包，包括：
- express: Web 框架
- mysql2: MySQL 数据库驱动
- jsonwebtoken: JWT 认证
- bcryptjs: 密码加密
- 等等...

### 3. 配置数据库

#### 3.1 创建 MySQL 数据库

登录 MySQL：
```bash
mysql -u root -p
```

创建数据库（可选，初始化脚本会自动创建）：
```sql
CREATE DATABASE customer_crm DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
EXIT;
```

#### 3.2 配置环境变量

复制环境变量模板：
```bash
cp .env.example .env
```

编辑 `.env` 文件：
```bash
# macOS/Linux
nano .env

# 或使用其他编辑器
vim .env
code .env
```

修改以下配置：
```env
# 数据库配置（必须修改）
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=你的MySQL密码
DB_NAME=customer_crm

# JWT密钥（建议修改为随机字符串）
JWT_SECRET=your_jwt_secret_key_change_this_in_production

# 其他配置可保持默认
PORT=3000
DEFAULT_PROTECTION_DAYS=30
MAX_DAILY_LEADS=5
```

### 4. 初始化数据库

运行初始化脚本：
```bash
npm run init-db
```

此脚本将：
- ✅ 创建数据库（如果不存在）
- ✅ 创建所有必需的数据表
- ✅ 创建默认管理员账号（admin / admin123）

如果看到以下输出，说明初始化成功：
```
数据库连接成功
数据库 customer_crm 创建成功
用户表创建成功
客户报备表创建成功
...
默认管理员账号创建成功 (用户名: admin, 密码: admin123)
数据库初始化完成！
```

### 5. 创建测试数据（可选）

如果您想要一些测试数据来体验系统：
```bash
node scripts/createTestData.js
```

这将创建：
- 3个测试用户（2个销售 + 1个经理）
- 25个测试客户（20个正在跟进，5个在公海池）
- 若干跟进记录

### 6. 启动服务

开发环境（推荐，支持热重载）：
```bash
npm run dev
```

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

看到以下输出说明启动成功：
```
==================================================
客户报备管理系统 (Customer Registration CRM)
==================================================
服务器运行在: http://localhost:3000
环境: development
API 文档: http://localhost:3000/api
==================================================
定时任务已启动
- 保护期检查: 每小时执行一次
- 到期提醒: 每天 09:00 执行
```

### 7. 访问系统

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

使用默认账号登录：
- 用户名：`admin`
- 密码：`admin123`

## 🧪 测试 API

### 使用 curl 测试

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

2. 使用 Token 访问 API：
```bash
# 替换 YOUR_TOKEN 为上一步获得的 token
curl -X GET http://localhost:3000/api/stats/dashboard \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### 使用 Postman 测试

1. 导入环境变量：
   - URL: `http://localhost:3000`
   - 创建变量 `token`

2. 测试登录接口：
   - POST `/api/auth/login`
   - Body: `{"username":"admin","password":"admin123"}`
   - 保存返回的 token

3. 测试其他接口时，在 Headers 中添加：
   - Key: `Authorization`
   - Value: `Bearer {{token}}`

## 🔧 常见问题

### 问题1：数据库连接失败

**错误信息**：
```
ER_ACCESS_DENIED_ERROR: Access denied for user 'root'@'localhost'
```

**解决方案**：
- 检查 `.env` 文件中的数据库密码是否正确
- 确认 MySQL 服务已启动：`mysql.server status`
- 测试数据库连接：`mysql -u root -p`

### 问题2：端口被占用

**错误信息**：
```
Error: listen EADDRINUSE: address already in use :::3000
```

**解决方案**：
1. 更改端口：修改 `.env` 文件中的 `PORT=3000` 为其他端口
2. 或杀掉占用端口的进程：
```bash
# 查找占用端口的进程
lsof -i :3000

# 杀掉进程（替换 PID）
kill -9 PID
```

### 问题3：npm install 失败

**解决方案**：
1. 清理 npm 缓存：
```bash
npm cache clean --force
```

2. 删除 node_modules 重新安装：
```bash
rm -rf node_modules
npm install
```

3. 使用国内镜像（如果网络慢）：
```bash
npm config set registry https://registry.npmmirror.com
npm install
```

### 问题4：初始化数据库时出错

**解决方案**：
1. 确保 MySQL 用户有创建数据库的权限：
```sql
GRANT ALL PRIVILEGES ON *.* TO 'root'@'localhost';
FLUSH PRIVILEGES;
```

2. 手动创建数据库后再运行初始化脚本：
```sql
CREATE DATABASE customer_crm DEFAULT CHARACTER SET utf8mb4;
```

## 🎯 下一步

安装完成后，您可以：

1. **阅读 API 文档**：查看 `README.md` 了解所有 API 接口
2. **创建测试数据**：运行 `node scripts/createTestData.js`
3. **修改配置**：根据需要调整 `.env` 中的业务配置
4. **开始开发**：基于现有代码进行二次开发

## 📦 生产环境部署

生产环境部署建议：

1. 使用 PM2 进程管理器：
```bash
npm install -g pm2
pm2 start src/server.js --name customer-crm
pm2 save
pm2 startup
```

2. 使用 Nginx 反向代理
3. 配置 HTTPS 证书
4. 定期备份数据库
5. 设置日志轮转

详细部署指南请参考生产环境文档。

## 💬 获取帮助

如遇到问题：
1. 查看日志输出
2. 检查 `.env` 配置
3. 参考 `README.md`
4. 提交 Issue

---

**祝您安装顺利！** 🎉