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

docs(database): 更新数据库设计规范和核心数据表结构

Browse Source 
- 新增数据库基础规范、API映射规范、安全规范等详细设计要求- 增加读写分离、分库分表、数据生命周期管理等策略说明
- 新建核心业务表结构，包括用户表、贷款申请表、保险申请表等
- 优化索引设计，提高查询效率
This commit is contained in:
mapleaf
2025-08-19 22:04:18 +08:00
parent 1dbfbebd05
commit 47c67ff704
70 changed files with 104406 additions and 825 deletions
Download Patch File Download Diff File Expand all files Collapse all files

425
docs/design/ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,425 @@
# 系统架构文档
## 1. 概述
本项目是一个综合性的畜牧业数字化管理平台，主要面向锡林郭勒盟地区的养殖产业，包含官网展示、后台管理、移动端小程序、大屏可视化等多个子系统。平台集成了养殖管理、金融服务（银行监管、保险监管）、政府监管、牛只交易、牛肉商城、数据分析等功能模块，旨在通过数字化手段提升整个产业链的管理效率和透明度。
## 2. 技术栈
### 2.1 前端技术栈
- **官网首页**: HTML5 + CSS3 + JavaScript
- **后台管理系统**: Vue.js 3 + TypeScript + Ant Design Vue + Pinia
- **大屏可视化系统**: Vue.js 3 + ECharts + 自定义可视化组件
- **微信小程序矩阵**: 微信小程序原生开发 + uni-app
### 2.2 后端技术栈
- **API服务**: Node.js + Express.js + TypeScript + RESTful API
- **数据库**: MySQL
- **缓存系统**: Redis
- **消息队列**: RabbitMQ（用于异步处理）
- **文件存储**: 腾讯云对象存储
- **实时通信**: WebSocket（用于大屏数据推送和实时通知）
### 2.3 数据库配置
#### 2.3.1 测试环境
- **主机**: `192.168.0.240` (MySQL主机地址)
- **端口**: `3306` (MySQL端口)
- **用户名**: `root`
- **密码**: `aiot$Aiot123`
- **数据库**: `xlxumudata`
#### 2.3.2 生产环境
- **主机**: `129.211.213.226`
- **端口**: `9527`（端口号）
- **用户名**: `root`
- **密码**: `aiotAiot123!`
- **数据库**: `xlxumudata`
### 2.4 安全架构
- **身份认证**: JWT (JSON Web Tokens)
- **权限管理**: 基于角色的访问控制 (RBAC)
- **数据传输**: HTTPS 加密传输
- **API防护**: 接口限流、参数校验、防SQL注入等
- **密码安全**: BCrypt加密存储
- **操作审计**: 用户操作日志记录和审计
### 2.5 数据架构
- **实时数据采集**: IoT设备数据接入
- **数据处理**: ETL数据处理流程
- **数据存储**: 分层数据存储（操作数据、历史数据、统计数据）
- **大数据分析**: 数据分析引擎
- **智能预警**: 基于规则的预警系统
- **可视化展示**: 图表化数据展示平台
## 3. 系统架构图
```
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ 用户端接入层 │
├─────────────────┬─────────────────────────────────────────────────────────────────────────┤
│ 官网首页 │ 专业管理系统 │
│ (HTML5展示) ├─────────────────────────────────────────────────────────────────────────┤
│ │ - 养殖管理系统 (Vue.js 3 + Ant) │
│ │ - 银行监管系统 (Vue.js 3 + Ant) │
│ │ - 保险监管系统 (Vue.js 3 + Ant) │
│ │ - 政府监管平台 (Vue.js 3 + Ant) │
│ │ - 活牛交易系统 (Vue.js 3 + Ant) │
│ │ - 商城管理系统 (Vue.js 3 + Ant) │
│ │ - 大屏可视化系统 (Vue.js 3 + ECharts) │
├─────────────────┼─────────────────────────────────────────────────────────────────────────┤
│ 微信小程序矩阵 │
│ - 牛肉商城小程序 │
│ - 养殖管理小程序 │
│ - 银行监管小程序 │
│ - 保险监管小程序 │
│ - 活牛交易小程序 │
│ - 政府监管小程序 │
│ - 数据中台小程序 │
│ - AI能力小程序 │
├─────────────────┴─────────────────────────────────────────────────────────────────────────┤
│ API服务层 (Node.js) │
├─────────────────────────────────────────────────────────────────────────────────────────────┤
│ 数据处理与存储层 │
├─────────────────────────────────────────────────────────────────────────────────────────────┤
│ 关系数据库(MySQL) │ 缓存系统(Redis) │ 消息队列(RabbitMQ) │ 文件存储(腾讯云) │
├─────────────────────────────────────────────────────────────────────────────────────────────┤
│ 数据分析与展示层 │
├─────────────────────────────────────────────────────────────────────────────────────────────┤
│ 大数据分析引擎 │ 智能预警系统 │ 可视化平台 │ 实时数据推送 │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
```
## 4. 前端系统架构
### 4.1 官网首页系统
- 纯HTML5、CSS3、JavaScript实现
- 响应式设计，适配多种设备
- 突出锡林郭勒盟地域元素和蒙古族文化特色
- 绿色草原主题风格
### 4.2 专业管理系统
#### 4.2.1 养殖管理系统
- 基于Vue.js 3 Composition API
- 使用Ant Design Vue组件库
- 状态管理采用Pinia
- TypeScript增强代码可维护性
##### 功能模块
1. 牛只档案管理
2. 饲养记录管理
3. 繁殖管理
4. 环境监测数据展示
5. 健康监测管理
6. 生产计划制定和执行跟踪
#### 4.2.2 银行监管系统
- 基于Vue.js 3 Composition API
- 使用Ant Design Vue组件库
- 状态管理采用Pinia
- TypeScript增强代码可维护性
##### 功能模块
1. 贷款申请和审批流程管理
2. 质押物（牛只）状态监控
3. 还款计划跟踪
4. 风险评估数据展示
5. 财务报表生成
6. 风控管理
#### 4.2.3 保险监管系统
- 基于Vue.js 3 Composition API
- 使用Ant Design Vue组件库
- 状态管理采用Pinia
- TypeScript增强代码可维护性
##### 功能模块
1. 保险投保管理
2. 理赔申请和处理流程
3. 风险评估和预警
4. 保险记录查询
5. 数据统计分析
#### 4.2.4 政府监管平台
- 基于Vue.js 3 Composition API
- 使用Ant Design Vue组件库
- 状态管理采用Pinia
- TypeScript增强代码可维护性
##### 功能模块
1. 产业数据总览
2. 各类监管数据汇总
3. 政策发布和通知
4. 合规性检查
5. 统计报表生成
6. 用户管理（集中式用户权限管理）
7. 系统配置管理
#### 4.2.5 活牛交易系统
- 基于Vue.js 3 Composition API
- 使用Ant Design Vue组件库
- 状态管理采用Pinia
- TypeScript增强代码可维护性
##### 功能模块
1. 牛只信息发布和展示
2. 在线交易撮合
3. 合同管理
4. 支付流程管理
5. 交易记录查询
6. 商户管理
7. 行情管理
#### 4.2.6 商城管理系统
- 基于Vue.js 3 Composition API
- 使用Ant Design Vue组件库
- 状态管理采用Pinia
- TypeScript增强代码可维护性
##### 功能模块
1. 商品信息管理
2. 库存管理
3. 订单处理
4. 物流跟踪
5. 售后服务管理
6. 营销管理
#### 4.2.7 大屏可视化系统
- 基于Vue.js 3 Composition API
- 使用ECharts和自定义可视化组件
- 状态管理采用Pinia
- TypeScript增强代码可维护性
- WebSocket实现实时数据推送
##### 功能模块
1. 产业概览
2. 养殖监控
3. 金融服务
4. 交易统计
5. 运输跟踪
6. 风险预警
7. 生态指标
8. 政府监管
### 4.3 微信小程序矩阵
- 使用微信小程序原生开发框架
- 跨平台支持采用uni-app
- 包含8个专门的小程序应用
#### 4.3.1 牛肉商城小程序（消费者端）
- 商品浏览和搜索
- 在线下单和支付
- 订单查询和跟踪
- 售后服务申请
- **认养功能**：用户可以认养特定牛只，跟踪其成长过程
#### 4.3.2 养殖管理小程序（牧民端）
- 移动端牛只档案查看
- 饲养记录录入
- 健康状况上报
- 通知消息接收
- 数据统计查看
#### 4.3.3 银行监管小程序（银行端）
- 移动端贷款审批
- 质押物状态查看
- 风险数据监控
- 移动办公支持
#### 4.3.4 保险监管小程序（保险端）
- 移动端保险处理
- 理赔流程管理
- 风险评估查看
- 移动查勘支持
#### 4.3.5 活牛交易小程序（交易员端）
- 活牛信息发布
- 在线交易撮合
- 合同查看和管理
- 交易记录查询
- 支付状态跟踪
#### 4.3.6 政府监管小程序（监管人员端）
- 防疫任务执行
- 补贴申请审核
- 政策信息查看
- 监管数据上报
#### 4.3.7 数据中台小程序（数据人员端）
- 数据查询和导出
- 统计报表查看
- 数据服务申请
#### 4.3.8 AI能力小程序（养殖户/兽医端）
- 牛只体况评估
- 饲料配方推荐
- 智能诊断辅助
## 5. 后端系统架构
### 5.1 API服务层
- 基于Node.js和Express.js构建
- 使用TypeScript增强代码健壮性
- RESTful API设计风格
- JWT身份认证机制
- 微服务架构设计（按业务模块划分）
### 5.2 数据存储层
- 主数据库：MySQL关系型数据库
- 缓存系统：Redis（用于会话缓存、数据缓存）
- 消息队列：RabbitMQ（用于异步任务处理）
- 文件存储：腾讯云对象存储服务
- 日志存储：Elasticsearch（用于日志分析）
### 5.3 安全架构
- 基于JWT的无状态认证
- RBAC角色权限管理系统（集中式用户管理）
- HTTPS加密传输
- API接口安全防护（限流、防注入等）
- 数据加密存储（BCrypt等）
- 操作日志审计
### 5.4 数据分析层
- 实时数据采集系统（IoT设备数据、用户行为数据）
- 大数据分析引擎
- 智能预警系统
- 数据可视化展示平台
## 6. 项目结构
```
.
├── frontend/ # 前端项目
│ ├── website/ # 官网首页
│ ├── farming-management/ # 养殖管理系统
│ ├── bank-supervision/ # 银行监管系统
│ ├── insurance-supervision/ # 保险监管系统
│ ├── government-platform/ # 政府监管平台
│ ├── cattle-trading/ # 活牛交易系统
│ ├── mall-management/ # 商城管理系统
│ ├── dashboard/ # 大屏可视化系统
│ └── mini-programs/ # 微信小程序矩阵
│ ├── beef-mall/ # 牛肉商城小程序
│ ├── farming-manager/ # 养殖管理小程序
│ ├── bank-supervision/ # 银行监管小程序
│ ├── insurance-supervision/ # 保险监管小程序
│ ├── cattle-trading/ # 活牛交易小程序
│ ├── gov-supervision/ # 政府监管小程序
│ ├── data-platform/ # 数据中台小程序
│ └── ai-capabilities/ # AI能力小程序
├── backend/ # 后端项目
│ ├── api/ # API服务
│ │ ├── farming/ # 养殖管理API
│ │ ├── finance/ # 金融服务API
│ │ ├── government/ # 政府监管API
│ │ ├── trade/ # 交易管理API
│ │ ├── mall/ # 商城管理API
│ │ ├── data-platform/ # 数据中台API
│ │ ├── ai/ # AI能力API
│ │ └── user-center/ # 用户中心API
│ ├── database/ # 数据库脚本
│ ├── utils/ # 工具函数
│ └── services/ # 微服务模块
├── docs/ # 文档
└── deployment/ # 部署相关配置
```
## 7. 用户权限管理架构
### 7.1 集中式用户管理
- 所有用户信息统一在政府监管平台进行管理
- 各子系统仅负责登录验证和部分权限校验
- 实现统一的RBAC权限模型
### 7.2 权限体系
- 基于角色的访问控制（RBAC）
- 支持多角色分配
- 细粒度权限控制（菜单权限、操作权限、数据权限）
- 权限继承机制
### 7.3 用户角色
1. 超级管理员
2. 政府监管员
3. 银行信贷员
4. 保险专员
5. 交易管理员
6. 商城管理员
7. 养殖户
8. 普通用户
9. 数据分析师
10. 系统审计员
## 8. 大屏可视化系统架构
### 8.1 系统概述
大屏可视化系统是本项目的重要组成部分，主要用于展示锡林郭勒盟安格斯牛养殖产业的整体数据、实时监控信息和分析结果。通过直观的图表和数据可视化方式，为管理者提供全面的产业洞察。
### 8.2 技术实现
- **前端框架**: Vue.js 3 + ECharts + 自定义可视化组件
- **可视化库**: Apache ECharts + D3.js
- **响应式设计**: 支持多种大屏比例(16:9, 4:3等)
- **实时数据**: WebSocket实时数据推送
- **性能优化**: 虚拟滚动、数据分页等技术
### 8.3 功能模块
1. **产业概览**: 展示整体产业规模、产值、增长率等关键指标
2. **养殖监控**: 实时展示各牧场的养殖情况、环境数据
3. **金融服务**: 展示贷款、保险等金融服务数据
4. **交易统计**: 牛只交易量、价格趋势、区域分布等数据
5. **运输跟踪**: 牛只运输实时状态和路径展示
6. **风险预警**: 风险事件展示和预警信息推送
7. **生态指标**: 环保数据、可持续发展指标展示
8. **政府监管**: 展示政府监管相关数据和政策执行效果
### 8.4 设计特色
- 融入锡林郭勒盟草原绿色主题
- 采用蒙古族文化元素的UI设计
- 突出安格斯牛品牌形象
- 支持多维度数据钻取和交互
## 9. 系统集成架构
### 9.1 外部系统集成
1. 银行系统对接
2. 政府监管平台对接
3. 第三方系统集成（LDAP/AD、OAuth2.0等）
4. 物联网设备集成（MQTT/CoAP协议）
5. 云服务集成（腾讯云COS、短信服务等）
### 9.2 数据交换机制
- RESTful API接口
- 消息队列异步处理
- 文件传输
- 数据库同步
## 10. 性能优化策略
### 10.1 前端优化
- 代码分割和按需加载
- 图片懒加载和压缩
- CDN加速静态资源
- 浏览器缓存策略
- 虚拟滚动处理大数据量展示
### 10.2 后端优化
- 数据库索引优化
- API响应缓存（Redis）
- 数据库连接池
- 负载均衡部署
- 异步任务处理（RabbitMQ）
## 11. 部署架构
### 11.1 开发环境
- 本地开发服务器
- 热重载功能
- 代理配置解决跨域问题
### 11.2 生产环境
- Nginx反向代理服务器
- 负载均衡配置
- SSL证书配置
- 日志收集和监控系统
- 容器化部署（Docker）
- 自动化部署（CI/CD）

