---
name: frontend-web-api
description: Web 前台 API 层规范（Nuxt 4），基于 $fetch 或 useFetch
globs:
  - "frontend/web/app/api/**/*.ts"
  - "frontend/web/app/apps/**/api/**/*.ts"
---

## 文件位置

```
frontend/web/app/api/{module}/index.ts
```

## 代码模板

当前项目 Web 端统一通过 `~/utils/request` 封装请求，自动处理 `/api/` 基础路径、认证头、响应解包和错误提示：

```typescript
import request from '~/utils/request'

export function get{Model}List(params: Record<string, any> = {}) {
  return request.get('/{module}/{model}', params)
}

export function get{Model}Detail(id: string | number) {
  return request.get(`/{module}/{model}/${id}`)
}
```

## 关键约定

- 优先使用 `~/utils/request`，不要在业务 API 中直接使用 axios 或 `$fetch`
- 传给 `request` 的路径使用后端业务路径（如 `/produce/process`），由请求封装统一拼接 `/api/`
- 默认响应已解包为 `data`；需要完整响应时传递 `{ returnFullResponse: true }`
- 上传使用 `request.upload` 并传入 `FormData`，不要在页面中重复实现认证和基础 URL 逻辑
- 错误由请求封装统一提示，业务层只处理状态和页面交互

## 检查清单

- [ ] 是否使用 $fetch/useFetch 而非 axios
- [ ] 路径是否以 /api/ 开头
- [ ] SSR 场景是否使用 useFetch
- [ ] 是否处理了请求错误