125 lines
5.4 KiB
Markdown
125 lines
5.4 KiB
Markdown
- # CLAUDE.md
|
||
|
||
此文件为 Claude Code (claude.ai/code) 在此仓库中工作时提供指导。
|
||
|
||
## 项目名称
|
||
经销商管理系统
|
||
|
||
## 项目概述
|
||
经销商管理系统是一款面向企业渠道管理的CRM系统，核心解决“客户报备冲突”与“保护期归属”问题。系统通过**唯一有效报备机制**与**自动到期释放机制**，确保同一客户在同一时间只能被一个经销商跟进，并在保护期结束后自动回归可报备池，避免长期占坑，提升渠道效率与公平性。
|
||
|
||
## 技术栈
|
||
- 前端：Vue 3 + TypeScript + Vite + Element Plus
|
||
- 后端：Spring Boot 2.7 + MyBatis + MySQL 8
|
||
- 架构模式：前后端分离，MVC 分层
|
||
- 构建工具：Maven（后端）、pnpm（前端）
|
||
- 代码规范：ESLint + Prettier（前端）、SpotBugs + Checkstyle（后端）
|
||
|
||
## 项目结构
|
||
```
|
||
by-crm/
|
||
├── backend/ # Spring Boot 工程
|
||
│ ├── src/main/com/bycrm/
|
||
│ │ ├── controller/ # Web 层，RESTful API
|
||
│ │ ├── service/ # 业务层
|
||
│ │ ├── mapper/ # MyBatis DAO
|
||
│ │ ├── entity/ # PO / DTO / VO
|
||
│ │ ├── config/ # 跨域、MyBatis、Swagger 等配置
|
||
│ │ └── ByCrmApplication.java
|
||
│ ├── src/main/resources/
|
||
│ │ ├── mapper/*.xml # SQL 映射
|
||
│ │ └── application.yml # 数据源、MyBatis、JWT、有效期等配置
|
||
│ └── pom.xml
|
||
├── frontend/ # Vue 3 工程
|
||
│ ├── src/
|
||
│ │ ├── api/ # 接口封装（axios）
|
||
│ │ ├── views/ # 页面级组件
|
||
│ │ ├── components/ # 通用组件
|
||
│ │ ├── router/ # Vue Router
|
||
│ │ ├── stores/ # Pinia 状态
|
||
│ │ ├── types/ # TypeScript 类型
|
||
│ │ └── utils/ # 权限、请求拦截、日期格式化
|
||
│ ├── vite.config.ts
|
||
│ └── package.json
|
||
├── sql/
|
||
│ └── init.sql # 客户表、报备表、经销商表、字典表
|
||
└── docs/
|
||
└── api.md # Swagger 导出文档
|
||
```
|
||
|
||
## 开发命令
|
||
### 后端
|
||
```bash
|
||
cd backend
|
||
mvn spring-boot:run # 本地启动（端口 8080）
|
||
mvn test # 单元测试
|
||
mvn spotbugs:check # 静态检查
|
||
```
|
||
|
||
### 前端
|
||
```bash
|
||
cd frontend
|
||
pnpm install
|
||
pnpm dev # 本地启动（端口 5173）
|
||
pnpm build # 生成 dist
|
||
pnpm lint # ESLint 检查
|
||
```
|
||
|
||
## 核心业务流程（供编码时参考）
|
||
1. 客户唯一性校验：新建客户时先模糊匹配名称，命中则禁止重复创建。
|
||
2. 报备申请：经销商选择客户 → 填写简要说明 → 提交。
|
||
3. 防撞单：提交瞬间校验该客户是否已存在“有效”报备，存在则直接提示冲突。
|
||
4. 审核：管理员在后台查看待审核列表 → 通过（生成保护期）/ 驳回（填写原因）。
|
||
5. 保护期：通过后自动计算到期日（默认 90 天，可配置），到期凌晨定时任务将状态置为“已失效”，客户重新变为“可报备”。
|
||
6. 数据可见性：经销商仅看“自己的客户 + 自己的报备”；管理员可看全部。
|
||
|
||
## 关键配置项
|
||
- `application.yml` 中的 `crm.report.ttl-days` 控制保护期天数。
|
||
- `crm.report.allow-overlap` 仅用于测试开关，生产必须保持 false。
|
||
- Vue 全局拦截器统一注入 JWT（登录后返回），权限粒度到按钮级。
|
||
|
||
## 数据库命名规范
|
||
- 表名：全小写，下划线分割，如 `customer`, `report`, `dealer`,以 `crm_` 开头。
|
||
- 字段：全小写，下划线，主键 `id`，不需要外键，外键由程序控制，时间 `created_at`, `updated_at`。
|
||
- 字典：使用 `tinyint` 并配套枚举类，如 `customer_status` 0-可报备 1-保护中。
|
||
|
||
## 后续迭代方向
|
||
- 微信小程序端提交报备
|
||
- 客户公海池与主动分配
|
||
- 报备延期申请流程
|
||
- 报表：经销商活跃度、客户转化率
|
||
|
||
## API 接口说明
|
||
### 认证接口
|
||
- POST `/api/auth/login` - 用户登录
|
||
- GET `/api/auth/user/info` - 获取当前用户信息
|
||
- POST `/api/auth/logout` - 用户退出
|
||
|
||
### 客户接口
|
||
- GET `/api/customer/page` - 分页查询客户
|
||
- GET `/api/customer/{id}` - 获取客户详情
|
||
- POST `/api/customer` - 创建客户
|
||
- PUT `/api/customer/{id}` - 更新客户
|
||
- DELETE `/api/customer/{id}` - 删除客户
|
||
- GET `/api/customer/search` - 搜索客户（用于客户唯一性校验）
|
||
|
||
### 报备接口
|
||
- GET `/api/report/page` - 分页查询报备
|
||
- GET `/api/report/{id}` - 获取报备详情
|
||
- POST `/api/report` - 创建报备
|
||
- PUT `/api/report/{id}/audit` - 审核报备
|
||
- DELETE `/api/report/{id}` - 撤回报备
|
||
|
||
### 经销商接口（仅管理员）
|
||
- GET `/api/dealer/list` - 查询所有经销商
|
||
- GET `/api/dealer/{id}` - 获取经销商详情
|
||
- POST `/api/dealer` - 创建经销商
|
||
- PUT `/api/dealer/{id}` - 更新经销商
|
||
- DELETE `/api/dealer/{id}` - 删除经销商
|
||
|
||
## 默认测试账号
|
||
- 管理员：`admin` / `admin123`
|
||
- 经销商用户1：`user001` / `admin123`
|
||
- 经销商用户2：`user002` / `admin123`
|
||
- 经销商用户3：`user003` / `admin123`
|