shenlu/MES

Fork 0

Files

hhh aed67ce1fd 初始代码

2026-04-02 10:39:03 +08:00

14 KiB

Raw Permalink Blame History

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 = 使用默认值

示例：

// 不传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：全部生成（默认）

{
  "orderNumbers": ["SO202602270001"]
}

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

场景2：只生成工单

{
  "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：只生成报工单（订单已有工单）

{
  "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：生成工单+报工单（不生成计划）

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

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

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

场景5：空值使用默认值

{
  "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或传空字符串 `""` 时使用当前时间

工序路线选择优先级：

workOrder.routeId（最高优先级）
订单明细配置的路线
物料默认路线
无路线则返回错误

可选参数 - 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时：按工序顺序与未完成工单一一映射

完整请求示例

{
  "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"}
    ]
  }
}

响应结果（立即返回）

{
  "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

响应示例（处理中）

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

响应示例（已完成）

{
  "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`

请求示例

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

响应示例

{
  "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

响应示例

{
  "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 才不生成

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

传了对象但不传开关：使用默认值，该业务生成

{"orderNumbers": ["SO001"], "plan": {"assignedUserIds": "101"}}
// plan没有传isGeneratePlan，默认为1，生成计划

传了开关=0：明确不生成

{"orderNumbers": ["SO001"], "plan": {"isGeneratePlan": 0}}
// 明确设置为0，不生成计划

传了开关=1：明确生成（与默认行为相同）

{"orderNumbers": ["SO001"], "plan": {"isGeneratePlan": 1}}
// 明确设置为1，生成计划

依赖关系

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

异步处理流程

提交任务（<1秒）：验证参数 → 创建任务记录 → 立即返回任务ID
异步执行（后台）：循环处理订单 → 每5个订单更新一次进度
查询状态（<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	新增开关参数，支持灵活控制计划、工单、报工单的生成

注意事项

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

14 KiB Raw Permalink Blame History Unescape Escape

ATS 批量排产报工接口文档

版本信息

快速开始

核心概念

常用场景

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

场景2：只生成工单

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

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

场景5：空值使用默认值

接口详情

1. 批量自动完成接口

请求参数

必填参数

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

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

可选参数 - reportWorkOrder（报工单）

完整请求示例

响应结果（立即返回）

2. 任务状态查询接口

请求示例

响应示例（处理中）

响应示例（已完成）

辅助接口

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

请求参数

请求示例

响应示例

4. 按用户查询报工单

查询参数

请求示例

响应示例

业务规则

开关控制规则

依赖关系

异步处理流程

性能说明

场景速查表

版本历史

注意事项

14 KiB

Raw Permalink Blame History