feat(website): 优化新闻轮播功能并更新导航链接

2025-09-01 01:24:55 +08:00
parent 451bab4a96
commit 2ba5ae0a72
15 changed files with 2926 additions and 193 deletions
--- a/docs/design/api/dashboard.md
+++ b/docs/design/api/dashboard.md
@@ -1,69 +1,58 @@
-# 大屏可视化系统 API 文档
+# 大屏可视化系统 API 文档 (v1.0.0)

-## 1. 概述
+## 1. 接口概述

-大屏可视化系统是锡林郭勒盟智慧养殖产业平台的重要组成部分，主要用于展示产业整体数据、实时监控信息和分析结果。该系统通过直观的图表和数据可视化方式，为管理者提供全面的产业洞察。
+### 1.1 功能范围
+- 产业数据概览展示
+- 实时监控数据推送
+- 历史数据查询分析
+- 地图区域数据展示

-## 2. 技术架构
+### 1.2 基础路径
+`/api/v1/dashboard`

- **前端框架**: Vue.js 3 + ECharts + 自定义可视化组件
- **可视化库**: Apache ECharts
- **响应式设计**: 支持多种大屏比例(16:9, 4:3等)
- **实时数据**: WebSocket实时数据推送
- **状态管理**: Pinia
+### 1.3 权限控制
+- 公开接口（无需认证）：数据查询和展示
+- 管理接口（需要认证）：数据配置和管理

-## 3. 功能模块
+### 1.4 全局错误码
+| 状态码 | 说明               |
+|--------|--------------------|
+| 400    | 请求参数无效       |
+| 401    | 未授权             |
+| 403    | 权限不足           |
+| 404    | 资源不存在         |
+| 500    | 服务器内部错误     |

-### 3.1 产业概览
-展示整体产业规模、产值、增长率等关键指标
+## 2. 接口明细

-### 3.2 养殖监控
-实时展示各牧场的养殖情况、环境数据
-
-### 3.3 金融服务
-展示贷款、保险等金融服务数据
-
-### 3.4 交易统计
-牛只交易量、价格趋势、区域分布等数据
-
-### 3.5 运输跟踪
-牛只运输实时状态和路径展示
-
-### 3.6 风险预警
-风险事件展示和预警信息推送
-
-### 3.7 生态指标
-环保数据、可持续发展指标展示
-
-### 3.8 政府监管
-展示政府监管相关数据和政策执行效果
-
-## 4. API 接口
-
-### 4.1 实时数据接口
-
-#### 获取实时数据
+### 2.1 获取实时数据
 ```
-GET /api/v1/dashboard/realtime
+GET /realtime
 ```

 **请求参数**:
- 无
+| 参数名      | 类型   | 必填 | 说明               |
+|-------------|--------|------|--------------------|
+| 无参数      |        |      |                    |

 **响应示例**:
 ```json
 {
-  "timestamp": "2023-08-19T10:30:00Z",
-  "total_cattle": 128456,
-  "total_farms": 1245,
-  "annual_output_value": 2860000000,
-  "total_transaction": 1520000000
+  "status": "success",
+  "data": {
+    "timestamp": "2023-08-19T10:30:00Z",
+    "total_cattle": 128456,
+    "total_farms": 1245,
+    "annual_output_value": 2860000000,
+    "total_transaction": 1520000000
+  }
 }
 ```

-#### WebSocket 实时推送
+### 2.2 WebSocket实时数据推送
 ```
-WebSocket /api/v1/dashboard/ws
+WebSocket /ws
 ```

 **推送数据格式**:
@@ -80,166 +69,178 @@ WebSocket /api/v1/dashboard/ws
 }
 ```

-### 4.2 历史数据接口
-
-#### 获取历史数据
+### 2.3 获取历史数据
 ```
