# ATS 批量排产报工接口文档

## 版本信息

- **版本号**：v2.0.002
- **创建日期**：2026-02-27
- **更新说明**：通过开关参数灵活控制计划、工单、报工单的生成
- **测试地址**：
  - 前端：http://192.168.1.244:80
  - 后端：http://192.168.1.244:8080

---

## 快速开始

### 核心概念

接口支持通过开关参数灵活控制三个业务模块的生成：

| 模块 | 开关参数 | 默认值 | 说明 |
|------|---------|--------|------|
| 生产计划 | `plan.isGeneratePlan` | `1` | `0`=不生成，`1`=生成 |
| 生产工单 | `workOrder.isGenerateWorkOrder` | `1` | `0`=不生成，`1`=生成 |
| 报工单 | `reportWorkOrder.isGenerateReportWorkOrder` | `1` | `0`=不生成，`1`=生成 |

**核心规则**：
- **不传对象** = 使用默认值（生成）
- **传了对象但不传开关** = 使用默认值（生成）
- **传了开关=0** = 明确不生成
- **传了开关=1** = 明确生成
- **传了空字符串 ""** = 使用默认值
- **传了空数组 []** = 使用默认值
- **传了 null** = 使用默认值

**示例**：
```json
// 不传plan对象 → 默认生成计划
{"orderNumbers": ["SO001"], "workOrder": {...}}

// 传了plan但不传开关 → 默认生成计划
{"orderNumbers": ["SO001"], "plan": {"assignedUserIds": "101"}}

// 传了开关=0 → 不生成计划
{"orderNumbers": ["SO001"], "plan": {"isGeneratePlan": 0}}

// 传了空字符串 → 使用默认值
{"orderNumbers": ["SO001"], "plan": {"assignedUserIds": ""}}  // 从工序路线获取

// 传了空数组 → 使用默认值
{"orderNumbers": ["SO001"], "reportWorkOrder": {"reporters": []}}  // 从工序路线获取
```

---

## 常用场景

### 场景1：全部生成（默认）

```json
{
  "orderNumbers": ["SO202602270001"]
}
```

**结果**：生成计划 → 生成工单 → 生成报工单

---

### 场景2：只生成工单

```json
{
  "orderNumbers": ["SO202602270001"],
  "plan": {
    "isGeneratePlan": 0
  },
  "workOrder": {
    "routeId": 1005,
    "processStartTime": "2026-02-27 08:00:00"
  },
  "reportWorkOrder": {
    "isGenerateReportWorkOrder": 0
  }
}
```

**结果**：只生成工单，工单状态保持"未完成"

**说明**：
- `plan.isGeneratePlan=0` 明确不生成计划
- `workOrder` 传了对象但没传开关，默认生成工单
- `reportWorkOrder.isGenerateReportWorkOrder=0` 明确不生成报工单

---

### 场景3：只生成报工单（订单已有工单）

```json
{
  "orderNumbers": ["SO202602270001"],
  "plan": {
    "isGeneratePlan": 0
  },
  "workOrder": {
    "isGenerateWorkOrder": 0
  },
  "reportWorkOrder": {
    "reporters": [
      {"operatorId": 101, "reportTime": "2026-02-27 10:00:00"}
    ]
  }
}
```

**结果**：为已有工单生成报工单，工单状态变为"已完成"

**说明**：
- `plan.isGeneratePlan=0` 明确不生成计划
- `workOrder.isGenerateWorkOrder=0` 明确不生成工单
- `reportWorkOrder` 传了对象但没传开关，默认生成报工单

---

### 场景4：生成工单+报工单（不生成计划）

```json
{
  "orderNumbers": ["SO202602270001"],
  "plan": {
    "isGeneratePlan": 0
  }
}
```

**结果**：生成工单 → 生成报工单（不生成计划）

**说明**：通过设置 `isGeneratePlan=0` 明确不生成计划，workOrder和reportWorkOrder使用默认值1，会生成工单和报工单

---

### 场景5：空值使用默认值

