baiyue-firstleg/docs/系统状态枚举说明.md

# 系统状态枚举说明

## 使用范围

本文档说明当前后端实际使用的状态值。状态值是接口、数据库和前端联调契约，不能为了展示中文而修改其英文编码；前端展示应使用本说明中的中文含义。

代码中的 Java 枚举、状态常量和数据库状态字段均已补充中文注释。本说明用于集中查询，不替代各业务状态机的校验。

## 通用响应码

| 状态值 | 中文含义 |
| --- | --- |
| `200` | 请求成功。 |
| `A0400` | 请求参数不符合接口要求。 |
| `A0401` | 未登录、令牌无效或会话过期。 |
| `A0403` | 已登录但没有权限。 |
| `A0404` | 资源不存在或不在可访问范围。 |
| `A0409` | 状态、版本或幂等键冲突。 |
| `A0422` | 字段或业务前置校验失败。 |
| `A0429` | 请求频率或并发数量超限。 |
| `B0001` | 通用业务失败。 |
| `S0500` | 服务内部异常。 |
| `S0503` | 下游服务、数据库或基础设施暂不可用。 |

## 账号和权限

| 字段 | 状态值 | 中文含义 |
| --- | --- | --- |
| 账号状态 | `ACTIVE` | 账号正常，可登录。 |
| 账号状态 | `DISABLED` | 账号已停用，不允许登录。 |
| 账号状态 | `LOCKED` | 账号已锁定，需要管理员解除。 |
| 客户资料状态 | `PROFILE_REQUIRED` | 客户资料尚未补全。 |
| 客户资料状态 | `PENDING` | 客户资料已提交，等待审核。 |
| 客户资料状态 | `ACTIVE` | 客户审核通过，可正常开展业务。 |
| 客户资料状态 | `REJECTED` | 客户资料审核驳回。 |
| 客户资料状态 | `DISABLED` | 客户已停用。 |
| 客户、成员、角色、权限状态 | `ACTIVE` | 已启用，可参与登录、授权或业务使用。 |
| 客户、成员、角色、权限状态 | `DISABLED` | 已停用，不可继续使用。 |
| 审核记录状态 | `PENDING` | 等待审核。 |
| 审核记录状态 | `APPROVED` | 审核通过。 |
| 审核记录状态 | `REJECTED` | 审核驳回。 |
| 审核记录状态 | `SUPERSEDED` | 已被更新后的审核记录替代。 |

## 订单状态

| 状态值 | 中文含义 |
| --- | --- |
| `DRAFT` | 草稿，可继续编辑。 |
| `SUBMITTED` | 已提交，等待平台审核。 |
| `APPROVED` | 审核通过，可接单或进入履约。 |
| `ACCEPTED` | 平台已接单。 |
| `REJECTED` | 审核驳回，不允许进入履约。 |
| `CANCELLED` | 已取消，订单结束。 |
| `PROCESSING` | 履约处理中。 |
| `COMPLETED` | 订单完成。 |

统一订单列表的主状态是展示分组，不等于订单表的内部状态：`PENDING_REVIEW`、`WAIT_MEASURE`、`WAIT_SPLIT`、`LOADING`、`LOADED`、`DELIVERED`。

## 仓库与库位

| 字段 | 状态值 | 中文含义 |
| --- | --- | --- |
| 仓库、往来单位、快递公司 | `ACTIVE` | 启用，可被下单和作业引用。 |
| 仓库、往来单位、快递公司 | `INACTIVE` | 停用，不允许新增业务引用。 |
| 托盘 | `AVAILABLE` | 可分配。 |
| 托盘 | `RESERVED` | 已预占，尚未确认占用。 |
| 托盘 | `OCCUPIED` | 已确认占用。 |
| 库位 | `AVAILABLE` | 可用。 |
| 库位 | `RESERVED` | 已预占。 |
| 库位 | `OCCUPIED` | 已占用。 |
| 库位 | `DISABLED` | 已停用，不允许分配。 |
| 库位预占记录 | `RESERVED` | 预占生效中。 |
| 库位预占记录 | `CONFIRMED` | 预占已转为正式占用。 |
| 库位预占记录 | `RELEASED` | 已释放。 |
| 库位预占记录 | `EXPIRED` | 预占超时失效。 |
| 库位占用记录 | `OCCUPIED` | 正在占用。 |
| 库位占用记录 | `RELEASED` | 已释放。 |

