# 政府服务API设计文档

## 1. 概述

本文档详细描述了政府服务(government-service)提供的API接口，包括政策法规查询、补贴申请、合规检查等核心功能。

## 2. 基础信息

- 基础路径: `/api/v1/government`
- 版本: v1
- 通信协议: HTTP/HTTPS
- 数据格式: JSON
- 状态码: 遵循HTTP状态码规范

## 3. 全局Headers

| Header名称 | 是否必填 | 描述 |
|------------|----------|------|
| Authorization | 是 | Bearer Token认证信息 |
| Content-Type | 是 | application/json |

## 4. 全局响应格式

### 4.1 成功响应
```json
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

### 4.2 错误响应
```json
{
  "code": 40001,
  "message": "错误描述",
  "data": null
}
```

## 5. 政策法规接口

### 5.1 获取政策法规列表

**接口地址**: `GET /policies`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| category | string | 否 | 政策分类 |
| status | string | 否 | 状态(PUBLISHED/DRAFT/EXPIRED) |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 政策法规列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 20,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 1,
        "title": "2024年农业补贴政策",
        "category": "农业扶持",
        "publish_date": "2024-01-15",
        "effective_date": "2024-02-01",
        "expiry_date": "2024-12-31",
        "issuing_authority": "农业农村部",
        "status": "PUBLISHED",
        "created_at": "2024-01-15T00:00:00Z"
      }
    ]
  }
}
```

### 5.2 获取政策法规详情

**接口地址**: `GET /policies/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 政策ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 政策ID |
| title | string | 政策标题 |
| content | string | 政策内容 |
| category | string | 政策分类 |
| publish_date | string | 发布日期 |
| effective_date | string | 生效日期 |
| expiry_date | string | 失效日期 |
| issuing_authority | string | 发布机构 |
| policy_number | string | 政策文号 |
| status | string | 状态 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "title": "2024年农业补贴政策",
    "content": "详细政策内容...",
    "category": "农业扶持",
    "publish_date": "2024-01-15",
    "effective_date": "2024-02-01",
    "expiry_date": "2024-12-31",
    "issuing_authority": "农业农村部",
    "policy_number": "NYB-2024-001",
    "status": "PUBLISHED",
    "created_at": "2024-01-15T00:00:00Z",
    "updated_at": "2024-01-15T00:00:00Z"
  }
}
```

## 6. 补贴申请接口

### 6.1 提交补贴申请

**接口地址**: `POST /subsidies/applications`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| policy_id | integer | 是 | 关联政策ID |
| project_name | string | 是 | 项目名称 |
| project_description | string | 是 | 项目描述 |
| applied_amount | number | 是 | 申请金额 |
| application_date | string | 是 | 申请日期(YYYY-MM-DD) |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 申请ID |
| applicant_id | integer | 申请人ID |
| applicant_type | string | 申请人类型 |
| policy_id | integer | 关联政策ID |
| application_number | string | 申请编号 |
| project_name | string | 项目名称 |
| project_description | string | 项目描述 |
| applied_amount | number | 申请金额 |
| application_date | string | 申请日期 |
| status | string | 申请状态 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "policy_id": 1,
  "project_name": "小麦种植补贴申请",
  "project_description": "申请2024年度小麦种植补贴",
  "applied_amount": 5000.00,
  "application_date": "2024-01-15"
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "applicant_id": 12345,
    "applicant_type": "FARMER",
    "policy_id": 1,
    "application_number": "SBA-20240115-0001",
    "project_name": "小麦种植补贴申请",
    "project_description": "申请2024年度小麦种植补贴",
    "applied_amount": 5000.00,
    "application_date": "2024-01-15",
    "status": "SUBMITTED",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 6.2 查询补贴申请列表

**接口地址**: `GET /subsidies/applications`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| status | string | 否 | 申请状态 |
| start_date | string | 否 | 申请开始日期(YYYY-MM-DD) |
| end_date | string | 否 | 申请结束日期(YYYY-MM-DD) |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 补贴申请列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 5,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 1001,
        "applicant_id": 12345,
        "applicant_type": "FARMER",
        "policy_id": 1,
        "application_number": "SBA-20240115-0001",
        "project_name": "小麦种植补贴申请",
        "applied_amount": 5000.00,
        "application_date": "2024-01-15",
        "status": "REVIEWING",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

### 6.3 查询补贴申请详情