```json
{
  "orderNumbers": ["SO202602270001"],
  "plan": {
    "isGeneratePlan": 1,
    "assignedUserIds": ""
  },
  "workOrder": {
    "isGenerateWorkOrder": 1,
    "processStartTime": ""
  },
  "reportWorkOrder": {
    "isGenerateReportWorkOrder": 1,
    "reporters": []
  }
}
```

**结果**：全部生成，所有空值参数都使用系统默认值

**说明**：
- `assignedUserIds: ""` → 从工序路线获取所有报工人（去重）
- `processStartTime: ""` → 使用当前时间
- `reporters: []` → 从工序路线获取每个工序的报工人

---

## 接口详情

### 1. 批量自动完成接口

**POST** `http://192.168.1.244:8080/production/autoComplete/batchAutoComplete`

#### 请求参数

##### 必填参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `orderNumbers` | Array\<String\> | 销售订单编号列表 |

##### 可选参数 - plan（生产计划）

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `isGeneratePlan` | Integer | `1` | `0`=不生成，`1`=生成 |
| `assignedUserIds` | String | 工序路线所有报工人（去重） | 负责人ID，逗号分隔，如 `"101,102"`；不传、传null或传空字符串 `""` 时，自动从工序路线中获取所有工序的报工人（去重）作为计划负责人 |

##### 可选参数 - workOrder（生产工单）

| 参数 | 类型 | 默认值 | 说明 |
|------|------|------|------|
| `isGenerateWorkOrder` | Integer | `1` | `0`=不生成，`1`=生成 |
| `routeId` | Long | 自动选择 | 工序路线ID；不传、传null时自动选择 |
| `processStartTime` | String | 自动生成 | 首道工序开始时间，格式 `yyyy-MM-dd HH:mm:ss`；不传、传null或传空字符串 `""` 时使用当前时间 |

**工序路线选择优先级**：
1. `workOrder.routeId`（最高优先级）
2. 订单明细配置的路线
3. 物料默认路线
4. 无路线则返回错误

##### 可选参数 - reportWorkOrder（报工单）

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `isGenerateReportWorkOrder` | Integer | `1` | `0`=不生成，`1`=生成 |
| `reporters` | Array | 工序路线的报工人 | 报工人列表；不传、传null或传空数组 `[]` 时，自动从工序路线中获取每个工序的报工人 |

**reporters 子字段**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `operatorId` | Long | 是 | 报工人用户ID |
| `reportTime` | String | 是 | 报工时间，格式 `yyyy-MM-dd HH:mm:ss` |

**说明**：
- 系统通过订单编号反查关联工单
- 只对未完成的工单创建报工记录
- **不传reporters、传null或传空数组 `[]` 时**：系统自动从工序路线中获取每个工序配置的报工人，按工序顺序为每个工单生成报工记录（每个工序一个报工人）
- **传1条reporter时**：该报工人对所有未完成工单均生成报工记录
- **传多条reporters时**：按工序顺序与未完成工单一一映射

---

#### 完整请求示例

```json
{
  "orderNumbers": ["SO202602270001", "SO202602270002"],
  "plan": {
    "isGeneratePlan": 1,
    "assignedUserIds": "101,102"
  },
  "workOrder": {
    "isGenerateWorkOrder": 1,
    "routeId": 1005,
    "processStartTime": "2026-02-27 08:00:00"
  },
  "reportWorkOrder": {
    "isGenerateReportWorkOrder": 1,
    "reporters": [
      {"operatorId": 101, "reportTime": "2026-02-27 10:00:00"},
      {"operatorId": 102, "reportTime": "2026-02-27 14:00:00"}
    ]
  }
}
```

---

#### 响应结果（立即返回）

```json
{
  "code": 200,
  "msg": "任务已提交，正在后台处理",
  "data": {
    "taskId": "TASK_20260227_001",
    "totalCount": 2,
    "estimatedSeconds": 10,
    "status": "PENDING",
    "message": "任务已创建，预计需要10秒完成"
  }
}
```

