# CRM 客户关系管理系统

**Repository Path**: MerlinRong/CRM

## Basic Information

- **Project Name**: CRM 客户关系管理系统
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CRM 客户关系管理系统

<p align="center">
  <b>线索获取 · 客户转化 · 销售跟进 · 合同回款 · 售后服务</b> 全流程闭环
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.12+-3776AB?logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/FastAPI-0.115+-009688?logo=fastapi&logoColor=white" alt="FastAPI">
  <img src="https://img.shields.io/badge/Vue-3.5+-4FC08D?logo=vuedotjs&logoColor=white" alt="Vue3">
  <img src="https://img.shields.io/badge/TypeScript-5.6+-3178C6?logo=typescript&logoColor=white" alt="TypeScript">
  <img src="https://img.shields.io/badge/tests-55%20passed-brightgreen" alt="tests">
</p>

一套面向中小销售团队的全生命周期 CRM 平台：销售过程可视化、客户资产数字化、业务决策数据化。采用**模块化单体**架构（DDD 分层 + 模块边界清晰），支持平滑演进为微服务。

---

## ✨ 功能特性

| 模块 | 能力 |
| :--- | :--- |
| 🔍 **线索管理** | 手工录入 / Excel 批量导入（Celery 异步，无 Broker 自动降级同步）/ 手机号+公司名双重撞单拦截（AES 盲索引 + 归一化变体识别）/ 一键转化为客户 |
| 👥 **客户管理** | 客户 360° 视图（联系人决策链 + 跟进时间轴）、公海/私海机制、掉保规则（X 天未跟进自动退回，Celery Beat 每日扫描）、离职交接转移 |
| 💼 **商机与销售漏斗** | 5 阶段状态机（禁止跳跃、输单强制归因）、阶段停留时长统计、漏斗转化率报表 |
| 📄 **报价与合同** | 产品库价格快照报价单、折扣审批流引擎（元数据驱动：折扣 >10% 触发总监审批）、电子签章集成（回调幂等） |
| 💰 **回款与发票** | 回款计划/登记、足额自动结清、逾期预警（Celery Beat）、开票申请 |
| 🎫 **服务与工单** | SLA 策略（创建即固化响应/解决时限）、超时自动升级（ETA 延时任务 + 每日兜底扫描）、知识库检索 |
| 📣 **营销管理** | 渠道/活动管理、ROI 归因链路（活动 → 线索 → 客户 → 生效合同 / 渠道成本）、沉睡客户唤醒（自动化规则 + 通知中心） |
| 📊 **数据分析** | 仪表盘核心指标、销售业绩报表、报表 CSV 异步导出（utf-8-sig，Excel 中文不乱码） |
| 🛡️ **系统与安全** | RBAC（菜单/按钮/接口三级权限）、五档数据范围（本人/本部门/下级/全公司/自定义）、审计日志（前后快照 + TraceID，只增不改）、手机号 AES-256-GCM 加密存储 |
| 🔌 **外部集成** | ERP 合同同步、电子签章回调、CTI 来电弹屏（脱敏），统一熔断器保护，未配置自动模拟模式 |
| 🔔 **消息中心** | 站内信 + 企微 Webhook 适配器（未配置降级日志）、未读角标、自动化营销通知消费 |

## 🛠️ 技术栈

**后端**：Python 3.12 · FastAPI · SQLAlchemy 2 (async) · Celery + Redis · Alembic · PyJWT + bcrypt · AES-256-GCM
**前端**：Vue 3（`<script setup>`）· TypeScript · Vite · Pinia · Element Plus · SCSS（BEM + 全局变量注入）
**基础设施**：MySQL 8 · Redis 7 · Elasticsearch 8 · MinIO · Docker/K8s (HPA)

## 🏗️ 架构总览

```
┌────────────────────────────────────────────────────┐
│  Vue3 + TS SPA（动态路由 / v-perm 按钮权限 / SCSS） │
└──────────────────────┬─────────────────────────────┘
                       │ REST /api/v1（统一信封 + TraceID）
┌──────────────────────▼─────────────────────────────┐
│  FastAPI 网关层：JWT │ RBAC │ 审计 │ 限流 │ 熔断    │
├────────────────────────────────────────────────────┤
│  应用层 → 领域层 → 基础设施层（模块化单体）          │
│  leads / accounts / sales / support / marketing    │
│  analytics / notifications / system / integrations │
└───────┬──────────────────────┬─────────────────────┘
        ▼                      ▼
  MySQL · Redis · ES       Celery（掉保/SLA/导出/营销）
  MinIO（附件/导出）        集成：ERP / 电子签章 / CTI
```