248
docs/design/DEVELOPMENT_PLAN.md Normal file
View File

@@ -0,0 +1,248 @@
# 开发计划
## 1. 项目概述
本项目是面向锡林郭勒盟地区养殖产业的综合性数字化管理平台，包含官网展示、多个专业管理系统（养殖管理、银行监管、保险监管、政府监管、活牛交易、商城管理）、大屏可视化系统、移动端小程序等多个子系统。平台旨在通过数字化手段提升整个产业链的管理效率和透明度。
## 2. 技术选型
### 2.1 前端技术栈
- **官网首页**: HTML5 + CSS3 + JavaScript
- **专业管理系统**: Vue.js 3 + TypeScript + Ant Design Vue + Pinia
- **大屏可视化系统**: Vue.js 3 + ECharts/DataV
- **微信小程序矩阵**: 微信小程序原生开发 + uni-app
### 2.2 后端技术栈
- **API服务**: Node.js + Express.js + RESTful API
- **数据库**: MySQL
- **缓存**: Redis（用于会话管理和高频数据缓存）
- **消息队列**: RabbitMQ（用于异步任务处理）
- **API文档**: Swagger
- **安全**: JWT认证 + 数据加密
- **文件存储**: 腾讯云存储
### 2.3 开发优先级
1. **第一阶段（2025-09-01至2025-10-31）**: 核心功能（养殖管理、银行监管）
2. **第二阶段（2025-11-01至2025-12-31）**: 扩展功能（保险监管、政府监管）
3. **第三阶段（2026-01-01至2026-02-28）**: 交易和商城功能
### 2.4 技术风险与应对
- **风险1**: 高并发场景下的数据库性能瓶颈
- **应对**: 引入读写分离和分库分表策略
- **风险2**: 第三方服务（如微信支付）的集成稳定性
- **应对**: 设计降级方案和本地Mock服务
### 2.5 开发工具
- VS Code (推荐IDE)
- Git (版本控制)
- ESLint + Prettier (代码规范)
- Jest/Vitest (单元测试)
## 3. 开发阶段规划
### 阶段一：项目初始化与基础架构搭建 (2周)
#### 3.1 环境配置 (2天)
- 搭建开发环境
- 配置代码编辑器
- 初始化Git仓库
- 配置ESLint和Prettier
#### 3.2 项目脚手架搭建 (3天)
- 官网首页静态页面搭建
- 6个专业管理系统Vue项目初始化（养殖管理、银行监管、保险监管、政府监管、活牛交易、商城管理）
- 大屏可视化系统初始化
- 微信小程序项目初始化（5个小程序）
- 后端API服务搭建
#### 3.3 基础设施集成 (3天)
- 数据库设计和初始化
- 腾讯云存储服务集成
- JWT身份认证实现
- 基础权限管理框架
#### 3.4 开发规范制定 (2天)
- 制定代码规范
- 确定目录结构
- 编写开发文档
### 阶段二：核心功能开发 (8周)
#### 3.5 用户认证和权限系统 (1周)
- 用户注册/登录功能
- JWT Token管理
- 角色权限管理
- RBAC权限控制实现
#### 3.6 官网首页和基础框架 (1周)
- 官网首页设计和实现
- 6个专业管理系统基础布局
- 导航菜单实现
- 响应式设计适配
#### 3.7 养殖管理系统 (2周)
- 牛只档案管理（耳标二维码管理、全生命周期记录）
- 饲养记录管理（饲料库存预警、每日投喂量记录）
- 繁殖管理（基因谱系分析、产犊预测模型）
- 环境监测数据展示（物联网设备接入、异常环境自动告警）
#### 3.8 银行监管系统 (1周)
- 贷款申请和审批流程管理
- 质押物（牛只）状态监控
- 还款计划跟踪
- 风险评估和预警
#### 3.9 保险监管系统 (1周)
- 保险投保管理
- 理赔申请和处理流程
- 风险评估和预警
- 保险记录查询
#### 3.10 政府监管平台 (1周)
- 产业数据总览
- 各类监管数据汇总
- 政策发布和通知
- 合规性检查
#### 3.11 活牛交易系统 (1周)
- 牛只信息发布和展示
- 在线交易撮合
- 合同管理
- 支付流程管理
### 阶段三：商城和小程序开发 (4周)
#### 3.12 商城管理系统 (1周)
- 商品信息管理
- 库存管理
- 订单处理
- 物流跟踪
#### 3.13 牛肉商城小程序（含认养功能） (1周)
- 商品浏览和搜索
- 在线下单和支付
- 订单查询和跟踪
- 认养功能实现
- 售后服务申请
#### 3.14 养殖管理小程序 (1周)
- 移动端牛只档案查看
- 饲养记录录入
- 健康状况上报
- 通知消息接收
#### 3.15 银行和保险监管小程序 (1周)
- 银行监管小程序功能开发
- 保险监管小程序功能开发
#### 3.16 活牛交易小程序 (1周)
- 活牛信息发布
- 在线交易撮合
- 合同查看和管理
### 阶段四：数据系统和特色功能 (3周)
#### 3.17 数据分析系统 (1周)
- 实时数据采集（IoT设备数据接入、用户行为数据采集）
- 大数据分析引擎（数据清洗和预处理、统计分析模型）
- 智能预警系统（异常数据检测、风险预警机制）
#### 3.18 大屏可视化系统 (1周)
- 数据图表展示
- 仪表盘设计
- 报表生成和导出
#### 3.19 特色功能实现 (1周)
- 锡林郭勒盟地域元素融入
- 蒙古族文化特色设计
- 安格斯牛品牌突出展示
### 阶段五：系统集成与测试 (2周)
#### 3.20 系统集成 (3天)
- 内蒙古畜牧云对接（数据同步、接口规范）
- 金融机构API对接（银行接口、保险接口）
- 第三方服务集成
#### 3.21 测试用例编写 (3天)
- 单元测试编写（核心功能模块单元测试覆盖率不低于80%）
- 集成测试实现
- E2E测试配置
#### 3.22 Bug修复与优化 (3天)
- 功能测试与Bug修复
- 性能调优（关键操作响应时间<2秒）
- 用户体验优化
#### 3.23 部署准备 (3天)
- 生产环境配置
- 构建脚本优化
- 部署文档编写
- Docker配置
#### 3.24 项目验收与交付 (1天)
- 用户验收测试
- 项目文档完善
- 代码交接
- 项目总结
## 4. 团队分工
### 4.1 前端开发团队
- 前端架构师(1名)：负责前端架构设计和技术选型
- 官网首页开发工程师(1名)：负责官网首页开发
- 专业管理系统开发工程师(4名)：负责6个专业管理系统开发
- 大屏可视化开发工程师(1名)：负责大屏可视化系统开发
- 小程序开发工程师(3名)：负责5个微信小程序开发
- UI设计师(1名)：负责界面设计和用户体验优化
### 4.2 后端开发团队
- 后端架构师(1名)：负责后端架构设计和技术选型
- API开发工程师(3名)：负责后端API服务开发
- 数据库工程师(1名)：负责数据库设计和优化
- 运维工程师(1名)：负责部署和运维工作
### 4.3 数据分析团队
- 数据分析师(1名)：负责数据分析和可视化
- 算法工程师(1名)：负责智能预警系统开发
### 4.4 测试团队
- 测试工程师(2名)：负责测试用例编写和执行
## 5. 质量保障
### 5.1 代码质量控制
- 使用ESLint和Prettier统一代码风格
- 通过Code Review确保代码质量
- 使用TypeScript增强代码可维护性
### 5.2 测试策略
- 单元测试：核心功能模块单元测试覆盖率不低于80%
- 集成测试：实现主要业务流程的集成测试
- E2E测试：关键用户路径的端到端测试
- 性能测试：确保系统支持500+并发用户
### 5.3 安全保障
- 数据传输加密（HTTPS）
- 敏感数据脱敏存储
- 防止SQL注入和XSS攻击
- CSRF防护机制
- API接口限流和防护
## 6. 部署与运维
### 6.1 部署方案
- 支持Docker容器化部署
- 支持云平台部署（腾讯云）
- 支持负载均衡部署
### 6.2 监控体系
- 系统运行状态监控
- 性能监控指标
- 异常告警功能
- 日志收集和分析
### 6.3 故障处理
- 提供故障诊断工具
- 实现自动故障恢复机制
- 提供故障处理文档

