# go-bcrm

**Repository Path**: saugage/go-bcrm

## Basic Information

- **Project Name**: go-bcrm
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-10
- **Last Updated**: 2026-06-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CRM系统 - 功能详解

## 项目概述
基于 Go(Gin+GORM) + Vue3(Naive UI) + SQLite 构建的客户关系管理系统。

## 技术栈
- **后端**: Go 1.22+, Gin, GORM, SQLite, JWT认证
- **前端**: Vue 3 + TypeScript, Naive UI, Pinia, Vue Router, Axios, ECharts

## 功能模块

### 1. 公海线索
- 未分配线索池，支持搜索筛选（关键词/来源/行业）
- 线索来源：手动录入、API对接、Webhook接收
- 操作：认领、分配、新增线索、删除线索
- 批量操作：批量分配（选择多个线索分配给指定用户）
- 数据导入导出：Excel/CSV格式导入导出
- 列自定义：支持拖拽调整列顺序、显示/隐藏列，配置自动持久化到localStorage

### 2. 线索管理
- 我的线索列表，支持搜索和状态筛选
- 列表字段：联系人信息(合并)、公司信息(合并)、所属人、跟进人、标签、SOP阶段、跟进记录、商机数、创建时间、渠道、分配时间
- 操作：新建线索、删除线索、查看详情、打标(直接在列表操作)
- 批量操作：批量删除（选择多条线索一次性删除）
- 数据导入导出：Excel/CSV格式导入导出
- 线索详情：左右分栏布局（左侧档案卡片+标签+联系人信息，右侧SOP/商机/跟进记录Tab页）
- 跟进记录：电话/拜访/微信/邮件/其他，时间线展示
- SOP任务：关联标准化跟进模板，步骤进度管理
- 标签管理：支持新建标签、设置标签、移除标签
- 线索转化：转化为客户（自动创建客户记录）
- 退回公海：将线索退回公共池
- 列自定义：支持拖拽调整列顺序、显示/隐藏列，配置自动持久化到localStorage

### 3. 客户管理
- 客户列表，支持搜索/等级/状态筛选
- 列表字段：联系人信息(合并)、公司信息(合并)、所属人、跟进人、标签、等级、状态、创建时间
- 操作：新建客户、查看详情、打标(直接在列表操作)
- 客户详情：左右分栏布局（左侧客户卡片+联系人+基本信息，右侧SOP/跟进记录Tab页）
- 一客户多联系人：支持主联系人标记
- 客户等级：普通/重要/核心
- 客户状态：活跃/沉默/流失
- 标签管理：支持新建标签、设置标签、移除标签
- 列自定义：支持拖拽调整列顺序、显示/隐藏列，配置自动持久化到localStorage

### 4. 产品管理
- 产品列表，搜索/分类筛选
- 产品字段：名称、编码、价格、单位、库存、分类、状态
- 产品分类：树形结构管理

### 5. 商机管理
- 商机列表，搜索/阶段筛选
- 商机详情：阶段步骤条 + 阶段变更
- 阶段流转：初步接触 → 需求确认 → 方案报价 → 商务谈判 → 成交/失败
- 商机漏斗统计
- 列自定义：支持拖拽调整列顺序、显示/隐藏列，配置自动持久化到localStorage

### 6. 系统设置
- **基本设置**
  - 用户管理：CRUD + 角色分配 + 状态管理 + 密码重置
  - 角色管理：CRUD + 权限分配树
  - 部门管理：树形结构
- **业务设置**
  - 标签管理：CRUD + 颜色配置
  - SOP模板：标准化跟进步骤管理
- **运维设置**
  - 接口配置：API/Webhook类型，定时同步，连通性测试
  - 菜单配置：支持菜单集/内部页面/外链页面/按钮四种类型，3级菜单树
  - 参数配置：系统参数键值对
  - 操作日志：查询/筛选

## 权限体系
- 菜单权限：动态路由和菜单
- 按钮权限：v-permission指令
- 接口权限：后端中间件校验
- 数据权限：全部/本部门/本人三级

## 项目结构
```
d:\golang\
├── crm-backend/          # 后端
│   ├── cmd/server/       # 入口
│   ├── internal/         # 业务代码
│   └── migrations/       # 数据库迁移
├── crm-frontend/         # 前端
│   └── src/
│       ├── api/          # API接口
│       ├── views/        # 页面
│       ├── stores/       # 状态管理
│       └── components/   # 组件
└── crm-design.pen        # 设计稿
```

## API接口

### 公海线索接口
| 接口 | 方法 | 说明 |
|------|------|------|
| /api/v1/public-clues | GET | 获取公海线索列表 |
| /api/v1/public-clues/:id/claim | POST | 认领线索 |
| /api/v1/public-clues/:id/assign | POST | 分配线索 |
| /api/v1/public-clues/:id | DELETE | 删除线索 |
| /api/v1/public-clues/batch-assign | POST | 批量分配线索 |
| /api/v1/public-clues/import | POST | 导入线索（Excel/CSV） |
| /api/v1/public-clues/export | GET | 导出线索（Excel/CSV） |

