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

feat(user-center): 新增收货地址管理功能

Browse Source 
- 添加收货地址实体类、控制器、服务类和数据访问接口
- 实现收货地址创建、获取列表、获取详情、更新和删除功能- 集成JWT认证，确保操作的安全性
- 新增相关API文档
This commit is contained in:
ylweng
2025-09-11 23:23:51 +08:00
parent 6c22882cb8
commit 33c138c839
77 changed files with 14049 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

467
docs/design/api/ai_service_api_design.md Normal file
View File

@@ -0,0 +1,467 @@
# AI服务API设计文档
## 1. 概述
本文档详细描述了AI服务(ai-service)提供的API接口，包括智能问答、图像识别、数据分析等核心功能。
## 2. 基础信息
- 基础路径: `/api/v1/ai`
- 版本: 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 提问
**接口地址**: `POST /qa/ask`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| question | string | 是 | 用户问题 |
| context | object | 否 | 上下文信息 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 问答记录ID |
| question | string | 用户问题 |
| answer | string | AI回答 |
| model_version | string | 使用的模型版本 |
| processing_time | integer | 处理耗时(毫秒) |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"question": "如何防治小麦赤霉病？",
"context": {
"crop": "小麦",
"region": "华北地区"
}
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1001,
"question": "如何防治小麦赤霉病？",
"answer": "小麦赤霉病防治方法：1.选用抗病品种；2.合理施肥，避免氮肥过量；3.及时排水，降低田间湿度；4.药剂防治，在抽穗扬花期喷施多菌灵等杀菌剂。",
"model_version": "v1.2.0",
"processing_time": 1200,
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 5.2 获取问答历史
**接口地址**: `GET /qa/history`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| 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,
"question": "如何防治小麦赤霉病？",
"answer": "小麦赤霉病防治方法：1.选用抗病品种；2.合理施肥，避免氮肥过量；3.及时排水，降低田间湿度；4.药剂防治，在抽穗扬花期喷施多菌灵等杀菌剂。",
"model_version": "v1.2.0",
"processing_time": 1200,
"created_at": "2024-01-15T10:30:00Z"
}
]
}
}
```
## 6. 图像识别接口
### 6.1 上传图片进行识别
**接口地址**: `POST /image/recognize`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| image_url | string | 是 | 图片URL |
| recognition_type | string | 是 | 识别类型(PestAndDisease/Plant/Crop等) |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 识别记录ID |
| image_url | string | 图片URL |
| recognition_type | string | 识别类型 |
| result | object | 识别结果 |
| confidence | number | 置信度 |
| processing_time | integer | 处理耗时(毫秒) |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"image_url": "https://example.com/image1.jpg",
"recognition_type": "PestAndDisease"
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 2001,
"image_url": "https://example.com/image1.jpg",
"recognition_type": "PestAndDisease",
"result": {
"name": "小麦赤霉病",
"description": "一种常见的小麦病害，主要危害小麦的穗部",
"prevention": "1.选用抗病品种；2.合理施肥；3.及时排水；4.药剂防治"
},
"confidence": 0.9567,
"processing_time": 2500,
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 6.2 获取识别历史
**接口地址**: `GET /image/history`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| recognition_type | string | 否 | 识别类型筛选 |
| 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": 2001,
"image_url": "https://example.com/image1.jpg",
"recognition_type": "PestAndDisease",
"result": {
"name": "小麦赤霉病",
"description": "一种常见的小麦病害，主要危害小麦的穗部"
},
"confidence": 0.9567,
"processing_time": 2500,
"created_at": "2024-01-15T10:30:00Z"
}
]
}
}
```
## 7. 数据分析接口
### 7.1 创建分析任务
**接口地址**: `POST /analysis/tasks`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| task_name | string | 是 | 任务名称 |
| task_type | string | 是 | 任务类型(YieldPrediction/PriceAnalysis等) |
| input_data | object | 是 | 输入数据 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 任务ID |
| task_name | string | 任务名称 |
| task_type | string | 任务类型 |
| status | string | 任务状态 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"task_name": "2024年小麦产量预测",
"task_type": "YieldPrediction",
"input_data": {
"crop": "小麦",
"region": "华北地区",
"planting_area": 10000,
"historical_data": [
{"year": 2021, "yield": 500},
{"year": 2022, "yield": 520},
{"year": 2023, "yield": 510}
]
}
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 3001,
"task_name": "2024年小麦产量预测",
"task_type": "YieldPrediction",
"status": "PENDING",
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 7.2 查询任务状态
**接口地址**: `GET /analysis/tasks/{id}`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 任务ID |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 任务ID |
| task_name | string | 任务名称 |
| task_type | string | 任务类型 |
| input_data | object | 输入数据 |
| result | object | 分析结果 |
| status | string | 任务状态 |
| processing_time | integer | 处理耗时(毫秒) |
| error_message | string | 错误信息 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 3001,
"task_name": "2024年小麦产量预测",
"task_type": "YieldPrediction",
"input_data": {
"crop": "小麦",
"region": "华北地区",
"planting_area": 10000,
"historical_data": [
{"year": 2021, "yield": 500},
{"year": 2022, "yield": 520},
{"year": 2023, "yield": 510}
]
},
"result": {
"predicted_yield": 515,
"confidence": 0.85,
"factors": ["气候条件", "土壤质量", "种植技术"]
},
"status": "COMPLETED",
"processing_time": 5000,
"error_message": null,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:05Z"
}
}
```
### 7.3 获取任务列表
**接口地址**: `GET /analysis/tasks`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| task_type | string | 否 | 任务类型筛选 |
| status | string | 否 | 任务状态筛选 |
| 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": 3001,
"task_name": "2024年小麦产量预测",
"task_type": "YieldPrediction",
"status": "COMPLETED",
"created_at": "2024-01-15T10:30:00Z"
}
]
}
}
```
## 8. 用户反馈接口
### 8.1 提交反馈
**接口地址**: `POST /feedback`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| service_type | string | 是 | 服务类型(QA/IMAGE_RECOGNITION/ANALYSIS) |
| record_id | integer | 是 | 相关记录ID |
| rating | integer | 是 | 评分(1-5星) |
| feedback | string | 否 | 反馈内容 |
| is_helpful | boolean | 是 | 是否有帮助 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 反馈ID |
| service_type | string | 服务类型 |
| record_id | integer | 相关记录ID |
| rating | integer | 评分 |
| feedback | string | 反馈内容 |
| is_helpful | boolean | 是否有帮助 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"service_type": "QA",
"record_id": 1001,
"rating": 5,
"feedback": "回答很详细，很有帮助",
"is_helpful": true
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 4001,
"service_type": "QA",
"record_id": 1001,
"rating": 5,
"feedback": "回答很详细，很有帮助",
"is_helpful": true,
"created_at": "2024-01-15T10:30:00Z"
}
}
```
## 9. 错误码定义
| 错误码 | 错误信息 | 描述 |
|--------|----------|------|
| 0 | success | 请求成功 |
| 40001 | 参数错误 | 请求参数不合法 |
| 40002 | 问答记录不存在 | 指定的问答记录不存在 |
| 40003 | 图像识别记录不存在 | 指定的图像识别记录不存在 |
| 40004 | 分析任务不存在 | 指定的分析任务不存在 |
| 40005 | 不支持的识别类型 | 指定的识别类型不被支持 |
| 40006 | 不支持的任务类型 | 指定的任务类型不被支持 |
| 40007 | 任务状态不允许此操作 | 当前任务状态不允许执行该操作 |
| 50001 | 权限不足 | 用户权限不足，无法访问该资源 |
| 50002 | 认证失败 | 用户认证失败 |
| 99999 | 系统错误 | 服务器内部错误 |

762
docs/design/api/data_platform_service_api_design.md Normal file
View File

@@ -0,0 +1,762 @@
# 数据平台服务API设计文档
## 1. 概述
本文档详细描述了数据平台服务(data-platform-service)提供的API接口，包括数据统计、报表生成、数据分析等核心功能。
## 2. 基础信息
- 基础路径: `/api/v1/data`
- 版本: 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 /statistics`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| stat_type | string | 是 | 统计类型(USER_COUNT, PRODUCT_COUNT, ORDER_COUNT, REVENUE等) |
| start_date | string | 否 | 开始日期(YYYY-MM-DD) |
| end_date | string | 否 | 结束日期(YYYY-MM-DD) |
| dimension1 | string | 否 | 维度1(如地区、品类等) |
| dimension2 | string | 否 | 维度2 |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 统计数据列表 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"total": 30,
"page": 1,
"size": 10,
"items": [
{
"id": 1,
"stat_type": "USER_COUNT",
"stat_value": 12500.00,
"stat_date": "2024-01-15",
"dimension1": "北京",
"dimension2": null,
"created_at": "2024-01-15T00:00:00Z"
}
]
}
}
```
### 5.2 批量获取统计数据
**接口地址**: `POST /statistics/batch`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| queries | array | 是 | 查询条件列表 |
**queries元素结构**:
| 字段名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| stat_type | string | 是 | 统计类型 |
| start_date | string | 否 | 开始日期(YYYY-MM-DD) |
| end_date | string | 否 | 结束日期(YYYY-MM-DD) |
| dimension1 | string | 否 | 维度1 |
| dimension2 | string | 否 | 维度2 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| results | array | 查询结果列表 |
**示例请求**:
```json
{
"queries": [
{
"stat_type": "USER_COUNT",
"start_date": "2024-01-01",
"end_date": "2024-01-31"
},
{
"stat_type": "ORDER_COUNT",
"start_date": "2024-01-01",
"end_date": "2024-01-31"
}
]
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"results": [
{
"stat_type": "USER_COUNT",
"data": [
{
"stat_value": 12500.00,
"stat_date": "2024-01-31"
}
]
},
{
"stat_type": "ORDER_COUNT",
"data": [
{
"stat_value": 3500.00,
"stat_date": "2024-01-31"
}
]
}
]
}
}
```
## 6. 报表管理接口
### 6.1 获取报表模板列表
**接口地址**: `GET /reports/templates`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| template_type | string | 否 | 模板类型(DAILY, WEEKLY, MONTHLY等) |
| data_source | string | 否 | 数据源 |
| status | string | 否 | 模板状态(ACTIVE/INACTIVE) |
| 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": 1,
"name": "用户增长日报",
"description": "每日用户增长情况统计报表",
"template_type": "DAILY",
"data_source": "user_center_service",
"status": "ACTIVE",
"created_at": "2024-01-01T00:00:00Z"
}
]
}
}
```
### 6.2 创建报表模板
**接口地址**: `POST /reports/templates`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| name | string | 是 | 报表名称 |
| description | string | 否 | 报表描述 |
| template_type | string | 是 | 模板类型 |
| data_source | string | 是 | 数据源 |
| query_sql | string | 是 | 查询SQL |
| columns_config | object | 否 | 列配置信息 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 模板ID |
| name | string | 报表名称 |
| description | string | 报表描述 |
| template_type | string | 模板类型 |
| data_source | string | 数据源 |
| query_sql | string | 查询SQL |
| columns_config | object | 列配置信息 |
| status | string | 模板状态 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"name": "交易统计月报",
"description": "每月交易情况统计报表",
"template_type": "MONTHLY",
"data_source": "trade_service",
"query_sql": "SELECT DATE_FORMAT(created_at, '%Y-%m') as month, COUNT(*) as order_count, SUM(total_amount) as total_revenue FROM orders WHERE created_at >= :startDate AND created_at <= :endDate GROUP BY month",
"columns_config": {
"month": "月份",
"order_count": "订单数量",
"total_revenue": "总收入"
}
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 2,
"name": "交易统计月报",
"description": "每月交易情况统计报表",
"template_type": "MONTHLY",
"data_source": "trade_service",
"query_sql": "SELECT DATE_FORMAT(created_at, '%Y-%m') as month, COUNT(*) as order_count, SUM(total_amount) as total_revenue FROM orders WHERE created_at >= :startDate AND created_at <= :endDate GROUP BY month",
"columns_config": {
"month": "月份",
"order_count": "订单数量",
"total_revenue": "总收入"
},
"status": "ACTIVE",
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 6.3 生成报表
**接口地址**: `POST /reports/generate`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| template_id | integer | 是 | 报表模板ID |
| start_date | string | 否 | 统计开始日期(YYYY-MM-DD) |
| end_date | string | 否 | 统计结束日期(YYYY-MM-DD) |
| report_format | string | 否 | 报表格式(PDF/EXCEL/CSV)，默认PDF |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 生成记录ID |
| template_id | integer | 报表模板ID |
| report_name | string | 报表文件名 |
| report_format | string | 报表格式 |
| status | string | 生成状态 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"template_id": 2,
"start_date": "2024-01-01",
"end_date": "2024-01-31",
"report_format": "PDF"
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1001,
"template_id": 2,
"report_name": "交易统计月报_2024-01.pdf",
"report_format": "PDF",
"status": "GENERATING",
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 6.4 查询报表生成状态
**接口地址**: `GET /reports/generations/{id}`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 生成记录ID |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 生成记录ID |
| template_id | integer | 报表模板ID |
| report_name | string | 报表文件名 |
| report_path | string | 报表文件路径 |
| report_format | string | 报表格式 |
| start_date | string | 统计开始日期 |
| end_date | string | 统计结束日期 |
| status | string | 生成状态 |
| generated_at | string | 生成完成时间 |
| created_at | string | 创建时间 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1001,
"template_id": 2,
"report_name": "交易统计月报_2024-01.pdf",
"report_path": "/reports/交易统计月报_2024-01.pdf",
"report_format": "PDF",
"start_date": "2024-01-01",
"end_date": "2024-01-31",
"status": "SUCCESS",
"generated_at": "2024-01-15T10:35:00Z",
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 6.5 下载报表
**接口地址**: `GET /reports/download/{id}`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 生成记录ID |
**响应**:
- 成功：返回报表文件流
- 失败：返回错误信息
## 7. 数据分析接口
### 7.1 创建分析任务
**接口地址**: `POST /analysis/tasks`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| name | string | 是 | 任务名称 |
| description | string | 否 | 任务描述 |
| analysis_type | string | 是 | 分析类型(TREND, CORRELATION, CLUSTER等) |
| data_source | string | 是 | 数据源 |
| parameters | object | 否 | 分析参数 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 任务ID |
| name | string | 任务名称 |
| description | string | 任务描述 |
| analysis_type | string | 分析类型 |
| data_source | string | 数据源 |
| parameters | object | 分析参数 |
| status | string | 任务状态 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"name": "用户增长趋势分析",
"description": "分析近一年用户增长趋势",
"analysis_type": "TREND",
"data_source": "user_center_service",
"parameters": {
"period": "YEARLY",
"metric": "user_count"
}
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 2001,
"name": "用户增长趋势分析",
"description": "分析近一年用户增长趋势",
"analysis_type": "TREND",
"data_source": "user_center_service",
"parameters": {
"period": "YEARLY",
"metric": "user_count"
},
"status": "PENDING",
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 7.2 查询分析任务列表
**接口地址**: `GET /analysis/tasks`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| analysis_type | string | 否 | 分析类型 |
| status | string | 否 | 任务状态 |
| 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": 2001,
"name": "用户增长趋势分析",
"description": "分析近一年用户增长趋势",
"analysis_type": "TREND",
"data_source": "user_center_service",
"status": "SUCCESS",
"started_at": "2024-01-15T10:31:00Z",
"completed_at": "2024-01-15T10:35:00Z",
"created_at": "2024-01-15T10:30:00Z"
}
]
}
}
```
### 7.3 查询分析任务详情
**接口地址**: `GET /analysis/tasks/{id}`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 任务ID |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 任务ID |
| name | string | 任务名称 |
| description | string | 任务描述 |
| analysis_type | string | 分析类型 |
| data_source | string | 数据源 |
| parameters | object | 分析参数 |
| result_data | object | 分析结果数据 |
| status | string | 任务状态 |
| started_at | string | 开始执行时间 |
| completed_at | string | 完成时间 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 2001,
"name": "用户增长趋势分析",
"description": "分析近一年用户增长趋势",
"analysis_type": "TREND",
"data_source": "user_center_service",
"parameters": {
"period": "YEARLY",
"metric": "user_count"
},
"result_data": {
"trend_data": [
{
"date": "2023-01",
"value": 8500
},
{
"date": "2023-02",
"value": 8750
}
],
"trend_chart": "base64_encoded_image_data"
},
"status": "SUCCESS",
"started_at": "2024-01-15T10:31:00Z",
"completed_at": "2024-01-15T10:35:00Z",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:35:00Z"
}
}
```
## 8. 数据看板接口
### 8.1 创建看板配置
**接口地址**: `POST /dashboards`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| name | string | 是 | 看板名称 |
| description | string | 否 | 看板描述 |
| layout_config | object | 是 | 布局配置 |
| widgets_config | object | 是 | 组件配置 |
| access_permissions | object | 否 | 访问权限配置 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 配置ID |
| name | string | 看板名称 |
| description | string | 看板描述 |
| layout_config | object | 布局配置 |
| widgets_config | object | 组件配置 |
| access_permissions | object | 访问权限配置 |
| status | string | 配置状态 |
| created_by | integer | 创建人用户ID |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"name": "运营数据看板",
"description": "展示核心运营数据",
"layout_config": {
"grid_columns": 12,
"widgets": [
{
"id": "widget1",
"x": 0,
"y": 0,
"width": 6,
"height": 4
}
]
},
"widgets_config": {
"widget1": {
"type": "statistic",
"title": "用户总数",
"data_source": "USER_COUNT",
"time_range": "today"
}
}
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 3001,
"name": "运营数据看板",
"description": "展示核心运营数据",
"layout_config": {
"grid_columns": 12,
"widgets": [
{
"id": "widget1",
"x": 0,
"y": 0,
"width": 6,
"height": 4
}
]
},
"widgets_config": {
"widget1": {
"type": "statistic",
"title": "用户总数",
"data_source": "USER_COUNT",
"time_range": "today"
}
},
"access_permissions": null,
"status": "ACTIVE",
"created_by": 12345,
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 8.2 查询看板配置列表
**接口地址**: `GET /dashboards`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| status | string | 否 | 配置状态 |
| 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": 3001,
"name": "运营数据看板",
"description": "展示核心运营数据",
"status": "ACTIVE",
"created_by": 12345,
"created_at": "2024-01-15T10:30:00Z"
}
]
}
}
```
### 8.3 获取看板数据
**接口地址**: `GET /dashboards/{id}/data`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 看板配置ID |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 配置ID |
| name | string | 看板名称 |
| widgets_data | object | 各组件数据 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 3001,
"name": "运营数据看板",
"widgets_data": {
"widget1": {
"title": "用户总数",
"value": 12500,
"change": 150
}
}
}
}
```
## 9. 错误码定义
| 错误码 | 错误信息 | 描述 |
|--------|----------|------|
| 0 | success | 请求成功 |
| 40001 | 参数错误 | 请求参数不合法 |
| 40002 | 统计数据不存在 | 指定的统计数据不存在 |
| 40003 | 报表模板不存在 | 指定的报表模板不存在 |
| 40004 | 报表生成记录不存在 | 指定的报表生成记录不存在 |
| 40005 | 分析任务不存在 | 指定的分析任务不存在 |
| 40006 | 看板配置不存在 | 指定的看板配置不存在 |
| 40007 | 报表生成失败 | 报表生成过程中发生错误 |
| 40008 | 数据分析失败 | 数据分析过程中发生错误 |
| 40009 | 报表文件不存在 | 指定的报表文件不存在 |
| 40010 | SQL查询错误 | 报表模板中的SQL查询存在错误 |
| 50001 | 权限不足 | 用户权限不足，无法访问该资源 |
| 50002 | 认证失败 | 用户认证失败 |
| 99999 | 系统错误 | 服务器内部错误 |