32
docs/design/api/data-platform.md Normal file
View File

@@ -0,0 +1,32 @@
# 数据中台系统 API 文档
## 1. 接口概述
### 1.1 功能范围
- 数据血缘追踪
- 接口调用分析
- 数据质量监控
### 1.2 基础路径
`/api/v1/data`
## 2. 接口明细
### 2.1 数据血缘查询
```
GET /lineage
```
| 参数 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| source | string | 否 | 源表名 |
| target | string | 否 | 目标表名 |
### 2.2 接口审计
```
GET /audit-logs
```
## 3. 性能指标
- 血缘查询响应时间 < 500ms
- 审计日志保留至少180天

57
docs/design/api/farming.md Normal file
View File

@@ -0,0 +1,57 @@
# 养殖管理系统 API 文档 (v1.1.0)
## 1. 接口概述
### 1.1 功能范围
- 牛只档案管理
- 饲喂记录
- 防疫管理
- 繁殖管理
### 1.2 基础路径
`/api/v1/farming`
## 2. 接口明细
### 2.1 添加牛只
```
POST /cattles
```
| 字段 | 类型 | 必填 | 说明 |
|--------------|--------|------|--------------------|
| ear_tag | string | 是 | 耳标号(唯一) |
| breed | string | 是 | 品种 |
| birth_date | string | 是 | 出生日期(YYYY-MM-DD)|
| gender | string | 是 | 性别(公/母) |
| weight | number | 否 | 体重(kg) |
### 2.2 批量导入牛只
```
POST /cattles/batch
```
| 字段 | 类型 | 必填 | 说明 |
|--------------|--------|------|--------------------|
| file | file | 是 | Excel文件 |
### 2.3 防疫记录
```
POST /vaccinations
```
| 字段 | 类型 | 必填 | 说明 |
|--------------|--------|------|--------------------|
| cattle_id | string | 是 | 牛只ID |
| vaccine_type | string | 是 | 疫苗类型 |
| date | string | 是 | 接种日期(YYYY-MM-DD)|
## 3. 数据规范
- 耳标号格式：省简称+6位数字(如NM000001)
- 疫苗记录保留至少5年
- 敏感数据需RSA加密传输
## 4. 权限控制
- 添加牛只：养殖管理员
- 批量导入：系统管理员
- 防疫记录：兽医

