# API 响应格式规范

## 统一响应结构

所有 API 响应都遵循以下基本结构：

```typescript
interface ApiResponse<T = any> {
  success: boolean;           // 请求是否成功
  data?: T;                   // 响应数据（成功时返回）
  message?: string;           // 提示信息（操作类接口）
  error?: string;             // 错误信息（失败时返回）
  pagination?: Pagination;    // 分页信息（列表类接口）
  meta?: Meta;                // 元数据（统计类接口）
}
```

---

## 1. 列表类接口（带分页）

### 适用接口
- `GET /api/prices/region` - 按地区查询价格
- `GET /api/prices/search` - 搜索价格数据

### 响应格式

```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "price_id": "2008067775216672769",
      "goods_material": "HPB300",
      "goods_spec": "Φ8",
      "hang_price": 3840,
      ...
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 100,
    "totalPages": 5
  }
}
```

### 分页对象定义

```typescript
interface Pagination {
  page: number;        // 当前页码（从 1 开始）
  pageSize: number;    // 每页记录数
  total: number;       // 总记录数
  totalPages: number;  // 总页数
}
```

### 默认值
- `page`: 1
- `pageSize`: 20

---

## 2. 统计类接口（带元数据）

### 适用接口
- `GET /api/prices/stats` - 获取价格统计
- `GET /api/prices/trend` - 获取价格趋势

### 响应格式（Stats）

```json
{
  "success": true,
  "data": {
    "count": 150,
    "avgPrice": 3850.5,
    "minPrice": 3600,
    "maxPrice": 4200,
    "stdDev": 150.25,
    "trend": "up",
    "changeRate": "+2.5%"
  }
}
```

### 响应格式（Trend）

```json
{
  "success": true,
  "data": [
    {
      "date": "2026-01-01",
      "avgPrice": 3850.5,
      "minPrice": 3600,
      "maxPrice": 4200
    },
    {
      "date": "2026-01-02",
      "avgPrice": 3875.0,
      "minPrice": 3650,
      "maxPrice": 4250
    }
  ],
  "meta": {
    "total": 30,
    "filters": {
      "region": "昆明",
      "material": "HPB300",
      "days": "30"
    }
  }
}
```

### 元数据定义

```typescript
interface Meta {
  total: number;           // 返回的记录总数
  filters?: {              // 请求的过滤条件（可选）
    region?: string;
    material?: string;
    days?: string;
  };
}
```

---

## 3. 操作类接口（带消息）

### 适用接口
- `POST /api/prices/import` - 导入数据

### 响应格式

```json
{
  "success": true,
  "message": "成功导入 300 条数据",
  "data": {
    "imported": 300
  }
}
```

---

## 4. 错误响应

### 统一错误格式

```json
{
  "success": false,
  "error": "错误描述信息"
}
```

### HTTP 状态码

| 状态码 | 说明 | 示例 |
|--------|------|------|
| 200 | 成功 | 数据查询成功 |
| 400 | 请求参数错误 | 缺少必填参数 |
| 404 | 资源不存在 | 数据未找到 |
| 500 | 服务器错误 | 数据库连接失败 |

---

## 5. 数据类型规范

### 价格字段
- `make_price`: `number \| null` - 钢厂价（元/吨）
- `hang_price`: `number` - 挂牌价（元/吨）
- 所有价格字段在返回时保留 2 位小数

### 日期字段
- `price_date`: `string` - ISO 8601 格式
- 统计时使用 `YYYY-MM-DD` 格式

### 分页参数
- 所有参数都是字符串类型（从 URL query 获取）
- 服务层自动转换为数字类型

---

## 6. 示例请求

### 按地区查询（带分页）

```bash
GET /api/prices/region?region=昆明&date=2026-01-05&page=1&pageSize=20
```

### 搜索价格（多条件）

```bash
GET /api/prices/search?material=HPB300&specification=Φ8&startDate=2026-01-01&endDate=2026-01-05&region=昆明&page=1&pageSize=20
```

### 获取价格趋势

```bash
GET /api/prices/trend?region=昆明&material=HPB300&days=30
```

---

## 7. 版本历史

| 版本 | 日期 | 变更说明 |
|------|------|----------|
| 1.0 | 2026-01-05 | 初始版本，统一所有接口响应格式 |

---

## 8. 注意事项

1. **分页一致性**：所有列表类接口必须返回 `pagination` 对象
2. **数字精度**：价格字段统一保留 2 位小数
3. **空值处理**：可选字段为空时返回 `null`，不返回 `undefined`
4. **错误消息**：错误消息使用中文，简洁明确
5. **时区处理**：所有日期时间统一使用 `+08:00` 时区