-GET /api/v1/dashboard/history
+GET /history
 ```

 **请求参数**:
- `start_date` (string, optional): 开始日期，格式 YYYY-MM-DD
- `end_date` (string, optional): 结束日期，格式 YYYY-MM-DD
- `type` (string, required): 数据类型 (breeding, transaction, transport, etc.)
+| 参数名      | 类型   | 必填 | 说明               |
+|-------------|--------|------|--------------------|
+| start_date  | string | 否   | 开始日期(YYYY-MM-DD)|
+| end_date    | string | 否   | 结束日期(YYYY-MM-DD)|
+| type        | string | 是   | 数据类型           |

 **响应示例**:
 ```json
 {
-  "data": [
-    {
-      "date": "2023-01",
-      "value": 8200
-    },
-    {
-      "date": "2023-02",
-      "value": 9100
-    }
-  ]
+  "status": "success",
+  "data": {
+    "items": [
+      {
+        "date": "2023-01",
+        "value": 8200
+      },
+      {
+        "date": "2023-02",
+        "value": 9100
+      }
+    ],
+    "total": 12,
+    "start_date": "2023-01-01",
+    "end_date": "2023-12-31"
+  }
 }
 ```

-### 4.3 首页地图数据接口
-
-#### 获取锡林郭勒盟区域地图数据
+### 2.4 获取区域地图数据
 ```
-GET /api/v1/dashboard/map/regions
+GET /map/regions
 ```

 **请求参数**:
- 无
+| 参数名      | 类型   | 必填 | 说明               |
+|-------------|--------|------|--------------------|
+| 无参数      |        |      |                    |

 **响应示例**:
 ```json
 {
-  "regions": [
-    {
+  "status": "success",
+  "data": {
+    "regions": [
+      {
+        "id": "xlg",
+        "name": "锡林浩特市",
+        "coordinates": [116.093, 43.946],
+        "cattle_count": 25600,
+        "farm_count": 120,
+        "output_value": 650000000
+      },
+      {
+        "id": "dwq",
+        "name": "东乌旗",
+        "coordinates": [116.980, 45.514],
+        "cattle_count": 18500,
+        "farm_count": 95,
+        "output_value": 480000000
+      }
+    ],
+    "total": 12
+  }
+}
+```
+
+### 2.5 获取指定区域详细数据
+```
+GET /map/region/{regionId}
+```
+
+**请求参数**:
+| 参数名      | 类型   | 必填 | 说明               |
+|-------------|--------|------|--------------------|
+| regionId    | string | 是   | 区域ID             |
+
+**响应示例**:
+```json
+{
+  "status": "success",
+  "data": {
+    "region": {
      "id": "xlg",
      "name": "锡林浩特市",
      "coordinates": [116.093, 43.946],
      "cattle_count": 25600,
      "farm_count": 120,
-      "output_value": 650000000
+      "output_value": 650000000,
+      "trend": "up"
    },
-    {
-      "id": "dwq",
-      "name": "东乌旗",
-      "coordinates": [116.980, 45.514],
-      "cattle_count": 18500,
-      "farm_count": 95,
-      "output_value": 480000000
-    },
-    {
-      "id": "xwq",
-      "name": "西乌旗",
-      "coordinates": [117.615, 44.587],
-      "cattle_count": 21200,
-      "farm_count": 108,
-      "output_value": 520000000
-    },
-    {
-      "id": "abg",
-      "name": "阿巴嘎旗",
-      "coordinates": [114.971, 44.022],
-      "cattle_count": 16800,
-      "farm_count": 86,
-      "output_value": 420000000
-    },
-    {
-      "id": "snz",
-      "name": "苏尼特左旗",
-      "coordinates": [113.653, 43.859],
-      "cattle_count": 12400,
-      "farm_count": 65,
-      "output_value": 310000000
-    }
-  ]
+    "farms": [
+      {
+        "id": "FARM001",
+        "name": "锡林浩特市第一牧场",
+        "coordinates": [116.120, 43.950],
+        "cattle_count": 2450,
+        "output_value": 62000000
+      }
+    ]
+  }
 }
 ```

-#### 获取指定区域详细数据
+## 3. 版本历史
+
+### v1.0.0 (2024-01-20)
+- 新增: 按照API文档规范标准统一格式
+- 优化: 统一响应格式和错误处理
+- 功能: 完成基础接口定义
+
+### 2.6 获取大屏配置
 ```
-GET /api/v1/dashboard/map/region/{regionId}
+GET /config
 ```

 **请求参数**:
- `regionId` (string, required): 区域ID
+| 参数名      | 类型   | 必填 | 说明               |
+|-------------|--------|------|--------------------|
+| 无参数      |        |      |                    |

 **响应示例**:
 ```json
 {
-  "region": {
-    "id": "xlg",
-    "name": "锡林浩特市",
-    "coordinates": [116.093, 43.946],
-    "cattle_count": 25600,
-    "farm_count": 120,
-    "output_value": 650000000,
-    "trend": "up"
-  },
-  "farms": [
-    {
-      "id": "FARM001",
-      "name": "锡林浩特市第一牧场",
-      "coordinates": [116.120, 43.950],
-      "cattle_count": 2450,
-      "output_value": 62000000
-    }
-  ]
+  "status": "success",
+  "data": {
+    "layout": "grid",
+    "theme": "dark",
+    "refresh_interval": 30,
+    "charts": [
+      {
+        "id": "cattle_count",
+        "type": "line",
+        "title": "牛只数量趋势",
+        "position": "top-left"
+      },
+      {
+        "id": "transaction_volume",
+        "type": "bar",
+        "title": "交易量统计",
+        "position": "top-right"
+      }
+    ]
+  }
 }
 ```

-### 4.4 配置接口
-
-#### 获取可视化配置
+### 2.7 更新大屏配置
 ```
-GET /api/v1/dashboard/config
+PUT /config
 ```

 **请求参数**:
- 无
+| 参数名          | 类型   | 必填 | 说明               |
+|-----------------|--------|------|--------------------|
+| layout          | string | 是   | 布局方式           |
+| theme           | string | 是   | 主题               |
+| refresh_interval| number | 是   | 刷新间隔(秒)       |
+| charts          | array  | 是   | 图表配置           |

 **响应示例**:
 ```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": "配置更新成功"
+  "status": "success",
+  "data": {
+    "message": "配置更新成功"
+  }
 }
 ```

--- a/docs/design/api/data-platform.md
+++ b/docs/design/api/data-platform.md
@@ -1,4 +1,4 @@
-# 数据中台系统 API 文档
+# 数据中台系统 API 文档 (v1.0.0)

 ## 1. 接口概述

@@ -8,6 +8,21 @@
 - 数据质量监控

 ### 1.2 基础路径
+`/api/v1/[系统名称]`
+
+### 1.3 权限控制
+- 公开接口（无需认证）：数据查询
+- 管理接口（需要认证）：数据管理
+- 系统接口（高级权限）：配置管理
+
+### 1.4 全局错误码
+| 状态码 | 说明               |
+|--------|--------------------|
+| 400    | 请求参数无效       |
+| 401    | 未授权             |
+| 403    | 权限不足           |
+| 404    | 资源不存在         |
+| 500    | 服务器内部错误     |
 `/api/v1/data`

 ## 2. 接口明细
@@ -17,16 +32,65 @@
 GET /lineage
 ```