## 入库

### 入库单主流程状态

| 状态值 | 中文含义 |
| --- | --- |
| `WAIT_MEASURE` | 等待录入或接收测量数据。 |
| `MEASURING` | 正在测量、识别重量或人工修正。 |
| `MEASURE_PENDING` | 测量已提交，等待审核。 |
| `MEASURE_REJECTED` | 测量审核被驳回，等待修正或异常放行。 |
| `WAIT_PRICING` | 测量通过或异常放行，等待计费。 |
| `FEE_CONFIRMING` | 已生成费用，等待费用确认和发送。 |
| `INBOUNDING` | 费用已确认，正在占用托盘、库位并完成入库。 |
| `WAIT_SPLIT` | 入库完成，可进入智能装柜或预装确认；费用状态独立维护。 |
| `LOADING` | 已进入装柜作业，PDA 可执行拣货。 |
| `LOADED` | 装柜完成，等待派送完成。 |
| `DELIVERED` | 已完成派送。 |
| `VOIDED` | 已作废，不允许继续处理。 |

主链路为：`WAIT_MEASURE` -> `MEASURING` -> `MEASURE_PENDING` -> `WAIT_PRICING` -> `FEE_CONFIRMING` -> `INBOUNDING` -> `WAIT_SPLIT` -> `LOADING` -> `LOADED` -> `DELIVERED`。测量驳回走 `MEASURE_PENDING` -> `MEASURE_REJECTED`；异常放行后回到 `WAIT_PRICING`。

### 测量、重量和费用状态

| 字段 | 状态值 | 中文含义 |
| --- | --- | --- |
| 测量批次 | `DRAFT` | 后台人工测量草稿，可编辑。 |
| 测量批次 | `RECEIVED` | 已接收第三方测量回传，待平台提交审核。 |
| 测量批次 | `SUBMITTED` | 已提交测量审核。 |
| 测量批次 | `APPROVED` | 测量审核通过。 |
| 测量批次 | `REJECTED` | 测量审核驳回。 |
| 重量识别 | `PENDING_CONFIRM` | OCR 已识别有效数值，等待人工确认。 |
| 重量识别 | `NEEDS_MANUAL` | OCR 无效或不完整，必须人工录入或修正。 |
| 重量识别 | `CONFIRMED` | 重量已确认，可参与计费。 |
| 测量审核、费用审核 | `NOT_SUBMITTED` | 尚未提交审核。 |
| 测量审核、费用审核 | `PENDING` | 等待审核。 |
| 测量审核、费用审核 | `APPROVED` | 审核通过。 |
| 测量审核、费用审核 | `REJECTED` | 审核驳回。 |
| 费用状态 | `UNPRICED` | 尚未计费。 |
| 费用状态 | `CALCULATED` | 已计算费用，等待确认。 |
| 费用状态 | `CONFIRMED` | 费用已确认，可发送给客户。 |
| 费用状态 | `SENT` | 费用明细已发送给客户。 |
| 客户通知状态 | `NOT_CREATED` | 尚未创建通知任务。 |
| 客户通知状态 | `PENDING` | 已创建待处理通知。当前代码未发现发送完成后的独立状态更新。 |

### 第三方回传和幂等记录

| 字段 | 状态值 | 中文含义 |
| --- | --- | --- |
| 第三方测量调用 | `PROCESSING` | 请求正在处理。 |
| 第三方测量调用 | `ACCEPTED` | 回传被接受，包含幂等重放成功。 |
| 第三方测量调用 | `REJECTED` | 回传校验或处理失败。 |
| 入库与计费幂等记录 | `PROCESSING` | 请求正在执行。 |
| 入库与计费幂等记录 | `COMPLETED` | 请求已成功完成，可返回幂等结果。 |

## 国内货柜履约智能装柜和 PDA

