# 生产报工 - 前端联调方案

## 涉及页面

- 待报工台账（报工入口，按工序筛选任务，选择任务进行报工）
- 生产报工（新增/编辑报工单）
- 报工审批（审批/驳回操作）
- 报工详情（查看报工信息 + 追溯产出/消耗/质检）

## 业务流程与数据带入

```
1. 待报工台账(按工序筛选) → 选择任务 → 报工
   选择任务后，自动带入：taskId、workOrderId、routeId、processId、
   workstationId、itemId、scheduledQuantity(排产数量)

2. 填写报工 → 保存(草稿) → 提交(审批中) → 审批通过(已完成/待检验)
   - 质检工序：只需填报工数量，合格/不合格由质检结果回填
   - 非质检工序：需填合格品 + 不良品数量

3. 审批驳回 → 退回草稿 → 修改后重新提交
```

## 状态流转

### 生产任务状态

| 状态值 | 状态名 | 说明 |
|--------|--------|------|
| 0 | 草稿(进行中) | 可报工 |
| 4 | 已完成 | 不可报工 |
| 5 | 已取消 | 不可报工 |

### 生产报工状态

| 状态值 | 状态名 | 可执行操作 | 说明 |
|--------|--------|-----------|------|
| 0 | 草稿 | 编辑、删除、提交 | 初始状态 |
| 2 | 审批中 | 审批、驳回 | 已提交待审批 |
| 3 | 待检验 | — | 关键+质检工序审批后进入，等IPQC回调 |
| 4 | 已完成 | — | 最终状态 |

---

## API

### 一、待报工台账接口

#### 1.1 待报工台账（分页）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /mes/pro/task/pending-feedback-page | 已排产且仍有待报工量的任务 |

**说明：** 此接口仅返回状态=进行中(0)且 `quantity - produced_quantity > 0` 的任务，是报工页面的入口数据源。

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| processId | Long | 否 | 工序编号（按工序筛选任务） |
| routeId | Long | 否 | 工艺路线编号 |
| workOrderId | Long | 否 | 生产工单编号 |
| workstationId | Long | 否 | 工作站编号 |
| code | String | 否 | 任务编码（模糊匹配） |
| name | String | 否 | 任务名称（模糊匹配） |
| checkFlag | Boolean | 否 | 是否质检工序 |
| createTime | String[] | 否 | 创建时间范围 |
| pageNo | Integer | 是 | 页码（默认1） |
| pageSize | Integer | 是 | 每页条数（默认10） |

**响应字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 任务编号 |
| code | String | 任务编码 |
| name | String | 任务名称 |
| workOrderId | Long | 工单编号 |
| workOrderCode | String | 工单编码 |
| workOrderName | String | 工单名称 |
| workstationId | Long | 工作站编号 |
| workstationCode | String | 工作站编码 |
| workstationName | String | 工作站名称 |
| routeId | Long | 工艺路线编号 |
| processId | Long | 工序编号 |
| processName | String | 工序名称 |
| itemId | Long | 产品物料编号 |
| itemCode | String | 物料编码 |
| itemName | String | 物料名称 |
| itemSpecification | String | 规格型号 |
| unitMeasureName | String | 计量单位 |
| quantity | BigDecimal | 排产数量 |
| producedQuantity | BigDecimal | 已生产数量 |
| qualifyQuantity | BigDecimal | 合格品数量 |
| unqualifyQuantity | BigDecimal | 不良品数量 |
| pendingQuantity | BigDecimal | 待报工数量（= 排产 - 已生产） |
| inTransitQuantity | BigDecimal | 在途报工数量（草稿/审批中/待检验状态的报工量合计） |
| reportableQuantity | BigDecimal | 可报工数量（= 排产 - 已生产 - 在途） |
| feedbackRate | BigDecimal | 报工完成率(%)，如 50.00 表示 50% |
| checkFlag | Boolean | 是否质检工序 |
| clientId | Long | 客户编号 |
| clientName | String | 客户名称 |
| startTime | LocalDateTime | 开始生产时间 |
| endTime | LocalDateTime | 结束生产时间 |
| duration | Integer | 生产时长（工作日） |
| requestDate | LocalDateTime | 需求日期 |
| status | Integer | 任务状态 |
| remark | String | 备注 |
| createTime | LocalDateTime | 创建时间 |