54
docs/design/api/finance.md Normal file
View File

@@ -0,0 +1,54 @@
# 金融业务系统 API 文档 (v1.1.0)
## 1. 接口概述
### 1.1 功能范围
- 贷款申请
- 保险购买
- 理赔处理
- 贷款审批
### 1.2 基础路径
`/api/v1/finance`
## 2. 接口明细
### 2.1 贷款申请
```
POST /loans
```
| 字段 | 类型 | 必填 | 说明 |
|-----------------|---------|------|--------------------|
| farmer_id | number | 是 | 牧户ID |
| amount | number | 是 | 申请金额(元) |
| collateral_type | string | 是 | 抵押物类型 |
| term | number | 是 | 贷款期限(月) |
| interest_rate | number | 是 | 年利率(%) |
### 2.2 贷款审批状态查询
```
GET /loans/:id/status
```
### 2.3 保险购买
```
POST /insurances
```
| 字段 | 类型 | 必填 | 说明 |
|-----------------|---------|------|--------------------|
| farmer_id | number | 是 | 牧户ID |
| cattle_id | string | 是 | 牛只ID |
| insurance_type | string | 是 | 保险类型 |
| premium | number | 是 | 保费(元) |
## 3. 风控规则
- 单笔贷款金额 ≤ 牧户资产总额的50%
- 理赔申请需在灾害发生后30天内提交
- 敏感数据需RSA加密传输
## 4. 权限控制
- 贷款申请：牧户
- 贷款审批：银行管理员
- 保险购买：牧户

