370 lines
10 KiB
Markdown
370 lines
10 KiB
Markdown
# 由壹点「视觉需求」系统扣分逻辑说明
|
||
|
||
## 一、当前系统扣分机制概述
|
||
|
||
系统采用**按比例扣分**的机制，扣分主要包含两部分：
|
||
1. **延误扣分** - 任务超时完成或进行中任务已超时
|
||
2. **进度未更新扣分** - 设计师未按时更新任务进度
|
||
|
||
---
|
||
|
||
## 二、延误扣分计算规则
|
||
|
||
### 1. 扣分公式
|
||
|
||
```
|
||
延误扣分 = 任务积分 × 延误工作小时数 × 扣分比例(%)
|
||
```
|
||
|
||
**重要说明：**
|
||
- **延误工作小时数**：只计算工作时间内的延误，非工作时间不计入（工作时间默认为 9:00-18:00，可在系统设置中配置）
|
||
- **扣分比例**：默认为 1%（即每延误1个工作小时，扣任务积分的1%）
|
||
- **扣分上限**：单个任务的扣分不能超过该任务的积分
|
||
|
||
### 2. 扣分比例配置
|
||
|
||
| 配置级别 | 说明 |
|
||
|---------|------|
|
||
| 默认值 | 1%（每延误1小时扣任务积分的1%）|
|
||
| 部门配置 | 可在部门目标积分设置中配置 `deductionRate` 字段 |
|
||
| 继承规则 | 三级部门继承二级部门的配置，如果二级部门未配置则使用默认值 |
|
||
|
||
### 3. 扣分场景
|
||
|
||
#### 场景A：已完成任务延误扣分
|
||
|
||
适用条件：
|
||
- 任务状态为 `completed`（已完成）
|
||
- 完成时间晚于截止时间
|
||
|
||
计算方式：
|
||
```
|
||
延误小时数 = 工作时间计算器.计算延误小时(截止时间, 实际完成时间)
|
||
扣分 = 任务积分 × 延误小时数 × 扣分比例 / 100
|
||
```
|
||
|
||
#### 场景B：进行中任务延误扣分
|
||
|
||
适用条件：
|
||
- 任务状态为 `in_progress`（进行中）
|
||
- 当前时间已超过截止时间
|
||
|
||
计算方式：
|
||
```
|
||
延误小时数 = 工作时间计算器.计算延误小时(截止时间, 当前时间)
|
||
扣分 = 任务积分 × 延误小时数 × 扣分比例 / 100
|
||
```
|
||
|
||
**注意**：进行中任务的延误扣分是**实时计算**的，会随着时间推移而增加。
|
||
|
||
### 4. 主任务与子任务扣分
|
||
|
||
系统同时计算主任务和子任务的延误扣分：
|
||
|
||
| 任务类型 | 截止时间来源 | 完成时间来源 |
|
||
|---------|-------------|-------------|
|
||
| 主任务 | `task.deadline` 字段 | `task.actualEndTime` 字段 |
|
||
| 子任务 | 根据 `createTime + estimatedHours` 计算 | `taskItem.completeTime` 字段 |
|
||
|
||
### 5. 扣分计算示例
|
||
|
||
**示例1：任务按时完成**
|
||
- 任务积分：10分
|
||
- 截止时间：2026-01-15 18:00
|
||
- 完成时间：2026-01-15 17:30
|
||
- 延误扣分：0分（未延误）
|
||
|
||
**示例2：任务延误2小时**
|
||
- 任务积分：10分
|
||
- 截止时间：2026-01-15 16:00
|
||
- 完成时间：2026-01-15 18:00
|
||
- 延误小时数：2小时（工作时间内）
|
||
- 扣分比例：1%
|
||
- 延误扣分：10 × 2 × 1% = 0.20分
|
||
|
||
**示例3：任务延误跨天**
|
||
- 任务积分：20分
|
||
- 截止时间：2026-01-15 17:00
|
||
- 完成时间：2026-01-16 11:00
|
||
- 延误工作小时数：1小时（15日17:00-18:00）+ 2小时（16日9:00-11:00）= 3小时
|
||
- 扣分比例：1%
|
||
- 延误扣分：20 × 3 × 1% = 0.60分
|
||
|
||
**示例4：延误扣分达到上限**
|
||
- 任务积分：5分
|
||
- 延误小时数：1000小时
|
||
- 理论扣分：5 × 1000 × 1% = 50分
|
||
- 实际扣分：5分（不能超过任务积分）
|
||
|
||
---
|
||
|
||
## 三、进度未更新扣分
|
||
|
||
### 1. 触发条件
|
||
|
||
- 设计师每日 17:30 后首次登录需要更新进行中任务的进度
|
||
- 如果未更新进度，系统将记录扣分
|
||
|
||
### 2. 扣分记录
|
||
|
||
- 存储在 `progress_deduction_log` 表中
|
||
- 按月汇总计入设计师的总扣分
|
||
|
||
### 3. 查询方式
|
||
|
||
```sql
|
||
SELECT SUM(deduction_amount)
|
||
FROM progress_deduction_log
|
||
WHERE user_id = ?
|
||
AND YEAR(deduction_date) = ?
|
||
AND MONTH(deduction_date) = ?
|
||
```
|
||
|
||
---
|
||
|
||
## 四、净积分计算
|
||
|
||
### 计算公式
|
||
|
||
```
|
||
总扣分 = 延误扣分 + 进度未更新扣分
|
||
净积分 = 获得积分 - 总扣分
|
||
如果净积分 < 0，则净积分 = 0
|
||
```
|
||
|
||
### 数据展示
|
||
|
||
在数据分析页面的设计师绩效排行榜中：
|
||
- **获得积分**：当月完成的所有任务（主任务+子任务）的积分总和
|
||
- **延误扣分**：当月所有任务的延误扣分总和
|
||
- **净积分**：获得积分 - 延误扣分（最小为0）
|
||
|
||
---
|
||
|
||
## 五、任务截止时间计算
|
||
|
||
### 1. 计算公式
|
||
|
||
```
|
||
截止时间 = 接单时间 + 预估工时（只计算工作时间段）
|
||
```
|
||
|
||
**核心原则**：截止时间的计算只累加工作时间段内的小时数，非工作时间（下班后、周末）自动跳过。
|
||
|
||
### 2. 计算逻辑详解
|
||
|
||
#### 步骤1：确定起始点
|
||
|
||
| 接单时间 | 起始点处理 |
|
||
|---------|-----------|
|
||
| 在工作时间内（9:00-18:00） | 从接单时间开始计算 |
|
||
| 在上班前（如 8:00） | 从当天 9:00 开始计算 |
|
||
| 在下班后（如 19:00） | 从次日 9:00 开始计算 |
|
||
|
||
#### 步骤2：累加工时
|
||
|
||
从起始点开始，逐步累加工作小时数：
|
||
1. 计算当天剩余工作时间
|
||
2. 如果当天工作时间足够，直接加上剩余工时
|
||
3. 如果当天工作时间不够，移动到下一个工作日继续累加
|
||
|
||
### 3. 计算示例
|
||
|
||
#### 示例1：当天可完成
|
||
|
||
```
|
||
接单时间：2026-01-15 10:00（周三）
|
||
预估工时：5小时
|
||
当天剩余工作时间：18:00 - 10:00 = 8小时 ✓ 足够
|
||
|
||
截止时间 = 10:00 + 5小时 = 2026-01-15 15:00
|
||
```
|
||
|
||
#### 示例2：需要跨天
|
||
|
||
```
|
||
接单时间：2026-01-15 16:00（周三）
|
||
预估工时：5小时
|
||
当天剩余工作时间：18:00 - 16:00 = 2小时 ✗ 不够
|
||
|
||
计算过程：
|
||
- 第1天（周三）：消耗 2小时，剩余 3小时
|
||
- 第2天（周四）：从 9:00 开始，消耗 3小时
|
||
|
||
截止时间 = 2026-01-16 12:00
|
||
```
|
||
|
||
#### 示例3：下班后接单
|
||
|
||
```
|
||
接单时间：2026-01-15 19:00（周三，下班后）
|
||
预估工时：3小时
|
||
|
||
计算过程：
|
||
- 起始点移动到次日 9:00
|
||
- 从 2026-01-16 09:00 开始计算
|
||
|
||
截止时间 = 2026-01-16 12:00
|
||
```
|
||
|
||
#### 示例4：跨多天
|
||
|
||
```
|
||
接单时间：2026-01-15 16:00（周三）
|
||
预估工时：12小时
|
||
当天剩余工作时间：18:00 - 16:00 = 2小时 ✗ 不够
|
||
|
||
计算过程：
|
||
- 第1天（周三）：消耗 2小时，剩余 10小时
|
||
- 第2天（周四）：消耗 9小时（9:00-18:00），剩余 1小时
|
||
- 第3天（周五）：从 9:00 开始，消耗 1小时
|
||
|
||
截止时间 = 2026-01-17 10:00（周五）
|
||
```
|
||
|
||
**注意**：当前系统按每天 9:00-18:00 计算工作时间，**周六周日也按正常工作日计算**，暂未配置节假日跳过功能。
|
||
|
||
### 4. 主任务与子任务的区别
|
||
|
||
| 任务类型 | 截止时间设置方式 | 说明 |
|
||
|---------|-----------------|------|
|
||
| 主任务 | 发布时直接设置 `deadline` | 由任务发布者手动设置 |
|
||
| 子任务 | 系统自动计算 | 接单时间 + 预估工时 |
|
||
|
||
#### 子任务截止时间触发时机
|
||
|
||
子任务的截止时间在以下场景自动计算：
|
||
1. **接单部门审核通过时** - 子任务状态变为 `in_progress`
|
||
2. **设计师接单时** - 从任务大厅抢单
|
||
|
||
### 5. 代码实现
|
||
|
||
**核心方法**：`WorkHoursCalculator.calculateDeadline()`
|
||
|
||
```java
|
||
/**
|
||
* 计算截止时间（只计算工作时间段）
|
||
* @param startTime 开始时间（接单时间）
|
||
* @param workHours 需要的工作小时数
|
||
* @return 截止时间
|
||
*/
|
||
public LocalDateTime calculateDeadline(LocalDateTime startTime, BigDecimal workHours) {
|
||
// 1. 获取工作时间配置（默认 9:00-18:00）
|
||
// 2. 如果开始时间不在工作时间内，移动到下一个工作时段
|
||
// 3. 循环累加工时，只在工作时间段内计算
|
||
// 4. 返回最终截止时间
|
||
}
|
||
```
|
||
|
||
**调用位置**：
|
||
- `TaskService.updatePipelineSubTasksForAssigned()` - 审核通过时设置
|
||
- `TaskItemService.approveTaskItemGroup()` - 指派设计师时设置
|
||
|
||
---
|
||
|
||
## 六、工作时间配置
|
||
|
||
### 1. 配置位置
|
||
|
||
系统设置 → 工作时间配置
|
||
|
||
### 2. 配置项
|
||
|
||
| 配置键 | 说明 | 默认值 |
|
||
|-------|------|--------|
|
||
| `work_hours.start_time` | 上班开始时间 | 09:00 |
|
||
| `work_hours.end_time` | 下班结束时间 | 18:00 |
|
||
|
||
### 3. 影响范围
|
||
|
||
- 任务截止时间计算
|
||
- 延误小时数计算（只计算工作时间内的延误）
|
||
- 延误扣分计算
|
||
|
||
---
|
||
|
||
## 七、代码位置参考
|
||
|
||
### 核心扣分计算
|
||
|
||
- **文件**：`backend/src/main/java/com/designhub/service/AnalyticsService.java`
|
||
- **方法**：`getDesignerPerformance()`
|
||
- **扣分比例获取**：`getDeductionRate()` 方法（第1325行）
|
||
|
||
### 工作时间计算器
|
||
|
||
- **文件**：`backend/src/main/java/com/designhub/util/WorkHoursCalculator.java`
|
||
- **截止时间计算**：`calculateDeadline()` 方法
|
||
- **延误小时计算**：`calculateDelayHours()` 方法
|
||
|
||
### 进度未更新扣分
|
||
|
||
- **记录表**：`progress_deduction_log`
|
||
- **汇总查询**：`ProgressDeductionLogMapper.sumMonthlyDeduction()`
|
||
|
||
---
|
||
|
||
## 八、扣分规则对比（历史参考）
|
||
|
||
### 当前实现（按比例扣分）
|
||
|
||
```
|
||
扣分 = 任务积分 × 延误工作小时数 × 扣分比例(1%)
|
||
扣分上限 = 任务积分
|
||
```
|
||
|
||
**优点**：
|
||
- 与任务价值挂钩，公平合理
|
||
- 扣分上限明确，不会出现扣分超过任务价值的情况
|
||
- 只计算工作时间，更加人性化
|
||
|
||
### 历史设计（按等级固定扣分，已废弃）
|
||
|
||
| 延误程度 | 延误时长 | 扣分规则 |
|
||
|---------|---------|---------|
|
||
| 轻微延误 | < 2小时 | 每小时扣2分 |
|
||
| 一般延误 | 2-8小时 | 每小时扣3分 |
|
||
| 严重延误 | 8-24小时 | 每小时扣5分 |
|
||
| 重大延误 | > 24小时 | 基础50分+每天10分 |
|
||
|
||
**注意**：此规则定义在 `DelayPenaltyService.java` 中，但**当前数据分析页面未使用**。
|
||
|
||
---
|
||
|
||
## 九、常见问题
|
||
|
||
### Q1：为什么扣分等于获得积分？
|
||
|
||
**原因**：扣分达到上限（任务积分）
|
||
|
||
**示例**：
|
||
- 任务积分：10分
|
||
- 延误100小时
|
||
- 理论扣分：10 × 100 × 1% = 10分
|
||
- 实际扣分：10分（达到上限）
|
||
|
||
### Q2：非工作时间（下班后）延误怎么计算？
|
||
|
||
**原因**：系统只计算工作时间内的延误（9:00-18:00）
|
||
|
||
**示例**：
|
||
- 截止时间：周三 17:00
|
||
- 完成时间：周四 11:00
|
||
- 延误工作小时：1小时（周三 17:00-18:00）+ 2小时（周四 9:00-11:00）= 3小时
|
||
- 晚上 18:00 到次日 9:00 的时间不计入延误
|
||
|
||
**注意**：当前系统周六周日也按正常工作日计算，暂未配置周末跳过功能。
|
||
|
||
### Q3：子任务没有设置截止时间怎么计算？
|
||
|
||
**方式**：根据子任务的创建时间 + 预估工时自动计算截止时间
|
||
|
||
```
|
||
子任务截止时间 = 创建时间 + 预估工时（按工作时间计算）
|
||
```
|
||
|
||
---
|
||
|
||
*文档更新时间：2026-01-15*
|
||
*文档版本：v2.1*
|