**响应示例：**

```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 1,
        "code": "PT202503150001",
        "name": "注塑任务",
        "workOrderId": 10,
        "workOrderCode": "MO202503120008",
        "workOrderName": "博世螺丝刀",
        "workstationId": 5,
        "workstationCode": "WS-001",
        "workstationName": "注塑工作站",
        "routeId": 3,
        "processId": 7,
        "processName": "注塑",
        "itemId": 75,
        "itemCode": "I-075",
        "itemName": "博世螺丝刀",
        "itemSpecification": "一字型",
        "unitMeasureName": "个",
        "quantity": 5000.00,
        "producedQuantity": 2000.00,
        "qualifyQuantity": 1950.00,
        "unqualifyQuantity": 50.00,
        "pendingQuantity": 3000.00,
        "inTransitQuantity": 500.00,
        "reportableQuantity": 2500.00,
        "feedbackRate": 40.00,
        "checkFlag": true,
        "status": 0,
        "createTime": "2025-03-15 10:00:00"
      }
    ],
    "total": 1
  }
}
```

---

#### 1.2 查询任务详情

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /mes/pro/task/get | 根据ID获取任务详情 |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 任务编号 |

**响应字段：** 同 1.1 响应字段（单条对象，非分页）

**响应示例：**

```json
{
  "code": 0,
  "data": {
    "id": 1,
    "code": "PT202503150001",
    "reportableQuantity": 2500.00,
    "checkFlag": true
  }
}
```

---

### 二、生产报工接口

#### 2.1 创建报工

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /mes/pro-feedback/create | 新建报工单（状态=草稿） |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| code | String | 是 | 报工单编号 |
| type | Integer | 是 | 报工类型：1=自行报工，2=统一报工 |
| workstationId | Long | 是 | 工作站编号 |
| routeId | Long | 是 | 工艺路线编号 |
| processId | Long | 是 | 工序编号 |
| workOrderId | Long | 是 | 生产工单编号 |
| taskId | Long | 是 | 生产任务编号 |
| itemId | Long | 是 | 产品物料编号 |
| feedbackQuantity | BigDecimal | 是 | 本次报工数量（必须 > 0） |
| feedbackUserId | Long | 是 | 报工人编号 |
| feedbackTime | LocalDateTime | 是 | 报工时间 |
| approveUserId | Long | 是 | 审核人编号 |
| qualifiedQuantity | BigDecimal | 条件必填 | 合格品数量（非质检工序必填） |
| unqualifiedQuantity | BigDecimal | 条件必填 | 不良品数量（非质检工序必填） |
| uncheckQuantity | BigDecimal | 否 | 待检测数量 |
| laborScrapQuantity | BigDecimal | 否 | 工废数量 |
| materialScrapQuantity | BigDecimal | 否 | 料废数量 |
| otherScrapQuantity | BigDecimal | 否 | 其他废品数量 |
| scheduledQuantity | BigDecimal | 否 | 排产数量 |
| expireDate | LocalDateTime | 否 | 过期日期 |
| lotNumber | String | 否 | 生产批号 |
| remark | String | 否 | 备注 |

**响应：** `Long`（报工记录ID）

```json
{
  "code": 0,
  "data": 1024
}
```

**数据带入说明：**

从待报工台账选择任务后，以下字段自动带入报工表单，无需用户手动填写：

| 报工表单字段 | 数据来源 | 来源字段 |
|-------------|---------|---------|
| taskId | 任务 | id |
| workOrderId | 任务 | workOrderId |
| routeId | 任务 | routeId |
| processId | 任务 | processId | 任务 | processId |
| workstationId | 任务 | workstationId |
| itemId | 任务 | itemId |
| scheduledQuantity | 任务 | quantity（排产数量） |