+**请求参数**:
 | 参数        | 类型   | 必填 | 说明               |
 |-------------|--------|------|--------------------|
 | source      | string | 否   | 源表名            |
 | target      | string | 否   | 目标表名          |

+**响应示例**:
+```json
+{
+  "status": "success",
+  "data": {
+    "lineage": [
+      {
+        "source": "table_a",
+        "target": "table_b",
+        "transform_type": "join"
+      }
+    ]
+  }
+}
+```
+
 ### 2.2 接口审计
 ```
 GET /audit-logs
 ```

+**请求参数**:
+| 参数        | 类型   | 必填 | 说明               |
+|-------------|--------|------|--------------------|
+| start_time  | string | 否   | 开始时间          |
+| end_time    | string | 否   | 结束时间          |
+| api_name    | string | 否   | 接口名称          |
+
+**响应示例**:
+```json
+{
+  "status": "success",
+  "data": {
+    "logs": [
+      {
+        "id": "log_001",
+        "api_name": "/lineage",
+        "request_time": "2024-01-20T10:00:00Z",
+        "response_time": 150,
+        "status": "success"
+      }
+    ],
+    "total_count": 100
+  }
+}
+```
+
 ## 3. 性能指标
 - 血缘查询响应时间 < 500ms
- 审计日志保留至少180天
+- 审计日志保留至少180天
+## 3. 版本历史
+
+### v1.0.0 (2024-01-20)
+- 新增: 按照API文档规范标准统一格式
+- 优化: 统一响应格式和错误处理
+- 功能: 完成基础接口定义
--- a/docs/design/api/farming.md
+++ b/docs/design/api/farming.md
@@ -4,13 +4,28 @@

 ### 1.1 功能范围
 - 牛只档案管理
