805 lines
23 KiB
Markdown
805 lines
23 KiB
Markdown
# 泊云智销通 CRM 系统
|
||
|
||
## 项目简介
|
||
|
||
泊云智销通是一款面向企业渠道管理的 CRM 系统，核心解决**报备冲突**与**保护期归属**问题。系统通过**唯一有效报备机制**与**自动到期释放机制**，确保同一学校的同一项目在同一时间只能被一个经销商跟进，并在保护期结束后自动释放资源，提升渠道效率与公平性。
|
||
|
||
### 核心价值
|
||
|
||
- **防撞单机制**：基于"学校+产品+项目类型"组合的唯一性校验，避免恶意抢占
|
||
- **保护期管理**：自动计算保护期，到期自动释放，无需人工干预
|
||
- **公平竞争**：防止资源长期占用，所有经销商公平竞争
|
||
- **全程可追溯**：报备记录永久保留，支持进展记录追踪
|
||
- **灵活配置**：支持手动输入学校名称，降低报备门槛
|
||
|
||
---
|
||
|
||
## 技术架构
|
||
|
||
### 后端技术栈
|
||
|
||
- **框架**: Spring Boot 2.7
|
||
- **ORM**: MyBatis
|
||
- **数据库**: MySQL 8
|
||
- **安全**: Spring Security + JWT + BCrypt
|
||
- **API 文档**: Swagger
|
||
- **构建工具**: Maven
|
||
- **定时任务**: Spring Task Scheduler
|
||
|
||
### 前端技术栈
|
||
|
||
- **框架**: Vue 3 + TypeScript
|
||
- **UI 组件**: Element Plus
|
||
- **路由**: Vue Router 4
|
||
- **状态管理**: Pinia
|
||
- **HTTP 客户端**: Axios
|
||
- **构建工具**: Vite
|
||
- **代码规范**: ESLint + Prettier
|
||
|
||
### 架构模式
|
||
|
||
- **前后端分离**: RESTful API 架构
|
||
- **MVC 分层**: Controller → Service → Mapper → Entity
|
||
- **数据库设计**: 遵循范式，合理使用索引
|
||
- **安全设计**: JWT 认证，BCrypt 密码加密
|
||
|
||
---
|
||
|
||
## 用户角色与权限
|
||
|
||
### 1. 管理员
|
||
|
||
**角色标识**: `role = 0`
|
||
|
||
**权限范围**:
|
||
- ✅ 报备管理（全部报备的查看、审核、编辑、作废）
|
||
- ✅ 经销商管理（经销商的增删改查、重置密码）
|
||
- ✅ 学校管理（查询、批量导入学校数据）
|
||
- ✅ 系统配置（保护期天数等参数配置）
|
||
- ✅ 查看所有运营数据
|
||
|
||
**主要职责**:
|
||
- 审核报备申请
|
||
- 管理经销商账号
|
||
- 配置系统参数
|
||
- 监控渠道数据
|
||
|
||
### 2. 经销商用户
|
||
|
||
**角色标识**: `role = 1`
|
||
|
||
**权限范围**:
|
||
- ✅ 查看自己的报备记录
|
||
- ✅ 提交报备申请
|
||
- ✅ 撤回待审核的报备
|
||
- ✅ 为已通过的报备添加进展记录
|
||
- ✅ 修改个人密码
|
||
|
||
**主要职责**:
|
||
- 报备意向学校项目
|
||
- 跟进保护期内的项目
|
||
- 维护进展记录
|
||
|
||
### 权限矩阵
|
||
|
||
| 功能模块 | 管理员 | 经销商 |
|
||
|---------|--------|--------|
|
||
| 报备管理 | 全部 | 自己的报备 |
|
||
| 提交报备 | ✅ | ✅ |
|
||
| 报备审核 | ✅ | ❌ |
|
||
| 报备编辑/作废 | ✅ | ❌ |
|
||
| 进展记录 | 全部 | 自己报备的进展 |
|
||
| 经销商管理 | ✅ | ❌ |
|
||
| 学校管理 | ✅ | ❌ |
|
||
| 系统配置 | ✅ | ❌ |
|
||
|
||
---
|
||
|
||
## 功能清单
|
||
|
||
### 1. 认证与授权
|
||
|
||
#### 1.1 用户登录
|
||
- **路径**: `POST /api/auth/login`
|
||
- **描述**: 用户登录系统，获取 JWT Token
|
||
- **安全**: BCrypt 加密存储
|
||
- **返回**: Token + 用户基本信息
|
||
|
||
**默认账号**:
|
||
- 管理员: `admin` / `admin123`
|
||
- 经销商用户: 根据经销商数据
|
||
|
||
#### 1.2 修改密码
|
||
- **路径**: `POST /api/auth/change-password`
|
||
- **权限**: 所有用户
|
||
- **功能**: 用户修改自己的登录密码
|
||
- **验证**: 需要输入原密码验证
|
||
|
||
#### 1.3 重置密码
|
||
- **路径**: `POST /api/auth/reset-password`
|
||
- **权限**: 仅管理员
|
||
- **功能**: 管理员重置经销商用户的密码
|
||
|
||
---
|
||
|
||
### 2. 报备管理
|
||
|
||
#### 2.1 报备列表
|
||
- **路径**: `GET /api/report/page`
|
||
- **权限**: 管理员查看全部，经销商查看自己的
|
||
- **功能**: 分页查询报备记录
|
||
- **搜索字段**: 学校名称、状态
|
||
- **状态说明**:
|
||
- `0 - 待审核`: 等待管理员审核
|
||
- `1 - 已通过`: 审核通过，保护期内
|
||
- `2 - 已驳回`: 审核未通过
|
||
- `3 - 已失效`: 保护期已过
|
||
- `4 - 已作废`: 管理员主动作废
|
||
|
||
#### 2.2 提交报备
|
||
- **路径**: `POST /api/report`
|
||
- **权限**: 经销商
|
||
- **功能**: 经销商报备意向学校项目
|
||
- **必填字段**: 学校名称、所属产品、项目类型
|
||
- **可选字段**: 报备说明
|
||
- **防撞单规则**:
|
||
- 同一学校的同一产品+项目类型组合，只能有一个有效报备
|
||
- 有效报备定义：状态为"待审核(0)"或"已通过(1)"
|
||
- 已失效、已驳回、已作废的报备不影响新报备
|
||
|
||
#### 2.3 撤回报备
|
||
- **路径**: `DELETE /api/report/{id}`
|
||
- **权限**: 报备所属经销商
|
||
- **功能**: 撤回待审核的报备申请
|
||
- **限制**: 只能撤回状态为"待审核"的报备
|
||
|
||
#### 2.4 审核报备
|
||
- **路径**: `PUT /api/report/{id}/audit`
|
||
- **权限**: 仅管理员
|
||
- **功能**: 审核报备申请
|
||
- **操作**:
|
||
- 通过：设置保护期（默认90天），状态变为"已通过"
|
||
- 驳回：填写驳回原因，状态变为"已驳回"
|
||
|
||
#### 2.5 编辑报备
|
||
- **路径**: `PUT /api/report/{id}`
|
||
- **权限**: 仅管理员
|
||
- **功能**: 编辑已通过的报备
|
||
- **可编辑字段**: 所属产品、项目类型、报备说明、状态
|
||
- **作废操作**: 状态改为"已作废"时必须填写作废原因
|
||
|
||
#### 2.6 报备详情
|
||
- **路径**: `GET /api/report/{id}`
|
||
- **权限**: 根据权限查看
|
||
- **功能**: 查看报备详细信息和进展记录
|
||
|
||
---
|
||
|
||
### 3. 进展记录管理
|
||
|
||
#### 3.1 添加进展记录
|
||
- **路径**: `POST /api/report-progress`
|
||
- **权限**: 经销商只能为自己的报备添加，管理员可查看所有
|
||
- **功能**: 为已通过的报备添加进展记录
|
||
- **限制**: 只能为状态为"已通过"的报备添加进展
|
||
|
||
#### 3.2 编辑进展记录
|
||
- **路径**: `PUT /api/report-progress/{id}`
|
||
- **权限**: 进展记录创建者
|
||
- **功能**: 修改进展记录内容
|
||
- **保留历史**: 不支持删除，确保数据完整性
|
||
|
||
---
|
||
|
||
### 4. 经销商管理
|
||
|
||
#### 4.1 经销商列表
|
||
- **路径**: `GET /api/dealer/list`
|
||
- **权限**: 仅管理员
|
||
- **功能**: 查询所有经销商信息
|
||
|
||
#### 4.2 新增经销商
|
||
- **路径**: `POST /api/dealer`
|
||
- **权限**: 仅管理员
|
||
- **必填字段**: 经销商名称、经销商账号、联系人、联系电话
|
||
- **自动创建**: 创建经销商记录的同时创建对应的登录用户
|
||
|
||
#### 4.3 编辑经销商
|
||
- **路径**: `PUT /api/dealer/{id}`
|
||
- **权限**: 仅管理员
|
||
- **功能**: 修改经销商信息
|
||
|
||
#### 4.4 删除经销商
|
||
- **路径**: `DELETE /api/dealer/{id}`
|
||
- **权限**: 仅管理员
|
||
- **功能**: 删除经销商及其关联用户
|
||
|
||
---
|
||
|
||
### 5. 学校管理
|
||
|
||
#### 5.1 学校列表
|
||
- **路径**: `GET /api/school/list`
|
||
- **权限**: 所有用户
|
||
- **功能**: 查询所有学校信息
|
||
|
||
#### 5.2 学校搜索
|
||
- **路径**: `GET /api/school/search?keyword=xxx`
|
||
- **权限**: 所有用户
|
||
- **功能**: 模糊搜索学校名称
|
||
- **应用场景**: 报备时学校名称的自动完成提示
|
||
|
||
#### 5.3 批量导入学校
|
||
- **路径**: `POST /api/school/import`
|
||
- **权限**: 仅管理员
|
||
- **功能**: 上传 Excel 文件批量导入学校数据
|
||
- **文件格式**: `.xls` 或 `.xlsx`
|
||
|
||
**学校数据结构**:
|
||
- 学校标识码（唯一）
|
||
- 学校名称
|
||
- 所在地（省份 + 城市）
|
||
|
||
---
|
||
|
||
### 6. 系统配置
|
||
|
||
#### 6.1 保护期配置
|
||
- **配置项**: `report.protect.days`
|
||
- **默认值**: `90` 天
|
||
- **说明**: 控制报备通过后的保护期时长
|
||
|
||
#### 6.2 报备冲突控制
|
||
- **配置项**: `report.allow.overlap`
|
||
- **默认值**: `false`
|
||
- **说明**: 是否允许重叠报备（仅用于测试）
|
||
- **生产环境**: 必须为 `false`
|
||
|
||
---
|
||
|
||
## 业务流程
|
||
|
||
### 报备完整生命周期
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 报备完整流程 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
|
||
1. 经销商提交报备
|
||
├─ 学校名称（可从学校库选择或手动输入）
|
||
├─ 所属产品（必填）
|
||
├─ 项目类型（必填）
|
||
├─ 报备说明（可选）
|
||
└─ 提交审核
|
||
↓
|
||
状态：待审核(0)
|
||
|
||
2. 管理员审核
|
||
├─ 通过 → 设置保护期（默认90天）
|
||
│ ├─ 报备状态：已通过(1)
|
||
│ └─ 保护期倒计时开始
|
||
│
|
||
└─ 驳回 → 填写驳回原因
|
||
└─ 报备状态：已驳回(2)
|
||
|
||
3. 保护期内
|
||
├─ 该"学校+产品+项目类型"组合被锁定
|
||
├─ 其他经销商无法报备相同组合
|
||
├─ 经销商可添加进展记录
|
||
└─ 剩余保护天数倒计时
|
||
|
||
4. 管理员操作（可选）
|
||
├─ 编辑报备：修改产品、项目类型、说明
|
||
└─ 作废报备：状态改为已作废(4)，填写原因
|
||
└─ 作废后该组合可重新报备
|
||
|
||
5. 保护期到期（定时任务）
|
||
└─ 每天凌晨1点自动执行
|
||
├─ 报备状态：已通过 → 已失效(3)
|
||
└─ 该"学校+产品+项目类型"组合可再次报备
|
||
```
|
||
|
||
### 报备状态转换规则
|
||
|
||
```
|
||
待审核(0)
|
||
↓ [管理员审核通过]
|
||
已通过(1) ←───────┐
|
||
↓ │
|
||
│ [保护期到期] │ [管理员编辑恢复]
|
||
↓ │
|
||
已失效(3) ─────────┘
|
||
|
||
待审核(0)
|
||
↓ [管理员驳回]
|
||
已驳回(2) ←─── 终态
|
||
|
||
待审核(0)
|
||
↓ [经销商撤回]
|
||
删除记录 ←─── 物理删除
|
||
|
||
已通过(1)
|
||
↓ [管理员作废]
|
||
已作废(4) ←─── 终态
|
||
```
|
||
|
||
---
|
||
|
||
## 数据库设计
|
||
|
||
### 核心表结构
|
||
|
||
#### 1. 报备表 (crm_report)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | BIGINT | 报备ID（主键） |
|
||
| dealer_id | BIGINT | 经销商ID |
|
||
| school_id | BIGINT | 学校ID（可为NULL，手动输入时为空） |
|
||
| school_name | VARCHAR(255) | 学校名称（冗余存储，方便查询） |
|
||
| product | VARCHAR(255) | 所属产品 |
|
||
| project_type | VARCHAR(255) | 项目类型 |
|
||
| description | VARCHAR(500) | 报备说明 |
|
||
| status | TINYINT | 状态：0-待审核 1-已通过 2-已驳回 3-已失效 4-已作废 |
|
||
| reject_reason | VARCHAR(255) | 驳回原因 |
|
||
| cancel_reason | VARCHAR(500) | 作废原因 |
|
||
| protect_start_date | DATE | 保护期开始日期 |
|
||
| protect_end_date | DATE | 保护期结束日期 |
|
||
| created_at | DATETIME | 创建时间 |
|
||
| updated_at | DATETIME | 更新时间 |
|
||
|
||
**索引**:
|
||
- `idx_dealer_id` - 经销商ID索引
|
||
- `idx_status` - 状态索引
|
||
- `idx_protect_end_date` - 保护期结束日期索引（定时任务使用）
|
||
|
||
#### 2. 经销商表 (crm_dealer)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | BIGINT | 经销商ID（主键） |
|
||
| name | VARCHAR(200) | 经销商名称 |
|
||
| code | VARCHAR(50) | 经销商账号（唯一） |
|
||
| contact_person | VARCHAR(50) | 联系人 |
|
||
| contact_phone | VARCHAR(20) | 联系电话 |
|
||
| email | VARCHAR(100) | 邮箱 |
|
||
| status | TINYINT | 状态：0-禁用 1-启用 |
|
||
| created_at | DATETIME | 创建时间 |
|
||
| updated_at | DATETIME | 更新时间 |
|
||
|
||
#### 3. 用户表 (crm_user)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | BIGINT | 用户ID（主键） |
|
||
| username | VARCHAR(50) | 用户名（登录账号） |
|
||
| password | VARCHAR(255) | 密码（BCrypt加密） |
|
||
| dealer_id | BIGINT | 关联经销商ID（管理员为NULL） |
|
||
| role | TINYINT | 角色：0-管理员 1-经销商用户 |
|
||
| status | TINYINT | 状态：0-禁用 1-启用 |
|
||
| created_at | DATETIME | 创建时间 |
|
||
| updated_at | DATETIME | 更新时间 |
|
||
|
||
#### 4. 学校表 (crm_school)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | BIGINT | 学校ID（主键） |
|
||
| school_code | VARCHAR(50) | 学校标识码（唯一） |
|
||
| school_name | VARCHAR(200) | 学校名称 |
|
||
| location | VARCHAR(255) | 所在地 |
|
||
| created_at | DATETIME | 创建时间 |
|
||
| updated_at | DATETIME | 更新时间 |
|
||
|
||
**索引**:
|
||
- `uk_school_code` - 学校标识码唯一索引
|
||
- `idx_school_name` - 学校名称索引
|
||
|
||
#### 5. 报备进展记录表 (crm_report_progress)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | BIGINT | 主键ID |
|
||
| report_id | BIGINT | 报备ID |
|
||
| progress_content | VARCHAR(500) | 进展内容 |
|
||
| created_by | BIGINT | 创建人ID |
|
||
| created_at | DATETIME | 创建时间 |
|
||
| updated_at | DATETIME | 更新时间 |
|
||
|
||
**索引**:
|
||
- `idx_report_id` - 报备ID索引
|
||
- `idx_created_by` - 创建人索引
|
||
|
||
#### 6. 系统配置表 (crm_system_config)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | BIGINT | 主键ID |
|
||
| config_key | VARCHAR(100) | 配置键（唯一） |
|
||
| config_value | VARCHAR(500) | 配置值 |
|
||
| config_type | VARCHAR(20) | 配置类型（string/integer/boolean） |
|
||
| is_editable | TINYINT | 是否可编辑（1-是 0-否） |
|
||
| created_at | DATETIME | 创建时间 |
|
||
| updated_at | DATETIME | 更新时间 |
|
||
|
||
---
|
||
|
||
## 定时任务
|
||
|
||
### 报备过期处理
|
||
|
||
**执行时间**: 每天凌晨 1 点
|
||
**Cron 表达式**: `0 0 1 * * ?`
|
||
|
||
**功能**:
|
||
1. 查询所有保护期已到的报备（`protect_end_date <= 今天` 且 `status = 1`）
|
||
2. 批量更新报备状态为"已失效"（`status = 3`）
|
||
3. 释放资源，允许相同"学校+产品+项目类型"组合重新报备
|
||
|
||
**核心代码**: `ReportExpireTask.java`
|
||
|
||
```java
|
||
@Scheduled(cron = "0 0 1 * * ?")
|
||
public void handleExpiredReports() {
|
||
log.info("开始处理过期报备...");
|
||
try {
|
||
reportService.handleExpiredReports();
|
||
log.info("过期报备处理完成");
|
||
} catch (Exception e) {
|
||
log.error("处理过期报备失败", e);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 防撞单机制详解
|
||
|
||
### 核心规则
|
||
|
||
**唯一性维度**: 学校 + 产品 + 项目类型
|
||
|
||
**有效报备定义**: 状态为"待审核(0)"或"已通过(1)"的报备
|
||
|
||
### 校验逻辑
|
||
|
||
```java
|
||
// 1. 如果选择了学校（有 school_id）
|
||
// 按 school_id + product + project_type 精确匹配
|
||
WHERE school_id = #{schoolId}
|
||
AND product = #{product}
|
||
AND project_type = #{projectType}
|
||
AND status IN (0, 1)
|
||
|
||
// 2. 如果手动输入学校（无 school_id）
|
||
// 按 school_name + product + project_type 匹配
|
||
WHERE school_name = #{schoolName}
|
||
AND product = #{product}
|
||
AND project_type = #{projectType}
|
||
AND status IN (0, 1)
|
||
```
|
||
|
||
### 业务意义
|
||
|
||
- **防止撞单**: 同一项目不能被多个经销商同时报备
|
||
- **公平竞争**: 保护期内锁定，到期后自动释放
|
||
- **灵活性**: 支持手动输入学校名称，降低报备门槛
|
||
|
||
---
|
||
|
||
## 学校选择机制
|
||
|
||
### 学校数据来源
|
||
|
||
学校数据存储在 `crm_school` 表中，包含：
|
||
- 学校标识码（唯一）
|
||
- 学校名称
|
||
- 所在地
|
||
|
||
### 前端交互
|
||
|
||
1. **自动完成搜索**
|
||
- 用户输入学校名称
|
||
- 前端调用 `/api/school/search?keyword=xxx` 接口
|
||
- 后端模糊匹配 `school_name`
|
||
- 返回匹配列表供用户选择
|
||
|
||
2. **手动输入**
|
||
- 用户可以直接输入学校名称
|
||
- 如果不从下拉列表选择，`school_id` 为 NULL
|
||
- `school_name` 保存用户输入的文本
|
||
- 防撞单校验时按 `school_name` 进行匹配
|
||
|
||
### 设计优势
|
||
|
||
- **降低门槛**: 学校不在库中也能报备，不影响业务
|
||
- **数据规范化**: 优先使用学校库数据，保证数据质量
|
||
- **灵活扩展**: 支持批量导入学校数据
|
||
|
||
---
|
||
|
||
## 安全机制
|
||
|
||
### 1. 认证与授权
|
||
|
||
#### JWT Token 认证
|
||
- 用户登录后获取 JWT Token
|
||
- Token 包含：用户ID、用户名、角色、经销商ID
|
||
- Token 存储在客户端 `localStorage`
|
||
- 每次请求在 Header 中携带：`Authorization: Bearer {token}`
|
||
|
||
#### 权限拦截
|
||
- 前端路由守卫：未登录重定向到登录页
|
||
- 后端拦截器：验证 Token 有效性
|
||
- 数据权限：经销商只能查看自己的报备
|
||
|
||
### 2. 密码安全
|
||
|
||
#### 密码规则
|
||
- 长度：6-20 位
|
||
- 加密：BCrypt（自动加盐）
|
||
- 修改密码：需验证原密码
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
by-crm/
|
||
├── backend/ # 后端工程
|
||
│ ├── src/main/java/com/bycrm/
|
||
│ │ ├── annotations/ # 自定义注解（权限等）
|
||
│ │ ├── common/ # 公共类（Result、Constants等）
|
||
│ │ ├── config/ # 配置类（CORS、MyBatis、Swagger等）
|
||
│ │ ├── controller/ # 控制器层
|
||
│ │ │ ├── AuthController.java
|
||
│ │ │ ├── ReportController.java
|
||
│ │ │ ├── DealerController.java
|
||
│ │ │ ├── SchoolController.java
|
||
│ │ │ └── ReportProgressController.java
|
||
│ │ ├── dto/ # 数据传输对象
|
||
│ │ ├── entity/ # 实体类
|
||
│ │ ├── exception/ # 异常处理
|
||
│ │ ├── mapper/ # MyBatis Mapper 接口
|
||
│ │ ├── service/ # 业务逻辑层
|
||
│ │ ├── task/ # 定时任务
|
||
│ │ ├── util/ # 工具类（JWT、加密等）
|
||
│ │ ├── vo/ # 视图对象
|
||
│ │ └── ByCrmApplication.java
|
||
│ ├── src/main/resources/
|
||
│ │ ├── mapper/*.xml # MyBatis SQL 映射
|
||
│ │ └── application.yml # 配置文件
|
||
│ └── pom.xml # Maven 依赖
|
||
│
|
||
├── frontend/ # 前端工程
|
||
│ ├── src/
|
||
│ │ ├── api/ # API 接口封装
|
||
│ │ ├── assets/ # 静态资源
|
||
│ │ ├── components/ # 通用组件
|
||
│ │ ├── router/ # Vue Router 配置
|
||
│ │ ├── stores/ # Pinia 状态管理
|
||
│ │ ├── types/ # TypeScript 类型定义
|
||
│ │ ├── utils/ # 工具函数（请求、加密等）
|
||
│ │ ├── views/ # 页面组件
|
||
│ │ │ ├── Login.vue # 登录页
|
||
│ │ │ ├── Layout.vue # 主布局
|
||
│ │ │ ├── Dashboard.vue # 首页
|
||
│ │ │ ├── Report.vue # 报备管理
|
||
│ │ │ └── Dealer.vue # 经销商管理
|
||
│ │ ├── App.vue # 根组件
|
||
│ │ └── main.ts # 入口文件
|
||
│ ├── vite.config.ts # Vite 配置
|
||
│ ├── package.json # 依赖配置
|
||
│ └── tsconfig.json # TS 配置
|
||
│
|
||
├── docs/ # 文档目录
|
||
│ └── README.md # 项目文档
|
||
│
|
||
└── sql/ # 数据库脚本
|
||
├── init.sql # 初始化脚本
|
||
└── *.sql # 其他 SQL 脚本
|
||
```
|
||
|
||
---
|
||
|
||
## 环境配置
|
||
|
||
### 后端配置 (application.yml)
|
||
|
||
```yaml
|
||
server:
|
||
port: 8080
|
||
|
||
spring:
|
||
datasource:
|
||
url: jdbc:mysql://localhost:3306/by_crm
|
||
username: root
|
||
password: your_password
|
||
driver-class-name: com.mysql.cj.jdbc.Driver
|
||
|
||
mybatis:
|
||
mapper-locations: classpath:mapper/*.xml
|
||
type-aliases-package: com.bycrm.entity
|
||
|
||
# JWT 配置
|
||
jwt:
|
||
secret: your-secret-key
|
||
expiration: 86400000 # 24小时（毫秒）
|
||
|
||
# 保护期配置
|
||
crm:
|
||
report:
|
||
protect-days: 90 # 保护期天数（默认90天）
|
||
allow-overlap: false # 是否允许报备重叠（测试用，生产必须false）
|
||
```
|
||
|
||
### 前端配置
|
||
|
||
```typescript
|
||
// API 基础地址
|
||
const BASE_URL = 'http://localhost:8080/api'
|
||
|
||
// Token 存储
|
||
const TOKEN_KEY = 'token'
|
||
```
|
||
|
||
---
|
||
|
||
## 部署说明
|
||
|
||
### 开发环境启动
|
||
|
||
**后端**:
|
||
```bash
|
||
cd backend
|
||
mvn spring-boot:run
|
||
# 访问: http://localhost:8080
|
||
# Swagger: http://localhost:8080/swagger-ui.html
|
||
```
|
||
|
||
**前端**:
|
||
```bash
|
||
cd frontend
|
||
pnpm install
|
||
pnpm dev
|
||
# 访问: http://localhost:5173
|
||
```
|
||
|
||
### 生产环境部署
|
||
|
||
**后端**:
|
||
```bash
|
||
# 编译打包
|
||
mvn clean package
|
||
|
||
# 运行 JAR
|
||
java -jar target/bycrm-0.0.1-SNAPSHOT.jar
|
||
```
|
||
|
||
**前端**:
|
||
```bash
|
||
# 编译打包
|
||
pnpm build
|
||
|
||
# 部署 dist 目录到 Web 服务器
|
||
```
|
||
|
||
### 数据库初始化
|
||
|
||
```bash
|
||
# 创建数据库
|
||
mysql -u root -p -e "CREATE DATABASE by_crm CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci"
|
||
|
||
# 导入初始化脚本
|
||
mysql -u root -p by_crm < sql/init.sql
|
||
```
|
||
|
||
---
|
||
|
||
## API 接口清单
|
||
|
||
### 认证接口
|
||
- `POST /api/auth/login` - 用户登录
|
||
- `GET /api/auth/user/info` - 获取当前用户信息
|
||
- `POST /api/auth/logout` - 用户退出
|
||
- `POST /api/auth/change-password` - 修改密码
|
||
- `POST /api/auth/reset-password` - 重置密码
|
||
|
||
### 报备接口
|
||
- `GET /api/report/page` - 分页查询报备
|
||
- `GET /api/report/{id}` - 获取报备详情
|
||
- `POST /api/report` - 创建报备
|
||
- `PUT /api/report/{id}` - 更新报备
|
||
- `DELETE /api/report/{id}` - 撤回报备
|
||
- `PUT /api/report/{id}/audit` - 审核报备
|
||
|
||
### 进展记录接口
|
||
- `GET /api/report-progress/list?reportId={id}` - 查询进展记录
|
||
- `POST /api/report-progress` - 添加进展记录
|
||
- `PUT /api/report-progress/{id}` - 编辑进展记录
|
||
|
||
### 经销商接口（仅管理员）
|
||
- `GET /api/dealer/list` - 查询所有经销商
|
||
- `POST /api/dealer` - 创建经销商
|
||
- `PUT /api/dealer/{id}` - 更新经销商
|
||
- `DELETE /api/dealer/{id}` - 删除经销商
|
||
|
||
### 学校接口
|
||
- `GET /api/school/list` - 查询所有学校
|
||
- `GET /api/school/search?keyword=xxx` - 搜索学校
|
||
- `POST /api/school` - 创建学校
|
||
- `POST /api/school/import` - 文件上传导入
|
||
|
||
---
|
||
|
||
## 版本历史
|
||
|
||
### v1.0.0 (当前版本)
|
||
|
||
**核心功能**:
|
||
- ✅ 报备管理（提交、审核、撤回、编辑、作废）
|
||
- ✅ 经销商管理（增删改查、重置密码）
|
||
- ✅ 学校管理（查询、搜索、导入）
|
||
- ✅ 用户认证（登录、密码管理）
|
||
- ✅ 进展记录（添加、编辑、查询）
|
||
- ✅ 自动保护期到期处理
|
||
- ✅ 防撞单机制（学校+产品+项目类型）
|
||
- ✅ 灵活的学校输入（库选择+手动输入）
|
||
|
||
**安全特性**:
|
||
- ✅ JWT Token 认证
|
||
- ✅ BCrypt 密码加密存储
|
||
- ✅ 权限注解拦截
|
||
- ✅ SQL 注入防护
|
||
- ✅ XSS 防护
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### 1. 默认账号是什么？
|
||
- 管理员账号：`admin` / `admin123`
|
||
- 经销商账号：根据经销商数据创建
|
||
|
||
### 2. 保护期可以修改吗？
|
||
- 可以，通过修改系统配置 `report.protect.days`
|
||
- 默认为 90 天，可根据业务需求调整
|
||
|
||
### 3. 同一学校项目可以同时被多个经销商报备吗？
|
||
- **不可以**，这是系统的核心规则
|
||
- 同一"学校+产品+项目类型"组合只能有一个"有效"报备
|
||
- 有效报备定义：状态为"待审核(0)"或"已通过(1)"
|
||
|
||
### 4. 保护期到期后会发生什么？
|
||
- 定时任务每天凌晨1点自动执行
|
||
- 将过期报备状态改为"已失效"
|
||
- 该"学校+产品+项目类型"组合可重新报备
|
||
|
||
### 5. 学校名称可以手动输入吗？
|
||
- 可以，支持从学校库选择或手动输入
|
||
- 从学校库选择时会保存 `school_id` 和标准学校名称
|
||
- 手动输入时 `school_id` 为 NULL，保存用户输入的文本
|
||
|
||
### 6. 报备可以作废吗？
|
||
- 可以，只有管理员可以作废已通过的报备
|
||
- 作废时必须填写作废原因
|
||
- 作废后该"学校+产品+项目类型"组合可重新报备
|
||
|
||
---
|
||
|
||
## 技术支持
|
||
|
||
### 开发团队
|
||
- 后端开发：Spring Boot + MyBatis + MySQL
|
||
- 前端开发：Vue 3 + TypeScript + Element Plus
|
||
- 项目管理：Maven + pnpm
|
||
|
||
### 联系方式
|
||
- 问题反馈：提交 Issue 到项目仓库
|
||
- 技术文档：详见 `docs/` 目录
|
||
|
||
---
|
||
|
||
**版权声明**: 本系统为企业内部使用，未经授权不得复制或传播。
|