32 lines
1.0 KiB
Plaintext
32 lines
1.0 KiB
Plaintext
---
|
|
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。
|
|
- 验证错误、业务异常、授权失败在异常处理器中统一转换为失败格式。
|