- 饲喂记录
+- 饲喂记录管理
 - 防疫管理
 - 繁殖管理
+- 环境监测

 ### 1.2 基础路径
 `/api/v1/farming`

+### 1.3 权限控制
+- 公开接口（无需认证）：数据查询
+- 管理接口（需要认证）：数据录入和管理
+- 系统接口（高级权限）：批量操作和配置
+
+### 1.4 全局错误码
+| 状态码 | 说明               |
+|--------|--------------------|
+| 400    | 请求参数无效       |
+| 401    | 未授权             |
+| 403    | 权限不足           |
+| 404    | 资源不存在         |
+| 500    | 服务器内部错误     |
+
 ## 2. 接口明细

 ### 2.1 添加牛只
@@ -18,40 +33,97 @@
 POST /cattles
 ```

+**请求参数**:
 | 字段         | 类型   | 必填 | 说明               |
 |--------------|--------|------|--------------------|
-| ear_tag      | string | 是   | 耳标号(唯一)      |
+| ear_tag      | string | 是   | 耳标号(唯一)       |
 | breed        | string | 是   | 品种               |
 | birth_date   | string | 是   | 出生日期(YYYY-MM-DD)|
-| gender       | string | 是   | 性别(公/母)       |
+| gender       | string | 是   | 性别(公/母)        |
 | weight       | number | 否   | 体重(kg)           |

+**响应示例**:
+```json
+{
+  "status": "success",
+  "data": {
+    "id": "CATTLE001",
+    "ear_tag": "NM000001",
+    "created_at": "2024-01-20T10:00:00Z"
+  }
+}
+```
+
 ### 2.2 批量导入牛只
 ```
 POST /cattles/batch
 ```

+**请求参数**:
 | 字段         | 类型   | 必填 | 说明               |
 |--------------|--------|------|--------------------|
 | file         | file   | 是   | Excel文件          |

-### 2.3 防疫记录
+**响应示例**:
+```json
+{
+  "status": "success",
+  "data": {
+    "imported_count": 50,
+    "failed_count": 2,
+    "failed_items": [
+      {
+        "row": 25,
+        "error": "耳标号格式错误"
+      }
+    ]
+  }
+}
+```
+
+### 2.3 添加防疫记录
 ```
 POST /vaccinations
 ```

+**请求参数**:
 | 字段         | 类型   | 必填 | 说明               |
 |--------------|--------|------|--------------------|
-| cattle_id    | string | 是   | 牛只ID            |
+| cattle_id    | string | 是   | 牛只ID             |
 | vaccine_type | string | 是   | 疫苗类型           |
 | date         | string | 是   | 接种日期(YYYY-MM-DD)|
+| dosage       | number | 否   | 剂量(ml)           |
+| veterinarian | string | 否   | 兽医姓名           |
+
+**响应示例**:
+```json
+{
+  "status": "success",
+  "data": {
+    "id": "VACC001",
+    "cattle_id": "CATTLE001",
+    "vaccine_type": "口蹄疫",
+    "created_at": "2024-01-20T10:30:00Z"
+  }
+}
+```

 ## 3. 数据规范
 - 耳标号格式：省简称+6位数字(如NM000001)
 - 疫苗记录保留至少5年
 - 敏感数据需RSA加密传输
+- 日期格式：YYYY-MM-DD
+- 时间格式：YYYY-MM-DDTHH:mm:ssZ

-## 4. 权限控制
- 添加牛只：养殖管理员
- 批量导入：系统管理员
- 防疫记录：兽医
+## 4. 版本历史
+
+### v1.1.0 (2024-01-20)
+- 新增: 按照API文档规范标准统一格式
+- 优化: 统一响应格式和错误处理
+- 功能: 完善养殖管理接口定义
+## 3. 版本历史
+
+### v1.0.0 (2024-01-20)
+- 新增: 按照API文档规范标准统一格式
+- 优化: 统一响应格式和错误处理
+- 功能: 完成基础接口定义
--- a/docs/design/api/finance.md
+++ b/docs/design/api/finance.md
@@ -9,6 +9,21 @@
 - 贷款审批

 ### 1.2 基础路径
+`/api/v1/[系统名称]`
+
+### 1.3 权限控制
+- 公开接口（无需认证）：数据查询
+- 管理接口（需要认证）：数据管理
+- 系统接口（高级权限）：配置管理
+
+### 1.4 全局错误码
+| 状态码 | 说明               |
+|--------|--------------------|
+| 400    | 请求参数无效       |
+| 401    | 未授权             |
+| 403    | 权限不足           |
+| 404    | 资源不存在         |
+| 500    | 服务器内部错误     |
 `/api/v1/finance`

 ## 2. 接口明细
@@ -18,6 +33,7 @@
 POST /loans
 ```