### 线索管理接口
| 接口 | 方法 | 说明 |
|------|------|------|
| /api/v1/clues | GET | 获取线索列表 |
| /api/v1/clues | POST | 创建线索 |
| /api/v1/clues/:id | GET | 获取线索详情 |
| /api/v1/clues/:id | PUT | 更新线索 |
| /api/v1/clues/:id | DELETE | 删除线索 |
| /api/v1/clues/batch-delete | POST | 批量删除线索 |
| /api/v1/clues/import | POST | 导入线索（Excel/CSV） |
| /api/v1/clues/export | GET | 导出线索（Excel/CSV） |
| /api/v1/clues/:id/convert | POST | 转化为客户 |
| /api/v1/clues/:id/return | POST | 退回公海 |
| /api/v1/clues/:id/follow | POST | 添加跟进记录 |
| /api/v1/clues/:id/follow-records | GET | 获取跟进记录 |
| /api/v1/clues/:id/sop-tasks | GET | 获取SOP任务 |
| /api/v1/clues/sop-tasks/:taskId | PUT | 更新SOP任务状态 |

## 端口配置

| 端口 | 服务 | 说明 |
|------|------|------|
| 1234 | 前端 (Docker/nginx) | Docker 容器对外映射端口 |
| 12001 | 前端 (Vite dev) | 本地开发模式 Vite 端口 |
| 12345 | 后端 (Go API) | 后端 API 服务端口 |
| 17680 | 系统 | 系统服务端口 |

> **端口变更记录**: 前端 Docker 80→1234，前端 Vite 3000→13001→12001，后端 8080→12345（原2345因Windows保留端口冲突调整），系统 7680→17680

## 导入导出模板

### Excel/CSV导入模板格式

**公海线索导入模板：**
| 线索名称 | 公司 | 联系人 | 联系电话 | 行业 | 地址 | 备注 | 来源 |
|---------|------|--------|----------|------|------|------|------|
| 示例线索 | 示例公司 | 张三 | 13800000000 | IT | 北京市 | 备注信息 | manual |

**线索导入模板：**
| 线索名称 | 公司 | 联系人 | 联系电话 | 行业 | 地址 | 备注 | 来源 |
|---------|------|--------|----------|------|------|------|------|
| 示例线索 | 示例公司 | 张三 | 13800000000 | IT | 北京市 | 备注信息 | manual |

**说明：**
- 支持 .xlsx、.xls、.csv 格式
- 第一行为表头，从第二行开始为数据
- 必填字段：线索名称
- 可选字段：公司、联系人、联系电话、行业、地址、备注、来源
- 来源可选值：manual（手动）、api（API）、webhook（Webhook）

## 启动方式

### 方式一：使用项目脚本启动/停止

已验证脚本入口：

```bash
# 启动前后端
node start.mjs

# 停止前后端
node stop.mjs
```

Windows 也可以直接双击：

```text
start.bat
stop.bat
```

脚本行为说明：

- `start.mjs` 会先检查 `12345` 和 `12001` 端口是否被占用
- 后端只有在 `http://127.0.0.1:12345/health` 可访问后才会继续启动前端
- 前端只有在 `12001` 端口真正监听后才会判定为启动成功
- `stop.mjs` 会优先关闭脚本自己拉起的进程组，随后再次校验端口是否已经释放
- 启动日志输出到根目录的 `backend.log`、`backend_err.log`、`frontend.log`、`frontend_err.log`

前置条件：

- 已安装 `Node.js`
- 已安装 `Go`
- `crm-frontend/node_modules` 已正确安装

本次检查结果：

- `stop.mjs` 原先存在“提示已关闭但端口未释放”的问题，现已修复
- `start.mjs` 原先存在“子进程已退出仍提示启动完成”的问题，现已修复
- 当前仓库在本机环境下执行 `node start.mjs` 时，后端和前端都可能因本地环境问题启动失败，失败原因会明确写入日志

当前已确认的环境问题：

- 后端若无法绑定 `12345` 端口，会在 `backend_err.log` 中报 `listen tcp :12345: bind: operation not permitted`
- 前端当前 `node_modules` 缺少 `@rolldown/binding-darwin-arm64`，会在 `frontend_err.log` 中报原生绑定缺失，需要在 `crm-frontend` 下重新安装依赖

前端依赖异常时可执行：

```bash
cd crm-frontend
rm -rf node_modules package-lock.json
npm install
```

重新安装后再执行：

```bash
cd ..
node start.mjs
```

### 方式二：本地开发手动启动
```bash
# 后端
cd crm-backend
go run ./cmd/server

# 前端
cd crm-frontend
npm run dev -- --host 127.0.0.1
```

### 方式三：Docker Compose（需要先构建镜像或导入离线包）

**在线构建：**
```bash
# 构建镜像
docker compose build

# 启动服务
docker compose up -d
```

**离线导入（适用于内网/无网络环境）：**

1. 将 `docker-offline/` 目录和 `docker-compose.yml` 复制到目标机器
2. 导入镜像 tar 文件：
   ```bash
   # Linux/Mac
   for f in docker-offline/*.tar; do docker load -i "$f"; done

   # Windows PowerShell
   .\docker-offline\import-offline.ps1
   ```
3. 启动服务：
   ```bash
   docker compose up -d
   ```

**离线 tar 文件说明：**

| 文件 | 说明 |
|------|------|
| `crm-backend.tar` | 后端 API 镜像 |
| `crm-frontend.tar` | 前端 Nginx 镜像 |
| `nginx-latest.tar` | Nginx 基础镜像（后端运行时也依赖此镜像） |

> 首次部署必须导入全部 tar 文件，后续更新只需导入对应的服务 tar 即可。

**手动导入单个镜像：**
```bash
docker load -i docker-offline/crm-backend.tar
docker load -i docker-offline/crm-frontend.tar
docker load -i docker-offline/nginx-latest.tar
```

## 默认账户
- 用户名: admin
- 密码: 123456