CodeBuddy/START_GUIDE.md

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

📦 项目包含

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

⚡ 快速启动（5步）

1️⃣ 安装后端依赖

# 在项目根目录
npm install

2️⃣ 配置数据库

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

DB_PASSWORD=你的MySQL密码

3️⃣ 初始化数据库

npm run init-db

4️⃣ 启动后端服务

npm run dev

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

5️⃣ 启动前端界面

打开新的终端窗口：

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

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

🔧 常用命令

后端命令

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

前端命令

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

🎯 测试流程

1. 创建测试数据

npm run test-data

这将创建：

• ✅ 3个测试用户
• ✅ 25个测试客户（含公海池）
• ✅ 跟进记录

2. 测试登录

使用以下账号登录前端界面：

• 销售：sales001 / 123456
• 经理：manager001 / 123456

3. 测试核心功能

1. 报备客户

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

2. 查看客户列表

   • 搜索、筛选
   • 查看客户详情
   • 添加跟进记录

3. 公海池

   • 查看公海池客户
   • 领取客户

4. 审批流程

   • 提交延期申请
   • 切换经理账号审批

5. 统计报表（经理账号）

   • 查看团队统计
   • 查看来源分析

📊 角色权限

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

🐛 故障排除

后端启动失败

问题1：数据库连接失败

解决：检查 .env 中的数据库配置
     确保 MySQL 服务已启动

问题2：端口被占用

# 查找占用端口的进程
lsof -i :3000

# 杀死进程
kill -9 PID

前端启动失败

问题1：依赖安装失败

# 清理缓存重新安装
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

   JWT_SECRET=修改为强随机字符串
   

2. 数据库密码

   DB_PASSWORD=使用强密码
   

3. 管理员密码

   # 首次登录后立即修改
   

🚀 生产部署

后端部署

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

前端部署

# 构建
cd client
npm run build

# 构建产物在 ../public/admin
# 配置 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 - 完整项目文档
• QUICKSTART.md - 快速启动指南
• INSTALL.md - 详细安装说明
• API_EXAMPLES.md - API 调用示例
• CLIENT_README.md - 前端开发文档

🎉 开始使用

现在您可以：

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

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

---

祝您使用愉快！ 🎊