# 首页质量类查询修复与优化前端联调文档

> 修复 `home` 模块下质量类接口的若干问题，并优化查询性能。
> 本次改动**只涉及响应数值**，**接口路径、请求参数、响应字段名均未变化**。

## 涉及页面

- 首页 / 数据看板 - 质量分析模块
- 首页 / 数据看板 - 质量检验数量卡片
- 首页 / 数据看板 - 不合格预警
- 首页 / 数据看板 - 完成检验数趋势
- 首页 / 数据看板 - 不合格产品排名
- 首页 / 数据看板 - 原材料/过程/出厂检测合格率
- 首页 / 数据看板 - 质量统计 (周/月/季)
- 质量管理 - 检验单新增/编辑页 (检验规则字段)

## 受影响接口一览

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /home/qualityInspectionCount | 质量检验数量 (语义有变更) |
| GET | /home/nonComplianceWarning | 近七天不合格预警 |
| GET | /home/completedInspectionCount | 近七天完成检验数 |
| GET | /home/unqualifiedProductRanking | 不合格产品排名 (口径变更) |
| GET | /home/rawMaterialDetection | 原材料检测合格率 |
| GET | /home/processDetection | 过程检测合格率 |
| GET | /home/factoryDetection | 出厂检测合格率 |
| GET | /home/qualityInspectionStatistics | 质量统计 (周/月/季) |
| POST | /qualityInspect | 新增检验单 (inspectRule 默认值逻辑) |

## 一、`/home/qualityInspectionCount` (语义变更，前端需关注)

### 变更原因

- 原实现把全表加载到内存进行求和，且 `totalCountGrowthRate` 用 *截止今日累计 vs 截止昨日累计* 计算，得到的实质是 `today_only / yesterday_cumulative`，无业务意义。
- 原实现对 `checkTime` 用 `eq(checkTime, "yyyy-MM-dd")`，若数据库 `check_time` 含非 0 时分秒会全部漏匹配，导致 `todayPendingCount`/`todayCompletedCount` 偶发为 0。

### 新口径

| 字段 | 旧口径 | 新口径 |
|------|--------|--------|
| `totalCount` | 截止今日所有 `quantity` 累加 | 不变，仍是历史累计 (改用 SQL `SUM` 聚合) |
| `totalCountGrowthRate` | (今日累计 - 昨日累计) / 昨日累计 × 100 | **(今日单日量 - 昨日单日量) / 昨日单日量 × 100** |
| `todayPendingCount` | `inspect_state=0` 且 `check_time = 今天 00:00:00` | `inspect_state=0` 且 `check_time` ∈ \[今天 00:00, 明天 00:00) |
| `todayPendingCountGrowthRate` | (今日待完成 - 昨日待完成) / 昨日待完成 × 100 | 不变，但分子分母都是真正"当日量" |
| `todayCompletedCount` | 同上 | 同上 |
| `todayCompletedCountGrowthRate` | 同上 | 同上 |

### 响应示例

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "totalCount": 12345.00,
    "totalCountGrowthRate": 8.50,
    "todayPendingCount": 12.00,
    "todayPendingCountGrowthRate": -20.00,
    "todayCompletedCount": 80.00,
    "todayCompletedCountGrowthRate": 15.50
  }
}
```

### 前端修改点

`totalCountGrowthRate` 的视觉提示文案建议从 "总检验数同比增长" 改为 "今日新增 vs 昨日新增"，避免误解为累计同比。

```html
<el-tooltip content="今日单日检验数相对昨日单日检验数的增长率">
  <span>总检验数同比 {{ formatRate(data.totalCountGrowthRate) }}</span>