+**请求参数**:
 | 字段            | 类型    | 必填 | 说明               |
 |-----------------|---------|------|--------------------|
 | farmer_id       | number  | 是   | 牧户ID            |
@@ -26,16 +42,55 @@ POST /loans
 | term           | number  | 是   | 贷款期限(月)      |
 | interest_rate   | number  | 是   | 年利率(%)         |

+**响应示例**:
+```json
+{
+  "status": "success",
+  "data": {
+    "loan_id": "loan_001",
+    "farmer_id": 1001,
+    "amount": 50000,
+    "collateral_type": "牛只",
+    "term": 12,
+    "interest_rate": 4.35,
+    "monthly_payment": 4260.25,
+    "application_date": "2024-01-20T10:00:00Z",
+    "status": "审批中"
+  }
+}
+```
+
 ### 2.2 贷款审批状态查询
 ```
 GET /loans/:id/status
 ```

+**请求参数**:
+| 参数        | 类型   | 必填 | 说明               |
+|-------------|--------|------|--------------------|
+| id          | string | 是   | 贷款ID             |
+
+**响应示例**:
+```json
+{
+  "status": "success",
+  "data": {
+    "loan_id": "loan_001",
+    "status": "已批准",
+    "approval_date": "2024-01-21T10:00:00Z",
+    "approved_amount": 50000,
+    "approver": "审批员001",
+    "next_payment_date": "2024-02-20T10:00:00Z"
+  }
+}
+```
+
 ### 2.3 保险购买
 ```
 POST /insurances
 ```

+**请求参数**:
 | 字段            | 类型    | 必填 | 说明               |
 |-----------------|---------|------|--------------------|
 | farmer_id       | number  | 是   | 牧户ID            |
@@ -43,6 +98,24 @@ POST /insurances
 | insurance_type  | string  | 是   | 保险类型          |
 | premium         | number  | 是   | 保费(元)          |

+**响应示例**:
+```json
+{
+  "status": "success",
+  "data": {
+    "insurance_id": "ins_001",
+    "farmer_id": 1001,
+    "cattle_id": "cattle_123",
+    "insurance_type": "疾病保险",
+    "premium": 500,
+    "coverage_amount": 10000,
+    "effective_date": "2024-01-20T10:00:00Z",
+    "expiry_date": "2025-01-20T10:00:00Z",
+    "policy_number": "POL-20240120-001"
+  }
+}
+```
+
 ## 3. 风控规则
 - 单笔贷款金额 ≤ 牧户资产总额的50%
 - 理赔申请需在灾害发生后30天内提交
@@ -51,4 +124,10 @@ POST /insurances
 ## 4. 权限控制
 - 贷款申请：牧户
 - 贷款审批：银行管理员
- 保险购买：牧户
+- 保险购买：牧户
+## 3. 版本历史
+
+### v1.0.0 (2024-01-20)
+- 新增: 按照API文档规范标准统一格式
+- 优化: 统一响应格式和错误处理
+- 功能: 完成基础接口定义
--- a/docs/design/api/government.md
+++ b/docs/design/api/government.md
@@ -9,6 +9,21 @@
 - 任务状态跟踪

 ### 1.2 基础路径
+`/api/v1/[系统名称]`
+
+### 1.3 权限控制
+- 公开接口（无需认证）：数据查询
+- 管理接口（需要认证）：数据管理
+- 系统接口（高级权限）：配置管理
+
+### 1.4 全局错误码
+| 状态码 | 说明               |
+|--------|--------------------|
+| 400    | 请求参数无效       |
+| 401    | 未授权             |
+| 403    | 权限不足           |
+| 404    | 资源不存在         |
+| 500    | 服务器内部错误     |
 `/api/v1/gov`

 ## 2. 接口明细
