# 待报工台账 接口方案

## 需求

排产后需要一个"待报工台账"：展示已排产但尚未报工完的任务，核心是 **待报工数量 = 排产数量 − 已报工数量**。

数据源用 `mes_pro_task`（任务级汇总，正确--待报工天然是任务级概念；已生产数量 producedQuantity 由报工审批累加回写，无需现算 feedback）。

## 核心过滤与字段

- **过滤**：`status = PREPARE(0)`（进行中，排除已完成/已取消）AND `(quantity - IFNULL(produced_quantity,0)) > 0`（仍有待报工量）
- **新增展示字段**：
  - `pendingQuantity` 待报工数量 = `quantity - producedQuantity`
  - `feedbackRate` 报工完成率 = `producedQuantity / quantity × 100`（排产数量为 0 时给 0）
- 其余展示字段复用现有 `MesProTaskRespVO`（工单号、产品、工序、工位、客户、排产/已生产/合格/不良数量、需求日期等，已由 `buildTaskRespVOList` 批量关联拼好）

## 改动清单

### 1. `MesProTaskRespVO` 加两个字段

`controller/admin/pro/task/vo/MesProTaskRespVO.java`，在 `unqualifyQuantity` 之后：

```java
@Schema(description = "待报工数量", example = "50.00")
private BigDecimal pendingQuantity;

@Schema(description = "报工完成率(%)", example = "50.00")
private BigDecimal feedbackRate;
```

### 2. `MesProTaskController.buildTaskRespVOList` 计算这两个字段

在 `convertList` 的 lambda 里，`BeanUtils.toBean` 之后追加：

```java
BigDecimal quantity = task.getQuantity() == null ? BigDecimal.ZERO : task.getQuantity();
BigDecimal produced = task.getProducedQuantity() == null ? BigDecimal.ZERO : task.getProducedQuantity();
vo.setPendingQuantity(quantity.subtract(produced));
vo.setFeedbackRate(quantity.compareTo(BigDecimal.ZERO) == 0 ? BigDecimal.ZERO
        : produced.multiply(new BigDecimal("100")).divide(quantity, 2, RoundingMode.HALF_UP));
```

> 现有 page / get / gantt 都走 `buildTaskRespVOList`，加这两列后它们也会带出，无害且更完整。

### 3. `MesProTaskMapper` 加 `selectPendingFeedbackPage`

`dal/mysql/pro/task/MesProTaskMapper.java`，仿 `selectPage`，强制 `status=PREPARE` + 待报工量>0，复用其余过滤条件，不需要 checkFlag join：

```java
default PageResult<MesProTaskDO> selectPendingFeedbackPage(MesProTaskPageReqVO reqVO) {
    MPJLambdaWrapperX<MesProTaskDO> query = new MPJLambdaWrapperX<>();
    query.selectAll(MesProTaskDO.class);
    query.eq(MesProTaskDO::getStatus, MesProTaskStatusEnum.PREPARE.getStatus()); // 待报工=进行中
    query.apply("(quantity - IFNULL(produced_quantity, 0)) > 0");                  // 仍有待报工量
    query.likeIfPresent(MesProTaskDO::getCode, reqVO.getCode())
            .likeIfPresent(MesProTaskDO::getName, reqVO.getName())
            .eqIfPresent(MesProTaskDO::getWorkOrderId, reqVO.getWorkOrderId())
            .eqIfPresent(MesProTaskDO::getRouteId, reqVO.getRouteId())
            .eqIfPresent(MesProTaskDO::getProcessId, reqVO.getProcessId())
            .eqIfPresent(MesProTaskDO::getWorkstationId, reqVO.getWorkstationId())
            .betweenIfPresent(MesProTaskDO::getCreateTime, reqVO.getCreateTime())
            .orderByDesc(MesProTaskDO::getId);
    return selectPage(reqVO, query);
}
```

> `apply` 用裸列名：本查询无 join，`quantity`/`produced_quantity` 无歧义。`reqVO.getStatus()`/`getStatuses()` 在此接口被忽略（强制 PREPARE），符合"待报工"语义。

### 4. `MesProTaskService` + Impl 加方法

接口加：

```java
PageResult<MesProTaskDO> getPendingFeedbackPage(MesProTaskPageReqVO pageReqVO);
```

Impl：

```java
@Override
public PageResult<MesProTaskDO> getPendingFeedbackPage(MesProTaskPageReqVO pageReqVO) {
    return taskMapper.selectPendingFeedbackPage(pageReqVO);
}
```

### 5. `MesProTaskController` 加接口

复用 `buildTaskRespVOList` 拼展示字段，复用 `MesProTaskPageReqVO` 做过滤：

```java
@GetMapping("/pending-feedback-page")
@Operation(summary = "获得待报工台账分页", description = "已排产且仍有待报工数量的任务（状态=进行中）")
@PreAuthorize("@ss.hasPermission('mes:pro-task:query')")
public CommonResult<PageResult<MesProTaskRespVO>> getPendingFeedbackPage(@Valid MesProTaskPageReqVO pageReqVO) {
    PageResult<MesProTaskDO> pageResult = taskService.getPendingFeedbackPage(pageReqVO);
    return success(new PageResult<>(buildTaskRespVOList(pageResult.getList()), pageResult.getTotal()));
}
```

### 6. 前端文档

按 frontend-docs 规则输出 `docs/task_pending_feedback_ledger.md`：接口路径、过滤参数、响应字段（含 pendingQuantity/feedbackRate）、前端表格列建议。

### 7. 编译校验

`mvn compile -pl yudao-module-mes -am -Dmaven.compiler.source=25 -Dmaven.compiler.target=25 -q`（按 compile-check 规则）

## 行为说明

| 任务情况 | 是否出现在待报工台账 |
|---------|--------------------|
| 状态=进行中，已报工 < 排产 | ✅ 出现，pendingQuantity>0 |
| 状态=进行中，已报工 = 排产（报满了但工单没完工）| ❌ 不出现（pendingQuantity=0）|
| 状态=已完成/已取消 | ❌ 不出现 |
| 状态=进行中，从未报工 | ✅ 出现，pendingQuantity=排产数量 |

> 已报工=排产但任务仍 PREPARE 的任务不在台账里（没待报工量了）。若想看"所有进行中任务"，用现有 `/mes/pro/task/page?status=0`。

## 不改动项

- 报工相关逻辑不动
- `MesProTaskPageReqVO` 不动（复用）
- `selectPage` 原逻辑不动
- 不新建独立 ReqVO/RespVO（复用现有，最小改动）

## 待确认

- `feedbackRate`（完成率）要不要？默认加上，展示更直观；不要可去掉。
- 是否需要"按待报工数量倒序"排列？当前按 id 倒序。可改 `orderByDesc(pendingQuantity)`，但 MPJ 对计算列排序需 raw SQL，略繁。默认 id 倒序，需要再说。