aiotagro/nxxmdata
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

完善项目

Browse Source
This commit is contained in:
xuqiuyun
2025-09-28 17:58:43 +08:00
parent ec3f472641
commit 5b615473e0
59 changed files with 5428 additions and 593 deletions
Download Patch File Download Diff File Expand all files Collapse all files

308
insurance_backend/docs/insurance-type-api-examples.md Normal file
View File

@@ -0,0 +1,308 @@
# 险种管理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)

690
insurance_backend/docs/insurance-type-api.yaml Normal file
View File

@@ -0,0 +1,690 @@
openapi: 3.0.0
info:
title: 险种管理API
description: 保险系统险种管理功能相关API接口文档
version: 1.0.0
contact:
name: 开发团队
email: dev@example.com
servers:
- url: http://localhost:3000/api
description: 开发环境
paths:
/insurance-types:
get:
summary: 获取险种列表
description: 分页获取险种列表，支持多种筛选条件
tags:
- 险种管理
security:
- bearerAuth: []
parameters:
- name: page
in: query
description: 页码
required: false
schema:
type: integer
default: 1
minimum: 1
- name: pageSize
in: query
description: 每页数量
required: false
schema:
type: integer
default: 10
minimum: 1
maximum: 100
- name: name
in: query
description: 险种名称（模糊搜索）
required: false
schema:
type: string
- name: status
in: query
description: 险种状态
required: false
schema:
type: string
enum: [active, inactive]
- name: applicable_livestock
in: query
description: 适用牲畜类型（模糊搜索）
required: false
schema:
type: string
- name: service_area
in: query
description: 服务区域（模糊搜索）
required: false
schema:
type: string
- name: on_sale_status
in: query
description: 在售状态
required: false
schema:
type: boolean
responses:
'200':
description: 获取成功
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "获取险种列表成功"
data:
type: array
items:
$ref: '#/components/schemas/InsuranceType'
pagination:
$ref: '#/components/schemas/Pagination'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
post:
summary: 创建险种
description: 创建新的保险险种
tags:
- 险种管理
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateInsuranceTypeRequest'
responses:
'201':
description: 创建成功
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "创建险种成功"
data:
$ref: '#/components/schemas/InsuranceType'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
/insurance-types/{id}:
get:
summary: 获取险种详情
description: 根据ID获取单个险种的详细信息
tags:
- 险种管理
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
description: 险种ID
schema:
type: integer
responses:
'200':
description: 获取成功
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "获取保险类型详情成功"
data:
$ref: '#/components/schemas/InsuranceType'
'404':
$ref: '#/components/responses/NotFound'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
put:
summary: 更新险种
description: 更新指定ID的险种信息
tags:
- 险种管理
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
description: 险种ID
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateInsuranceTypeRequest'
responses:
'200':
description: 更新成功
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "更新险种成功"
data:
$ref: '#/components/schemas/InsuranceType'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
delete:
summary: 删除险种
description: 删除指定ID的险种
tags:
- 险种管理
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
description: 险种ID
schema:
type: integer
responses:
'200':
description: 删除成功
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
status:
type: string
example: "success"
data:
type: null
example: null
message:
type: string
example: "删除险种成功"
timestamp:
type: string
format: date-time
example: "2025-09-28T06:28:03.150Z"
'400':
description: 删除失败 - 外键约束错误
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 400
status: error
data: null
message: "该险种下存在保险申请，无法删除"
timestamp: "2025-09-28T06:28:02.881Z"
'404':
description: 险种不存在
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 404
status: error
data: null
message: "险种不存在"
timestamp: "2025-09-28T06:28:02.881Z"
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
/insurance-types/{id}/status:
patch:
summary: 更新险种状态
description: 更新指定ID险种的状态或在售状态
tags:
- 险种管理
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
description: 险种ID
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateInsuranceTypeStatusRequest'
responses:
'200':
description: 更新成功
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: "更新险种状态成功"
data:
$ref: '#/components/schemas/InsuranceType'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
InsuranceType:
type: object
properties:
id:
type: integer
description: 险种ID
example: 1
name:
type: string
description: 险种名称
example: "牛羊保险"
description:
type: string
description: 险种描述
example: "针对牛羊等大型牲畜的综合保险产品"
applicable_livestock:
type: string
description: 适用牲畜类型
example: "牛、羊"
insurance_term:
type: integer
description: 保险期限（月）
example: 12
policy_form:
type: string
description: 保单形式
example: "电子保单"
coverage_amount_min:
type: number
format: decimal
description: 最低保额
example: 1000.00
coverage_amount_max:
type: number
format: decimal
description: 最高保额
example: 50000.00
premium_rate:
type: number
format: decimal
description: 保险费率
example: 0.0350
service_area:
type: string
description: 服务区域
example: "宁夏回族自治区"
add_time:
type: string
format: date-time
description: 添加时间
example: "2024-01-15T10:30:00.000Z"
on_sale_status:
type: boolean
description: 在售状态
example: true
sort_order:
type: integer
description: 排序顺序
example: 0
remarks:
type: string
description: 备注
example: "特殊说明信息"
status:
type: string
enum: [active, inactive]
description: 险种状态
example: "active"
created_by:
type: integer
description: 创建人ID
example: 1
updated_by:
type: integer
description: 更新人ID
example: 1
created_at:
type: string
format: date-time
description: 创建时间
example: "2024-01-15T10:30:00.000Z"
updated_at:
type: string
format: date-time
description: 更新时间
example: "2024-01-15T10:30:00.000Z"
CreateInsuranceTypeRequest:
type: object
required:
- name
- coverage_amount_min
- coverage_amount_max
- premium_rate
properties:
name:
type: string
description: 险种名称
example: "牛羊保险"
minLength: 1
maxLength: 100
description:
type: string
description: 险种描述
example: "针对牛羊等大型牲畜的综合保险产品"
applicable_livestock:
type: string
description: 适用牲畜类型
example: "牛、羊"
maxLength: 100
insurance_term:
type: integer
description: 保险期限（月）
example: 12
minimum: 1
policy_form:
type: string
description: 保单形式
example: "电子保单"
maxLength: 50
coverage_amount_min:
type: number
format: decimal
description: 最低保额
example: 1000.00
minimum: 0
coverage_amount_max:
type: number
format: decimal
description: 最高保额
example: 50000.00
minimum: 0
premium_rate:
type: number
format: decimal
description: 保险费率
example: 0.0350
minimum: 0
maximum: 1
service_area:
type: string
description: 服务区域
example: "宁夏回族自治区"
add_time:
type: string
format: date-time
description: 添加时间
example: "2024-01-15T10:30:00.000Z"
on_sale_status:
type: boolean
description: 在售状态
example: true
default: true
sort_order:
type: integer
description: 排序顺序
example: 0
default: 0
remarks:
type: string
description: 备注
example: "特殊说明信息"
status:
type: string
enum: [active, inactive]
description: 险种状态
example: "active"
default: "active"
UpdateInsuranceTypeRequest:
type: object
properties:
name:
type: string
description: 险种名称
example: "牛羊保险"
minLength: 1
maxLength: 100
description:
type: string
description: 险种描述
example: "针对牛羊等大型牲畜的综合保险产品"
applicable_livestock:
type: string
description: 适用牲畜类型
example: "牛、羊"
maxLength: 100
insurance_term:
type: integer
description: 保险期限（月）
example: 12
minimum: 1
policy_form:
type: string
description: 保单形式
example: "电子保单"
maxLength: 50
coverage_amount_min:
type: number
format: decimal
description: 最低保额
example: 1000.00
minimum: 0
coverage_amount_max:
type: number
format: decimal
description: 最高保额
example: 50000.00
minimum: 0
premium_rate:
type: number
format: decimal
description: 保险费率
example: 0.0350
minimum: 0
maximum: 1
service_area:
type: string
description: 服务区域
example: "宁夏回族自治区"
add_time:
type: string
format: date-time
description: 添加时间
example: "2024-01-15T10:30:00.000Z"
on_sale_status:
type: boolean
description: 在售状态
example: true
sort_order:
type: integer
description: 排序顺序
example: 0
remarks:
type: string
description: 备注
example: "特殊说明信息"
status:
type: string
enum: [active, inactive]
description: 险种状态
example: "active"
UpdateInsuranceTypeStatusRequest:
type: object
properties:
status:
type: string
enum: [active, inactive]
description: 险种状态
example: "active"
on_sale_status:
type: boolean
description: 在售状态
example: true
Pagination:
type: object
properties:
page:
type: integer
description: 当前页码
example: 1
limit:
type: integer
description: 每页数量
example: 10
total:
type: integer
description: 总记录数
example: 100
responses:
BadRequest:
description: 请求参数错误
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: "请求参数错误"
Unauthorized:
description: 未授权
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: "未授权访问"
Forbidden:
description: 权限不足
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: "权限不足"
NotFound:
description: 资源不存在
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: "险种不存在"
InternalServerError:
description: 服务器内部错误
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: "服务器内部错误"