52
docs/design/api/government.md Normal file
View File

@@ -0,0 +1,52 @@
# 政府监管系统 API 文档 (v1.1.0)
## 1. 接口概述
### 1.1 功能范围
- 防疫任务下发
- 补贴发放
- 检疫监管
- 任务状态跟踪
### 1.2 基础路径
`/api/v1/gov`
## 2. 接口明细
### 2.1 创建防疫任务
```
POST /quarantines
```
| 字段 | 类型 | 必填 | 说明 |
|---------------|--------|------|--------------------|
| location | string | 是 | GPS坐标(纬度,经度)|
| inspector_id | number | 是 | 检疫员ID |
| deadline | string | 是 | 截止日期(YYYY-MM-DD)|
| task_type | string | 是 | 任务类型(常规/紧急)|
| priority | number | 否 | 优先级(1-5) |
### 2.2 防疫任务状态查询
```
GET /quarantines/:id/status
```
### 2.3 检疫监管
```
POST /inspections
```
| 字段 | 类型 | 必填 | 说明 |
|---------------|--------|------|--------------------|
| cattle_id | string | 是 | 牛只ID |
| inspector_id | number | 是 | 检疫员ID |
| result | string | 是 | 检疫结果(合格/不合格)|
## 3. 审计要求
- 所有操作记录操作人IP和时间
- 敏感数据需RSA加密传输
## 4. 权限控制
- 防疫任务下发：政府管理员
- 检疫监管：检疫员
- 补贴发放：财务人员