## 🚀 快速开始

### 0. 拉起中间件

```bash
docker compose -f deploy/docker-compose.dev.yml up -d
```

### 1. 后端（Python 虚拟环境 `.venv`）

```bash
cd backend

# 创建并激活虚拟环境
python -m venv .venv
.venv\Scripts\Activate.ps1        # Windows PowerShell
# source .venv/bin/activate       # Linux / macOS

pip install -r requirements-dev.txt
uvicorn app.main:app --reload     # http://127.0.0.1:8000，dev 环境自动建表+种子数据
```

### 2. 前端（Vue3 + SCSS）

```bash
cd frontend
npm install
npm run dev                       # http://localhost:5173（/api 代理到 8000）
```

### 3. 登录

| 账号 | 密码 | 说明 |
| :--- | :--- | :--- |
| `admin` | `admin123` | 开发环境种子超管（仅限开发） |

## 🧪 测试与质量

```bash
# 后端：55+ 用例（RBAC 数据范围矩阵 / 商机状态机 / 审批流 / 掉保 / 加密查重 / 熔断三态…）
cd backend && .venv\Scripts\python -m pytest -q
cd backend && ruff check . && ruff format --check .

# 前端：类型检查 + 构建 + 单测
cd frontend && npm run build && npm test

# 性能压测（SRS 4.1：1000 并发 / QPS≥2000）
locust -f backend/tests/load/locustfile.py --host http://127.0.0.1:8000
```

## 📦 部署

```bash
# 容器化（deploy/ 下含 K8s 清单：Deployment + HPA + Ingress 限流 + 探针）
docker build -f deploy/Dockerfile.backend  -t crm/backend  .
docker build -f deploy/Dockerfile.frontend -t crm/frontend .
kubectl apply -f deploy/k8s.yaml
```

生产检查清单：更换 `CRM_SECRET_KEY` / `CRM_ENCRYPT_KEY`（KMS 管理）→ Alembic 迁移建表（禁用 create_all）→ 配置 ERP/签章/企微通道。

## 📁 目录结构

```
├── backend/                  # FastAPI 后端
│   ├── app/
│   │   ├── main.py           # 应用工厂（中间件/异常/路由）
│   │   ├── core/             # 配置/DB/安全/RBAC/审计/熔断/中间件
│   │   ├── modules/          # 业务模块（router→service→models）
│   │   │   ├── system/       # 用户/角色/权限/部门/字典/审计
│   │   │   ├── customers/    # 线索/客户/公海/联系人/跟进
│   │   │   ├── sales/        # 商机/报价/合同/审批/回款
│   │   │   ├── support/      # 工单/SLA/知识库
│   │   │   ├── marketing/    # 渠道/活动/ROI/自动化
│   │   │   └── analytics/    # 仪表盘/报表/导出
│   │   ├── integrations/     # ERP/电子签章/CTI 适配器（熔断）
│   │   └── tasks/            # Celery 定时与异步任务
│   ├── alembic/              # 数据库迁移
│   └── tests/                # pytest（单元/接口/压测）
├── frontend/                 # Vue3 + TS + SCSS 前端
│   └── src/
│       ├── api/              # Axios 封装（幂等键/401 静默续期）
│       ├── modules & views/  # 业务页面
│       ├── components/       # DynamicForm 动态表单渲染器
│       ├── directives/       # v-perm 按钮权限
│       └── styles/           # SCSS 变量/混入/层级管理
├── deploy/                   # docker-compose / Dockerfile / k8s / nginx
└── .github/workflows/        # CI（lint + test + build 门禁）
```

## 📚 文档

完整设计文档位于 `.codebuddy/docs/`：

- 《需求规格说明书 (SRS)》— 功能与非功能需求基线
- 《系统架构设计文档 (SAD)》— 总体设计 + 详细设计（领域模型/表结构/API/时序）
- 《编码实现方案》— 环境规范/编码规范/迭代计划/DoD

## 📄 License

[MIT](LICENSE)