# 报工等待时长倒计时 + 报工数量可选 - 前端联调方案

## 涉及页面

- 工序管理（`src/views/mes/pro/process`，表单 `modules/form.vue`）
- 快速报工（`src/views/mes/pro/workorder-center/modules/quick-feedback.vue`）
- 报工表单（`src/views/mes/pro/feedback/modules/form.vue`）
- 生产任务相关展示（列表/详情，报工倒计时状态展示）

## 业务流程与数据带入

1. **工序主数据配置**：在工序管理页面为工序配置「等待时长（小时）」与「是否需要填写报工数量」两个新字段。字段保存到工序主数据（`mes_pro_process`），所有引用该工序的工艺路线共用。
2. **报工界面读取工序配置**：报工表单（新增/编辑）选择任务后，通过 `getRouteProcessByRouteAndProcess(routeId, processId)`（现有调用）拉取工序配置，响应新增返回 `waitDuration`、`needReportQuantity`。
   - `waitDuration > 0`：该工序报工前必须先点击「开始倒计时」，倒计时结束才能报工。
   - `needReportQuantity = false`：报工数量允许为空（不显示数量输入项、不做"必须大于 0"校验）。
3. **开始倒计时**：操作员点击「开始倒计时」→ 调用新接口 `startWaitCountdown` → 后端把当前时间写入任务（`mes_pro_task.wait_start_time`）。
4. **任务状态回显**：任务列表/详情响应新增 `waitStartTime` 字段，前端用于展示倒计时状态（已开始/进行中/已结束）。
5. **提交报工**：报工提交（快速报工 / 报工表单提交 / 审批通过）时，后端统一校验等待时长与数量规则。

## API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/mes/pro/task/start-wait-countdown` | 开始报工倒计时（记录开始时间到任务） |
| GET | `/mes/pro/route/process/get-by-route-and-process` | 现有接口，响应新增 `waitDuration`/`needReportQuantity` |

### 新增接口：开始报工倒计时

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskId | Long | 是 | 生产任务编号（POST body JSON 传递） |

**请求示例：**

```json
{
  "taskId": 35
}
```

**响应：** 返回倒计时开始时间（`yyyy-MM-dd HH:mm:ss`）。

**响应示例：**

```json
{
  "code": 0,
  "data": "2026-08-29 10:30:00"
}
```

**业务前置校验（后端）：**

| 场景 | 结果 |
|------|------|
| 任务不存在 / 已终态（完成、取消） | 报错（任务异常） |
| 任务已停工 | 报错（停工不能报工） |
| 工序未配置等待时长（为空或 0） | 报错「该工序未配置等待时长，无需倒计时」 |
| 工序已配置等待时长 | 成功，记录开始时间；重复点击会重置为当前时间 |

### 现有接口响应字段新增

**`get-by-route-and-process` 响应新增字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| waitDuration | BigDecimal | 等待时长（小时）。>0 表示报工前需倒计时等待 |
| needReportQuantity | Boolean | 是否需要填写报工数量。`false`=报工数量允许为空 |

**生产任务相关响应新增字段（列表/详情/任务选择组件）：**

| 字段 | 类型 | 说明 |
|------|------|------|
| waitStartTime | LocalDateTime | 报工倒计时开始时间。为空表示尚未开始倒计时 |

**工序主数据保存/响应新增字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| waitDuration | BigDecimal | 等待时长（小时），报工前需倒计时等待 |
| needReportQuantity | Boolean | 是否需要填写报工数量 |

## 字段展示规则

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| 等待时长（小时） | 工序管理表单 | 数字输入，小数最多 2 位；留空/0 表示该工序报工无需倒计时 |
| 是否需要填写报工数量 | 工序管理表单 | 开关。关闭后该工序报工数量允许为空 |
| 待报工数量 | 快速报工 / 报工表单 | 现有字段。若工序无需填写数量，报工数量输入项可不显示 |
| 本次报工数量 | 快速报工 / 报工表单 | 按工序配置决定是否必填/可空 |
| 开始倒计时 按钮 + 倒计时剩余时间 | 快速报工 / 报工表单 | 工序配置等待时长时展示；点击后展示倒计时剩余时间 |
| 倒计时状态 | 生产任务列表/详情（可选） | 依据 `waitStartTime` 与当前时间计算剩余时间 |

## 业务规则说明

| 场景 | 规则 |
|------|------|
| 工序 `waitDuration` 为空或 0 | 报工无需倒计时，原流程不变 |
| 工序 `waitDuration > 0`，任务未点「开始倒计时」 | 报工报错「该工序设置了等待时长，请先点击"开始倒计时"」 |
| 工序 `waitDuration > 0`，倒计时未结束 | 报工报错「等待倒计时未结束，还需等待 X小时X分钟」 |
| 工序 `waitDuration > 0`，倒计时已结束 | 可正常报工；开始时间记录在任务上，每任务一次 |
| 重复点击「开始倒计时」 | 重置开始时间为当前时间 |
| 工序 `needReportQuantity = true` 或未配置 | 报工数量必须 > 0（原逻辑） |
| 工序 `needReportQuantity = false` | 报工数量允许为空/0；后端跳过数量校验，审批时不生成产出单/批次，不扣倒冲物料，仅完成报工 |
| 倒计时适用范围 | 按工序判断，开始时间记录到生产任务，每任务一次 |

## 注意事项

- 等待时长单位固定为**小时**，前端输入时注意单位提示（示例 `2.00` 表示 2 小时；`0.5` 表示 30 分钟）。
- 倒计时开始时间记录在**生产任务**上，与工序等待时长（主数据）分开维护；修改工序等待时长不影响已开始的任务倒计时。
- 若工序配置了等待时长但任务未开始倒计时，直接提交报工会被后端拦截（创建、快速报工、审批通过三处入口都校验）。
- 快速报工当前为数量必填，接入后需按 `needReportQuantity` 调整「请输入报工数量」的必填校验与数量输入框展示。
- 报工数量为空/0 的报工：不会生成产出单/批次、不会倒冲扣料，仅把报工标记为已完成并更新任务进度；请在前端相应隐藏数量相关展示，避免误导。
- 报工表单编辑/审批时任务可能已过等待期，此时无需再倒计时即可提交。