---

### 2. 任务状态查询接口

**GET** `http://192.168.1.244:8080/production/autoComplete/taskStatus/{taskId}`

#### 请求示例

```
GET /production/autoComplete/taskStatus/TASK_20260227_001
```

#### 响应示例（处理中）

```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "taskId": "TASK_20260227_001",
    "status": "PROCESSING",
    "totalCount": 50,
    "processedCount": 25,
    "successCount": 23,
    "failedCount": 2,
    "percentage": 50,
    "message": "正在处理中，已完成50%"
  }
}
```

#### 响应示例（已完成）

```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "taskId": "TASK_20260227_001",
    "status": "COMPLETED",
    "totalCount": 50,
    "processedCount": 50,
    "successCount": 48,
    "failedCount": 2,
    "percentage": 100,
    "message": "任务已完成",
    "result": {
      "successOrders": ["SO001", "SO002"],
      "failedOrders": ["SO025", "SO038"],
      "failureReasons": {
        "SO025": "订单不存在",
        "SO038": "物料未配置工序路线"
      }
    }
  }
}
```

---

## 辅助接口

### 3. 库存式生产自动创建订单

**POST** `http://192.168.1.244:8080/production/plan/autoCreateOrder`

用于库存式生产（MTS），自动生成以"生产备货"为客户的销售订单。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `materialId` | Long | 是 | 产品ID |
| `materialName` | String | 建议 | 产品名称 |
| `totalQuantity` | BigDecimal | 是 | 生产数量（必须 > 0） |
| `endTime` | String | 是 | 交货日期，格式 `yyyy-MM-dd HH:mm:ss` |

#### 请求示例

```json
{
  "materialId": 101,
  "materialName": "产品A",
  "totalQuantity": 100,
  "endTime": "2026-03-31 18:00:00"
}
```

#### 响应示例

```json
{
  "code": 200,
  "msg": "订单创建成功",
  "data": {
    "orderId": 999,
    "orderNumber": "PL20260227001"
  }
}
```

---

### 4. 按用户查询报工单

**GET** `http://192.168.1.244:8080/production/report/list`

#### 查询参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `reportUserName` | String | 是 | 报工人姓名（模糊匹配） |
| `reportTimeQuery[0]` | String | 否 | 报工时间起，格式 `yyyy-MM-dd` |
| `reportTimeQuery[1]` | String | 否 | 报工时间止，格式 `yyyy-MM-dd` |
| `workOrderId` | Long | 否 | 工单ID |
| `pageNum` | Integer | 否 | 页码（默认1） |
| `pageSize` | Integer | 否 | 每页条数（默认10） |

#### 请求示例

```
GET /production/report/list?reportUserName=张三&reportTimeQuery[0]=2026-02-01&reportTimeQuery[1]=2026-02-27
```

#### 响应示例

```json
{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 501,
      "reportUserId": 1,
      "reportUserName": "张三",
      "reportTime": "2026-02-27 10:00:00",
      "reportQuantity": 50,
      "qualifiedQuantity": 50,
      "workOrderId": 301,
      "status": "A"
    }
  ],
  "total": 1
}
```

---

## 业务规则

### 开关控制规则

**核心原则**：所有开关默认值都是 `1`（生成），只有明确设置为 `0` 才不生成

1. **不传任何对象**：使用默认值，全部生成（计划+工单+报工单）
   ```json
   {"orderNumbers": ["SO001"]}
   ```

2. **传了对象但不传开关**：使用默认值，该业务生成
   ```json
   {"orderNumbers": ["SO001"], "plan": {"assignedUserIds": "101"}}
   // plan没有传isGeneratePlan，默认为1，生成计划
   ```

3. **传了开关=0**：明确不生成
   ```json
   {"orderNumbers": ["SO001"], "plan": {"isGeneratePlan": 0}}
   // 明确设置为0，不生成计划
   ```

