forked from erp-dev/erp
feat: external_order refetch api
This commit is contained in:
320
docs/api_v2_printing_order_sync_external_snapshot.md
Normal file
320
docs/api_v2_printing_order_sync_external_snapshot.md
Normal file
@@ -0,0 +1,320 @@
|
||||
# 按 external_order_id 同步外部订单快照 API
|
||||
|
||||
## 概述
|
||||
|
||||
用于前端按 `external_order_id` 手动触发一次“外部订单快照重拉并覆盖更新本地数据”的操作。
|
||||
|
||||
- **端点**: `POST /api/v2/printing-orders/sync-external-snapshot/`
|
||||
- **认证**: 需要登录
|
||||
- **权限**: 印染工厂用户
|
||||
|
||||
此接口适用于以下场景：
|
||||
|
||||
- 外部订单已同步过一次，但后续外部系统又修改了订单数据
|
||||
- 人工发现本地 `PrintingOrder` / `PrintingJob` 与外部系统不一致
|
||||
- 需要按单号重新拉取该订单当前完整快照并覆盖到本地
|
||||
|
||||
## 同步行为说明
|
||||
|
||||
接口会按以下顺序执行：
|
||||
|
||||
1. 根据 `external_order_id` 查找本地目标 `PrintingOrder`
|
||||
2. 先写入一条同步审计记录，保存同步前本地快照
|
||||
3. 做覆盖前检查
|
||||
4. 调用外部快照接口拉取该订单当前完整 `records`
|
||||
5. 复用现有外部同步映射逻辑，更新或创建本地 `PrintingOrder` / `PrintingJob`
|
||||
6. 删除“本地存在但外部快照已不存在”的旧 `PrintingJob`（仅在安全条件满足时）
|
||||
|
||||
## 覆盖前检查规则
|
||||
|
||||
### 1. 关联销售品时立即失败
|
||||
|
||||
如果目标 `PrintingOrder` 下任意 `PrintingJob` 已关联销售品，则接口会立即失败，不会请求外部快照接口。
|
||||
|
||||
失败时会：
|
||||
|
||||
- 返回 `409 Conflict`
|
||||
- 写入失败审计记录
|
||||
- 在失败原因中明确给出涉及的 `printing_job_ids` 和 `sales_item_ids`
|
||||
|
||||
### 2. 已有工序记录时默认失败
|
||||
|
||||
如果目标 `PrintingOrder` 下存在任意 `PrintingJob` 已有未撤销的工序记录，则默认失败。
|
||||
|
||||
失败时会：
|
||||
|
||||
- 返回 `409 Conflict`
|
||||
- 写入失败审计记录
|
||||
- 提示前端可使用 `allow_reset_stateflow=true` 重试
|
||||
|
||||
### 3. `allow_reset_stateflow=true` 的含义
|
||||
|
||||
当请求体传入：
|
||||
|
||||
```json
|
||||
{
|
||||
"allow_reset_stateflow": true
|
||||
}
|
||||
```
|
||||
|
||||
接口会先撤销目标订单下所有 `PrintingJob` 的未撤销工序记录，然后再执行覆盖同步。
|
||||
|
||||
注意：
|
||||
|
||||
- 默认值是 `false`
|
||||
- 只有在“没有销售品关联”的前提下才会继续执行
|
||||
- 该撤销操作只处理工序状态，不会保留当前流程执行进度
|
||||
|
||||
## 请求
|
||||
|
||||
### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"external_order_id": "KD20432358",
|
||||
"allow_reset_stateflow": false
|
||||
}
|
||||
```
|
||||
|
||||
### 字段说明
|
||||
|
||||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| `external_order_id` | string | 是 | - | 外部订单号 |
|
||||
| `allow_reset_stateflow` | boolean | 否 | `false` | 是否允许先撤销目标订单下已有工序再执行覆盖同步 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:8000/api/v2/printing-orders/sync-external-snapshot/" \
|
||||
-H "Authorization: Token <your-token>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"external_order_id": "KD20432358",
|
||||
"allow_reset_stateflow": false
|
||||
}'
|
||||
```
|
||||
|
||||
## 响应
|
||||
|
||||
### 成功响应 (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "外部订单快照同步成功",
|
||||
"audit_id": 12,
|
||||
"external_order_id": "KD20432358",
|
||||
"printing_order_id": 55,
|
||||
"orders_created": 0,
|
||||
"orders_updated": 1,
|
||||
"jobs_created": 1,
|
||||
"jobs_updated": 2,
|
||||
"jobs_deleted": 1,
|
||||
"reset_stateflow_job_count": 0
|
||||
}
|
||||
```
|
||||
|
||||
### 成功响应字段说明
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `detail` | string | 结果说明 |
|
||||
| `audit_id` | int | 同步审计记录ID |
|
||||
| `external_order_id` | string | 本次同步的外部订单号 |
|
||||
| `printing_order_id` | int | 本地印染订单ID |
|
||||
| `orders_created` | int | 是否创建了新订单，`0` 或 `1` |
|
||||
| `orders_updated` | int | 是否更新了已有订单，`0` 或 `1` |
|
||||
| `jobs_created` | int | 新创建的 `PrintingJob` 数量 |
|
||||
| `jobs_updated` | int | 被更新的 `PrintingJob` 数量 |
|
||||
| `jobs_deleted` | int | 被删除的旧 `PrintingJob` 数量 |
|
||||
| `reset_stateflow_job_count` | int | 本次先撤销工序的 `PrintingJob` 数量 |
|
||||
|
||||
## 错误响应
|
||||
|
||||
### 1. 参数错误 (400 Bad Request)
|
||||
|
||||
#### `external_order_id` 为空
|
||||
|
||||
```json
|
||||
{
|
||||
"external_order_id": ["external_order_id 不能为空"]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 未认证 (401 Unauthorized)
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "Authentication credentials were not provided."
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 无权限 (403 Forbidden)
|
||||
|
||||
当用户不是印染工厂用户时：
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "您没有访问印染订单的权限"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 外部订单不存在 (404 Not Found)
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "未找到该 external_order_id 对应的订单",
|
||||
"audit_id": 13,
|
||||
"external_order_id": "KD-NOT-FOUND"
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 即使外部未命中，也会创建失败审计记录
|
||||
- 可通过 `audit_id` 关联后端审计信息
|
||||
|
||||
### 5. 目标订单下已有销售品，禁止覆盖 (409 Conflict)
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "目标订单存在已关联销售品的 printing_job，禁止覆盖同步。 printing_job_ids=[101], sales_item_ids=[201]",
|
||||
"audit_id": 14,
|
||||
"external_order_id": "KD20432358"
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 这是最优先的阻断条件
|
||||
- 一旦命中，不会继续请求外部快照接口
|
||||
|
||||
### 6. 目标订单下已有工序记录，默认禁止覆盖 (409 Conflict)
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "目标订单存在已执行工序的 printing_job，默认不允许覆盖同步。 如确认要覆盖，请传 allow_reset_stateflow=true。 printing_job_ids=[101]",
|
||||
"audit_id": 15,
|
||||
"external_order_id": "KD20432358"
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 当前端收到这类错误时，可以提示用户确认是否改用 `allow_reset_stateflow=true` 再次发起请求
|
||||
|
||||
### 7. 旧明细存在业务引用，无法删除 (409 Conflict)
|
||||
|
||||
在外部快照同步阶段，如果发现本地“待删除旧明细”仍被其他业务引用，也会失败：
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "以下待删除 printing_job 已关联销售单明细，禁止覆盖同步: [102]",
|
||||
"audit_id": 16,
|
||||
"external_order_id": "KD20432358"
|
||||
}
|
||||
```
|
||||
|
||||
## 审计说明
|
||||
|
||||
每次请求都会生成一条审计记录，无论成功还是失败。
|
||||
|
||||
当前审计记录包含：
|
||||
|
||||
- `external_order_id`
|
||||
- 操作者 `request.user`
|
||||
- 操作员工 `request.user.employee`
|
||||
- 同步前本地订单与明细快照（JSON）
|
||||
- 本次是否允许撤销工序
|
||||
- 是否成功
|
||||
- 失败原因
|
||||
|
||||
前端当前只会收到：
|
||||
|
||||
- `audit_id`
|
||||
|
||||
如果后续需要展示详细审计记录，需要后端再补充查询接口。
|
||||
|
||||
## 前端使用建议
|
||||
|
||||
### 普通重同步
|
||||
|
||||
默认先使用：
|
||||
|
||||
```json
|
||||
{
|
||||
"external_order_id": "KD20432358"
|
||||
}
|
||||
```
|
||||
|
||||
### 当后端提示存在工序记录时
|
||||
|
||||
可以提示用户：
|
||||
|
||||
- 覆盖同步会先撤销当前流程进度
|
||||
- 是否继续
|
||||
|
||||
用户确认后，再次发送：
|
||||
|
||||
```json
|
||||
{
|
||||
"external_order_id": "KD20432358",
|
||||
"allow_reset_stateflow": true
|
||||
}
|
||||
```
|
||||
|
||||
### 不建议自动重试的情况
|
||||
|
||||
遇到以下错误时，前端不应自动重试：
|
||||
|
||||
- 已关联销售品
|
||||
- 已关联销售单明细
|
||||
- 外部订单不存在
|
||||
|
||||
这些都应提示人工处理。
|
||||
|
||||
## 前端调用示例
|
||||
|
||||
```javascript
|
||||
async function syncExternalSnapshot(externalOrderId, allowResetStateflow = false) {
|
||||
const response = await fetch('/api/v2/printing-orders/sync-external-snapshot/', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
Authorization: `Token ${token}`,
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
body: JSON.stringify({
|
||||
external_order_id: externalOrderId,
|
||||
allow_reset_stateflow: allowResetStateflow,
|
||||
}),
|
||||
});
|
||||
|
||||
const data = await response.json();
|
||||
|
||||
if (!response.ok) {
|
||||
const error = new Error(data.detail || '同步失败');
|
||||
error.status = response.status;
|
||||
error.auditId = data.audit_id;
|
||||
error.externalOrderId = data.external_order_id;
|
||||
throw error;
|
||||
}
|
||||
|
||||
return data;
|
||||
}
|
||||
|
||||
// 示例：先按默认模式重同步
|
||||
try {
|
||||
const result = await syncExternalSnapshot('KD20432358');
|
||||
console.log('同步成功', result);
|
||||
} catch (error) {
|
||||
// 如果提示需要 allow_reset_stateflow=true，再由用户二次确认
|
||||
console.error(error.message, error.auditId);
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文件
|
||||
|
||||
- 路由: [api_v2/urls.py](/home/f/coding/flower/api_v2/urls.py)
|
||||
- 视图: [api_v2/views/printing.py](/home/f/coding/flower/api_v2/views/printing.py)
|
||||
- 核心同步逻辑: [api_v1/tasks.py](/home/f/coding/flower/api_v1/tasks.py)
|
||||
- 审计模型: [printing/models.py](/home/f/coding/flower/printing/models.py)
|
||||
Reference in New Issue
Block a user