---
name: cross-api-convention
description: 前后端 API 对接规范，响应格式/错误码/查询操作符/分页
globs:
  - "**/*.php"
  - "**/*.ts"
---

## 响应格式

### 成功响应
```json
{
  "code": 0,
  "msg": "ok",
  "data": { "items": [...], "total": 100 }
}
```

### 失败响应
```json
{
  "code": -1,
  "msg": "操作失败",
  "data": null
}
```

## 错误码

| code | 说明 |
|------|------|
| 0 | 成功 |
| -1 | 业务失败 |
| 400 | 参数错误 |
| 401 | 未认证 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 500 | 服务器错误 |

## 查询操作符

| 操作符 | 说明 | 示例 |
|--------|------|------|
| `LIKE_` | 模糊匹配 | `LIKE_name=菜单` |
| `EQ_` | 精确匹配 | `EQ_status=1` |
| `NE_` | 不等于 | `NE_setting_type=issue` |
| `GT_` | 大于 | `GT_sort=10` |
| `LT_` | 小于 | `LT_sort=100` |
| `BETWEEN_` | 范围 | `BETWEEN_created_at=1700000000,1800000000` |

## 分页参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| page | 1 | 页码 |
| limit | 15 | 每页条数 |
| field | '' | 排序字段 |
| order | 'desc' | 排序方向 |

## 检查清单

- [ ] 响应格式是否为 {code, msg, data}
- [ ] 成功时 code 是否为 0
- [ ] 列表是否返回 items 和 total
- [ ] 查询参数是否使用标准操作符