用户需手动填写：报工数量、合格/不良品数量、报工人、报工时间、审核人等。

---

#### 2.2 更新报工

| 方法 | 路径 | 说明 |
|------|------|------|
| PUT | /mes/pro-feedback/update | 修改报工单（仅草稿状态可修改） |

**请求参数：** 同 2.1（需额外传 id）

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 报工编号 |

**响应：** `{ "code": 0, "data": true }`

---

#### 2.3 提交报工

| 方法 | 路径 | 说明 |
|------|------|------|
| PUT | /mes/pro-feedback/submit | 草稿 → 审批中 |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 报工编号 |

**响应：** `{ "code": 0, "data": true }`

**状态变化：** 草稿(0) → 审批中(2)

---

#### 2.4 审批报工

| 方法 | 路径 | 说明 |
|------|------|------|
| PUT | /mes/pro-feedback/approve | 审批通过，触发入库/扣料/质检 |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 报工编号 |

**响应：**

```json
{
  "code": 0,
  "data": true   // true=审批完成(已入库)，false=进入待检验(等质检回调)
}
```

**状态变化：**

| 场景 | 状态变化 | 返回值 |
|------|---------|--------|
| 非关键工序 | 审批中(2) → 已完成(4) | true |
| 关键+非质检工序 | 审批中(2) → 已完成(4)，同时入库 | true |
| 关键+质检工序 | 审批中(2) → 待检验(3)，等IPQC回调 | false |

---

#### 2.5 驳回报工

| 方法 | 路径 | 说明 |
|------|------|------|
| PUT | /mes/pro-feedback/reject | 审批中 → 草稿 |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 报工编号 |

**响应：** `{ "code": 0, "data": true }`

**状态变化：** 审批中(2) → 草稿(0)

---

#### 2.6 查询报工详情

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /mes/pro-feedback/get | 获取单条报工详情 |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 报工编号 |

**响应字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 编号 |
| code | String | 报工单编号 |
| type | Integer | 报工类型：1=自行报工，2=统一报工 |
| channel | String | 报工途径 |
| feedbackTime | LocalDateTime | 报工时间 |
| workstationId | Long | 工作站编号 |
| workstationCode | String | 工作站编码 |
| workstationName | String | 工作站名称 |
| routeId | Long | 工艺路线编号 |
| routeCode | String | 工艺路线编码 |
| processId | Long | 工序编号 |
| processCode | String | 工序编码 |
| processName | String | 工序名称 |
| checkFlag | Boolean | 是否需要检验 |
| workOrderId | Long | 工单编号 |
| workOrderCode | String | 工单编码 |
| workOrderName | String | 工单名称 |
| taskId | Long | 任务编号 |
| taskCode | String | 任务编码 |
| itemId | Long | 物料编号 |
| itemCode | String | 物料编码 |
| itemName | String | 物料名称 |
| itemSpecification | String | 规格型号 |
| unitMeasureId | Long | 单位编号 |
| unitMeasureName | String | 单位名称 |
| scheduledQuantity | BigDecimal | 排产数量 |
| feedbackQuantity | BigDecimal | 报工数量 |
| qualifiedQuantity | BigDecimal | 合格品数量 |
| unqualifiedQuantity | BigDecimal | 不良品数量 |
| uncheckQuantity | BigDecimal | 待检测数量 |
| laborScrapQuantity | BigDecimal | 工废数量 |
| materialScrapQuantity | BigDecimal | 料废数量 |
| otherScrapQuantity | BigDecimal | 其他废品数量 |
| feedbackUserId | Long | 报工人编号 |
| feedbackUserNickname | String | 报工人昵称 |
| approveUserId | Long | 审核人编号 |
| approveUserNickname | String | 审核人昵称 |
| status | Integer | 状态 |
| remark | String | 备注 |
| createTime | LocalDateTime | 创建时间 |

---