33
docs/design/api/miniprograms/farming-app.md Normal file
View File

@@ -0,0 +1,33 @@
# 养殖助手小程序 API 文档
## 1. 接口概述
### 1.1 功能范围
- 养殖记录
- 饲喂提醒
- 防疫上报
### 1.2 基础路径
`/api/mini/farming`
## 2. 接口明细
### 2.1 添加饲喂记录
```
POST /feedings
```
| 字段 | 类型 | 必填 | 说明 |
|--------------|--------|------|--------------------|
| cattle_id | number | 是 | 牛只ID |
| feed_type | string | 是 | 饲料类型 |
| amount | number | 是 | 投喂量(kg) |
### 2.2 防疫上报
```
POST /vaccinations
```
## 3. 数据规范
- 时间字段格式: YYYY-MM-DD HH:mm:ss
- 数量单位统一使用kg

33
docs/design/api/miniprograms/gov-app.md Normal file
View File

@@ -0,0 +1,33 @@
# 政府监管小程序 API 文档
## 1. 接口概述
### 1.1 功能范围
- 防疫检查
- 补贴发放
- 违规上报
### 1.2 基础路径
`/api/mini/gov`
## 2. 接口明细
### 2.1 提交检查报告
```
POST /inspections
```
| 字段 | 类型 | 必填 | 说明 |
|---------------|--------|------|--------------------|
| farm_id | number | 是 | 养殖场ID |
| result | string | 是 | 检查结果 |
| photos | array | 是 | 现场照片URL数组 |
### 2.2 查看补贴名单
```
GET /subsidies
```
## 3. 安全要求
- 所有接口需政府专线VPN接入
- 照片数据需加密存储

