# 险种管理API使用示例

## 概述

本文档提供了险种管理API的详细使用示例，包括请求格式、响应格式和错误处理。

## 基础信息

- **基础URL**: `http://localhost:3000/api`
- **认证方式**: Bearer Token (JWT)
- **内容类型**: `application/json`

## 认证

所有API请求都需要在请求头中包含有效的JWT令牌：

```http
Authorization: Bearer <your-jwt-token>
```

## API端点

### 1. 获取险种列表

**请求**
```http
GET /api/insurance-types?page=1&pageSize=10&name=牛&status=active
Authorization: Bearer <your-jwt-token>
```

**响应示例**
```json
{
  "success": true,
  "message": "获取险种列表成功",
  "data": [
    {
      "id": 1,
      "name": "牛只意外伤害保险",
      "description": "为牛只提供意外伤害保障",
      "applicable_livestock": "牛",
      "insurance_term": "1年",
      "policy_form": "团体保险",
      "on_sale_status": true,
      "coverage_amount_min": 1000.00,
      "coverage_amount_max": 50000.00,
      "premium_rate": 0.05,
      "status": "active",
      "add_time": "2024-01-15T08:30:00.000Z",
      "created_at": "2024-01-15T08:30:00.000Z",
      "updated_at": "2024-01-15T08:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  }
}
```

### 2. 获取单个险种详情

**请求**
```http
GET /api/insurance-types/1
Authorization: Bearer <your-jwt-token>
```

**响应示例**
```json
{
  "success": true,
  "message": "获取险种详情成功",
  "data": {
    "id": 1,
    "name": "牛只意外伤害保险",
    "description": "为牛只提供意外伤害保障",
    "applicable_livestock": "牛",
    "insurance_term": "1年",
    "policy_form": "团体保险",
    "on_sale_status": true,
    "coverage_amount_min": 1000.00,
    "coverage_amount_max": 50000.00,
    "premium_rate": 0.05,
    "status": "active",
    "add_time": "2024-01-15T08:30:00.000Z",
    "created_at": "2024-01-15T08:30:00.000Z",
    "updated_at": "2024-01-15T08:30:00.000Z"
  }
}
```

### 3. 创建险种

**请求**
```http
POST /api/insurance-types
Authorization: Bearer <your-jwt-token>
Content-Type: application/json

{
  "name": "羊只疾病保险",
  "description": "为羊只提供疾病保障",
  "applicable_livestock": "羊",
  "insurance_term": "1年",
  "policy_form": "个体保险",
  "coverage_amount_min": 500.00,
  "coverage_amount_max": 20000.00,
  "premium_rate": 0.08
}
```

**响应示例**
```json
{
  "success": true,
  "message": "创建险种成功",
  "data": {
    "id": 2,
    "name": "羊只疾病保险",
    "description": "为羊只提供疾病保障",
    "applicable_livestock": "羊",
    "insurance_term": "1年",
    "policy_form": "个体保险",
    "on_sale_status": false,
    "coverage_amount_min": 500.00,
    "coverage_amount_max": 20000.00,
    "premium_rate": 0.08,
    "status": "active",
    "add_time": "2024-01-15T09:00:00.000Z",
    "created_at": "2024-01-15T09:00:00.000Z",
    "updated_at": "2024-01-15T09:00:00.000Z"
  }
}
```

### 4. 更新险种

**请求**
```http
PUT /api/insurance-types/2
Authorization: Bearer <your-jwt-token>
Content-Type: application/json

{
  "name": "羊只综合保险",
  "description": "为羊只提供疾病和意外伤害综合保障",
  "premium_rate": 0.10
}
```

**响应示例**
```json
{
  "success": true,
  "message": "更新险种成功",
  "data": {
    "id": 2,
    "name": "羊只综合保险",
    "description": "为羊只提供疾病和意外伤害综合保障",
    "applicable_livestock": "羊",
    "insurance_term": "1年",
    "policy_form": "个体保险",
    "on_sale_status": false,
    "coverage_amount_min": 500.00,
    "coverage_amount_max": 20000.00,
    "premium_rate": 0.10,
    "status": "active",
    "add_time": "2024-01-15T09:00:00.000Z",
    "created_at": "2024-01-15T09:00:00.000Z",
    "updated_at": "2024-01-15T09:15:00.000Z"
  }
}
```

### 5. 更新险种状态

**请求**
```http
PATCH /api/insurance-types/2/status
Authorization: Bearer <your-jwt-token>
Content-Type: application/json

{
  "status": "active",
  "on_sale_status": true
}
```

**响应示例**
```json
{
  "success": true,
  "message": "更新险种状态成功",
  "data": {
    "id": 2,
    "name": "羊只综合保险",
    "description": "为羊只提供疾病和意外伤害综合保障",
    "applicable_livestock": "羊",
    "insurance_term": "1年",
    "policy_form": "个体保险",
    "on_sale_status": true,
    "coverage_amount_min": 500.00,
    "coverage_amount_max": 20000.00,
    "premium_rate": 0.10,
    "status": "active",
    "add_time": "2024-01-15T09:00:00.000Z",
    "created_at": "2024-01-15T09:00:00.000Z",
    "updated_at": "2024-01-15T09:20:00.000Z"
  }
}
```

### 6. 删除险种

**请求**
```http
DELETE /api/insurance-types/2
Authorization: Bearer <your-jwt-token>
```

**响应示例**
```json
{
  "success": true,
  "message": "删除险种成功"
}
```

## 错误处理

### 常见错误响应

#### 401 未授权
```json
{
  "success": false,
  "message": "未授权访问",
  "error": "Unauthorized"
}
```

#### 403 权限不足
```json
{
  "success": false,
  "message": "权限不足",
  "error": "Forbidden"
}
```

#### 404 资源不存在
```json
{
  "success": false,
  "message": "险种不存在",
  "error": "Not Found"
}
```

#### 400 请求参数错误
```json
{
  "success": false,
  "message": "险种名称已存在",
  "error": "Bad Request"
}
```

#### 500 服务器内部错误
```json
{
  "success": false,
  "message": "服务器内部错误",
  "error": "Internal Server Error"
}
```

## 查询参数说明

### 获取险种列表支持的查询参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| page | integer | 否 | 1 | 页码，最小值为1 |
| pageSize | integer | 否 | 10 | 每页数量，范围1-100 |
| name | string | 否 | - | 险种名称，支持模糊搜索 |
| status | string | 否 | - | 险种状态，可选值：active, inactive |
| applicable_livestock | string | 否 | - | 适用牲畜类型，支持模糊搜索 |
| service_area | string | 否 | - | 服务区域，支持模糊搜索 |
| on_sale_status | boolean | 否 | - | 在售状态，true或false |

## 使用注意事项

1. **认证令牌**: 所有请求都需要有效的JWT令牌
2. **权限检查**: 用户需要具有相应的险种管理权限
3. **数据验证**: 创建和更新时会进行数据格式验证
4. **唯一性检查**: 险种名称必须唯一
5. **分页限制**: 每页最多返回100条记录
6. **状态管理**: 险种状态和在售状态可以独立管理

## 测试工具推荐

- **Postman**: 用于API测试和调试
- **curl**: 命令行工具，适合脚本化测试
- **Swagger UI**: 在线API文档和测试界面 (http://localhost:3000/api-docs)