# simple-crm

**Repository Path**: zhbs/simple-crm

## Basic Information

- **Project Name**: simple-crm
- **Description**: 一个基于 Go + Gin + GORM + MySQL 的简单 CRM 系统，支持客户管理、合作机构管理和智能推送功能。 教育CRM（学生管理，机构管理，推荐管理），医美CRM（客户管理，机构管理，权限管理），房产中介CRM（客户管理，机构管理，地产CRM（客户管理，机构管理）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-06-24
- **Last Updated**: 2025-12-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Simple CRM 系统

一个基于 Go + Gin + GORM + MySQL 的简单 CRM 系统，支持客户管理、合作机构管理和智能推送功能。

## 功能特性

## 功能特性

<img src="./AIMG/image1.png" width="980px" alt="功能特性图">
<img src="./AIMG/image2.png" width="980px" alt="系统架构图">
<img src="./AIMG/image3.png" width="980px" alt="数据流程图">
<img src="./AIMG/image4.png" width="980px" alt="用户界面示例">
<img src="./AIMG/image5.png" width="980px" alt="用户界面示例">


## 作者信息

- 作者微信: my39622 , 18691625262 , 可提供 技术支持 
- 欢迎交流学习和项目合作


### 核心功能
- **用户认证系统**：JWT 认证、用户注册/登录/登出
- **RBAC 权限管理**：基于角色的访问控制
- **客户管理**：客户信息的增删改查、状态管理
- **合作机构管理**：机构信息管理、按城市/主题筛选
- **智能推送系统**：
  - 智能推送：基于客户信息自动匹配合适的合作机构
  - 手动推送：手动选择客户和机构进行推送
  - 批量推送：批量处理多个客户的推送
  - 推送重试：失败推送的重试机制
- **操作日志**：记录所有用户操作，便于审计
- **数据统计**：推送成功率、机构推荐等统计信息

### 技术特性
- RESTful API 设计
- 中间件支持（认证、权限、日志、CORS）
- 数据库自动迁移
- 密码加密存储
- JWT Token 刷新机制
- 分页查询支持
- 错误处理和响应统一格式

## 技术栈

- **后端框架**：Gin (Go Web Framework)
- **ORM**：GORM
- **数据库**：MySQL
- **认证**：JWT (JSON Web Token)
- **密码加密**：bcrypt
- **配置管理**：godotenv

## 项目结构

```
simple-crm/
├── main.go                 # 应用入口
├── go.mod                  # Go 模块文件
├── config/                 # 配置管理
│   ├── config.go          # 配置结构和加载
│   └── database.go        # 数据库连接和迁移
├── models/                 # 数据模型
│   ├── user.go            # 用户模型
│   ├── role.go            # 角色模型
│   ├── customer.go        # 客户模型
│   ├── partner.go         # 合作机构模型
│   ├── push_record.go     # 推送记录模型
│   └── operation_log.go   # 操作日志模型
├── controllers/            # 控制器层
│   ├── auth_controller.go # 认证控制器
│   ├── customer_controller.go # 客户管理控制器
│   ├── partner_controller.go  # 合作机构控制器
│   └── push_controller.go     # 推送管理控制器
├── services/               # 服务层
│   └── push_service.go    # 推送服务
├── middleware/             # 中间件
│   ├── auth.go            # 认证中间件
│   ├── cors.go            # CORS 中间件
│   └── logger.go          # 日志中间件
├── utils/                  # 工具函数
│   ├── jwt.go             # JWT 工具
│   ├── password.go        # 密码工具
│   └── response.go        # 响应工具
└── routes/                 # 路由配置
    └── routes.go          # 路由定义
```

## 快速开始

### 环境要求

- Go 1.21+
- MySQL 5.7+

### 安装步骤

1. **克隆项目**
```bash
git clone <repository-url>
cd simple-crm
```

2. **安装依赖**
```bash
go mod tidy
```

3. **配置环境变量**

创建 `.env` 文件：
```env
# 应用配置
APP_MODE=development
APP_PORT=8080
APP_NAME=Simple CRM

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=simple_crm

# JWT 配置
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRE_HOURS=24
```

4. **创建数据库**
```sql
CREATE DATABASE simple_crm CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

5. **运行应用**
```bash
go run main.go
```

应用将在 `http://localhost:8080` 启动。

## API 文档

### 认证相关

- `POST /api/v1/auth/register` - 用户注册
- `POST /api/v1/auth/login` - 用户登录
- `POST /api/v1/auth/logout` - 用户登出
- `POST /api/v1/auth/refresh` - 刷新 Token
- `GET /api/v1/auth/profile` - 获取用户信息

### 客户管理

- `GET /api/v1/customers` - 获取客户列表
- `GET /api/v1/customers/:id` - 获取客户详情
- `POST /api/v1/customers` - 创建客户
- `PUT /api/v1/customers/:id` - 更新客户
- `DELETE /api/v1/customers/:id` - 删除客户
- `PATCH /api/v1/customers/:id/status` - 更新客户状态

### 合作机构管理

- `GET /api/v1/partners` - 获取机构列表
- `GET /api/v1/partners/active` - 获取活跃机构
- `GET /api/v1/partners/by-city` - 按城市获取机构
- `GET /api/v1/partners/by-subject` - 按主题获取机构
- `GET /api/v1/partners/:id` - 获取机构详情
- `POST /api/v1/partners` - 创建机构
- `PUT /api/v1/partners/:id` - 更新机构
- `DELETE /api/v1/partners/:id` - 删除机构
- `PATCH /api/v1/partners/:id/status` - 更新机构状态

### 推送管理

- `POST /api/v1/push/smart` - 智能推送
- `POST /api/v1/push/manual` - 手动推送
- `POST /api/v1/push/batch` - 批量推送
- `POST /api/v1/push/retry/:id` - 重试推送
- `GET /api/v1/push/records` - 获取推送记录
- `GET /api/v1/push/records/:id` - 获取推送详情
- `GET /api/v1/push/recommended/:customer_id` - 获取推荐机构
- `GET /api/v1/push/stats` - 获取推送统计

### 健康检查

- `GET /health` - 健康检查

## 权限说明

系统采用 RBAC 权限模型，主要权限包括：

- `customer.view` - 查看客户
- `customer.create` - 创建客户
- `customer.update` - 更新客户
- `customer.delete` - 删除客户
- `partner.view` - 查看机构
- `partner.create` - 创建机构
- `partner.update` - 更新机构
- `partner.delete` - 删除机构
- `push.smart` - 智能推送
- `push.manual` - 手动推送
- `push.batch` - 批量推送
- `push.retry` - 重试推送
- `push.view` - 查看推送记录
- `push.stats` - 查看推送统计

## 开发说明

### 添加新功能

1. 在 `models/` 中定义数据模型
2. 在 `controllers/` 中实现业务逻辑
3. 在 `routes/` 中添加路由配置
4. 如需要，在 `services/` 中添加服务层逻辑
5. 在 `middleware/` 中添加必要的中间件

### 数据库迁移

系统启动时会自动执行数据库迁移，创建必要的表结构。

### 日志记录

系统会自动记录所有 API 请求和用户操作到 `operation_logs` 表中。

## 部署

### 编译

```bash
go build -o simple-crm main.go
```

### 运行

```bash
./simple-crm
```

### Docker 部署

可以创建 Dockerfile 进行容器化部署：

```dockerfile
FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY . .
RUN go mod tidy && go build -o simple-crm main.go

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/simple-crm .
CMD ["./simple-crm"]
```

## 贡献

欢迎提交 Issue 和 Pull Request 来改进项目。

## 许可证

MIT License