</el-tooltip>
```

```js
methods: {
  formatRate(rate) {
    if (rate === null || rate === undefined) return '0%';
    const sign = rate > 0 ? '+' : '';
    return `${sign}${rate}%`;
  }
}
```

## 二、`/home/unqualifiedProductRanking` (口径变更，前端需关注)

### 变更原因

原实现拉取所有 `inspect_state=1` 的记录到内存做聚合排序，数据量大时存在 OOM 风险。

### 新口径

| 维度 | 旧 | 新 |
|------|----|----|
| 时间范围 | 全历史 | **近 30 天 (含今天)** |
| 排序 | 合格率升序 Top5 | 不变 |
| 字段 | `productName / totalCount / completedCount / passRate` | 不变 |

### 前端修改点

如果当前页面有 "全历史" 之类的文案，请改成 "近 30 天"。

```html
<div class="card-title">不合格产品排名 <span class="sub">(近 30 天)</span></div>
```

## 三、日期上界统一改为右开区间 (语义未变，但补全数据)

`commonDetection` (rawMaterial / process / factoryDetection)、`nonComplianceWarning`、`completedInspectionCount`、`qualityInspectionStatistics` 之前都用 `le(checkTime, endDate)`。
当 `check_time` 是 `datetime` 列时，`<= "yyyy-MM-dd"` 等价于 `<= "yyyy-MM-dd 00:00:00"`，会漏掉当天 00:00:00 之后的所有记录。

后端已统一改为 `lt(checkTime, endDate + 1 天)`，**响应字段、字段语义不变**，只是当天数据不再丢失。

### 前端修改点

无需改动代码。但建议联调时核对：周/月/季视图最后一天是否出现以前缺失的检验记录。

## 四、其他内部优化 (前端无感)

- `qualityInspectionCount` 改用 `SELECT COALESCE(SUM(quantity), 0)` 聚合，单次 SQL 替代之前的 6 次全表 `selectList`。
- `qualityInspectionStatistics` 中 `i.getInspectType() == 0` 修复为 `Objects.equals(...)`，避免 Integer 自动装箱缓存范围外的等值误判。

## 注意事项

- `qualityInspectionCount` 的 `totalCountGrowthRate` 现在反映的是"日环比增长率"，业务侧文案与图表说明需同步调整。
- `unqualifiedProductRanking` 改为近 30 天后，**Top5 列表可能变化**，请通知业务确认。
- 上线后建议联调以下场景：
  - `check_time` 为非 00:00:00 的检验记录是否被正确统计 (周/月视图最后一天)。
  - 今日所有报检的"待完成 / 已完成"数据是否能实时反映到首页卡片。
- 若某接口需要保留旧的全历史口径 (例如导出、对账)，请单独提需求增加新接口，避免改回首页接口。

---

## 五、检验规则默认值逻辑变更 (新增检验单)

### 业务规则

当新建检验单时，后端会根据 `inspectRule` 自动补全 `sampleRatio` 和 `sampleQuantity`：

| inspectRule | 含义 | sampleRatio | sampleQuantity |
|-------------|------|-------------|----------------|
| 0 或 null | 全检 | 100 (固定) | `quantity` (全部数量) |
| 1 | 抽检 | 取 `sampleRatio` 传入值 (若为空则 0) | `quantity × sampleRatio / 100` (向上取整) |

### 前端修改点

新增检验单页面，检验规则下拉选择后：

```html
<el-form-item label="检验规则">
  <el-select v-model="form.inspectRule" @change="onInspectRuleChange">
    <el-option label="全检" :value="0" />
    <el-option label="抽检" :value="1" />
  </el-select>
</el-form-item>

<el-form-item label="抽检比例(%)" v-if="form.inspectRule === 1">
  <el-input-number v-model="form.sampleRatio" :min="0" :max="100" />
</el-form-item>

<el-form-item label="抽检数量">
  <el-input :value="computedSampleQuantity" disabled />
</el-form-item>
```

```js
computed: {
  computedSampleQuantity() {
    if (this.form.inspectRule === 0 || this.form.inspectRule === null) {
      // 全检时，抽检数量 = 总数量
      return this.form.quantity || 0;
    }
    // 抽检时，抽检数量 = 总数量 × 比例 / 100 (向上取整)
    const qty = this.form.quantity || 0;
    const ratio = this.form.sampleRatio || 0;
    return Math.ceil(qty * ratio / 100);
  }
},
methods: {
  onInspectRuleChange(val) {
    if (val === 0) {
      // 全检时自动清空抽检比例输入框
      this.form.sampleRatio = 100;
    }
  }
}
```

### 注意事项

- 后端已做兜底处理，即使前端不传 `sampleRatio/sampleQuantity`，也会自动补全。
- 建议前端在提交前做预计算展示，提升用户体验。
- 采购入库自动生成检验单、报工生成过程/出厂检验单时，同样会按此规则自动填充。