35
docs/design/api/miniprograms/merchant-app.md Normal file
View File

@@ -0,0 +1,35 @@
# 商户小程序 API 文档
## 1. 接口概述
### 1.1 功能范围
- 商品管理
- 订单处理
- 数据统计
### 1.2 基础路径
`/api/mini/merchant`
## 2. 接口明细
### 2.1 添加商品
```
POST /products
```
| 字段 | 类型 | 必填 | 说明 |
|--------------|--------|------|--------------------|
| name | string | 是 | 商品名称 |
| price | number | 是 | 价格(元) |
| stock | number | 是 | 库存数量 |
### 2.2 处理订单
```
PUT /orders/{id}
```
## 3. 错误码规范
| 代码 | 说明 |
|------|----------------|
| 4001 | 库存不足 |
| 4002 | 订单已过期 |

34
docs/design/api/miniprograms/user-app.md Normal file
View File

@@ -0,0 +1,34 @@
# 用户小程序 API 文档
## 1. 接口概述
### 1.1 功能范围
- 用户登录/注册
- 商品浏览/购买
- 订单查询
- 个人中心
### 1.2 基础路径
`/api/mini/user`
## 2. 接口明细
### 2.1 微信登录
```
POST /login
```
| 字段 | 类型 | 必填 | 说明 |
|------------|--------|------|----------------|
| code | string | 是 | 微信登录code |
| encryptedData | string | 是 | 加密用户数据 |
| iv | string | 是 | 加密算法的初始向量 |
### 2.2 获取商品列表
```
GET /products
```
## 3. 权限控制
- 所有接口需携带`access_token`
- 敏感接口需二次验证（如支付密码）