900
docs/design/api/farming_service_api_design.md Normal file
View File

@@ -0,0 +1,900 @@
# 农业服务API设计文档
## 1. 概述
本文档详细描述了农业服务(farming-service)提供的API接口，包括农田管理、农事活动记录、作物生长监测、病虫害防治、环境数据监测、收获管理等核心功能。
## 2. 基础信息
- 基础路径: `/api/v1/farming`
- 版本: 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 创建农田
**接口地址**: `POST /farmlands`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| name | string | 是 | 农田名称 |
| location | string | 是 | 地理位置 |
| area | number | 是 | 面积(亩) |
| crop_type | string | 是 | 作物类型 |
| planting_date | string | 否 | 种植日期(YYYY-MM-DD) |
| description | string | 否 | 描述 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 农田ID |
| user_id | integer | 用户ID |
| name | string | 农田名称 |
| location | string | 地理位置 |
| area | number | 面积(亩) |
| crop_type | string | 作物类型 |
| planting_date | string | 种植日期 |
| status | string | 状态 |
| description | string | 描述 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"name": "一号小麦田",
"location": "北京市朝阳区某农场",
"area": 100.5,
"crop_type": "小麦",
"planting_date": "2024-01-15",
"description": "春季小麦种植"
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1001,
"user_id": 12345,
"name": "一号小麦田",
"location": "北京市朝阳区某农场",
"area": 100.5,
"crop_type": "小麦",
"planting_date": "2024-01-15",
"status": "ACTIVE",
"description": "春季小麦种植",
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 5.2 获取农田列表
**接口地址**: `GET /farmlands`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| crop_type | string | 否 | 作物类型筛选 |
| status | string | 否 | 状态筛选 |
| 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": 1001,
"name": "一号小麦田",
"location": "北京市朝阳区某农场",
"area": 100.5,
"crop_type": "小麦",
"planting_date": "2024-01-15",
"status": "ACTIVE",
"description": "春季小麦种植",
"created_at": "2024-01-15T10:30:00Z"
}
]
}
}
```
### 5.3 获取农田详情
**接口地址**: `GET /farmlands/{id}`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 农田ID |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 农田ID |
| user_id | integer | 用户ID |
| name | string | 农田名称 |
| location | string | 地理位置 |
| area | number | 面积(亩) |
| crop_type | string | 作物类型 |
| planting_date | string | 种植日期 |
| status | string | 状态 |
| description | string | 描述 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1001,
"user_id": 12345,
"name": "一号小麦田",
"location": "北京市朝阳区某农场",
"area": 100.5,
"crop_type": "小麦",
"planting_date": "2024-01-15",
"status": "ACTIVE",
"description": "春季小麦种植",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
```
### 5.4 更新农田信息
**接口地址**: `PUT /farmlands/{id}`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 农田ID |
| name | string | 否 | 农田名称 |
| location | string | 否 | 地理位置 |
| area | number | 否 | 面积(亩) |
| crop_type | string | 否 | 作物类型 |
| planting_date | string | 否 | 种植日期(YYYY-MM-DD) |
| status | string | 否 | 状态 |
| description | string | 否 | 描述 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 农田ID |
| user_id | integer | 用户ID |
| name | string | 农田名称 |
| location | string | 地理位置 |
| area | number | 面积(亩) |
| crop_type | string | 作物类型 |
| planting_date | string | 种植日期 |
| status | string | 状态 |
| description | string | 描述 |
| updated_at | string | 更新时间 |
**示例请求**:
```json
{
"name": "一号小麦田",
"location": "北京市朝阳区某农场",
"area": 100.5,
"crop_type": "小麦",
"planting_date": "2024-01-15",
"status": "ACTIVE",
"description": "春季小麦种植，已施肥"
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1001,
"user_id": 12345,
"name": "一号小麦田",
"location": "北京市朝阳区某农场",
"area": 100.5,
"crop_type": "小麦",
"planting_date": "2024-01-15",
"status": "ACTIVE",
"description": "春季小麦种植，已施肥",
"updated_at": "2024-01-15T11:00:00Z"
}
}
```
## 6. 农事活动接口
### 6.1 记录农事活动
**接口地址**: `POST /activities`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 是 | 农田ID |
| activity_type | string | 是 | 活动类型(播种/施肥/除草/收割等) |
| activity_date | string | 是 | 活动日期(YYYY-MM-DD) |
| description | string | 否 | 活动描述 |
| cost | number | 否 | 费用 |
| operator | string | 否 | 操作人员 |
| images | array | 否 | 活动图片URL列表 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 活动记录ID |
| farmland_id | integer | 农田ID |
| activity_type | string | 活动类型 |
| activity_date | string | 活动日期 |
| description | string | 活动描述 |
| cost | number | 费用 |
| operator | string | 操作人员 |
| images | array | 活动图片URL列表 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"farmland_id": 1001,
"activity_type": "施肥",
"activity_date": "2024-01-20",
"description": "施用氮肥",
"cost": 500.00,
"operator": "张三",
"images": ["https://example.com/image1.jpg"]
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 2001,
"farmland_id": 1001,
"activity_type": "施肥",
"activity_date": "2024-01-20",
"description": "施用氮肥",
"cost": 500.00,
"operator": "张三",
"images": ["https://example.com/image1.jpg"],
"created_at": "2024-01-20T10:30:00Z"
}
}
```
### 6.2 获取农事活动列表
**接口地址**: `GET /activities`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 否 | 农田ID筛选 |
| activity_type | 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": 1,
"page": 1,
"size": 10,
"items": [
{
"id": 2001,
"farmland_id": 1001,
"activity_type": "施肥",
"activity_date": "2024-01-20",
"description": "施用氮肥",
"cost": 500.00,
"operator": "张三",
"images": ["https://example.com/image1.jpg"],
"created_at": "2024-01-20T10:30:00Z"
}
]
}
}
```
## 7. 作物生长监测接口
### 7.1 记录作物生长情况
**接口地址**: `POST /growth-records`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 是 | 农田ID |
| record_date | string | 是 | 记录日期(YYYY-MM-DD) |
| growth_stage | string | 是 | 生长阶段 |
| height | number | 否 | 株高(cm) |
| leaf_count | integer | 否 | 叶片数 |
| health_status | string | 否 | 健康状况 |
| notes | string | 否 | 备注 |
| images | array | 否 | 图片URL列表 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 记录ID |
| farmland_id | integer | 农田ID |
| record_date | string | 记录日期 |
| growth_stage | string | 生长阶段 |
| height | number | 株高(cm) |
| leaf_count | integer | 叶片数 |
| health_status | string | 健康状况 |
| notes | string | 备注 |
| images | array | 图片URL列表 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"farmland_id": 1001,
"record_date": "2024-01-25",
"growth_stage": "分蘖期",
"height": 15.5,
"leaf_count": 6,
"health_status": "健康",
"notes": "生长良好",
"images": ["https://example.com/image2.jpg"]
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 3001,
"farmland_id": 1001,
"record_date": "2024-01-25",
"growth_stage": "分蘖期",
"height": 15.5,
"leaf_count": 6,
"health_status": "健康",
"notes": "生长良好",
"images": ["https://example.com/image2.jpg"],
"created_at": "2024-01-25T10:30:00Z"
}
}
```
### 7.2 获取作物生长记录列表
**接口地址**: `GET /growth-records`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 否 | 农田ID筛选 |
| growth_stage | 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": 1,
"page": 1,
"size": 10,
"items": [
{
"id": 3001,
"farmland_id": 1001,
"record_date": "2024-01-25",
"growth_stage": "分蘖期",
"height": 15.5,
"leaf_count": 6,
"health_status": "健康",
"notes": "生长良好",
"images": ["https://example.com/image2.jpg"],
"created_at": "2024-01-25T10:30:00Z"
}
]
}
}
```
## 8. 病虫害防治接口
### 8.1 记录病虫害情况
**接口地址**: `POST /pest-disease-records`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 是 | 农田ID |
| record_date | string | 是 | 记录日期(YYYY-MM-DD) |
| type | string | 是 | 类型(病害/虫害) |
| name | string | 是 | 病虫害名称 |
| severity | string | 是 | 严重程度(轻/中/重) |
| affected_area | number | 否 | 受害面积(亩) |
| control_method | string | 否 | 防治方法 |
| control_date | string | 否 | 防治日期(YYYY-MM-DD) |
| control_result | string | 否 | 防治效果 |
| notes | string | 否 | 备注 |
| images | array | 否 | 图片URL列表 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 记录ID |
| farmland_id | integer | 农田ID |
| record_date | string | 记录日期 |
| type | string | 类型 |
| name | string | 病虫害名称 |
| severity | string | 严重程度 |
| affected_area | number | 受害面积(亩) |
| control_method | string | 防治方法 |
| control_date | string | 防治日期 |
| control_result | string | 防治效果 |
| notes | string | 备注 |
| images | array | 图片URL列表 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"farmland_id": 1001,
"record_date": "2024-01-30",
"type": "病害",
"name": "小麦赤霉病",
"severity": "中",
"affected_area": 20.0,
"control_method": "喷施多菌灵",
"control_date": "2024-01-31",
"control_result": "控制良好",
"notes": "发现较早，及时处理",
"images": ["https://example.com/image3.jpg"]
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 4001,
"farmland_id": 1001,
"record_date": "2024-01-30",
"type": "病害",
"name": "小麦赤霉病",
"severity": "中",
"affected_area": 20.0,
"control_method": "喷施多菌灵",
"control_date": "2024-01-31",
"control_result": "控制良好",
"notes": "发现较早，及时处理",
"images": ["https://example.com/image3.jpg"],
"created_at": "2024-01-30T10:30:00Z"
}
}
```
### 8.2 获取病虫害记录列表
**接口地址**: `GET /pest-disease-records`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 否 | 农田ID筛选 |
| type | string | 否 | 类型筛选 |
| name | 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": 1,
"page": 1,
"size": 10,
"items": [
{
"id": 4001,
"farmland_id": 1001,
"record_date": "2024-01-30",
"type": "病害",
"name": "小麦赤霉病",
"severity": "中",
"affected_area": 20.0,
"control_method": "喷施多菌灵",
"control_date": "2024-01-31",
"control_result": "控制良好",
"notes": "发现较早，及时处理",
"images": ["https://example.com/image3.jpg"],
"created_at": "2024-01-30T10:30:00Z"
}
]
}
}
```
## 9. 环境数据监测接口
### 9.1 记录环境数据
**接口地址**: `POST /environmental-data`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 是 | 农田ID |
| record_time | string | 否 | 记录时间(ISO8601格式)，默认为当前时间 |
| temperature | number | 否 | 温度(℃) |
| humidity | number | 否 | 湿度(%) |
| soil_moisture | number | 否 | 土壤湿度(%) |
| ph_value | number | 否 | 土壤pH值 |
| nitrogen | number | 否 | 氮含量(mg/kg) |
| phosphorus | number | 否 | 磷含量(mg/kg) |
| potassium | number | 否 | 钾含量(mg/kg) |
| notes | string | 否 | 备注 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 记录ID |
| farmland_id | integer | 农田ID |
| record_time | string | 记录时间 |
| temperature | number | 温度(℃) |
| humidity | number | 湿度(%) |
| soil_moisture | number | 土壤湿度(%) |
| ph_value | number | 土壤pH值 |
| nitrogen | number | 氮含量(mg/kg) |
| phosphorus | number | 磷含量(mg/kg) |
| potassium | number | 钾含量(mg/kg) |
| notes | string | 备注 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"farmland_id": 1001,
"record_time": "2024-02-01T10:00:00Z",
"temperature": 15.5,
"humidity": 65.0,
"soil_moisture": 45.0,
"ph_value": 6.8,
"nitrogen": 120.5,
"phosphorus": 45.2,
"potassium": 180.3,
"notes": "环境适宜作物生长"
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 5001,
"farmland_id": 1001,
"record_time": "2024-02-01T10:00:00Z",
"temperature": 15.5,
"humidity": 65.0,
"soil_moisture": 45.0,
"ph_value": 6.8,
"nitrogen": 120.5,
"phosphorus": 45.2,
"potassium": 180.3,
"notes": "环境适宜作物生长",
"created_at": "2024-02-01T10:00:00Z"
}
}
```
### 9.2 获取环境数据列表
**接口地址**: `GET /environmental-data`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 否 | 农田ID筛选 |
| start_time | string | 否 | 开始时间(ISO8601格式) |
| end_time | string | 否 | 结束时间(ISO8601格式) |
| 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,
"farmland_id": 1001,
"record_time": "2024-02-01T10:00:00Z",
"temperature": 15.5,
"humidity": 65.0,
"soil_moisture": 45.0,
"ph_value": 6.8,
"nitrogen": 120.5,
"phosphorus": 45.2,
"potassium": 180.3,
"notes": "环境适宜作物生长",
"created_at": "2024-02-01T10:00:00Z"
}
]
}
}
```
## 10. 收获管理接口
### 10.1 记录收获信息
**接口地址**: `POST /harvest-records`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 是 | 农田ID |
| harvest_date | string | 是 | 收获日期(YYYY-MM-DD) |
| yield | number | 是 | 产量(公斤) |
| quality | string | 否 | 质量等级 |
| storage_location | string | 否 | 存储位置 |
| selling_price | number | 否 | 销售价格(元/公斤) |
| sold_quantity | number | 否 | 已售数量(公斤) |
| notes | string | 否 | 备注 |
| images | array | 否 | 图片URL列表 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 记录ID |
| farmland_id | integer | 农田ID |
| harvest_date | string | 收获日期 |
| yield | number | 产量(公斤) |
| quality | string | 质量等级 |
| storage_location | string | 存储位置 |
| selling_price | number | 销售价格(元/公斤) |
| sold_quantity | number | 已售数量(公斤) |
| notes | string | 备注 |
| images | array | 图片URL列表 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"farmland_id": 1001,
"harvest_date": "2024-06-15",
"yield": 52000.0,
"quality": "一级",
"storage_location": "一号仓库",
"selling_price": 2.5,
"sold_quantity": 30000.0,
"notes": "丰收年，质量上乘",
"images": ["https://example.com/image4.jpg"]
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 6001,
"farmland_id": 1001,
"harvest_date": "2024-06-15",
"yield": 52000.0,
"quality": "一级",
"storage_location": "一号仓库",
"selling_price": 2.5,
"sold_quantity": 30000.0,
"notes": "丰收年，质量上乘",
"images": ["https://example.com/image4.jpg"],
"created_at": "2024-06-15T10:30:00Z"
}
}
```
### 10.2 获取收获记录列表
**接口地址**: `GET /harvest-records`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 否 | 农田ID筛选 |
| 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": 1,
"page": 1,
"size": 10,
"items": [
{
"id": 6001,
"farmland_id": 1001,
"harvest_date": "2024-06-15",
"yield": 52000.0,
"quality": "一级",
"storage_location": "一号仓库",
"selling_price": 2.5,
"sold_quantity": 30000.0,
"notes": "丰收年，质量上乘",
"images": ["https://example.com/image4.jpg"],
"created_at": "2024-06-15T10:30:00Z"
}
]
}
}
```
## 11. 错误码定义
| 错误码 | 错误信息 | 描述 |
|--------|----------|------|
| 0 | success | 请求成功 |
| 40001 | 参数错误 | 请求参数不合法 |
| 40002 | 农田不存在 | 指定的农田不存在 |
| 40003 | 农田状态不允许此操作 | 当前农田状态不允许执行该操作 |
| 40004 | 农事活动记录不存在 | 指定的农事活动记录不存在 |
| 40005 | 作物生长记录不存在 | 指定的作物生长记录不存在 |
| 40006 | 病虫害记录不存在 | 指定的病虫害记录不存在 |
| 40007 | 环境数据记录不存在 | 指定的环境数据记录不存在 |
| 40008 | 收获记录不存在 | 指定的收获记录不存在 |
| 50001 | 权限不足 | 用户权限不足，无法访问该资源 |
| 50002 | 认证失败 | 用户认证失败 |
| 99999 | 系统错误 | 服务器内部错误 |

