MES/yawei-mes/.tasks/2026-02-24_v2.0.000_ATS接口文档.md

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

## 版本信息
- 版本号：v2.0.0
- 创建日期：2026-02-24
- 当前局域网测试地址：
- **前端地址**：http://192.168.1.244:80
- **后端地址**：http://192.168.1.244:8080

## 接口说明

### 1. 批量自动完成接口（异步模式）

#### 1.1 基本信息
- **接口名称**：批量自动完成销售订单（异步提交）
- **接口路径**：`后端地址/production/autoComplete/batchAutoComplete`
- **请求方法**：POST
- **Content-Type**：application/json;charset=UTF-8
- **认证方式**：无需认证（已配置匿名访问）
- **执行模式**：异步执行，立即返回任务ID

#### 1.2 请求参数

##### 请求体（JSON）

```json
{
  "orderNumbers": ["SO202602240001", "SO202602240002"],//订单编号列表，必填
  "routeId": 1001,//工序路线id，可选
  "productionStartTime": "2026-02-24 08:00:00"//生产计划开始时间，可选
}
```

##### 参数说明

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| orderNumbers | Array<String> | 是 | 销售订单编号列表，不能为空 |
| routeId | Long | 否 | 工序路线ID，如不指定则使用物料默认路线 |
| productionStartTime | String | 否 | 生产开始时间，格式：yyyy-MM-dd HH:mm:ss |

##### 参数约束
- `orderNumbers`：必填，至少包含一个有效订单编号
- 订单编号会自动过滤空字符串和null值
- `routeId`：可选，不指定时系统会根据物料配置自动选择路线
- `productionStartTime`：可选，指第一条工单的计划开始时间，不指定时系统会生成模拟时间(生产订单日期作为日期，早8:00-9:00随机时间，后续工单按照系统逻辑读取工序持续时间生成)

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

##### 成功响应示例

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

##### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 响应状态码，200表示成功 |
| msg | String | 响应消息 |
| data.taskId | String | 任务ID，用于后续查询任务状态 |
| data.totalCount | Integer | 总订单数 |
| data.estimatedSeconds | Integer | 预计耗时（秒） |
| data.status | String | 任务状态：PENDING-待处理 |
| data.message | String | 提示信息 |

---

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

#### 2.1 基本信息
- **接口名称**：查询批量任务状态
- **接口路径**：`后端地址/production/autoComplete/taskStatus/{taskId}`
- **请求方法**：GET
- **认证方式**：无需认证（已配置匿名访问）

#### 2.2 请求参数

##### 路径参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| taskId | String | 是 | 任务ID，由提交接口返回 |

##### 请求示例

```
GET /production/autoComplete/taskStatus/TASK_20260224_001
```

#### 2.3 响应结果

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

```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "taskId": "TASK_20260224_001",
    "status": "PROCESSING",
    "totalCount": 50,
    "processedCount": 25,
    "successCount": 23,
    "failedCount": 2,
    "completedCount": 0,
    "percentage": 50,
    "startTime": "2026-02-24 10:00:00",
    "estimatedSeconds": 50,
    "elapsedSeconds": 25,
    "message": "正在处理中，已完成50%"
  }
}
```

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

```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "taskId": "TASK_20260224_001",
    "status": "COMPLETED",
    "totalCount": 50,
    "processedCount": 50,
    "successCount": 48,
    "failedCount": 2,
    "completedCount": 0,
    "percentage": 100,
    "startTime": "2026-02-24 10:00:00",
    "endTime": "2026-02-24 10:00:52",
    "estimatedSeconds": 50,
    "elapsedSeconds": 52,
    "message": "任务已完成",
    "result": {
      "successOrders": ["SO001", "SO002", "..."],
      "failedOrders": ["SO025", "SO038"],
      "completedOrders": [],
      "failureReasons": {
        "SO025": "订单不存在",
        "SO038": "物料未配置工序路线"
      }
    }
  }
}
```

##### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 响应状态码，200表示成功 |
| msg | String | 响应消息 |
| data.taskId | String | 任务ID |
| data.status | String | 任务状态：PENDING-待处理/PROCESSING-处理中/COMPLETED-已完成/FAILED-失败 |
| data.totalCount | Integer | 总订单数 |
| data.processedCount | Integer | 已处理数量 |
| data.successCount | Integer | 成功数量 |
| data.failedCount | Integer | 失败数量 |
| data.completedCount | Integer | 已完成（跳过）数量 |
| data.percentage | Integer | 完成百分比（0-100） |
| data.startTime | String | 开始时间 |
| data.endTime | String | 结束时间（仅完成时有值） |
| data.estimatedSeconds | Integer | 预计耗时（秒） |
| data.elapsedSeconds | Integer | 已耗时（秒） |
| data.message | String | 状态描述信息 |
| data.result | Object | 详细结果（仅完成时有值） |
| data.result.successOrders | Array<String> | 成功处理的订单编号列表 |
| data.result.failedOrders | Array<String> | 处理失败的订单编号列表 |
| data.result.completedOrders | Array<String> | 已完成（跳过）的订单编号列表 |
| data.result.failureReasons | Map<String, String> | 失败原因映射 |


#### 2.4 错误响应

##### 任务不存在

```json
{
  "code": 500,
  "msg": "任务不存在"
}
```

---

## 业务流程

### 3.1 异步处理流程

```
客户端                    服务端                     数据库
  |                        |                          |
  |--1.提交批量请求------->|                          |
  |                        |--2.创建任务记录--------->|
  |                        |                          |
  |<--3.返回任务ID---------|                          |
  |                        |                          |
  |                        |--4.异步执行任务--------->|
  |                        |   (后台线程池)           |
  |                        |                          |
  |--5.查询任务状态------->|                          |
  |                        |--6.查询任务记录--------->|
  |<--7.返回当前进度-------|<--返回任务数据-----------|
  |                        |                          |
  |--8.再次查询状态------->|                          |
  |                        |--9.查询任务记录--------->|
  |<--10.返回完成结果------|<--返回完成数据-----------|
```

### 3.2 详细处理步骤

#### 步骤1：提交任务（同步，<1秒）

1. **参数验证**
   - 验证订单编号列表不为空
   - 过滤无效的订单编号（null或空字符串）

2. **创建任务记录**
   - 生成唯一任务ID（格式：TASK_yyyyMMdd_HHmmss_随机数）
   - 计算预计耗时（订单数 × 1秒）
   - 初始化任务状态为 PENDING
   - 写入数据库

3. **立即返回**
   - 返回任务ID、总订单数、预计耗时
   - 客户端收到响应，可以开始轮询查询状态

#### 步骤2：异步执行（后台线程池）

1. **更新任务状态为 PROCESSING**
   - 记录开始时间
   - 写入数据库

2. **循环处理订单**
   - 验证订单是否存在
   - 检查订单状态（已完成的订单会跳过）
   - 根据订单类型（连续制造/离散制造）执行不同流程
   - 生成工单、报工单
   - 更新工单状态

3. **批量更新进度（每5个订单）**
   - 更新 processedCount、successCount、failedCount
   - 写入数据库
   - 减少数据库写入频率，提升性能

4. **任务完成**
   - 更新任务状态为 COMPLETED 或 FAILED
   - 记录结束时间
   - 保存完整结果数据（JSON格式）
   - 写入数据库

#### 步骤3：查询任务状态（同步，<100ms）

1. **根据任务ID查询数据库**
2. **计算实时数据**
   - 完成百分比 = (processedCount / totalCount) × 100
   - 已耗时 = 当前时间 - 开始时间
3. **返回任务状态和进度**

### 3.3 数据库更新策略

为了平衡性能和实时性，采用**批量更新策略**：

| 更新时机 | 说明 | 频率 |
|---------|------|------|
| 任务创建 | 初始化任务记录 | 1次 |
| 任务开始 | 更新状态为PROCESSING | 1次 |
| 处理过程 | 每处理5个订单更新一次进度 | N/5次 |
| 任务完成 | 更新状态为COMPLETED，保存完整结果 | 1次 |
| 任务失败 | 更新状态为FAILED，保存错误信息 | 1次 |

**示例**：处理50个订单
- 总更新次数：1（创建）+ 1（开始）+ 10（进度）+ 1（完成）= 13次
- 相比实时更新（53次），减少了75%的数据库写入

