wms-saas/docs/07-api.md

07 API 规范

路由

RESTful，统一前缀 /api/v1/。

GET  /api/v1/warehouses
GET  /api/v1/skus
GET  /api/v1/inventory

POST /api/v1/inbounds
POST /api/v1/inbounds/{inbound_no}/receive
POST /api/v1/inbounds/{inbound_no}/putaway

GET  /api/v1/outbounds
POST /api/v1/outbounds/{outbound_no}/allocate
POST /api/v1/outbounds/{outbound_no}/pick
POST /api/v1/outbounds/{outbound_no}/pack
POST /api/v1/outbounds/{outbound_no}/ship

要点：

• 资源名使用复数。
• 路由参数优先使用业务编码（inbound_no、outbound_no），而非自增 ID。
• 业务动作（状态流转）使用 POST /{resource}/{code}/{action}。
• 认证使用 Laravel Sanctum，授权使用 Policies / Gates。

统一返回格式

不要每个 Controller 自己定义一套返回结构。

成功：

{
    "success": true,
    "message": "OK",
    "data": {}
}

失败：

{
    "success": false,
    "message": "操作失败",
    "errors": {}
}

分页列表的 data 是当前页记录，分页信息放在同级 meta。所有列表接口都走 ApiResponse::paginated()。

{
    "success": true,
    "message": "OK",
    "data": [],
    "meta": {
        "current_page": 1,
        "per_page": 20,
        "total": 0,
        "last_page": 1
    }
}

默认每页 20 条，最大 100 条。失败响应的 errors 没有内容时是 JSON 对象 {}，不是数组。

/api/* 的异常由统一异常处理转成失败格式，不返回框架堆栈。响应头 X-Request-Id 贯穿本次请求；客户端传入的值仅在字母、数字、下划线、连字符且不超过 64 位时沿用。

内部 API（Python Service）

Laravel 调用 Python 的内部接口统一使用 /internal/v1/ 前缀，见 11-py-service.md。