535
docs/design/api/finance_service_api_design.md Normal file
View File

@@ -0,0 +1,535 @@
# 金融服务API设计文档
## 1. 概述
本文档详细描述了金融服务(finance-service)提供的API接口，包括贷款管理、保险管理等核心功能。
## 2. 基础信息
- 基础路径: `/api/v1/finance`
- 版本: 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": 20001,
"message": "错误描述",
"data": null
}
```
## 5. 贷款管理接口
### 5.1 获取贷款产品列表
**接口地址**: `GET /loans/products`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| status | string | 否 | 产品状态(ACTIVE/INACTIVE) |
| 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": 1,
"name": "养殖贷款",
"description": "专为养殖户设计的贷款产品",
"interest_rate": 0.052,
"term_months": 12,
"min_amount": 10000.00,
"max_amount": 1000000.00,
"status": "ACTIVE",
"created_at": "2024-01-01T00:00:00Z"
}
]
}
}
```
### 5.2 提交贷款申请
**接口地址**: `POST /loans/applications`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| product_id | integer | 是 | 贷款产品ID |
| amount | number | 是 | 申请金额 |
| term_months | integer | 是 | 申请期限(月) |
| purpose | string | 否 | 贷款用途 |
| contact_info | object | 是 | 联系信息 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 贷款申请ID |
| user_id | integer | 申请人用户ID |
| product_id | integer | 贷款产品ID |
| amount | number | 申请金额 |
| term_months | integer | 申请期限(月) |
| status | string | 申请状态 |
| purpose | string | 贷款用途 |
| contact_info | object | 联系信息 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"product_id": 1,
"amount": 50000.00,
"term_months": 12,
"purpose": "购买饲料",
"contact_info": {
"phone": "13800138000",
"email": "user@example.com",
"address": "北京市朝阳区xxx街道"
}
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1001,
"user_id": 12345,
"product_id": 1,
"amount": 50000.00,
"term_months": 12,
"status": "SUBMITTED",
"purpose": "购买饲料",
"contact_info": {
"phone": "13800138000",
"email": "user@example.com",
"address": "北京市朝阳区xxx街道"
},
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 5.3 查询贷款申请列表
**接口地址**: `GET /loans/applications`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| status | string | 否 | 申请状态 |
| 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": 1001,
"user_id": 12345,
"product": {
"id": 1,
"name": "养殖贷款"
},
"amount": 50000.00,
"term_months": 12,
"status": "APPROVED",
"purpose": "购买饲料",
"contact_info": {
"phone": "13800138000",
"email": "user@example.com"
},
"approval_time": "2024-01-16T09:00:00Z",
"created_at": "2024-01-15T10:30:00Z"
}
]
}
}
```
### 5.4 查询贷款申请详情
**接口地址**: `GET /loans/applications/{id}`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 贷款申请ID |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 贷款申请ID |
| user_id | integer | 申请人用户ID |
| product | object | 贷款产品信息 |
| amount | number | 申请金额 |
| term_months | integer | 申请期限(月) |
| status | string | 申请状态 |
| purpose | string | 贷款用途 |
| contact_info | object | 联系信息 |
| credit_score | integer | 信用评分 |
| approval_time | string | 审批时间 |
| disbursement_time | string | 放款时间 |
| settlement_time | string | 结清时间 |
| repayment_schedules | array | 还款计划列表 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1001,
"user_id": 12345,
"product": {
"id": 1,
"name": "养殖贷款",
"interest_rate": 0.052,
"term_months": 12
},
"amount": 50000.00,
"term_months": 12,
"status": "DISBURSED",
"purpose": "购买饲料",
"contact_info": {
"phone": "13800138000",
"email": "user@example.com",
"address": "北京市朝阳区xxx街道"
},
"credit_score": 750,
"approval_time": "2024-01-16T09:00:00Z",
"disbursement_time": "2024-01-17T10:00:00Z",
"repayment_schedules": [
{
"id": 1,
"installment_number": 1,
"due_date": "2024-02-17",
"principal_amount": 4166.67,
"interest_amount": 216.67,
"total_amount": 4383.34,
"status": "PENDING"
}
],
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-17T10:00:00Z"
}
}
```
## 6. 保险管理接口
### 6.1 获取保险产品列表
**接口地址**: `GET /insurance/products`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| type | string | 否 | 保险类型(CATTLE/PROPERTY/LIABILITY) |
| status | string | 否 | 产品状态(ACTIVE/INACTIVE) |
| 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": 1,
"name": "牲畜保险",
"description": "为牲畜提供全面保障的保险产品",
"premium_rate": 0.005,
"coverage_amount": 10000.00,
"term_months": 12,
"type": "CATTLE",
"status": "ACTIVE",
"created_at": "2024-01-01T00:00:00Z"
}
]
}
}
```
### 6.2 提交保险投保申请
**接口地址**: `POST /insurance/policies`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| product_id | integer | 是 | 保险产品ID |
| insured_amount | number | 是 | 投保金额 |
| start_date | string | 是 | 保险起始日期(YYYY-MM-DD) |
| beneficiary_info | object | 是 | 受益人信息 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 保单ID |
| user_id | integer | 投保人用户ID |
| product_id | integer | 保险产品ID |
| policy_no | string | 保单号 |
| insured_amount | number | 投保金额 |
| premium_amount | number | 保费金额 |
| status | string | 保单状态 |
| start_date | string | 保险起始日期 |
| end_date | string | 保险结束日期 |
| beneficiary_info | object | 受益人信息 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"product_id": 1,
"insured_amount": 50000.00,
"start_date": "2024-02-01",
"beneficiary_info": {
"name": "张三",
"id_card": "110101199001011234",
"phone": "13800138000"
}
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 2001,
"user_id": 12345,
"product_id": 1,
"policy_no": "INS202401150001",
"insured_amount": 50000.00,
"premium_amount": 250.00,
"status": "ACTIVE",
"start_date": "2024-02-01",
"end_date": "2025-01-31",
"beneficiary_info": {
"name": "张三",
"id_card": "110101199001011234",
"phone": "13800138000"
},
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 6.3 查询保险投保列表
**接口地址**: `GET /insurance/policies`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| status | string | 否 | 保单状态 |
| 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": 2001,
"user_id": 12345,
"policy_no": "INS202401150001",
"product": {
"id": 1,
"name": "牲畜保险"
},
"insured_amount": 50000.00,
"premium_amount": 250.00,
"status": "ACTIVE",
"start_date": "2024-02-01",
"end_date": "2025-01-31",
"created_at": "2024-01-15T10:30:00Z"
}
]
}
}
```
### 6.4 提交理赔申请
**接口地址**: `POST /insurance/claims`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| policy_id | integer | 是 | 保单ID |
| claim_amount | number | 是 | 理赔金额 |
| incident_date | string | 是 | 事故日期(YYYY-MM-DD) |
| incident_description | string | 是 | 事故描述 |
| supporting_documents | array | 否 | 支持文件URL列表 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 理赔申请ID |
| policy_id | integer | 关联保单ID |
| claim_no | string | 理赔编号 |
| claim_amount | number | 理赔金额 |
| status | string | 理赔状态 |
| incident_date | string | 事故日期 |
| incident_description | string | 事故描述 |
| supporting_documents | array | 支持文件URL列表 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"policy_id": 2001,
"claim_amount": 20000.00,
"incident_date": "2024-03-01",
"incident_description": "牲畜因疾病死亡",
"supporting_documents": [
"http://example.com/document1.jpg",
"http://example.com/document2.jpg"
]
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 3001,
"policy_id": 2001,
"claim_no": "CLM202403010001",
"claim_amount": 20000.00,
"status": "SUBMITTED",
"incident_date": "2024-03-01",
"incident_description": "牲畜因疾病死亡",
"supporting_documents": [
"http://example.com/document1.jpg",
"http://example.com/document2.jpg"
],
"created_at": "2024-03-01T10:30:00Z"
}
}
```
## 7. 错误码定义
| 错误码 | 错误信息 | 描述 |
|--------|----------|------|
| 0 | success | 请求成功 |
| 20001 | 参数错误 | 请求参数不合法 |
| 20002 | 贷款产品不存在 | 指定的贷款产品不存在 |
| 20003 | 贷款申请不存在 | 指定的贷款申请不存在 |
| 20004 | 保险产品不存在 | 指定的保险产品不存在 |
| 20005 | 保单不存在 | 指定的保单不存在 |
| 20006 | 理赔申请不存在 | 指定的理赔申请不存在 |
| 20007 | 申请金额超出范围 | 贷款申请金额超出产品规定范围 |
| 20008 | 保险金额超出范围 | 保险金额超出产品规定范围 |
| 20009 | 保单已过期 | 保单已过期，无法提交理赔 |
| 20010 | 理赔金额超出保额 | 理赔金额超出保险金额 |
| 20011 | 申请状态错误 | 当前申请状态无法执行该操作 |
| 30001 | 权限不足 | 用户权限不足，无法访问该资源 |
| 30002 | 认证失败 | 用户认证失败 |
| 99999 | 系统错误 | 服务器内部错误 |

883
docs/design/api/government_service_api_design.md Normal file
View File

@@ -0,0 +1,883 @@
# 政府服务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 | 系统错误 | 服务器内部错误 |

812
docs/design/api/iot_service_api_design.md Normal file
View File

@@ -0,0 +1,812 @@
# 物联网服务API设计文档
## 1. 概述
本文档详细描述了物联网服务(iot-service)提供的API接口，包括设备管理、传感器数据采集、设备控制、告警管理等核心功能。
## 2. 基础信息
- 基础路径: `/api/v1/iot`
- 版本: 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 注册设备
**接口地址**: `POST /devices`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| device_id | string | 是 | 设备唯一标识 |
| name | string | 是 | 设备名称 |
| type | string | 是 | 设备类型(传感器/控制器等) |
| model | string | 否 | 设备型号 |
| manufacturer | string | 否 | 制造商 |
| location | string | 否 | 设备位置 |
| description | string | 否 | 描述 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 设备ID |
| user_id | integer | 用户ID |
| device_id | string | 设备唯一标识 |
| name | string | 设备名称 |
| type | string | 设备类型 |
| model | string | 设备型号 |
| manufacturer | string | 制造商 |
| location | string | 设备位置 |
| status | string | 设备状态 |
| last_heartbeat | string | 最后心跳时间 |
| firmware_version | string | 固件版本 |
| description | string | 描述 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"device_id": "SENSOR001",
"name": "温湿度传感器001",
"type": "传感器",
"model": "DHT22",
"manufacturer": "某某电子",
"location": "一号小麦田",
"description": "用于监测农田环境温湿度"
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1001,
"user_id": 12345,
"device_id": "SENSOR001",
"name": "温湿度传感器001",
"type": "传感器",
"model": "DHT22",
"manufacturer": "某某电子",
"location": "一号小麦田",
"status": "ACTIVE",
"last_heartbeat": null,
"firmware_version": null,
"description": "用于监测农田环境温湿度",
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 5.2 获取设备列表
**接口地址**: `GET /devices`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| type | string | 否 | 设备类型筛选 |
| status | string | 否 | 设备状态筛选 |
| 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": 1001,
"user_id": 12345,
"device_id": "SENSOR001",
"name": "温湿度传感器001",
"type": "传感器",
"model": "DHT22",
"manufacturer": "某某电子",
"location": "一号小麦田",
"status": "ACTIVE",
"last_heartbeat": null,
"firmware_version": null,
"description": "用于监测农田环境温湿度",
"created_at": "2024-01-15T10:30:00Z"
}
]
}
}
```
### 5.3 获取设备详情
**接口地址**: `GET /devices/{id}`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 设备ID |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 设备ID |
| user_id | integer | 用户ID |
| device_id | string | 设备唯一标识 |
| name | string | 设备名称 |
| type | string | 设备类型 |
| model | string | 设备型号 |
| manufacturer | string | 制造商 |
| location | string | 设备位置 |
| status | string | 设备状态 |
| last_heartbeat | string | 最后心跳时间 |
| firmware_version | string | 固件版本 |
| description | string | 描述 |
| configs | array | 设备配置列表 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1001,
"user_id": 12345,
"device_id": "SENSOR001",
"name": "温湿度传感器001",
"type": "传感器",
"model": "DHT22",
"manufacturer": "某某电子",
"location": "一号小麦田",
"status": "ACTIVE",
"last_heartbeat": "2024-01-15T10:30:00Z",
"firmware_version": "v1.0.0",
"description": "用于监测农田环境温湿度",
"configs": [
{
"config_key": "sampling_interval",
"config_value": "300",
"description": "采样间隔(秒)"
}
],
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
```
### 5.4 更新设备信息
**接口地址**: `PUT /devices/{id}`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 设备ID |
| name | string | 否 | 设备名称 |
| location | string | 否 | 设备位置 |
| status | string | 否 | 设备状态 |
| description | string | 否 | 描述 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 设备ID |
| user_id | integer | 用户ID |
| device_id | string | 设备唯一标识 |
| name | string | 设备名称 |
| type | string | 设备类型 |
| model | string | 设备型号 |
| manufacturer | string | 制造商 |
| location | string | 设备位置 |
| status | string | 设备状态 |
| last_heartbeat | string | 最后心跳时间 |
| firmware_version | string | 固件版本 |
| description | string | 描述 |
| updated_at | string | 更新时间 |
**示例请求**:
```json
{
"name": "温湿度传感器001",
"location": "一号小麦田A区",
"status": "ACTIVE",
"description": "用于监测农田环境温湿度，位置已更新"
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1001,
"user_id": 12345,
"device_id": "SENSOR001",
"name": "温湿度传感器001",
"type": "传感器",
"model": "DHT22",
"manufacturer": "某某电子",
"location": "一号小麦田A区",
"status": "ACTIVE",
"last_heartbeat": "2024-01-15T10:30:00Z",
"firmware_version": "v1.0.0",
"description": "用于监测农田环境温湿度，位置已更新",
"updated_at": "2024-01-15T11:00:00Z"
}
}
```
### 5.5 删除设备
**接口地址**: `DELETE /devices/{id}`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 设备ID |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| message | string | 删除结果信息 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"message": "设备删除成功"
}
}
```
## 6. 传感器数据接口
### 6.1 上报传感器数据
**接口地址**: `POST /sensor-data`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| device_id | string | 是 | 设备ID |
| sensor_type | string | 是 | 传感器类型(温度/湿度/光照等) |
| value | number | 是 | 传感器数值 |
| unit | string | 是 | 单位 |
| timestamp | string | 否 | 数据时间戳(ISO8601格式)，默认为当前时间 |
| latitude | number | 否 | 纬度 |
| longitude | number | 否 | 经度 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 数据记录ID |
| device_id | string | 设备ID |
| sensor_type | string | 传感器类型 |
| value | number | 传感器数值 |
| unit | string | 单位 |
| timestamp | string | 数据时间戳 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"device_id": "SENSOR001",
"sensor_type": "温度",
"value": 25.6,
"unit": "℃",
"timestamp": "2024-01-15T10:30:00Z",
"latitude": 39.9042,
"longitude": 116.4074
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 2001,
"device_id": "SENSOR001",
"sensor_type": "温度",
"value": 25.6,
"unit": "℃",
"timestamp": "2024-01-15T10:30:00Z",
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 6.2 获取传感器数据列表
**接口地址**: `GET /sensor-data`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| device_id | string | 否 | 设备ID筛选 |
| sensor_type | string | 否 | 传感器类型筛选 |
| start_time | string | 否 | 开始时间(ISO8601格式) |
| end_time | string | 否 | 结束时间(ISO8601格式) |
| 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": 2001,
"device_id": "SENSOR001",
"sensor_type": "温度",
"value": 25.6,
"unit": "℃",
"timestamp": "2024-01-15T10:30:00Z",
"created_at": "2024-01-15T10:30:00Z"
}
]
}
}
```
### 6.3 获取传感器数据统计
**接口地址**: `GET /sensor-data/statistics`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| device_id | string | 是 | 设备ID |
| sensor_type | string | 是 | 传感器类型 |
| aggregation_type | string | 是 | 聚合类型(HOURLY/DAILY/WEEKLY/MONTHLY) |
| start_time | string | 否 | 开始时间(ISO8601格式) |
| end_time | string | 否 | 结束时间(ISO8601格式) |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| device_id | string | 设备ID |
| sensor_type | string | 传感器类型 |
| aggregation_type | string | 聚合类型 |
| data | array | 统计数据列表 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"device_id": "SENSOR001",
"sensor_type": "温度",
"aggregation_type": "DAILY",
"data": [
{
"timestamp": "2024-01-15T00:00:00Z",
"min_value": 22.1,
"max_value": 26.8,
"avg_value": 24.5,
"count": 24
}
]
}
}
```
## 7. 设备控制接口
### 7.1 发送控制命令
**接口地址**: `POST /commands`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| device_id | string | 是 | 设备ID |
| command | string | 是 | 命令名称 |
| parameters | object | 否 | 命令参数 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 命令ID |
| device_id | string | 设备ID |
| command | string | 命令名称 |
| parameters | object | 命令参数 |
| status | string | 命令状态 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"device_id": "CTRL001",
"command": "开启灌溉",
"parameters": {
"duration": 300,
"flow_rate": 10
}
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 3001,
"device_id": "CTRL001",
"command": "开启灌溉",
"parameters": {
"duration": 300,
"flow_rate": 10
},
"status": "PENDING",
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 7.2 获取命令执行状态
**接口地址**: `GET /commands/{id}`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 命令ID |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 命令ID |
| device_id | string | 设备ID |
| command | string | 命令名称 |
| parameters | object | 命令参数 |
| status | string | 命令状态 |
| result | string | 执行结果 |
| sent_at | string | 发送时间 |
| executed_at | string | 执行时间 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 3001,
"device_id": "CTRL001",
"command": "开启灌溉",
"parameters": {
"duration": 300,
"flow_rate": 10
},
"status": "EXECUTED",
"result": "灌溉系统已开启，将持续300秒",
"sent_at": "2024-01-15T10:30:00Z",
"executed_at": "2024-01-15T10:30:05Z",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:05Z"
}
}
```
### 7.3 获取命令历史列表
**接口地址**: `GET /commands`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| device_id | string | 否 | 设备ID筛选 |
| command | string | 否 | 命令名称筛选 |
| status | string | 否 | 命令状态筛选 |
| 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": 3001,
"device_id": "CTRL001",
"command": "开启灌溉",
"parameters": {
"duration": 300,
"flow_rate": 10
},
"status": "EXECUTED",
"result": "灌溉系统已开启，将持续300秒",
"sent_at": "2024-01-15T10:30:00Z",
"executed_at": "2024-01-15T10:30:05Z",
"created_at": "2024-01-15T10:30:00Z"
}
]
}
}
```
## 8. 告警管理接口
### 8.1 获取告警列表
**接口地址**: `GET /alerts`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| device_id | string | 否 | 设备ID筛选 |
| alert_type | string | 否 | 告警类型筛选 |
| alert_level | string | 否 | 告警级别筛选 |
| resolved | boolean | 否 | 是否已解决筛选 |
| 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": 4001,
"device_id": "SENSOR001",
"alert_type": "阈值超限",
"alert_level": "WARNING",
"message": "温度超过阈值35℃",
"value": 36.5,
"threshold": 35.0,
"resolved": false,
"timestamp": "2024-01-15T10:30:00Z",
"created_at": "2024-01-15T10:30:00Z"
}
]
}
}
```
### 8.2 标记告警为已解决
**接口地址**: `PUT /alerts/{id}/resolve`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 告警ID |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 告警ID |
| resolved | boolean | 是否已解决 |
| resolved_at | string | 解决时间 |
| updated_at | string | 更新时间 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 4001,
"resolved": true,
"resolved_at": "2024-01-15T11:00:00Z",
"updated_at": "2024-01-15T11:00:00Z"
}
}
```
## 9. 设备配置接口
### 9.1 获取设备配置
**接口地址**: `GET /devices/{id}/configs`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 设备ID |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| items | array | 配置列表 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"items": [
{
"config_key": "sampling_interval",
"config_value": "300",
"description": "采样间隔(秒)"
}
]
}
}
```
### 9.2 更新设备配置
**接口地址**: `PUT /devices/{id}/configs`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 设备ID |
| configs | array | 是 | 配置列表 |
**configs元素结构**:
| 字段名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| config_key | string | 是 | 配置键 |
| config_value | string | 是 | 配置值 |
| description | string | 否 | 配置描述 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| message | string | 更新结果信息 |
**示例请求**:
```json
{
"configs": [
{
"config_key": "sampling_interval",
"config_value": "600",
"description": "采样间隔(秒)"
}
]
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"message": "设备配置更新成功"
}
}
```
## 10. 错误码定义
| 错误码 | 错误信息 | 描述 |
|--------|----------|------|
| 0 | success | 请求成功 |
| 40001 | 参数错误 | 请求参数不合法 |
| 40002 | 设备不存在 | 指定的设备不存在 |
| 40003 | 设备状态不允许此操作 | 当前设备状态不允许执行该操作 |
| 40004 | 传感器数据记录不存在 | 指定的传感器数据记录不存在 |
| 40005 | 设备命令不存在 | 指定的设备命令不存在 |
| 40006 | 命令状态不允许此操作 | 当前命令状态不允许执行该操作 |
| 40007 | 告警记录不存在 | 指定的告警记录不存在 |
| 50001 | 权限不足 | 用户权限不足，无法访问该资源 |
| 50002 | 认证失败 | 用户认证失败 |
| 99999 | 系统错误 | 服务器内部错误 |

1233
docs/design/api/mall_service_api_design.md Normal file
View File

File diff suppressed because it is too large Load Diff

501
docs/design/api/trade_service_api_design.md Normal file
View File

@@ -0,0 +1,501 @@
# 交易服务API设计文档
## 1. 概述
本文档详细描述了交易服务(trade-service)提供的API接口，包括商品管理、订单处理、支付和物流等核心功能。
## 2. 基础信息
- 基础路径: `/api/v1/trade`
- 版本: 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": 10001,
"message": "错误描述",
"data": null
}
```
## 5. 商品管理接口
### 5.1 发布商品
**接口地址**: `POST /products`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| title | string | 是 | 商品标题 |
| description | string | 否 | 商品描述 |
| category | string | 是 | 商品分类 |
| price | number | 是 | 商品价格 |
| quantity | integer | 是 | 商品数量 |
| images | array | 否 | 商品图片URL列表 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 商品ID |
| seller_id | integer | 卖家用户ID |
| title | string | 商品标题 |
| description | string | 商品描述 |
| category | string | 商品分类 |
| price | number | 商品价格 |
| quantity | integer | 商品数量 |
| status | string | 商品状态 |
| images | array | 商品图片URL列表 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"title": "优质黄牛",
"description": "3岁健康黄牛，体重500公斤",
"category": "livestock",
"price": 15000.00,
"quantity": 1,
"images": [
"http://example.com/image1.jpg",
"http://example.com/image2.jpg"
]
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1001,
"seller_id": 12345,
"title": "优质黄牛",
"description": "3岁健康黄牛，体重500公斤",
"category": "livestock",
"price": 15000.00,
"quantity": 1,
"status": "PENDING",
"images": [
"http://example.com/image1.jpg",
"http://example.com/image2.jpg"
],
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 5.2 查询商品列表
**接口地址**: `GET /products`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| category | string | 否 | 商品分类 |
| status | string | 否 | 商品状态 |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 商品列表 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"total": 100,
"page": 1,
"size": 10,
"items": [
{
"id": 1001,
"seller_id": 12345,
"title": "优质黄牛",
"description": "3岁健康黄牛，体重500公斤",
"category": "livestock",
"price": 15000.00,
"quantity": 1,
"status": "APPROVED",
"images": [
"http://example.com/image1.jpg"
],
"created_at": "2024-01-15T10:30:00Z"
}
]
}
}
```
### 5.3 查询商品详情
**接口地址**: `GET /products/{id}`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 商品ID |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 商品ID |
| seller_id | integer | 卖家用户ID |
| title | string | 商品标题 |
| description | string | 商品描述 |
| category | string | 商品分类 |
| price | number | 商品价格 |
| quantity | integer | 商品数量 |
| status | string | 商品状态 |
| images | array | 商品图片URL列表 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1001,
"seller_id": 12345,
"title": "优质黄牛",
"description": "3岁健康黄牛，体重500公斤",
"category": "livestock",
"price": 15000.00,
"quantity": 1,
"status": "APPROVED",
"images": [
"http://example.com/image1.jpg",
"http://example.com/image2.jpg"
],
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
```
## 6. 订单管理接口
### 6.1 创建订单
**接口地址**: `POST /orders`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| product_id | integer | 是 | 商品ID |
| quantity | integer | 是 | 购买数量 |
| shipping_address | string | 是 | 收货地址 |
| contact_phone | string | 是 | 联系电话 |
| remark | string | 否 | 买家备注 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 订单ID |
| order_no | string | 订单编号 |
| buyer_id | integer | 买家用户ID |
| seller_id | integer | 卖家用户ID |
| product_id | integer | 商品ID |
| quantity | integer | 购买数量 |
| unit_price | number | 单价 |
| total_amount | number | 总金额 |
| status | string | 订单状态 |
| shipping_address | string | 收货地址 |
| contact_phone | string | 联系电话 |
| remark | string | 买家备注 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"product_id": 1001,
"quantity": 1,
"shipping_address": "北京市朝阳区xxx街道",
"contact_phone": "13800138000",
"remark": "请尽快发货"
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 2001,
"order_no": "ORD20240115103000001",
"buyer_id": 54321,
"seller_id": 12345,
"product_id": 1001,
"quantity": 1,
"unit_price": 15000.00,
"total_amount": 15000.00,
"status": "CREATED",
"shipping_address": "北京市朝阳区xxx街道",
"contact_phone": "13800138000",
"remark": "请尽快发货",
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 6.2 查询订单列表
**接口地址**: `GET /orders`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| status | string | 否 | 订单状态 |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 订单列表 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"total": 50,
"page": 1,
"size": 10,
"items": [
{
"id": 2001,
"order_no": "ORD20240115103000001",
"buyer_id": 54321,
"seller_id": 12345,
"product_id": 1001,
"quantity": 1,
"unit_price": 15000.00,
"total_amount": 15000.00,
"status": "PAID",
"shipping_address": "北京市朝阳区xxx街道",
"contact_phone": "13800138000",
"remark": "请尽快发货",
"created_at": "2024-01-15T10:30:00Z"
}
]
}
}
```
### 6.3 查询订单详情
**接口地址**: `GET /orders/{id}`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 订单ID |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 订单ID |
| order_no | string | 订单编号 |
| buyer_id | integer | 买家用户ID |
| seller_id | integer | 卖家用户ID |
| product | object | 商品信息 |
| quantity | integer | 购买数量 |
| unit_price | number | 单价 |
| total_amount | number | 总金额 |
| status | string | 订单状态 |
| shipping_address | string | 收货地址 |
| contact_phone | string | 联系电话 |
| remark | string | 买家备注 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 2001,
"order_no": "ORD20240115103000001",
"buyer_id": 54321,
"seller_id": 12345,
"product": {
"id": 1001,
"title": "优质黄牛",
"price": 15000.00,
"images": [
"http://example.com/image1.jpg"
]
},
"quantity": 1,
"unit_price": 15000.00,
"total_amount": 15000.00,
"status": "PAID",
"shipping_address": "北京市朝阳区xxx街道",
"contact_phone": "13800138000",
"remark": "请尽快发货",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T11:00:00Z"
}
}
```
## 7. 支付接口
### 7.1 发起支付
**接口地址**: `POST /payments`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| order_id | integer | 是 | 订单ID |
| payment_method | string | 是 | 支付方式(WECHAT/ALIPAY/BANK) |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 支付ID |
| order_id | integer | 关联订单ID |
| payment_no | string | 支付流水号 |
| amount | number | 支付金额 |
| payment_method | string | 支付方式 |
| status | string | 支付状态 |
| created_at | string | 创建时间 |
**示例请求**:
```json
{
"order_id": 2001,
"payment_method": "WECHAT"
}
```
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 3001,
"order_id": 2001,
"payment_no": "PAY20240115103000001",
"amount": 15000.00,
"payment_method": "WECHAT",
"status": "PENDING",
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 7.2 查询支付状态
**接口地址**: `GET /payments/{id}`
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 支付ID |
**响应数据**:
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 支付ID |
| order_id | integer | 关联订单ID |
| payment_no | string | 支付流水号 |
| amount | number | 支付金额 |
| payment_method | string | 支付方式 |
| status | string | 支付状态 |
| transaction_id | string | 第三方支付平台交易ID |
| paid_at | string | 实际支付时间 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |
**示例响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 3001,
"order_id": 2001,
"payment_no": "PAY20240115103000001",
"amount": 15000.00,
"payment_method": "WECHAT",
"status": "SUCCESS",
"transaction_id": "wx1234567890",
"paid_at": "2024-01-15T11:00:00Z",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T11:00:00Z"
}
}
```
## 8. 错误码定义
| 错误码 | 错误信息 | 描述 |
|--------|----------|------|
| 0 | success | 请求成功 |
| 10001 | 参数错误 | 请求参数不合法 |
| 10002 | 商品不存在 | 指定的商品不存在 |
| 10003 | 订单不存在 | 指定的订单不存在 |
| 10004 | 支付记录不存在 | 指定的支付记录不存在 |
| 10005 | 库存不足 | 商品库存不足 |
| 10006 | 订单状态错误 | 订单状态不正确，无法执行当前操作 |
| 10007 | 支付失败 | 支付处理失败 |
| 20001 | 权限不足 | 用户权限不足，无法访问该资源 |
| 20002 | 认证失败 | 用户认证失败 |
| 99999 | 系统错误 | 服务器内部错误 |

1162
docs/design/api/user_center_service_api_design.md Normal file
View File

File diff suppressed because it is too large Load Diff