### 3.4 订单处理流程

#### 连续制造流程
1. 为每个订单明细生成工单
2. 生成默认工序配置
3. 批量生成报工单
4. 更新工单状态为"已完成"

#### 离散制造流程
1. 为每个订单明细生成工单
2. 生成默认工序配置
3. 批量生成报工单
4. 更新工单状态为"已完成"

### 3.5 订单状态说明

| 状态 | 说明 | 处理方式 |
|------|------|----------|
| 待生产 | 订单未开始生产 | 正常处理 |
| 生产中 | 订单正在生产 | 正常处理 |
| 已完成 | 订单已完成 | 跳过处理，计入completedCount |
| 已删除 | 订单已删除 | 返回错误 |

### 3.6 工序路线选择逻辑

1. 如果请求中指定了`routeId`，优先使用指定的路线
2. 如果订单明细中配置了路线，使用明细配置的路线
3. 如果物料配置了默认路线，使用物料默认路线
4. 如果以上都没有，返回错误

## 性能说明

### 4.1 执行时长估算

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

**说明**：
- 单个订单平均处理时间：1秒（包含生成工单、报工单、更新状态）
- 实际耗时可能因服务器性能、数据库负载而有所差异

### 4.2 并发限制

- **线程池大小**：10个线程
- **最大并发任务数**：10个
- **任务队列长度**：100个
- **超过限制时**：新任务会进入队列等待

### 4.3 超时设置

- **单个任务最大执行时间**：5分钟（300秒）
- **超时后**：任务状态标记为FAILED
- **建议**：单次批量不超过100个订单

---

## 注意事项

### 5.1 性能考虑

- 建议单次批量处理的订单数量不超过100个
- 大批量处理建议分批调用
- 查询状态的轮询间隔建议3-5秒

### 5.2 事务处理

- 每个订单的处理是独立的事务
- 单个订单失败不会影响其他订单的处理
- 任务记录的更新是独立事务

### 5.3 幂等性

- 已完成的订单会被跳过，不会重复处理
- 可以安全地重复调用接口
- 相同订单号不会重复生成工单

### 5.4 匿名访问

- 该接口已配置为允许匿名访问
- 系统会自动使用"system"用户进行数据创建和更新
- 无需传递token或其他认证信息

### 5.5 日志记录

- 所有操作都会记录详细日志
- 建议在生产环境中监控日志以便排查问题
- 任务失败时会记录详细的错误信息

### 5.6 日志记录

- 所有操作都会记录详细日志
- 建议在生产环境中监控日志以便排查问题
- 任务失败时会记录详细的错误信息

---


---

## 为什么必须使用异步模式？

### 同步方式的严重问题

如果不使用异步批量处理方法，而是用同步方式处理大批量订单，会带来以下严重问题：

### 1. HTTP超时问题 ⚠️ 严重

**问题描述**：
- 假设处理50个订单需要50秒
- 大多数HTTP客户端默认超时时间：30-60秒
- Nginx/负载均衡器默认超时：60秒
- 浏览器默认超时：通常2分钟

**后果**：
```
客户端发送请求 → 服务器开始处理50个订单
↓
30秒后...客户端超时断开连接
↓
服务器还在继续处理（已经处理了30个）
↓
客户端收到：504 Gateway Timeout 或 Connection Reset
↓
客户端不知道：订单到底处理了多少？成功了多少？
```

**实际影响**：
- ❌ 客户端认为请求失败，但服务器可能已经处理了部分订单
- ❌ 无法知道哪些订单成功，哪些失败
- ❌ 可能重复提交，导致数据重复
- ❌ 用户体验极差，不知道发生了什么

### 2. 数据库连接占用 ⚠️ 严重

**问题描述**：
- 同步处理会长时间占用数据库连接
- 处理50个订单可能需要50秒
- 这期间数据库连接一直被占用

**后果**：
```
数据库连接池大小：20个连接
↓
10个客户端同时提交批量请求（每个50个订单）
↓
10个连接被占用50秒
↓
其他正常业务请求无法获取连接
↓
整个系统卡死！
```