**接口地址**: `GET /subsidies/applications/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 申请ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 申请ID |
| applicant_id | integer | 申请人ID |
| applicant_type | string | 申请人类型 |
| policy | object | 关联政策信息 |
| application_number | string | 申请编号 |
| project_name | string | 项目名称 |
| project_description | string | 项目描述 |
| applied_amount | number | 申请金额 |
| actual_amount | number | 实际发放金额 |
| application_date | string | 申请日期 |
| status | string | 申请状态 |
| review_notes | string | 审核备注 |
| review_date | string | 审核日期 |
| disbursement_date | string | 发放日期 |
| disbursements | array | 发放记录列表 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "applicant_id": 12345,
    "applicant_type": "FARMER",
    "policy": {
      "id": 1,
      "title": "2024年农业补贴政策",
      "category": "农业扶持"
    },
    "application_number": "SBA-20240115-0001",
    "project_name": "小麦种植补贴申请",
    "project_description": "申请2024年度小麦种植补贴",
    "applied_amount": 5000.00,
    "actual_amount": 4800.00,
    "application_date": "2024-01-15",
    "status": "DISBURSED",
    "review_notes": "审核通过",
    "review_date": "2024-01-20T00:00:00Z",
    "disbursement_date": "2024-01-25",
    "disbursements": [
      {
        "id": 2001,
        "disbursement_amount": 4800.00,
        "disbursement_date": "2024-01-25",
        "payment_method": "BANK_TRANSFER",
        "payment_reference": "PAY-20240125-0001",
        "recipient_account": "6222********1234",
        "status": "SUCCESS"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-25T00:00:00Z"
  }
}
```

## 7. 合规检查接口

### 7.1 提交合规检查记录

**接口地址**: `POST /compliance/inspections`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| inspected_entity_id | integer | 是 | 被检查实体ID |
| entity_type | string | 是 | 实体类型(FARMER/COMPANY) |
| inspection_date | string | 是 | 检查日期(YYYY-MM-DD) |
| inspection_type | string | 是 | 检查类型 |
| findings | string | 否 | 检查发现 |
| corrective_actions | string | 否 | 整改措施 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 检查记录ID |
| inspected_entity_id | integer | 被检查实体ID |
| entity_type | string | 实体类型 |
| inspector_id | integer | 检查员ID |
| inspection_date | string | 检查日期 |
| inspection_type | string | 检查类型 |
| inspection_result | string | 检查结果 |
| findings | string | 检查发现 |
| corrective_actions | string | 整改措施 |
| status | string | 状态 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "inspected_entity_id": 12345,
  "entity_type": "FARMER",
  "inspection_date": "2024-01-15",
  "inspection_type": "环保检查",
  "findings": "农药使用记录不完整",
  "corrective_actions": "要求完善农药使用记录"
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 3001,
    "inspected_entity_id": 12345,
    "entity_type": "FARMER",
    "inspector_id": 54321,
    "inspection_date": "2024-01-15",
    "inspection_type": "环保检查",
    "inspection_result": "FAIL",
    "findings": "农药使用记录不完整",
    "corrective_actions": "要求完善农药使用记录",
    "status": "COMPLETED",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 7.2 查询合规检查记录列表

**接口地址**: `GET /compliance/inspections`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| entity_type | string | 否 | 实体类型 |
| inspection_type | string | 否 | 检查类型 |
| inspection_result | string | 否 | 检查结果 |
| start_date | string | 否 | 检查开始日期(YYYY-MM-DD) |
| end_date | string | 否 | 检查结束日期(YYYY-MM-DD) |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 检查记录列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 3,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 3001,
        "inspected_entity_id": 12345,
        "entity_type": "FARMER",
        "inspector_id": 54321,
        "inspection_date": "2024-01-15",
        "inspection_type": "环保检查",
        "inspection_result": "FAIL",
        "status": "COMPLETED",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

### 7.3 查询合规检查记录详情