| 字段 | 状态值 | 中文含义 |
| --- | --- | --- |
| 货柜聚合 | `WAIT_LOADING` | 待装柜。货柜已创建但尚未创建装柜计划的派生状态，只在查询结果中返回，不写入装柜计划表。 |
| 装柜计划 | `EDITING` | 预装柜中，可维护货柜信息，并可增删未拣货明细。 |
| 装柜计划 | `LOADING` | 拣货中，已生成拣货任务；未拣货明细仍可追加、修改或删除。 |
| 装柜计划 | `COMPLETED` | 装柜完成。拣货完成后自动完成，计划、明细和货柜信息只读。 |
| PDA 拣货任务 | `LOADING` | 拣货作业进行中。 |
| PDA 拣货任务 | `COMPLETED` | 拣货已完成。 |
| PDA 拣货明细 | `PENDING` | 尚未开始拣货。 |
| PDA 拣货明细 | `PICKING` | 已拣部分数量，仍可继续拣货。 |
| PDA 拣货明细 | `PICKED` | 计划箱数已全部拣完。 |
| PDA 拣货明细 | `PARTIAL` | 只拣到部分箱数，剩余数量需要生成关联子入库单。 |
| PDA 拣货明细 | `SKIPPED` | 本次跳过，入库单回退为已入库并可重新参与智能装柜。 |
| 预装清单 | `PENDING` | 预装草稿，尚未开始确认。 |
| 预装清单 | `CONFIRMING` | 正在确认预装明细。 |
| 预装清单 | `CONFIRMED` | 预装已确认，可进入装柜作业。 |
| 新版拆单批次 | `PREPARED` | 已准备待应用。 |
| 新版拆单批次 | `APPLIED` | 已应用并生成关联子入库单。 |
| 新版拆单批次 | `CANCELLED` | 已取消，不能再次应用。 |
| 旧版拆单记录 | `LOCKED` | 已锁定待完成。 |
| 旧版拆单记录 | `COMPLETED` | 已完成并关联子入库单。 |

货柜列表状态为：`WAIT_LOADING`（待装柜）-> `EDITING`（预装柜中）-> `LOADING`（拣货中）-> `COMPLETED`（装柜完成）。其中 `WAIT_LOADING` 是货柜没有装柜计划时的派生状态；装柜计划持久化状态只能单向推进：`EDITING` -> `LOADING` -> `COMPLETED`，没有撤回状态。`COMPLETED` 后不允许编辑或删除装柜明细。

## 文件、导出和审计

| 字段 | 状态值 | 中文含义 |
| --- | --- | --- |
| 导出任务 | `PENDING` | 等待执行。 |
| 导出任务 | `RUNNING` | 正在生成文件。 |
| 导出任务 | `SUCCEEDED` | 文件已生成，可下载。 |
| 导出任务 | `FAILED` | 生成失败，可按规则重试。 |
| 导出任务 | `EXPIRED` | 文件已过期。 |
| 导出消息 | `PENDING` | 等待投递。 |
| 导出消息 | `CLAIMED` | 已被工作线程领取。 |
| 导出消息 | `SENT` | 已成功投递。 |
| 导出消息 | `QUARANTINED` | 异常隔离，等待人工或补偿处理。 |
| 审计消息 | `PENDING` | 等待发送。 |
| 审计消息 | `SENDING` | 正在发送。 |
| 审计消息 | `SENT` | 已发送成功。 |
| 审计消息 | `DEAD` | 多次失败，进入死信补偿。 |

## 第三方能力和 OCR

| 字段 | 状态值 | 中文含义 |
| --- | --- | --- |
| 第三方能力 | `DISABLED` | 能力未启用。 |
| 第三方能力 | `NOT_CONFIGURED` | 已启用但密钥或配置不完整。 |
| 第三方能力 | `READY` | 已启用且配置完整。 |
| 单图 OCR | `RECOGNIZED` | 已识别到有效重量。 |
| 单图 OCR | `NO_WEIGHT_FOUND` | 已处理图片但未识别到可用重量。 |
| 单图 OCR | `FAILED` | 图片处理、供应商调用或解析失败。 |