#### 2.7 报工分页查询

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /mes/pro-feedback/page | 分页查询报工列表 |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| code | String | 否 | 报工单编号（模糊匹配） |
| type | Integer | 否 | 报工类型 |
| workOrderId | Long | 否 | 生产工单编号 |
| taskId | Long | 否 | 生产任务编号（精确匹配） |
| taskCode | String | 否 | 生产任务编码（模糊匹配，如 "PT202503"） |
| status | Integer | 否 | 状态 |
| itemId | Long | 否 | 产品物料编号 |
| feedbackUserId | Long | 否 | 报工人编号 |
| creator | String | 否 | 记录人编号 |
| feedbackTime | String[] | 否 | 报工时间范围 |
| pageNo | Integer | 是 | 页码 |
| pageSize | Integer | 是 | 每页条数 |

**响应字段：** 同 2.6（分页列表）

**查询说明：**

| 场景 | 用法 | 示例 |
|------|------|------|
| 按任务编码模糊查询 | 传 taskCode | `taskCode=PT202503` 匹配 PT202503150001、PT202503150002 等 |
| 按任务ID精确查询 | 传 taskId | `taskId=1024` |
| 同时传 taskId 和 taskCode | taskId 优先精确匹配，taskCode 额外模糊过滤 | 一般不同时传 |
| 不传任务相关参数 | 查询所有报工 | — |

---

#### 2.8 按任务查询报工历史

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /mes/pro-feedback/list-by-task | 查询某任务下所有报工记录 |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskId | Long | 是 | 任务编号 |

**响应字段：** `List<MesProFeedbackRespVO>`（同 2.6 字段，数组形式）

**说明：** 返回该任务下所有状态的报工记录（草稿/审批中/待检验/已完成），用于在任务详情中展示报工历史。

---

#### 2.9 报工追溯信息

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /mes/pro-feedback/trace/{id} | 报工 + 产出 + 消耗 + IPQC检验 |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 报工编号（路径参数） |

**响应字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| feedback | MesProFeedbackRespVO | 报工信息（同 2.6 字段） |
| productProduce | Object | 生产产出单（关键工序才有，否则 null） |
| productProduceLines | Array | 产出明细行（按合格/不合格/待检验拆行） |
| itemConsume | Object | 物料消耗单（倒冲工序才有，否则 null） |
| itemConsumeLines | Array | 消耗明细行（按 BOM 物料拆行） |
| ipqcList | Array | IPQC 过程检验单列表（关键+需检验工序才有） |

**响应示例：**

```json
{
  "code": 0,
  "data": {
    "feedback": {
      "id": 1024,
      "code": "FB202503160001",
      "status": 4,
      "feedbackQuantity": 500.00,
      "qualifiedQuantity": 490.00,
      "unqualifiedQuantity": 10.00
    },
    "productProduce": {
      "id": 50,
      "code": "PP202503160001"
    },
    "productProduceLines": [
      { "id": 101, "qualityStatus": 1, "quantity": 490.00 },
      { "id": 102, "qualityStatus": 2, "quantity": 10.00 }
    ],
    "itemConsume": null,
    "itemConsumeLines": [],
    "ipqcList": []
  }
}
```

---

#### 2.10 删除报工

| 方法 | 路径 | 说明 |
|------|------|------|
| DELETE | /mes/pro-feedback/delete | 删除报工（仅草稿状态可删除） |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 报工编号 |

**响应：** `{ "code": 0, "data": true }`

---

## 字段展示规则

### 待报工台账列表

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| code | 列表 | 任务编码 |
| workOrderCode + workOrderName | 列表 | 工单编码+名称 |
| workstationName | 列表 | 工作站 |
| processName | 列表 | 工序名称 |
| itemCode + itemName | 列表 | 物料编码+名称 |
| quantity | 列表 | 排产数量 |
| producedQuantity | 列表 | 已生产数量 |
| reportableQuantity | 列表 | 可报工数量（高亮显示） |
| feedbackRate | 列表 | 报工完成率(%) |
| checkFlag | 列表 | 是否质检（标签展示） |