**接口地址**: `GET /compliance/inspections/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 检查记录ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 检查记录ID |
| inspected_entity | object | 被检查实体信息 |
| inspector | object | 检查员信息 |
| inspection_date | string | 检查日期 |
| inspection_type | string | 检查类型 |
| inspection_result | string | 检查结果 |
| findings | string | 检查发现 |
| corrective_actions | string | 整改措施 |
| follow_up_date | string | 跟进日期 |
| status | string | 状态 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 3001,
    "inspected_entity": {
      "id": 12345,
      "name": "张三农场",
      "type": "FARMER"
    },
    "inspector": {
      "id": 54321,
      "name": "李四"
    },
    "inspection_date": "2024-01-15",
    "inspection_type": "环保检查",
    "inspection_result": "FAIL",
    "findings": "农药使用记录不完整",
    "corrective_actions": "要求完善农药使用记录",
    "follow_up_date": "2024-02-15",
    "status": "FOLLOW_UP_REQUIRED",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

## 8. 土地流转接口

### 8.1 提交土地流转信息

**接口地址**: `POST /land/transfers`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| land_owner_id | integer | 是 | 土地所有者ID |
| transferee_id | integer | 是 | 受让方ID |
| land_location | string | 是 | 土地位置 |
| land_area | number | 是 | 土地面积(亩) |
| transfer_type | string | 是 | 流转类型(LEASE/SALE/CONTRACT) |
| transfer_term | integer | 是 | 流转期限(年) |
| annual_rent | number | 否 | 年租金(元/亩) |
| total_amount | number | 否 | 总金额 |
| start_date | string | 是 | 开始日期(YYYY-MM-DD) |
| end_date | string | 是 | 结束日期(YYYY-MM-DD) |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 流转信息ID |
| land_owner_id | integer | 土地所有者ID |
| transferee_id | integer | 受让方ID |
| land_location | string | 土地位置 |
| land_area | number | 土地面积 |
| transfer_type | string | 流转类型 |
| transfer_term | integer | 流转期限 |
| annual_rent | number | 年租金 |
| total_amount | number | 总金额 |
| start_date | string | 开始日期 |
| end_date | string | 结束日期 |
| contract_number | string | 合同编号 |
| status | string | 状态 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "land_owner_id": 12345,
  "transferee_id": 67890,
  "land_location": "北京市朝阳区某村",
  "land_area": 50.00,
  "transfer_type": "LEASE",
  "transfer_term": 5,
  "annual_rent": 1000.00,
  "start_date": "2024-01-01",
  "end_date": "2028-12-31"
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 4001,
    "land_owner_id": 12345,
    "transferee_id": 67890,
    "land_location": "北京市朝阳区某村",
    "land_area": 50.00,
    "transfer_type": "LEASE",
    "transfer_term": 5,
    "annual_rent": 1000.00,
    "total_amount": 50000.00,
    "start_date": "2024-01-01",
    "end_date": "2028-12-31",
    "contract_number": "LTC-20240101-0001",
    "status": "ACTIVE",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 8.2 查询土地流转信息列表

**接口地址**: `GET /land/transfers`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| land_owner_id | integer | 否 | 土地所有者ID |
| transferee_id | integer | 否 | 受让方ID |
| status | string | 否 | 状态 |
| start_date | string | 否 | 开始日期(YYYY-MM-DD) |
| end_date | string | 否 | 结束日期(YYYY-MM-DD) |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 流转信息列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 2,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 4001,
        "land_owner_id": 12345,
        "transferee_id": 67890,
        "land_location": "北京市朝阳区某村",
        "land_area": 50.00,
        "transfer_type": "LEASE",
        "transfer_term": 5,
        "annual_rent": 1000.00,
        "total_amount": 50000.00,
        "start_date": "2024-01-01",
        "end_date": "2028-12-31",
        "contract_number": "LTC-20240101-0001",
        "status": "ACTIVE",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

### 8.3 查询土地流转信息详情

**接口地址**: `GET /land/transfers/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 流转信息ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 流转信息ID |
| land_owner | object | 土地所有者信息 |
| transferee | object | 受让方信息 |
| land_location | string | 土地位置 |
| land_area | number | 土地面积 |
| transfer_type | string | 流转类型 |
| transfer_term | integer | 流转期限 |
| annual_rent | number | 年租金 |
| total_amount | number | 总金额 |
| start_date | string | 开始日期 |
| end_date | string | 结束日期 |
| contract_number | string | 合同编号 |
| status | string | 状态 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 4001,
    "land_owner": {
      "id": 12345,
      "name": "张三"
    },
    "transferee": {
      "id": 67890,
      "name": "李四农业合作社"
    },
    "land_location": "北京市朝阳区某村",
    "land_area": 50.00,
    "transfer_type": "LEASE",
    "transfer_term": 5,
    "annual_rent": 1000.00,
    "total_amount": 50000.00,
    "start_date": "2024-01-01",
    "end_date": "2028-12-31",
    "contract_number": "LTC-20240101-0001",
    "status": "ACTIVE",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