@@ -18,6 +33,7 @@
 POST /quarantines
 ```

+**请求参数**:
 | 字段          | 类型   | 必填 | 说明               |
 |---------------|--------|------|--------------------|
 | location      | string | 是   | GPS坐标(纬度,经度)|
@@ -26,22 +42,74 @@ POST /quarantines
 | task_type     | string | 是   | 任务类型(常规/紧急)|
 | priority      | number | 否   | 优先级(1-5)       |

+**响应示例**:
+```json
+{
+  "status": "success",
+  "data": {
+    "task_id": "task_001",
+    "location": "39.9042,116.4074",
+    "inspector_id": 1001,
+    "deadline": "2024-01-25",
+    "task_type": "紧急",
+    "priority": 1,
+    "created_at": "2024-01-20T10:00:00Z"
+  }
+}
+```
+
 ### 2.2 防疫任务状态查询
 ```
 GET /quarantines/:id/status
 ```

+**请求参数**:
+| 参数        | 类型   | 必填 | 说明               |
+|-------------|--------|------|--------------------|
+| id          | string | 是   | 任务ID             |
+
+**响应示例**:
+```json
+{
+  "status": "success",
+  "data": {
+    "task_id": "task_001",
+    "status": "进行中",
+    "progress": 50,
+    "inspector": "张三",
+    "start_time": "2024-01-20T10:00:00Z",
+    "estimated_completion": "2024-01-22T10:00:00Z"
+  }
+}
+```
+
 ### 2.3 检疫监管
 ```
 POST /inspections
 ```

+**请求参数**:
 | 字段          | 类型   | 必填 | 说明               |
 |---------------|--------|------|--------------------|
 | cattle_id     | string | 是   | 牛只ID            |
 | inspector_id  | number | 是   | 检疫员ID          |
 | result        | string | 是   | 检疫结果(合格/不合格)|

+**响应示例**:
+```json
+{
+  "status": "success",
+  "data": {
+    "inspection_id": "insp_001",
+    "cattle_id": "cattle_123",
+    "inspector_id": 1001,
+    "result": "合格",
+    "inspection_time": "2024-01-20T10:00:00Z",
+    "certificate_number": "CERT-20240120-001"
+  }
+}
+```
+
 ## 3. 审计要求
 - 所有操作记录操作人IP和时间
 - 敏感数据需RSA加密传输
@@ -49,4 +117,10 @@ POST /inspections
 ## 4. 权限控制
 - 防疫任务下发：政府管理员
 - 检疫监管：检疫员
- 补贴发放：财务人员
+- 补贴发放：财务人员
+## 3. 版本历史
+
+### v1.0.0 (2024-01-20)
+- 新增: 按照API文档规范标准统一格式
+- 优化: 统一响应格式和错误处理
+- 功能: 完成基础接口定义
--- a/docs/design/api/trade.md
+++ b/docs/design/api/trade.md
@@ -9,6 +9,21 @@
 - 订单状态查询

 ### 1.2 基础路径
+`/api/v1/[系统名称]`
+
+### 1.3 权限控制
+- 公开接口（无需认证）：数据查询
+- 管理接口（需要认证）：数据管理
+- 系统接口（高级权限）：配置管理
+
+### 1.4 全局错误码
+| 状态码 | 说明               |
+|--------|--------------------|
+| 400    | 请求参数无效       |
+| 401    | 未授权             |
+| 403    | 权限不足           |
+| 404    | 资源不存在         |
+| 500    | 服务器内部错误     |
 `/api/v1/trades`

 ## 2. 接口明细
@@ -59,4 +74,10 @@ stateDiagram
 ## 5. 权限控制
 - 商品发布：商户
 - 订单创建：用户
- 物流跟踪：用户/商户
+- 物流跟踪：用户/商户
+## 3. 版本历史
+
+### v1.0.0 (2024-01-20)
+- 新增: 按照API文档规范标准统一格式
+- 优化: 统一响应格式和错误处理
+- 功能: 完成基础接口定义
--- a/docs/design/api/user-center.md
+++ b/docs/design/api/user-center.md
@@ -1,4 +1,4 @@
-# 用户中心系统 API 文档
+# 用户中心系统 API 文档 (v1.0.0)

 ## 1. 接口概述

@@ -8,6 +8,21 @@
 - 权限控制

 ### 1.2 基础路径
+`/api/v1/[系统名称]`
+
+### 1.3 权限控制
+- 公开接口（无需认证）：数据查询
+- 管理接口（需要认证）：数据管理
+- 系统接口（高级权限）：配置管理
+
+### 1.4 全局错误码
+| 状态码 | 说明               |
+|--------|--------------------|
+| 400    | 请求参数无效       |
+| 401    | 未授权             |
+| 403    | 权限不足           |
+| 404    | 资源不存在         |
+| 500    | 服务器内部错误     |
 `/api/v1/users`

 ## 2. 接口明细
@@ -17,20 +32,62 @@
 POST /register
 ```

