---
description: REST API 路由与统一 JSON 返回格式
globs: backend/routes/**/*.php,backend/app/Http/**/*.php
alwaysApply: false
---
# API 规范

详见 `docs/07-api.md`。

## 路由
- 统一前缀 `/api/v1/`，资源名复数，路由参数优先业务编码。
- 状态动作：`POST /api/v1/{resource}/{code}/{action}`

```
POST /api/v1/inbounds/{inbound_no}/receive
POST /api/v1/outbounds/{outbound_no}/allocate
```

- 认证 Sanctum；每个接口都要经过 Policy / Gate 授权，权限码形如 `outbound:allocate`。
- 列表接口必须分页并使用统一分页格式。

## 统一返回
所有接口通过统一响应工具（如 `App\Support\ApiResponse`）返回，禁止 Controller 自定义结构。

```json
{ "success": true,  "message": "OK",     "data": {} }
{ "success": false, "message": "操作失败", "errors": {} }
```

- 输出数据统一经 API Resource 转换，不直接返回 Model。
- 验证错误、业务异常、授权失败在异常处理器中统一转换为失败格式。