## 9. 农产品质量认证接口

### 9.1 提交农产品质量认证申请

**接口地址**: `POST /certifications`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| product_name | string | 是 | 产品名称 |
| certification_type | string | 是 | 认证类型 |
| issuing_authority | string | 是 | 发证机构 |
| issue_date | string | 是 | 发证日期(YYYY-MM-DD) |
| expiry_date | string | 是 | 有效期至(YYYY-MM-DD) |
| inspection_report | string | 否 | 检验报告 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 认证ID |
| producer_id | integer | 生产者ID |
| product_name | string | 产品名称 |
| certification_type | string | 认证类型 |
| certification_number | string | 认证编号 |
| issuing_authority | string | 发证机构 |
| issue_date | string | 发证日期 |
| expiry_date | string | 有效期至 |
| certification_status | string | 认证状态 |
| inspection_report | string | 检验报告 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "product_name": "绿色有机苹果",
  "certification_type": "绿色食品",
  "issuing_authority": "中国绿色食品发展中心",
  "issue_date": "2024-01-01",
  "expiry_date": "2025-01-01",
  "inspection_report": "检验报告内容..."
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 5001,
    "producer_id": 12345,
    "product_name": "绿色有机苹果",
    "certification_type": "绿色食品",
    "certification_number": "GF-20240101-0001",
    "issuing_authority": "中国绿色食品发展中心",
    "issue_date": "2024-01-01",
    "expiry_date": "2025-01-01",
    "certification_status": "VALID",
    "inspection_report": "检验报告内容...",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 9.2 查询农产品质量认证列表

**接口地址**: `GET /certifications`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| certification_type | string | 否 | 认证类型 |
| certification_status | string | 否 | 认证状态 |
| expiry_start_date | string | 否 | 到期开始日期(YYYY-MM-DD) |
| expiry_end_date | string | 否 | 到期结束日期(YYYY-MM-DD) |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 认证信息列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 5001,
        "producer_id": 12345,
        "product_name": "绿色有机苹果",
        "certification_type": "绿色食品",
        "certification_number": "GF-20240101-0001",
        "issuing_authority": "中国绿色食品发展中心",
        "issue_date": "2024-01-01",
        "expiry_date": "2025-01-01",
        "certification_status": "VALID",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

### 9.3 查询农产品质量认证详情

**接口地址**: `GET /certifications/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 认证ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 认证ID |
| producer | object | 生产者信息 |
| product_name | string | 产品名称 |
| certification_type | string | 认证类型 |
| certification_number | string | 认证编号 |
| issuing_authority | string | 发证机构 |
| issue_date | string | 发证日期 |
| expiry_date | string | 有效期至 |
| certification_status | string | 认证状态 |
| inspection_report | string | 检验报告 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 5001,
    "producer": {
      "id": 12345,
      "name": "张三农场"
    },
    "product_name": "绿色有机苹果",
    "certification_type": "绿色食品",
    "certification_number": "GF-20240101-0001",
    "issuing_authority": "中国绿色食品发展中心",
    "issue_date": "2024-01-01",
    "expiry_date": "2025-01-01",
    "certification_status": "VALID",
    "inspection_report": "检验报告内容...",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

## 10. 错误码定义

| 错误码 | 错误信息 | 描述 |
|--------|----------|------|
| 0 | success | 请求成功 |
| 40001 | 参数错误 | 请求参数不合法 |
| 40002 | 政策法规不存在 | 指定的政策法规不存在 |
| 40003 | 补贴申请不存在 | 指定的补贴申请不存在 |
| 40004 | 合规检查记录不存在 | 指定的合规检查记录不存在 |
| 40005 | 土地流转信息不存在 | 指定的土地流转信息不存在 |
| 40006 | 农产品质量认证不存在 | 指定的农产品质量认证不存在 |
| 40007 | 补贴申请提交失败 | 补贴申请提交过程中发生错误 |
| 40008 | 合规检查记录提交失败 | 合规检查记录提交过程中发生错误 |
| 40009 | 土地流转信息提交失败 | 土地流转信息提交过程中发生错误 |
| 40010 | 农产品质量认证提交失败 | 农产品质量认证提交过程中发生错误 |
| 50001 | 权限不足 | 用户权限不足，无法访问该资源 |
| 50002 | 认证失败 | 用户认证失败 |
| 99999 | 系统错误 | 服务器内部错误 |