+**请求参数**:
 | 字段       | 类型   | 必填 | 说明           |
 |------------|--------|------|----------------|
 | username   | string | 是   | 4-20位字母数字 |
 | password   | string | 是   | 6-20位含大小写 |
 | phone      | string | 是   | 11位手机号     |

+**响应示例**:
+```json
+{
+  "status": "success",
+  "data": {
+    "user_id": "user_001",
+    "username": "testuser",
+    "phone": "13800138000",
+    "created_at": "2024-01-20T10:00:00Z"
+  }
+}
+```
+
 ### 2.2 用户登录
 ```
 POST /login
 ```

+**请求参数**:
+| 字段       | 类型   | 必填 | 说明           |
+|------------|--------|------|----------------|
+| username   | string | 是   | 用户名         |
+| password   | string | 是   | 密码           |
+
+**响应示例**:
+```json
+{
+  "status": "success",
+  "data": {
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
+    "user_info": {
+      "user_id": "user_001",
+      "username": "testuser",
+      "roles": ["user"]
+    },
+    "expires_in": 86400
+  }
+}
+```
+
 ## 3. 状态码规范
 | 代码 | 说明           |
 |------|----------------|
 | 200  | 成功           |
 | 400  | 参数校验失败   |
-| 401  | 认证失败       |
+| 401  | 认证失败       |
+## 3. 版本历史
+
+### v1.0.0 (2024-01-20)
+- 新增: 按照API文档规范标准统一格式
+- 优化: 统一响应格式和错误处理
+- 功能: 完成基础接口定义
--- a/docs/design/api/website.md
+++ b/docs/design/api/website.md
@@ -7,13 +7,15 @@
 - 平台数据展示
 - 用户留言处理
 - 平台信息配置
+- 管理员认证

 ### 1.2 基础路径
 `/api/v1/website`

 ### 1.3 权限控制
- 公开接口（无需认证）：新闻列表、数据展示等
- 管理接口（需要认证）：新闻管理、留言处理等
+- 公开接口（无需认证）：新闻列表、数据展示、留言提交
+- 管理接口（需要认证）：新闻管理、留言处理、配置管理
+- 认证接口：管理员登录

 ### 1.4 全局错误码
 | 状态码 | 说明               |