### 报工表单

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| taskId → taskCode | 表单（只读） | 从任务自动带入 |
| workOrderId → workOrderCode + workOrderName | 表单（只读） | 从任务自动带入 |
| processId → processName | 表单（只读） | 从任务自动带入 |
| workstationId → workstationName | 表单（只读） | 从任务自动带入 |
| itemId → itemCode + itemName | 表单（只读） | 从任务自动带入 |
| scheduledQuantity | 表单（只读） | 排产数量，从任务带入 |
| feedbackQuantity | 表单（可编辑） | 本次报工数量，必填 |
| qualifiedQuantity | 表单（条件可编辑） | 非质检工序必填；质检工序隐藏或禁用 |
| unqualifiedQuantity | 表单（条件可编辑） | 非质检工序必填；质检工序隐藏或禁用 |
| feedbackUserId → feedbackUserNickname | 表单（可编辑） | 报工人，选择用户 |
| feedbackTime | 表单（可编辑） | 报工时间，默认当前时间 |
| approveUserId → approveUserNickname | 表单（可编辑） | 审核人，选择用户 |
| remark | 表单（可编辑） | 备注 |

### 报工列表

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| code | 列表 | 报工单编号 |
| workOrderCode | 列表 | 工单编码 |
| taskCode | 列表 | 任务编码 |
| processName | 列表 | 工序 |
| itemName | 列表 | 物料 |
| feedbackQuantity | 列表 | 报工数量 |
| qualifiedQuantity | 列表 | 合格品 |
| unqualifiedQuantity | 列表 | 不良品 |
| feedbackUserNickname | 列表 | 报工人 |
| approveUserNickname | 列表 | 审核人 |
| status | 列表 | 状态（字典标签，不同状态不同颜色） |
| feedbackTime | 列表 | 报工时间 |

**搜索条件：**

| 字段 | 控件类型 | 说明 |
|------|---------|------|
| taskCode | 输入框 | 生产任务编码（模糊匹配，主要搜索条件） |
| code | 输入框 | 报工单编号（模糊匹配） |
| status | 下拉选择 | 状态筛选 |
| feedbackTime | 日期范围 | 报工时间范围 |

---

## 业务规则说明

| 场景 | 规则 |
|------|------|
| 报工数量上限 | 报工数量不应超过任务的 `reportableQuantity`（可报工数量），前端应做校验提示 |
| 质检工序报工 | checkFlag=true 时，只需填报工数量，合格/不合格数量由质检结果回填，前端应隐藏或禁用合格/不良品输入 |
| 非质检工序报工 | checkFlag=false 时，合格品 + 不良品数量必须 > 0，前端应校验 |
| 草稿状态操作 | 仅草稿(0)状态可编辑、删除 |
| 审批中状态操作 | 仅审批中(2)状态可审批、驳回 |
| 待检验状态 | 待检验(3)状态不可操作，等IPQC质检完成后系统自动回调更新为已完成(4) |
| 审批返回值 | approve 接口返回 true=已完成，false=待检验，前端应根据返回值展示不同提示 |
| 任务数据带入 | 从待报工台账选择任务后，7个字段自动带入报工表单（见数据带入说明），用户不可修改 |

## 注意事项

- 报工单编号(code)由前端生成或调用自动编码接口获取，创建时必传
- 报工类型(type)字段：1=自行报工，2=统一报工，前端根据业务场景选择
- 审批是简单权限控制（`mes:pro-feedback:approve`），非BPM工作流，有权限的用户直接点击审批即可
- 审批通过后会自动触发：倒冲扣料（倒冲工序）、产出入库（关键工序），这些是后端自动处理的，前端无需额外操作
- 待检验状态的报工单，其合格/不合格数量会在IPQC质检完成后由后端自动回填，前端无需手动更新
- 待报工台账的 `reportableQuantity` 已扣除在途报工量，前端可直接用此值做报工数量上限校验
- 删除操作仅草稿状态可用，审批中/待检验/已完成状态不可删除