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

docs: 更新项目文档和数据库设计，添加官网相关功能

Browse Source
This commit is contained in:
ylweng
2025-08-20 03:01:14 +08:00
parent 47c67ff704
commit fdc58aa3a2
58 changed files with 37635 additions and 28437 deletions
Download Patch File Download Diff File Expand all files Collapse all files

234
docs/design/api/dashboard.md Normal file
View File

@@ -0,0 +1,234 @@
# 大屏可视化系统 API 文档
## 1. 概述
大屏可视化系统是锡林郭勒盟智慧养殖产业平台的重要组成部分，主要用于展示产业整体数据、实时监控信息和分析结果。该系统通过直观的图表和数据可视化方式，为管理者提供全面的产业洞察。
## 2. 技术架构
- **前端框架**: Vue.js 3 + ECharts + 自定义可视化组件
- **可视化库**: Apache ECharts
- **响应式设计**: 支持多种大屏比例(16:9, 4:3等)
- **实时数据**: WebSocket实时数据推送
- **状态管理**: Pinia
## 3. 功能模块
### 3.1 产业概览
展示整体产业规模、产值、增长率等关键指标
### 3.2 养殖监控
实时展示各牧场的养殖情况、环境数据
### 3.3 金融服务
展示贷款、保险等金融服务数据
### 3.4 交易统计
牛只交易量、价格趋势、区域分布等数据
### 3.5 运输跟踪
牛只运输实时状态和路径展示
### 3.6 风险预警
风险事件展示和预警信息推送
### 3.7 生态指标
环保数据、可持续发展指标展示
### 3.8 政府监管
展示政府监管相关数据和政策执行效果
## 4. API 接口
### 4.1 实时数据接口
#### 获取实时数据
```
GET /api/v1/dashboard/realtime
```
**请求参数**:
- 无
**响应示例**:
```json
{
"timestamp": "2023-08-19T10:30:00Z",
"total_cattle": 128456,
"total_farms": 1245,
"annual_output_value": 2860000000,
"total_transaction": 1520000000
}
```
#### WebSocket 实时推送
```
WebSocket /api/v1/dashboard/ws
```
**推送数据格式**:
```json
{
"type": "realtime_update",
"data": {
"timestamp": "2023-08-19T10:30:00Z",
"total_cattle": 128456,
"total_farms": 1245,
"annual_output_value": 2860000000,
"total_transaction": 1520000000
}
}
```
### 4.2 历史数据接口
#### 获取历史数据
```
GET /api/v1/dashboard/history
```
**请求参数**:
- `start_date` (string, optional): 开始日期，格式 YYYY-MM-DD
- `end_date` (string, optional): 结束日期，格式 YYYY-MM-DD
- `type` (string, required): 数据类型 (breeding, transaction, transport, etc.)
**响应示例**:
```json
{
"data": [
{
"date": "2023-01",
"value": 8200
},
{
"date": "2023-02",
"value": 9100
}
]
}
```
### 4.3 配置接口
#### 获取可视化配置
```
GET /api/v1/dashboard/config
```
**请求参数**:
- 无
**响应示例**:
```json
{
"theme": "dark",
"refresh_interval": 30,
"charts": [
{
"id": "breeding_trend",
"type": "line",
"title": "养殖趋势"
}
]
}
```
#### 更新可视化配置
```
PUT /api/v1/dashboard/config
```
**请求体**:
```json
{
"theme": "dark",
"refresh_interval": 30
}
```
**响应示例**:
```json
{
"message": "配置更新成功"
}
```
## 5. 数据格式
### 5.1 产业概览数据
```json
{
"total_cattle": 128456,
"total_farms": 1245,
"annual_output_value": 2860000000,
"total_transaction": 1520000000,
"growth_rate": 5.2
}
```
### 5.2 养殖监控数据
```json
{
"farm_id": "FARM001",
"temperature": 22.5,
"humidity": 65,
"cattle_count": 245,
"feed_consumption": 1200
}
```
### 5.3 金融服务数据
```json
{
"loan_amount": 8600000,
"insurance_policies": 12450,
"claim_amount": 245000,
"approval_rate": 92.5
}
```
### 5.4 交易统计数据
```json
{
"daily_transactions": 125,
"average_price": 18500,
"regional_distribution": [
{
"region": "东乌旗",
"count": 1200
}
]
}
```
## 6. 错误处理
### 6.1 错误响应格式
```json
{
"error": {
"code": "DASHBOARD_001",
"message": "获取数据失败",
"details": "数据库连接异常"
}
}
```
### 6.2 常见错误码
- `DASHBOARD_001`: 数据获取失败
- `DASHBOARD_002`: 参数错误
- `DASHBOARD_003`: 权限不足
- `DASHBOARD_004`: 系统内部错误
## 7. 权限说明
大屏可视化系统接口需要以下权限：
- `dashboard:view`: 查看大屏数据权限
- `dashboard:config`: 配置大屏权限
## 8. 注意事项
1. 大屏可视化系统主要面向内部管理使用，需要相应权限才能访问
2. 实时数据推送通过WebSocket实现，需要保持长连接
3. 历史数据支持分页查询，避免一次性加载大量数据
4. 所有接口均采用HTTPS加密传输