4. **传了开关=1**：明确生成（与默认行为相同）
   ```json
   {"orderNumbers": ["SO001"], "plan": {"isGeneratePlan": 1}}
   // 明确设置为1，生成计划
   ```

### 依赖关系

| 场景 | 说明 |
|------|------|
| 报工单依赖工单 | 如果 `isGenerateWorkOrder=0` 且 `isGenerateReportWorkOrder=1`，则只为已有工单生成报工单；如果订单无工单，跳过该订单 |
| 计划独立 | 计划的生成不依赖工单和报工单 |
| 工单独立 | 工单可以单独生成，不依赖计划和报工单 |

### 异步处理流程

1. **提交任务**（<1秒）：验证参数 → 创建任务记录 → 立即返回任务ID
2. **异步执行**（后台）：循环处理订单 → 每5个订单更新一次进度
3. **查询状态**（<100ms）：根据任务ID查询实时进度

### 性能说明

| 订单数 | 预计耗时 | 数据库更新次数 |
|--------|---------|--------------|
| 5个 | ~5秒 | 4次 |
| 10个 | ~10秒 | 5次 |
| 50个 | ~50秒 | 13次 |
| 100个 | ~100秒 | 23次 |

**并发限制**：
- 线程池大小：10个线程
- 最大并发任务数：10个
- 单个任务最大执行时间：5分钟
- 建议：单次批量不超过100个订单

---

## 场景速查表

| 场景 | 参数配置示例 | 结果 |
|------|------------|------|
| 全部生成 | `{}` 不传任何对象 | 计划+工单+报工单 |
| 只生成计划 | `{plan: {}, workOrder: {isGenerateWorkOrder: 0}, report: {isGenerateReportWorkOrder: 0}}` | 只生成计划 |
| 只生成工单 | `{plan: {isGeneratePlan: 0}, workOrder: {}, report: {isGenerateReportWorkOrder: 0}}` | 只生成工单 |
| 只生成报工单 | `{plan: {isGeneratePlan: 0}, workOrder: {isGenerateWorkOrder: 0}, report: {}}` | 只为已有工单生成报工单 |
| 工单+报工单 | `{plan: {isGeneratePlan: 0}}` | 生成工单和报工单 |
| 计划+工单 | `{report: {isGenerateReportWorkOrder: 0}}` | 生成计划和工单 |

**说明**：
- 开关默认值都是1（生成）
- 不传对象 = 使用默认值1 = 生成
- 传了对象但不传开关 = 使用默认值1 = 生成
- 只有明确设置开关=0才不生成

---

## 版本历史

| 版本号 | 日期 | 变更说明 |
|--------|------|---------|
| v2.0.000 | 2026-02-24 | 初始版本，支持基础批量排产 |
| v2.0.002 | 2026-02-27 | 新增开关参数，支持灵活控制计划、工单、报工单的生成 |

---

## 注意事项

1. **认证方式**：接口已配置匿名访问，无需认证
2. **异步执行**：接口立即返回任务ID，实际处理在后台进行
3. **进度查询**：通过任务状态查询接口轮询获取进度
4. **错误处理**：单个订单失败不影响其他订单，最终返回详细的成功/失败列表
5. **工序路线**：优先使用 `workOrder.routeId`，其次使用订单/物料配置的路线
6. **默认值逻辑**：
   - **计划负责人**：不传 `plan.assignedUserIds`、传null或传空字符串 `""` 时，系统自动从工序路线中获取所有工序的报工人（去重）作为计划负责人
   - **工序开始时间**：不传 `workOrder.processStartTime`、传null或传空字符串 `""` 时，系统使用当前时间
   - **报工单报工人**：不传 `reportWorkOrder.reporters`、传null或传空数组 `[]` 时，系统自动从工序路线中获取每个工序配置的报工人，按工序顺序生成报工记录
7. **空值处理规则**：
   - 字符串类型：`null`、`""`（空字符串）、不传 → 都使用默认值
   - 数组类型：`null`、`[]`（空数组）、不传 → 都使用默认值
   - 数值类型：`null`、不传 → 使用默认值