@@ -31,13 +33,14 @@
 GET /news
 ```

-| 参数        | 类型   | 必填 | 说明               |
+**请求参数**:
+| 参数名      | 类型   | 必填 | 说明               |
 |-------------|--------|------|--------------------|
 | page        | number | 否   | 页码(默认1)        |
 | limit       | number | 否   | 每页数量(默认10)   |
 | category    | string | 否   | 分类筛选           |

-#### 响应示例
+**响应示例**:
 ```json
 {
  "status": "success",
@@ -64,11 +67,12 @@ GET /news
 GET /news/{id}
 ```

-| 参数        | 类型   | 必填 | 说明               |
+**请求参数**:
+| 参数名      | 类型   | 必填 | 说明               |
 |-------------|--------|------|--------------------|
 | id          | number | 是   | 新闻ID             |

-#### 响应示例
+**响应示例**:
 ```json
 {
  "status": "success",
@@ -89,7 +93,12 @@ GET /news/{id}
 GET /statistics
 ```

-#### 响应示例
+**请求参数**:
+| 参数名      | 类型   | 必填 | 说明               |
+|-------------|--------|------|--------------------|
+| 无参数      |        |      |                    |
+
+**响应示例**:
 ```json
 {
  "status": "success",
@@ -113,19 +122,21 @@ GET /statistics
 POST /messages
 ```

-| 字段        | 类型   | 必填 | 说明               |
+**请求参数**:
+| 字段名      | 类型   | 必填 | 说明               |
 |-------------|--------|------|--------------------|
 | name        | string | 是   | 姓名               |
 | email       | string | 是   | 邮箱               |
 | phone       | string | 否   | 电话               |
 | content     | string | 是   | 留言内容           |

-#### 响应示例
+**响应示例**:
 ```json
 {
  "status": "success",
  "data": {
-    "message": "留言提交成功，我们会尽快回复您"
+    "message": "留言提交成功，我们会尽快回复您",
+    "message_id": "MSG001"
  }
 }
 ```
@@ -135,18 +146,23 @@ POST /messages
 POST /auth/login
 ```

-| 字段        | 类型   | 必填 | 说明               |
+**请求参数**:
+| 字段名      | 类型   | 必填 | 说明               |
 |-------------|--------|------|--------------------|
 | username    | string | 是   | 用户名             |
 | password    | string | 是   | 密码               |

-#### 响应示例
+**响应示例**:
 ```json
 {
  "status": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-    "expires_in": 3600
+    "expires_in": 3600,
+    "user_info": {
+      "username": "admin",
+      "role": "administrator"
+    }
  }
 }
 ```
@@ -156,21 +172,32 @@ POST /auth/login
 POST /news
 ```

-| 字段        | 类型   | 必填 | 说明               |
+**请求参数**:
+| 字段名      | 类型   | 必填 | 说明               |
 |-------------|--------|------|--------------------|
 | title       | string | 是   | 标题               |
 | content     | string | 是   | 内容               |
 | summary     | string | 否   | 摘要               |
 | category    | string | 是   | 分类               |
+| author      | string | 否   | 作者               |
+| image_url   | string | 否   | 图片URL            |

-#### 响应示例
+**响应示例**:
 ```json
 {
  "status": "success",
  "data": {
    "id": 101,
    "title": "新发布的新闻",
-    "created_at": "2025-08-19T10:00:00Z"
+    "created_at": "2025-08-19T10:00:00Z",
+    "publish_time": "2025-08-19T10:00:00Z"
  }
 }
-```
+```
+
+## 3. 版本历史
+
+### v1.1.0 (2024-01-20)
+- 新增: 按照API文档规范标准统一格式
+- 优化: 统一响应格式和错误处理
+- 功能: 完善官网接口定义
--- a/docs/design/database/DESIGN.md
+++ b/docs/design/database/DESIGN.md
--- a/docs/design/database/README.md
+++ b/docs/design/database/README.md
@@ -0,0 +1,58 @@
+# 数据库设计
+
+## 概述
+
+本项目使用MySQL作为主要的关系型数据库，存储用户信息、牛只档案、交易记录、监管数据等核心业务数据。
+
+## 数据库设计规范
+
+1. 使用InnoDB存储引擎
+2. 字符集使用utf8mb4
+3. 所有表都有创建时间和更新时间字段
+4. 主键使用自增ID
+5. 外键约束用于保证数据一致性
+
+## 备份与恢复策略
+- **每日全量备份**: 通过`mysqldump`导出数据
+- **Binlog增量备份**: 实时同步到备份服务器
+- **恢复测试**: 每月验证备份文件可用性
+
+## 数据迁移工具
+- 使用Flyway管理数据库版本变更
+- 迁移脚本存放在`/migrations`目录
+
+## 核心数据表
+
+### 1. 用户表 (users)
+存储系统用户信息，包括牧民、银行职员、保险员、政府监管人员等。
+
+### 2. 角色表 (roles)
+存储系统角色信息，如管理员、牧民、银行职员等。
+
+### 3. 权限表 (permissions)
+存储系统权限信息。
+
+### 4. 牛只档案表 (cattle)
+存储牛只基本信息，包括品种、年龄、健康状况等。
+
+### 5. 饲养记录表 (feeding_records)
+存储牛只饲养记录，包括饲料、疫苗、治疗等信息。
+
+### 6. 繁殖记录表 (breeding_records)
+存储牛只繁殖相关信息。
+
+### 7. 交易记录表 (transactions)
+存储活牛交易记录。
+
+### 8. 合同表 (contracts)
+存储交易合同信息。
+
+### 9. 商品表 (products)
+存储牛肉商城商品信息。
+
+### 10. 订单表 (orders)
+存储用户订单信息。
+
+## 数据库脚本
+
+数据库初始化脚本和迁移脚本将存放在此目录中。