**实际影响**：
- ❌ 数据库连接池耗尽
- ❌ 其他业务功能无法使用
- ❌ 系统整体性能下降
- ❌ 可能导致系统崩溃

### 3. 线程阻塞问题 ⚠️ 严重

**问题描述**：
- Tomcat默认最大线程数：200
- 每个同步请求占用一个线程直到完成

**后果**：
```
Tomcat线程池：200个线程
↓
20个客户端同时提交批量请求（每个处理50秒）
↓
20个线程被阻塞50秒
↓
如果有100个这样的请求...
↓
所有线程被占满，新请求无法处理
↓
系统完全无响应！
```

**实际影响**：
- ❌ 线程池耗尽
- ❌ 新请求被拒绝（503 Service Unavailable）
- ❌ 系统无法处理任何请求
- ❌ 需要重启服务器才能恢复

### 4. 用户体验问题 ⚠️ 中等

**问题描述**：
- 用户点击提交后，页面一直转圈
- 50秒内无法做任何操作
- 不知道进度，不知道还要等多久

**后果**：
```
用户点击提交
↓
页面loading...
↓
10秒...20秒...30秒...
↓
用户：是不是卡死了？要不要刷新？
↓
用户刷新页面或关闭浏览器
↓
但服务器还在处理...
↓
数据可能处理了一半，状态不一致
```

**实际影响**：
- ❌ 用户体验极差
- ❌ 用户不知道进度
- ❌ 容易误操作（刷新、重复提交）
- ❌ 客户投诉增加

### 5. 事务管理问题 ⚠️ 中等

**问题描述**：
- 如果50个订单在一个事务中
- 第49个订单失败，前48个都要回滚

**后果**：
```
开始事务
↓
处理订单1...成功
处理订单2...成功
...
处理订单48...成功
处理订单49...失败！
↓
整个事务回滚
↓
前48个订单的工作全部白做
↓
浪费了48秒的处理时间
```

**实际影响**：
- ❌ 一个订单失败，全部失败
- ❌ 无法部分成功
- ❌ 处理效率低下
- ❌ 资源浪费

### 6. 无法监控和追踪 ⚠️ 中等

**问题描述**：
- 同步处理无法查询进度
- 不知道处理到第几个订单
- 出错后无法定位问题

**后果**：
```
提交50个订单
↓
处理中...（黑盒）
↓
30秒后超时
↓
问题：
- 处理了多少个？不知道
- 哪些成功了？不知道
- 哪些失败了？不知道
- 为什么失败？不知道
```

**实际影响**：
- ❌ 无法追踪进度
- ❌ 问题难以排查
- ❌ 无法提供客户支持
- ❌ 数据状态不明确

### 7. 系统稳定性问题 ⚠️ 严重

**问题描述**：
- 大批量同步请求会导致系统资源耗尽
- 可能引发雪崩效应

**后果**：
```
高峰期：100个客户端同时提交批量请求
↓
线程池满 + 数据库连接池满
↓
系统响应变慢
↓
客户端超时重试
↓
更多请求涌入
↓
系统完全崩溃
↓
需要紧急重启
```

**实际影响**：
- ❌ 系统不稳定
- ❌ 容易崩溃
- ❌ 影响所有用户
- ❌ 需要人工干预

### 8. 扩展性问题 ⚠️ 中等

**问题描述**：
- 同步方式无法应对业务增长
- 订单量增加时系统无法承受

**后果**：
```
现在：每次处理50个订单
↓
业务增长：每次需要处理200个订单
↓
处理时间：200秒（3分20秒）
↓
必然超时，系统无法使用
↓
需要重新设计架构
```

**实际影响**：
- ❌ 无法应对业务增长
- ❌ 需要重构代码
- ❌ 技术债务增加
- ❌ 开发成本增加

---

## 同步 vs 异步对比

### 性能对比表