62
docs/design/api/trade.md Normal file
View File

@@ -0,0 +1,62 @@
# 交易系统 API 文档 (v1.1.0)
## 1. 接口概述
### 1.1 功能范围
- 商品发布/下架
- 订单创建/支付
- 物流跟踪
- 订单状态查询
### 1.2 基础路径
`/api/v1/trades`
## 2. 接口明细
### 2.1 商品发布
```
POST /products
```
| 字段 | 类型 | 必填 | 说明 |
|--------------|--------|------|--------------------|
| name | string | 是 | 商品名称 |
| price | number | 是 | 价格(元) |
| stock | number | 是 | 库存数量 |
| category | string | 是 | 商品分类 |
### 2.2 创建订单
```
POST /orders
```
| 字段 | 类型 | 必填 | 说明 |
|--------------|--------|------|--------------------|
| product_id | number | 是 | 商品ID |
| quantity | number | 是 | 购买数量 |
| address_id | number | 是 | 收货地址ID |
| payment_method | string | 是 | 支付方式(微信/支付宝)|
| coupon_code | string | 否 | 优惠券码 |
### 2.3 物流跟踪
```
GET /logistics/:order_id
```
## 3. 状态流转
```mermaid
stateDiagram
[*] --> 待支付
待支付 --> 已支付: 支付成功
已支付 --> 配送中: 商家发货
配送中 --> 已完成: 确认收货
```
## 4. 安全要求
- 支付接口需HTTPS加密
- 敏感数据需RSA加密传输
## 5. 权限控制
- 商品发布：商户
- 订单创建：用户
- 物流跟踪：用户/商户

36
docs/design/api/user-center.md Normal file
View File

@@ -0,0 +1,36 @@
# 用户中心系统 API 文档
## 1. 接口概述
### 1.1 功能范围
- 用户注册/登录/注销
- 个人信息管理
- 权限控制
### 1.2 基础路径
`/api/v1/users`
## 2. 接口明细
### 2.1 用户注册
```
POST /register
```
| 字段 | 类型 | 必填 | 说明 |
|------------|--------|------|----------------|
| username | string | 是 | 4-20位字母数字 |
| password | string | 是 | 6-20位含大小写 |
| phone | string | 是 | 11位手机号 |
### 2.2 用户登录
```
POST /login
```
## 3. 状态码规范
| 代码 | 说明 |
|------|----------------|
| 200 | 成功 |
| 400 | 参数校验失败 |
| 401 | 认证失败 |