176
docs/design/api/website.md Normal file
View File

@@ -0,0 +1,176 @@
# 官网 API 文档 (v1.1.0)
## 1. 接口概述
### 1.1 功能范围
- 新闻资讯管理
- 平台数据展示
- 用户留言处理
- 平台信息配置
### 1.2 基础路径
`/api/v1/website`
### 1.3 权限控制
- 公开接口（无需认证）：新闻列表、数据展示等
- 管理接口（需要认证）：新闻管理、留言处理等
### 1.4 全局错误码
| 状态码 | 说明 |
|--------|--------------------|
| 400 | 请求参数无效 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
## 2. 接口明细
### 2.1 获取新闻列表
```
GET /news
```
| 参数 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| page | number | 否 | 页码(默认1) |
| limit | number | 否 | 每页数量(默认10) |
| category | string | 否 | 分类筛选 |
#### 响应示例
```json
{
"status": "success",
"data": {
"items": [
{
"id": 1,
"title": "锡林郭勒盟出台畜牧业数字化发展三年规划",
"summary": "规划提出到2027年实现全盟畜牧业数字化覆盖率90%以上",
"category": "政策解读",
"publish_time": "2025-08-15T10:00:00Z",
"image_url": "/images/news-1.jpg"
}
],
"total": 100,
"page": 1,
"limit": 10
}
}
```
### 2.2 获取新闻详情
```
GET /news/{id}
```
| 参数 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| id | number | 是 | 新闻ID |
#### 响应示例
```json
{
"status": "success",
"data": {
"id": 1,
"title": "锡林郭勒盟出台畜牧业数字化发展三年规划",
"content": "详细新闻内容...",
"category": "政策解读",
"publish_time": "2025-08-15T10:00:00Z",
"author": "管理员",
"views": 1250
}
}
```
### 2.3 获取统计数据
```
GET /statistics
```
#### 响应示例
```json
{
"status": "success",
"data": {
"livestock_count": {
"cattle": 1200000,
"sheep": 850000,
"horse": 320000,
"camel": 80000
},
"forage_data": {
"production": [12, 19, 15, 22, 28, 35],
"price": [1800, 1750, 1850, 1900, 1950, 2000]
}
}
}
```
### 2.4 提交留言
```
POST /messages
```
| 字段 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| name | string | 是 | 姓名 |
| email | string | 是 | 邮箱 |
| phone | string | 否 | 电话 |
| content | string | 是 | 留言内容 |
#### 响应示例
```json
{
"status": "success",
"data": {
"message": "留言提交成功，我们会尽快回复您"
}
}
```
### 2.5 管理员登录
```
POST /auth/login
```
| 字段 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |
#### 响应示例
```json
{
"status": "success",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 3600
}
}
```
### 2.6 创建新闻（管理员）
```
POST /news
```
| 字段 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| title | string | 是 | 标题 |
| content | string | 是 | 内容 |
| summary | string | 否 | 摘要 |
| category | string | 是 | 分类 |
#### 响应示例
```json
{
"status": "success",
"data": {
"id": 101,
"title": "新发布的新闻",
"created_at": "2025-08-19T10:00:00Z"
}
}
```