1304 lines
21 KiB
Markdown
1304 lines
21 KiB
Markdown
# 前端 API 文档（基于《系统设计方案.md》）
|
||
|
||
> 版本依据：`系统设计方案.md` V2.4（2026-05-01，最终生产版·固定槽位与批量补料）
|
||
> 适用对象：React 前端、API 对接、联调、后续接口生成
|
||
> 说明：本文描述目标设计契约，不以当前过渡期 `apis/*.api` 的实现为准。若当前实现与本文不一致，应以本文作为后续对齐目标。
|
||
|
||
---
|
||
|
||
## 1. 通用约定
|
||
|
||
### 1.1 Base URL
|
||
|
||
```text
|
||
/api/v1
|
||
```
|
||
|
||
### 1.2 鉴权
|
||
|
||
除登录、刷新 token 外，所有接口默认需要登录态。
|
||
|
||
```http
|
||
Authorization: <accessToken>
|
||
```
|
||
|
||
### 1.3 时间格式
|
||
|
||
前端统一按 ISO 8601 字符串处理时间。
|
||
|
||
```ts
|
||
type ISODateTime = string // 例：2026-05-01T10:30:00+08:00
|
||
```
|
||
|
||
### 1.4 分页参数
|
||
|
||
```ts
|
||
interface PageReq {
|
||
page?: number // 默认 1
|
||
limit?: number // 默认 10，最大 100
|
||
}
|
||
|
||
interface PageReply {
|
||
page: number
|
||
limit: number
|
||
total: number
|
||
}
|
||
```
|
||
|
||
### 1.5 排序参数
|
||
|
||
```ts
|
||
interface SortReq {
|
||
sort?: string
|
||
order?: 'asc' | 'desc' | 'ascend' | 'descend'
|
||
}
|
||
```
|
||
|
||
### 1.6 通用响应 envelope
|
||
|
||
目标设计建议前端统一按如下响应格式接入；如果后端某些接口仍返回裸数据，需要在请求封装层兼容。
|
||
|
||
```ts
|
||
interface ApiResponse<T> {
|
||
code: number
|
||
message: string
|
||
data: T
|
||
}
|
||
```
|
||
|
||
成功：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "ok",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
失败：
|
||
|
||
```json
|
||
{
|
||
"code": 40001,
|
||
"message": "工件状态不允许执行该操作",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 核心枚举
|
||
|
||
### 2.1 工单状态 `WorkOrderStatus`
|
||
|
||
```ts
|
||
type WorkOrderStatus =
|
||
| 'CREATED'
|
||
| 'IN_PROGRESS'
|
||
| 'PAUSED'
|
||
| 'COMPLETED'
|
||
| 'CANCELLED'
|
||
| 'ERROR'
|
||
```
|
||
|
||
### 2.2 工件状态 `JobStatus`
|
||
|
||
来自设计第 7.1 节。
|
||
|
||
```ts
|
||
type JobStatus =
|
||
| 'CREATED'
|
||
| 'IN_HANDLING'
|
||
| 'PROCESSING'
|
||
| 'WAITING_UNLOAD'
|
||
| 'ON_BUFFER'
|
||
| 'WAITING_DECISION'
|
||
| 'COMPLETED'
|
||
| 'SCRAPPED'
|
||
| 'SUSPENDED'
|
||
```
|
||
|
||
### 2.3 工件位置类型 `PositionType`
|
||
|
||
```ts
|
||
type PositionType = 'ON_EQUIPMENT' | 'ON_BUFFER' | 'IN_HAND'
|
||
```
|
||
|
||
### 2.4 设备状态 `StationStatus`
|
||
|
||
```ts
|
||
type StationStatus = 'IDLE' | 'BUSY' | 'WAITING' | 'FAULT' | 'OFFLINE'
|
||
```
|
||
|
||
### 2.5 任务状态 `TaskStatus`
|
||
|
||
来自设计第 9 节。
|
||
|
||
```ts
|
||
type TaskStatus =
|
||
| 'CREATED'
|
||
| 'DISPATCHED'
|
||
| 'RUNNING'
|
||
| 'SUCCESS'
|
||
| 'FAILED'
|
||
| 'TIMEOUT'
|
||
```
|
||
|
||
### 2.6 工序类型 `RecipeStepType`
|
||
|
||
来自设计第 5.1 节。
|
||
|
||
```ts
|
||
type RecipeStepType =
|
||
| 'LOAD'
|
||
| 'BUFFER_STAGE'
|
||
| 'MACHINING'
|
||
| 'UNLOAD'
|
||
| 'WASH'
|
||
| 'INSPECTION'
|
||
| 'JUDGE'
|
||
| 'DEBURR'
|
||
| 'RUST_WASH'
|
||
| 'FINAL_SCAN'
|
||
| 'LASER_MARK'
|
||
| 'DECISION'
|
||
| 'PLACE_SAMPLING'
|
||
| 'PLACE_AGV'
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 登录与当前用户
|
||
|
||
### 3.1 登录
|
||
|
||
```http
|
||
POST /api/v1/login
|
||
```
|
||
|
||
请求：
|
||
|
||
```ts
|
||
interface LoginReq {
|
||
username: string
|
||
password: string
|
||
captchaId?: string
|
||
captchaCode?: string
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface TokenReply {
|
||
accessToken: string
|
||
accessExpire: number
|
||
refreshToken: string
|
||
refreshExpire: number
|
||
}
|
||
```
|
||
|
||
### 3.2 刷新 token
|
||
|
||
```http
|
||
POST /api/v1/refreshToken
|
||
```
|
||
|
||
请求：
|
||
|
||
```ts
|
||
interface RefreshTokenReq {
|
||
refreshToken: string
|
||
}
|
||
```
|
||
|
||
响应：`TokenReply`
|
||
|
||
### 3.3 当前用户信息
|
||
|
||
```http
|
||
GET /api/v1/userinfo
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface UserInfoReply {
|
||
id: number
|
||
name: string
|
||
username: string
|
||
mobile: string
|
||
gender: number
|
||
roleId: number
|
||
roleName: string
|
||
deptId: number
|
||
deptName: string
|
||
position: string
|
||
status: number
|
||
createdAt: number
|
||
updatedAt: number
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 产品类型与工艺路线
|
||
|
||
设计依据：第 1.1 节机床绑定关系、第 5 节工艺路线定义、第 6.1 节 `product_type/recipe/recipe_step`。
|
||
|
||
### 4.1 产品类型列表
|
||
|
||
```http
|
||
GET /api/v1/product-types/list
|
||
```
|
||
|
||
查询：
|
||
|
||
```ts
|
||
interface ListProductTypesReq {
|
||
keyword?: string
|
||
activeOnly?: boolean
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface ProductTypeReply {
|
||
id: string // 例：A6VM107
|
||
code: string
|
||
name: string
|
||
recipeId: string
|
||
cncMachineIds: string[] // 例：['CNC_3', 'CNC_4']
|
||
isActive: boolean
|
||
remark: string
|
||
}
|
||
```
|
||
|
||
### 4.2 产品类型详情
|
||
|
||
```http
|
||
GET /api/v1/product-types/:id
|
||
```
|
||
|
||
响应：`ProductTypeReply`
|
||
|
||
### 4.3 工艺路线详情
|
||
|
||
```http
|
||
GET /api/v1/recipes/:id
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface RecipeReply {
|
||
id: string
|
||
name: string
|
||
version: number
|
||
steps: RecipeStepReply[]
|
||
}
|
||
|
||
interface RecipeStepReply {
|
||
stepId: string
|
||
stepName: string
|
||
stepType: RecipeStepType
|
||
resourceType?: string
|
||
toolType?: 'SCANNER' | 'LASER'
|
||
allowedResources?: string[]
|
||
processingParams?: Record<string, unknown>
|
||
nextStepDefault?: string
|
||
nextStepBranches?: Record<string, string>
|
||
stepTimeout?: number
|
||
description?: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 工单管理
|
||
|
||
设计依据：第 10 节。
|
||
|
||
### 5.1 工单分页列表
|
||
|
||
```http
|
||
GET /api/v1/work-orders
|
||
```
|
||
|
||
查询：
|
||
|
||
```ts
|
||
interface QueryWorkOrdersReq extends PageReq, SortReq {
|
||
keyword?: string
|
||
statuses?: WorkOrderStatus[]
|
||
productTypeId?: string
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface QueryWorkOrdersReply extends PageReply {
|
||
data: WorkOrderReply[]
|
||
}
|
||
|
||
interface WorkOrderReply {
|
||
id: string
|
||
no: string
|
||
productTypeId: string
|
||
quantity: number
|
||
finishedNum: number
|
||
failNum: number
|
||
status: WorkOrderStatus
|
||
sourceBaySlotId?: string
|
||
context?: Record<string, unknown>
|
||
createdTime: ISODateTime
|
||
updatedTime: ISODateTime
|
||
completedTime?: ISODateTime
|
||
}
|
||
```
|
||
|
||
### 5.2 工单详情
|
||
|
||
```http
|
||
GET /api/v1/work-orders/:id
|
||
```
|
||
|
||
响应：`WorkOrderReply`
|
||
|
||
### 5.3 创建工单
|
||
|
||
```http
|
||
POST /api/v1/work-orders
|
||
```
|
||
|
||
请求：
|
||
|
||
```ts
|
||
interface CreateWorkOrderReq {
|
||
productTypeId: string
|
||
quantity: number
|
||
dockSlots: string[] // 格式：dockNo.slotNo，例如 '1.3'
|
||
context?: Record<string, unknown>
|
||
remark?: string
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface CreateWorkOrderReply {
|
||
id: string
|
||
}
|
||
```
|
||
|
||
### 5.4 更新工单
|
||
|
||
```http
|
||
PUT /api/v1/work-orders/:id
|
||
```
|
||
|
||
请求：
|
||
|
||
```ts
|
||
interface UpdateWorkOrderReq {
|
||
productTypeId?: string
|
||
quantity?: number
|
||
remark?: string
|
||
context?: Record<string, unknown>
|
||
}
|
||
```
|
||
|
||
### 5.5 开始工单
|
||
|
||
```http
|
||
POST /api/v1/work-orders/:id/start
|
||
```
|
||
|
||
效果：工单进入 `IN_PROGRESS`，触发初始补料/调度。
|
||
|
||
### 5.6 暂停工单
|
||
|
||
```http
|
||
POST /api/v1/work-orders/:id/pause
|
||
```
|
||
|
||
效果：只修改工单为 `PAUSED`，调度过滤层排除该工单，不污染工件状态。
|
||
|
||
### 5.7 恢复工单
|
||
|
||
```http
|
||
POST /api/v1/work-orders/:id/resume
|
||
```
|
||
|
||
效果：工单从 `PAUSED` 回到 `IN_PROGRESS`，调度重新纳入。
|
||
|
||
### 5.8 断电恢复工单
|
||
|
||
```http
|
||
POST /api/v1/work-orders/:id/restore
|
||
```
|
||
|
||
效果：按设计第 15 节恢复等级执行恢复。
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface RestoreWorkOrderReply {
|
||
orderId: string
|
||
restoredJobs: number
|
||
level: 'L1' | 'L2' | 'L3'
|
||
manualRequired: boolean
|
||
message?: string
|
||
}
|
||
```
|
||
|
||
### 5.9 取消工单
|
||
|
||
```http
|
||
POST /api/v1/work-orders/:id/cancel
|
||
```
|
||
|
||
效果：终止未完成工件，释放可释放资源。
|
||
|
||
### 5.10 删除工单
|
||
|
||
```http
|
||
DELETE /api/v1/work-orders/:id
|
||
```
|
||
|
||
约束：仅允许删除未运行或已终态工单。
|
||
|
||
---
|
||
|
||
## 6. 工件 / Job 管理
|
||
|
||
设计依据：第 6.2 节 `job`，第 7 节工件生命周期。
|
||
|
||
### 6.1 工件分页列表
|
||
|
||
```http
|
||
GET /api/v1/jobs
|
||
```
|
||
|
||
查询：
|
||
|
||
```ts
|
||
interface QueryJobsReq extends PageReq, SortReq {
|
||
keyword?: string
|
||
workOrderId?: string
|
||
productTypeId?: string
|
||
statuses?: JobStatus[]
|
||
positionType?: PositionType
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface QueryJobsReply extends PageReply {
|
||
data: JobReply[]
|
||
}
|
||
|
||
interface JobReply {
|
||
id: string
|
||
workOrderId: string
|
||
workpieceNo: string
|
||
productTypeId: string
|
||
recipeId: string
|
||
currentStepId: string
|
||
currentStepName: string
|
||
status: JobStatus
|
||
positionType: PositionType
|
||
positionRefId: string
|
||
priority: number
|
||
suspendedReason?: string
|
||
context?: Record<string, unknown>
|
||
version: number
|
||
createdTime: ISODateTime
|
||
lastUpdated: ISODateTime
|
||
}
|
||
```
|
||
|
||
### 6.2 工单下工件分页
|
||
|
||
```http
|
||
GET /api/v1/work-orders/:id/jobs
|
||
```
|
||
|
||
查询：
|
||
|
||
```ts
|
||
interface QueryJobsOfWorkOrderReq extends PageReq, SortReq {
|
||
statuses?: JobStatus[]
|
||
}
|
||
```
|
||
|
||
响应：`QueryJobsReply`
|
||
|
||
### 6.3 工件详情
|
||
|
||
```http
|
||
GET /api/v1/jobs/:id
|
||
```
|
||
|
||
响应：`JobReply`
|
||
|
||
### 6.4 挂起工件
|
||
|
||
```http
|
||
POST /api/v1/jobs/:id/suspend
|
||
```
|
||
|
||
请求：
|
||
|
||
```ts
|
||
interface SuspendJobReq {
|
||
reason?: string
|
||
}
|
||
```
|
||
|
||
效果：工件进入 `SUSPENDED`。如果当前 `IN_HANDLING` 或设备处理中，按后端策略延迟挂起或要求人工确认。
|
||
|
||
### 6.5 恢复工件
|
||
|
||
```http
|
||
POST /api/v1/jobs/:id/resume
|
||
```
|
||
|
||
效果：从 `SUSPENDED` 恢复到可调度状态。
|
||
|
||
### 6.6 返工工件
|
||
|
||
```http
|
||
POST /api/v1/jobs/:id/rework
|
||
```
|
||
|
||
请求：
|
||
|
||
```ts
|
||
interface ReworkJobReq {
|
||
targetStepId: string
|
||
reason?: string
|
||
}
|
||
```
|
||
|
||
效果：修改 `current_step_id`，新增 `job_step_instance`。
|
||
|
||
---
|
||
|
||
## 7. 看板 / 监控 API
|
||
|
||
设计依据：第 3 节人工终端、第 7 节状态管理、第 11 节工站接口、第 16 节 Redis SSOT。
|
||
|
||
### 7.1 生产线总览
|
||
|
||
```http
|
||
GET /api/v1/dashboard/overview
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface DashboardOverviewReply {
|
||
activeOrderCount: number
|
||
activeJobCount: number
|
||
completedToday: number
|
||
scrappedToday: number
|
||
stationFaultCount: number
|
||
buffer: BufferSummary
|
||
}
|
||
|
||
interface BufferSummary {
|
||
total: number
|
||
occupied: number
|
||
free: number
|
||
needRefill: boolean
|
||
}
|
||
```
|
||
|
||
### 7.2 工站监控
|
||
|
||
```http
|
||
GET /api/v1/stations/monitor
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface StationMonitorReply {
|
||
stations: StationMonitorItem[]
|
||
activeOrders: ActiveOrderSummary[]
|
||
}
|
||
|
||
interface StationMonitorItem {
|
||
id: string // 例：CNC_1、WASHER_1、BUFFER、SAMPLING_1
|
||
type: string
|
||
name: string
|
||
status: StationStatus
|
||
heartbeatOnline: boolean
|
||
currentJobs: StationJobBrief[]
|
||
waitingUnloadJobs: StationJobBrief[]
|
||
updatedAt: ISODateTime
|
||
}
|
||
|
||
interface StationJobBrief {
|
||
jobId: string
|
||
workOrderId: string
|
||
productTypeId: string
|
||
status: JobStatus
|
||
positionRefId: string
|
||
currentStepId: string
|
||
currentStepName: string
|
||
}
|
||
|
||
interface ActiveOrderSummary {
|
||
orderId: string
|
||
orderNo: string
|
||
status: WorkOrderStatus
|
||
productTypeId: string
|
||
totalJobs: number
|
||
completedJobs: number
|
||
scrappedJobs: number
|
||
}
|
||
```
|
||
|
||
> 设计说明：工站对外不暴露内部槽位写接口；前端仅展示 Redis 推导出的当前工件、等待下料工件和设备状态。设备槽位属于后端工站内部实现细节，不作为前端操作入口。
|
||
|
||
### 7.3 暂存台槽位监控
|
||
|
||
```http
|
||
GET /api/v1/buffer/slots
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface BufferSlotsReply {
|
||
slots: BufferSlotReply[]
|
||
occupied: number
|
||
free: number
|
||
total: 8
|
||
refillThreshold: 4
|
||
needRefill: boolean
|
||
}
|
||
|
||
interface BufferSlotReply {
|
||
slotNo: number // 1~8
|
||
occupied: boolean
|
||
job?: JobBrief
|
||
}
|
||
|
||
interface JobBrief {
|
||
id: string
|
||
workOrderId: string
|
||
workpieceNo: string
|
||
productTypeId: string
|
||
status: JobStatus
|
||
currentStepId: string
|
||
currentStepName: string
|
||
}
|
||
```
|
||
|
||
### 7.4 接驳台槽位监控
|
||
|
||
```http
|
||
GET /api/v1/docks/loading/slots
|
||
GET /api/v1/docks/unloading/slots
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface DockSlotsReply {
|
||
docks: DockReply[]
|
||
}
|
||
|
||
interface DockReply {
|
||
dockNo: number
|
||
type: 'LOADING' | 'UNLOADING'
|
||
slots: DockSlotReply[]
|
||
}
|
||
|
||
interface DockSlotReply {
|
||
slotNo: number
|
||
status: 'EMPTY' | 'UNPUBLISHED' | 'PUBLISHED' | 'SCAN_FAILED' | 'PROCESSING' | 'COMPLETED'
|
||
job?: JobBrief
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 调度与任务 API
|
||
|
||
设计依据：第 8 节调度器三层架构、第 9 节任务状态机。
|
||
|
||
### 8.1 当前调度队列
|
||
|
||
```http
|
||
GET /api/v1/scheduler/ready-jobs
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface ReadyJobsReply {
|
||
jobs: ReadyJobReply[]
|
||
}
|
||
|
||
interface ReadyJobReply {
|
||
jobId: string
|
||
workOrderId: string
|
||
status: JobStatus
|
||
priority: number
|
||
reason: string
|
||
queuedAt: ISODateTime
|
||
}
|
||
```
|
||
|
||
### 8.2 当前任务列表
|
||
|
||
```http
|
||
GET /api/v1/tasks
|
||
```
|
||
|
||
查询：
|
||
|
||
```ts
|
||
interface QueryTasksReq extends PageReq, SortReq {
|
||
jobId?: string
|
||
workOrderId?: string
|
||
statuses?: TaskStatus[]
|
||
type?: string
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface QueryTasksReply extends PageReply {
|
||
data: TaskReply[]
|
||
}
|
||
|
||
interface TaskReply {
|
||
id: string
|
||
jobId: string
|
||
type: string
|
||
status: TaskStatus
|
||
fromPos?: PositionRef
|
||
toPos?: PositionRef
|
||
assignedRobot?: string
|
||
startedTime?: ISODateTime
|
||
completedTime?: ISODateTime
|
||
result?: Record<string, unknown>
|
||
}
|
||
|
||
interface PositionRef {
|
||
type: PositionType | 'DOCK' | 'AGV' | 'SAMPLING'
|
||
refId: string
|
||
}
|
||
```
|
||
|
||
### 8.3 任务详情
|
||
|
||
```http
|
||
GET /api/v1/tasks/:id
|
||
```
|
||
|
||
响应：`TaskReply`
|
||
|
||
### 8.4 任务日志
|
||
|
||
```http
|
||
GET /api/v1/work-orders/:id/task-logs
|
||
```
|
||
|
||
查询：
|
||
|
||
```ts
|
||
interface QueryTaskLogsReq extends PageReq, SortReq {
|
||
jobId?: string
|
||
status?: TaskStatus
|
||
taskKind?: string
|
||
startTime?: ISODateTime
|
||
endTime?: ISODateTime
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface QueryTaskLogsReply extends PageReply {
|
||
data: TaskLogReply[]
|
||
}
|
||
|
||
interface TaskLogReply {
|
||
id: number
|
||
workOrderId: string
|
||
jobId: string
|
||
stepId: string
|
||
stepName: string
|
||
taskKind: string
|
||
status: TaskStatus
|
||
content: string
|
||
durationMs: number
|
||
createdAt: ISODateTime
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 人工交互 API
|
||
|
||
设计依据：第 10 节单工件暂存/返工、第 15 节 L3 人工恢复、第 18 节人工终端。
|
||
|
||
### 9.1 待人工处理事项
|
||
|
||
```http
|
||
GET /api/v1/manual-actions
|
||
```
|
||
|
||
查询：
|
||
|
||
```ts
|
||
interface QueryManualActionsReq extends PageReq, SortReq {
|
||
type?: string
|
||
resolved?: boolean
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface QueryManualActionsReply extends PageReply {
|
||
data: ManualActionReply[]
|
||
}
|
||
|
||
interface ManualActionReply {
|
||
id: string
|
||
type: 'SCAN_FAILED' | 'RECOVERY_REQUIRED' | 'INSPECTION_DECISION' | 'FAULT_CONFIRM'
|
||
jobId?: string
|
||
workOrderId?: string
|
||
message: string
|
||
payload?: Record<string, unknown>
|
||
resolved: boolean
|
||
createdAt: ISODateTime
|
||
resolvedAt?: ISODateTime
|
||
}
|
||
```
|
||
|
||
### 9.2 确认扫码失败处理
|
||
|
||
```http
|
||
POST /api/v1/manual-actions/:id/resolve-scan-failed
|
||
```
|
||
|
||
请求：
|
||
|
||
```ts
|
||
interface ResolveScanFailedReq {
|
||
action: 'RETRY_SCAN' | 'RETURN_BAY' | 'SCRAP'
|
||
remark?: string
|
||
}
|
||
```
|
||
|
||
### 9.3 检测结果人工判定
|
||
|
||
```http
|
||
POST /api/v1/jobs/:id/inspection-decision
|
||
```
|
||
|
||
请求：
|
||
|
||
```ts
|
||
interface InspectionDecisionReq {
|
||
result: 'PASS' | 'FAIL'
|
||
needSampling?: boolean
|
||
remark?: string
|
||
}
|
||
```
|
||
|
||
### 9.4 L3 断电恢复人工确认
|
||
|
||
```http
|
||
POST /api/v1/recovery/actions/:id/confirm
|
||
```
|
||
|
||
请求：
|
||
|
||
```ts
|
||
interface ConfirmRecoveryReq {
|
||
decision: 'RESUME' | 'WAIT_UNLOAD' | 'SUSPEND' | 'SCRAP'
|
||
confirmedPosition?: PositionRef
|
||
remark?: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 设备与心跳 API
|
||
|
||
设计依据：第 6.1 节 `equipment`、第 13 节心跳。
|
||
|
||
### 10.1 设备列表
|
||
|
||
```http
|
||
GET /api/v1/equipments
|
||
```
|
||
|
||
查询：
|
||
|
||
```ts
|
||
interface QueryEquipmentsReq extends PageReq, SortReq {
|
||
keyword?: string
|
||
typeCode?: string
|
||
status?: StationStatus
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface QueryEquipmentsReply extends PageReply {
|
||
data: EquipmentReply[]
|
||
}
|
||
|
||
interface EquipmentReply {
|
||
id: string
|
||
typeCode: string
|
||
name: string
|
||
status: StationStatus
|
||
slotCount: number
|
||
ipAddress?: string
|
||
location?: string
|
||
heartbeatOnline: boolean
|
||
lastHeartbeatAt?: ISODateTime
|
||
}
|
||
```
|
||
|
||
### 10.2 设备详情
|
||
|
||
```http
|
||
GET /api/v1/equipments/:id
|
||
```
|
||
|
||
响应：`EquipmentReply`
|
||
|
||
### 10.3 设备心跳状态
|
||
|
||
```http
|
||
GET /api/v1/equipments/:id/heartbeat
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface EquipmentHeartbeatReply {
|
||
equipmentId: string
|
||
online: boolean
|
||
ttlMs: number
|
||
lastHeartbeatAt?: ISODateTime
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 报警与运行校验
|
||
|
||
设计依据：第 14 节运行期状态校验、附录 PLC 错误码。
|
||
|
||
### 11.1 报警分页列表
|
||
|
||
```http
|
||
GET /api/v1/alarms
|
||
```
|
||
|
||
查询：
|
||
|
||
```ts
|
||
interface QueryAlarmsReq extends PageReq, SortReq {
|
||
equipmentId?: string
|
||
level?: 'INFO' | 'WARN' | 'ERROR' | 'CRITICAL'
|
||
resolved?: boolean
|
||
startTime?: ISODateTime
|
||
endTime?: ISODateTime
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface QueryAlarmsReply extends PageReply {
|
||
data: AlarmReply[]
|
||
}
|
||
|
||
interface AlarmReply {
|
||
id: string
|
||
alarmCode: string
|
||
alarmMessage: string
|
||
level: 'INFO' | 'WARN' | 'ERROR' | 'CRITICAL'
|
||
equipmentId?: string
|
||
jobId?: string
|
||
resolved: boolean
|
||
createdAt: ISODateTime
|
||
resolvedAt?: ISODateTime
|
||
}
|
||
```
|
||
|
||
### 11.2 确认报警
|
||
|
||
```http
|
||
POST /api/v1/alarms/:id/ack
|
||
```
|
||
|
||
请求：
|
||
|
||
```ts
|
||
interface AckAlarmReq {
|
||
remark?: string
|
||
}
|
||
```
|
||
|
||
### 11.3 状态一致性校验结果
|
||
|
||
```http
|
||
GET /api/v1/state-checks/latest
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface StateCheckReply {
|
||
checkedAt: ISODateTime
|
||
ok: boolean
|
||
issues: StateCheckIssue[]
|
||
}
|
||
|
||
interface StateCheckIssue {
|
||
type: 'PLC_REDIS_MISMATCH' | 'MISSING_HEARTBEAT' | 'UNKNOWN_POSITION'
|
||
equipmentId?: string
|
||
jobId?: string
|
||
message: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 事件流 API
|
||
|
||
设计依据：第 3 节 WebSocket/HTTP、第 4 节事件总线、第 16 节 Redis Stream。
|
||
|
||
### 12.1 WebSocket 实时事件
|
||
|
||
```text
|
||
WS /api/v1/events/ws
|
||
```
|
||
|
||
前端连接后接收统一事件：
|
||
|
||
```ts
|
||
interface RealtimeEvent<T = unknown> {
|
||
id: string
|
||
entityId: string
|
||
entityVersion: number
|
||
type: RealtimeEventType
|
||
source: string
|
||
timestamp: ISODateTime
|
||
payload: T
|
||
}
|
||
|
||
type RealtimeEventType =
|
||
| 'PALLET_ARRIVED'
|
||
| 'PALLET_REMOVED'
|
||
| 'MACHINE_TASK_COMPLETE'
|
||
| 'ROBOT_ACTION_DONE'
|
||
| 'SCAN_RESULT'
|
||
| 'JOB_STATUS_CHANGED'
|
||
| 'STATION_READY'
|
||
| 'STATION_REQUEST_LOAD'
|
||
| 'INSPECTION_PASS'
|
||
| 'INSPECTION_FAIL'
|
||
| 'SAMPLING_REQUEST'
|
||
| 'SAMPLING_COMPLETE_OK'
|
||
| 'SAMPLING_COMPLETE_NG'
|
||
| 'ROBOT_ERROR'
|
||
```
|
||
|
||
常用 payload：
|
||
|
||
```ts
|
||
interface JobStatusChangedPayload {
|
||
jobId: string
|
||
workOrderId: string
|
||
fromStatus: JobStatus
|
||
toStatus: JobStatus
|
||
positionType: PositionType
|
||
positionRefId: string
|
||
}
|
||
|
||
interface MachineTaskCompletePayload {
|
||
equipmentId: string
|
||
jobId?: string
|
||
slotNo?: number
|
||
}
|
||
|
||
interface ScanResultPayload {
|
||
jobId: string
|
||
success: boolean
|
||
scanCode?: string
|
||
reason?: string
|
||
}
|
||
```
|
||
|
||
### 12.2 SSE 兼容事件流（可选）
|
||
|
||
```http
|
||
GET /api/v1/events/sse
|
||
```
|
||
|
||
返回格式：标准 `text/event-stream`。
|
||
|
||
---
|
||
|
||
## 13. 断电恢复 API
|
||
|
||
设计依据：第 15 节。
|
||
|
||
### 13.1 恢复扫描
|
||
|
||
```http
|
||
POST /api/v1/recovery/scan
|
||
```
|
||
|
||
效果：扫描 Redis/PG/PLC 状态，生成恢复建议。
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface RecoveryScanReply {
|
||
items: RecoveryItem[]
|
||
summary: {
|
||
l1: number
|
||
l2: number
|
||
l3: number
|
||
}
|
||
}
|
||
|
||
interface RecoveryItem {
|
||
id: string
|
||
level: 'L1' | 'L2' | 'L3'
|
||
jobId?: string
|
||
workOrderId?: string
|
||
equipmentId?: string
|
||
currentStatus?: JobStatus
|
||
suggestedAction: string
|
||
manualRequired: boolean
|
||
message: string
|
||
}
|
||
```
|
||
|
||
### 13.2 执行自动恢复
|
||
|
||
```http
|
||
POST /api/v1/recovery/auto-restore
|
||
```
|
||
|
||
请求：
|
||
|
||
```ts
|
||
interface AutoRestoreReq {
|
||
levels?: Array<'L1' | 'L2'>
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface AutoRestoreReply {
|
||
restoredCount: number
|
||
skippedCount: number
|
||
failedItems: Array<{
|
||
id: string
|
||
message: string
|
||
}>
|
||
}
|
||
```
|
||
|
||
### 13.3 事件重放
|
||
|
||
```http
|
||
POST /api/v1/recovery/replay-events
|
||
```
|
||
|
||
请求：
|
||
|
||
```ts
|
||
interface ReplayEventsReq {
|
||
afterEventId?: string
|
||
dryRun?: boolean
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```ts
|
||
interface ReplayEventsReply {
|
||
applied: number
|
||
skipped: number
|
||
lastEventId?: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 14. 前端模块建议
|
||
|
||
建议前端按以下 client 模块组织：
|
||
|
||
```text
|
||
frontend/src/api/auth.ts
|
||
frontend/src/api/product-type.ts
|
||
frontend/src/api/recipe.ts
|
||
frontend/src/api/work-order.ts
|
||
frontend/src/api/job.ts
|
||
frontend/src/api/dashboard.ts
|
||
frontend/src/api/station-monitor.ts
|
||
frontend/src/api/buffer.ts
|
||
frontend/src/api/dock.ts
|
||
frontend/src/api/task.ts
|
||
frontend/src/api/manual-action.ts
|
||
frontend/src/api/equipment.ts
|
||
frontend/src/api/alarm.ts
|
||
frontend/src/api/recovery.ts
|
||
frontend/src/api/events.ts
|
||
```
|
||
|
||
---
|
||
|
||
## 15. 与当前实现的主要差异提示
|
||
|
||
以下是前端联调时需要注意的目标差异：
|
||
|
||
1. **工件资源命名**：目标设计使用 `job` 作为运行时工件实体；当前实现部分接口仍使用 `workpiece` 命名。
|
||
2. **ID 类型**：目标设计中 `product_type/equipment/work_order/job` 更偏向字符串业务 ID；当前实现大量使用 int ID。前端新契约应优先按本文类型建模。
|
||
3. **工站监控**：目标契约不要求前端直接操作或依赖工站内部槽位写方法；监控数据应来自 Redis SSOT 推导结果。
|
||
4. **暂存台**：目标设计明确为 8 个固定槽位，工件全周期独占槽位，接口应体现 `slotNo 1~8` 和 `needRefill`。
|
||
5. **事件流**：目标架构要求 WebSocket/SSE 实时推送；仅轮询 `/stations/monitor` 不能满足最终生产版看板体验。
|
||
6. **恢复 API**：目标设计需要 L1/L2/L3 分级恢复接口；当前实现如果只有单个 restore endpoint，应继续补齐扫描、自动恢复和人工确认能力。
|
||
|
||
---
|
||
|
||
## 16. 最小前端接入优先级
|
||
|
||
建议按以下顺序落地：
|
||
|
||
1. `auth`：登录、刷新 token、当前用户。
|
||
2. `product-type/recipe`：产品与工艺路线展示。
|
||
3. `work-order/job`：工单创建、启动、暂停、恢复、工件列表。
|
||
4. `buffer/dock/station-monitor`：生产线看板。
|
||
5. `events`：实时事件流。
|
||
6. `manual-action/recovery`：异常处理和断电恢复。
|
||
7. `task/alarm/equipment`：任务追踪、报警、设备运维。
|