| 问题 | 同步方式 | 异步方式 |
|------|---------|---------|
| HTTP超时 | ❌ 必然超时（>30秒） | ✅ 立即返回（<1秒） |
| 数据库连接 | ❌ 长时间占用（50秒） | ✅ 短时间占用（<1秒） |
| 线程阻塞 | ❌ 长时间阻塞（50秒） | ✅ 立即释放（<1秒） |
| 用户体验 | ❌ 长时间等待，无反馈 | ✅ 立即响应，可查询进度 |
| 事务管理 | ❌ 全部回滚，一个失败全失败 | ✅ 独立事务，部分成功 |
| 进度追踪 | ❌ 无法追踪，黑盒处理 | ✅ 实时查询进度和结果 |
| 系统稳定性 | ❌ 容易崩溃，资源耗尽 | ✅ 稳定可靠，资源可控 |
| 扩展性 | ❌ 无法扩展，订单量增加即崩溃 | ✅ 易于扩展，支持大批量 |
| 错误处理 | ❌ 难以定位，状态不明 | ✅ 详细错误信息和原因 |
| 并发能力 | ❌ 极差，10个请求即可拖垮系统 | ✅ 优秀，支持高并发 |

### 实际场景对比

**场景**: 10个客户端同时提交50个订单

#### 同步方式：
```
每个请求耗时：50秒
占用线程：10个（持续50秒）
占用数据库连接：10个（持续50秒）
用户等待时间：50秒
超时风险：100%
系统可用性：严重下降
其他业务影响：严重（连接池和线程池被占用）
```

#### 异步方式：
```
每个请求耗时：<1秒（立即返回）
占用线程：10个（持续<1秒）
占用数据库连接：10个（持续<1秒）
用户等待时间：<1秒（可查询进度）
超时风险：0%
系统可用性：正常
其他业务影响：无（资源立即释放）
```

### 资源占用对比图

```
同步方式资源占用：
时间轴：0s -------- 10s -------- 20s -------- 30s -------- 40s -------- 50s
线程：  ████████████████████████████████████████████████████████ (持续占用)
连接：  ████████████████████████████████████████████████████████ (持续占用)
用户：  ⏳等待中...................................................

异步方式资源占用：
时间轴：0s - 1s
线程：  █ (立即释放)
连接：  █ (立即释放)
用户：  ✅已收到任务ID，可查询进度

后台处理：
时间轴：0s -------- 10s -------- 20s -------- 30s -------- 40s -------- 50s
线程：  ████████████████████████████████████████████████████████ (后台线程池)
连接：  █ █ █ █ █ █ █ █ █ █ (批量更新，间歇占用)
用户：  ✅可随时查询进度：20%...40%...60%...80%...100%
```

---

## 异步模式的核心优势

### 1. 立即响应
- ✅ 接口在1秒内返回任务ID
- ✅ 用户无需等待
- ✅ 不会超时

### 2. 进度可追踪
- ✅ 实时查询处理进度（百分比）
- ✅ 查看成功/失败数量
- ✅ 获取详细错误信息

### 3. 资源高效利用
- ✅ HTTP线程立即释放
- ✅ 数据库连接短时间占用
- ✅ 后台线程池统一管理

### 4. 部分成功机制
- ✅ 单个订单失败不影响其他订单
- ✅ 独立事务，可部分成功
- ✅ 详细记录每个订单的处理结果

### 5. 系统稳定性
- ✅ 不会因大批量请求导致系统崩溃
- ✅ 线程池和连接池可控
- ✅ 支持高并发场景

### 6. 易于扩展
- ✅ 订单量增加不影响系统稳定性
- ✅ 可通过调整线程池大小扩展
- ✅ 支持未来业务增长

---

## 结论

**强烈建议使用异步模式！**

异步批量处理是处理大批量、长时间任务的行业标准做法。不使用异步方式会导致：

1. ❌ **系统不可用** - HTTP超时、线程阻塞、连接池耗尽
2. ❌ **用户体验差** - 长时间等待、无进度反馈
3. ❌ **数据不一致** - 超时后状态不明确
4. ❌ **无法扩展** - 业务增长后系统崩溃
5. ❌ **运维困难** - 问题难以排查和监控

使用异步模式后：

1. ✅ **系统稳定** - 资源可控，不会崩溃
2. ✅ **用户体验好** - 立即响应，实时进度
3. ✅ **数据一致** - 详细记录，状态明确
4. ✅ **易于扩展** - 支持大批量和高并发
5. ✅ **运维友好** - 完整日志，易于监控