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

refactor(backend): 重构动物相关 API 接口

Browse Source 
- 更新了动物数据结构和相关类型定义
- 优化了动物列表、详情、创建、更新和删除接口
- 新增了更新动物状态接口
- 移除了与认领记录相关的接口
-调整了 API 响应结构
This commit is contained in:
ylweng
2025-08-31 00:45:46 +08:00
parent 0cad74b06f
commit 8e5295b572
111 changed files with 15290 additions and 1972 deletions
Download Patch File Download Diff File Expand all files Collapse all files

215
docs/architecture.md
View File

@@ -4,93 +4,43 @@
### 1.1 架构图
```mermaid
graph TB
subgraph "客户端层"
MP[微信小程序<br/>uni-app]
ADMIN[后台管理系统<br/>Vue.js 3 + Ant Design]
WEBSITE[官网系统<br/>HTML5 + Bootstrap]
end
**系统架构层次说明：**
subgraph "接入层"
GATEWAY[API网关<br/>Nginx + Node.js]
end
**1. 客户端层**
- **微信小程序**: 基于uni-app开发，提供用户端功能
- **后台管理系统**: 基于Vue.js 3 + Ant Design开发，提供管理功能
- **官网系统**: 基于HTML5 + Bootstrap开发，提供企业宣传功能
subgraph "应用服务层"
AUTH[认证服务]
USER[用户服务]
TRAVEL[旅行服务]
ANIMAL[动物服务]
MERCHANT[商家服务]
PAYMENT[支付服务]
PROMOTION[推广服务]
end
**2. 接入层**
- **API网关**: 基于Nginx + Node.js，提供统一的API接入和路由分发
subgraph "基础设施层"
DB[MySQL数据库<br/>主从复制]
CACHE[Redis缓存<br/>集群模式]
MQ[RabbitMQ<br/>消息队列]
STORAGE[对象存储<br/>腾讯云COS]
end
**3. 应用服务层**
- **认证服务**: 用户身份认证和权限管理
- **用户服务**: 用户信息管理和个人中心功能
- **旅行服务**: 旅行计划创建、查询和匹配功能
- **动物服务**: 动物信息管理和认领功能
- **商家服务**: 商家认证、商品和服务管理
- **支付服务**: 支付处理和交易管理
- **推广服务**: 推广活动和奖励管理
subgraph "监控运维层"
MONITOR[监控系统<br/>Prometheus + Grafana]
LOG[日志系统<br/>ELK Stack]
CI_CD[CI/CD<br/>Jenkins + Docker]
end
**4. 基础设施层**
- **MySQL数据库**: 主从复制架构，存储核心业务数据
- **Redis缓存**: 集群模式，提供高性能缓存服务
- **RabbitMQ消息队列**: 异步消息处理和解耦
- **对象存储**: 腾讯云COS，存储图片和文件资源
MP --> GATEWAY
ADMIN --> GATEWAY
WEBSITE --> GATEWAY
GATEWAY --> AUTH
GATEWAY --> USER
GATEWAY --> TRAVEL
GATEWAY --> ANIMAL
GATEWAY --> MERCHANT
GATEWAY --> PAYMENT
GATEWAY --> PROMOTION
**5. 监控运维层**
- **监控系统**: Prometheus + Grafana，系统性能监控
- **日志系统**: ELK Stack，日志收集和分析
- **CI/CD**: Jenkins + Docker，持续集成和部署
AUTH --> DB
USER --> DB
TRAVEL --> DB
ANIMAL --> DB
MERCHANT --> DB
PAYMENT --> DB
PROMOTION --> DB
AUTH --> CACHE
USER --> CACHE
TRAVEL --> CACHE
ANIMAL --> CACHE
MERCHANT --> CACHE
PAYMENT --> MQ
PROMOTION --> MQ
AUTH --> STORAGE
USER --> STORAGE
ANIMAL --> STORAGE
MERCHANT --> STORAGE
MONITOR -.-> AUTH
MONITOR -.-> USER
MONITOR -.-> TRAVEL
MONITOR -.-> ANIMAL
MONITOR -.-> MERCHANT
LOG -.-> AUTH
LOG -.-> USER
LOG -.-> TRAVEL
LOG -.-> ANIMAL
LOG -.-> MERCHANT
CI_CD -.-> AUTH
CI_CD -.-> USER
CI_CD -.-> TRAVEL
CI_CD -.-> ANIMAL
CI_CD -.-> MERCHANT
```
**架构连接关系：**
- 所有客户端通过API网关访问后端服务
- 应用服务层各服务独立部署，通过API网关统一暴露接口
- 认证服务、用户服务、旅行服务、动物服务、商家服务连接MySQL数据库和Redis缓存
- 支付服务和推广服务连接MySQL数据库和RabbitMQ消息队列
- 认证服务、用户服务、动物服务、商家服务连接对象存储
- 监控系统、日志系统、CI/CD系统监控所有应用服务
## 2. 项目结构
@@ -153,7 +103,7 @@ graph TB
├── admin-system // 后台管理系统 (Vue.js 3 + TypeScript + Ant Design Vue + Pinia)
│ ├── public // 静态资源
│ ├── src
│ │ ├── api // API接口
│ │ ├── api // API接口 (TypeScript类型定义)
│ │ │ ├── user // 用户相关接口
│ │ │ ├── merchant // 商家相关接口
│ │ │ ├── travel // 旅行相关接口
@@ -162,7 +112,7 @@ graph TB
│ │ │ ├── promotion // 推广相关接口
│ │ │ └── system // 系统管理接口
│ │ ├── assets // 静态资源
│ │ ├── components // 公共组件
│ │ ├── components // 公共组件 (Vue 3 Composition API)
│ │ │ ├── layout // 布局组件
│ │ │ ├── common // 通用组件
│ │ │ ├── user // 用户相关组件
@@ -172,7 +122,7 @@ graph TB
│ │ │ ├── order // 订单相关组件
│ │ │ ├── promotion // 推广相关组件
│ │ │ └── dashboard // 仪表板组件
│ │ ├── composables // 组合式函数
│ │ ├── composables // 组合式函数 (Vue 3 Composition API)
│ │ ├── directives // 自定义指令
│ │ ├── layouts // 页面布局
│ │ │ ├── default.vue // 默认布局
@@ -181,7 +131,7 @@ graph TB
│ │ ├── locales // 国际化资源
│ │ │ ├── zh-CN.json // 中文语言包
│ │ │ └── en-US.json // 英文语言包
│ │ ├── pages // 页面视图
│ │ ├── pages // 页面视图 (Vue 3 + TypeScript)
│ │ │ ├── dashboard // 仪表板页面
│ │ │ ├── user // 用户管理页面
│ │ │ ├── merchant // 商家管理页面
@@ -193,7 +143,7 @@ graph TB
│ │ │ ├── login.vue // 登录页面
│ │ │ └── register.vue // 注册页面
│ │ ├── plugins // 插件
│ │ ├── router // 路由配置
│ │ ├── router // 路由配置 (Vue Router 4 + TypeScript)
│ │ │ ├── modules // 模块路由
│ │ │ │ ├── user.ts // 用户路由
│ │ │ │ ├── merchant.ts // 商家路由
@@ -203,7 +153,7 @@ graph TB
│ │ │ │ ├── promotion.ts // 推广路由
│ │ │ │ └── system.ts // 系统路由
│ │ │ └── index.ts // 路由入口
│ │ ├── stores // 状态管理
│ │ ├── stores // 状态管理 (Pinia 2 + TypeScript)
│ │ │ ├── modules // 模块状态
│ │ │ │ ├── user.ts // 用户状态
│ │ │ │ ├── merchant.ts // 商家状态
@@ -215,22 +165,22 @@ graph TB
│ │ │ └── index.ts // 状态管理入口
│ │ ├── styles // 样式文件
│ │ ├── types // TypeScript类型定义
│ │ ├── utils // 工具函数
│ │ │ ├── request.ts // 请求封装
│ │ ├── utils // 工具函数 (TypeScript)
│ │ │ ├── request.ts // 请求封装 (Axios + TypeScript)
│ │ │ ├── auth.ts // 认证工具
│ │ │ ├── storage.ts // 存储工具
│ │ │ ├── format.ts // 格式化工具
│ │ │ └── validate.ts // 验证工具
│ │ └── App.vue // 根组件
│ │ └── main.ts // 入口文件
│ ├── tests // 测试目录
│ │ └── App.vue // 根组件 (Vue 3 + TypeScript)
│ │ └── main.ts // 入口文件 (Vue 3 + TypeScript + Pinia + Ant Design Vue)
│ ├── tests // 测试目录 (Vitest + Vue Test Utils)
│ ├── .env // 环境配置
│ ├── .env.development // 开发环境配置
│ ├── .env.production // 生产环境配置
│ ├── index.html // HTML模板
│ ├── tsconfig.json // TypeScript配置
│ ├── vite.config.ts // 构建配置
│ └── package.json // 依赖配置
│ ├── tsconfig.json // TypeScript配置 (严格模式)
│ ├── vite.config.ts // 构建配置 (Vite 4 + TypeScript)
│ └── package.json // 依赖配置 (Vue 3 + TypeScript + Ant Design Vue + Pinia)
├── website // 官网系统 (HTML5 + Bootstrap)
│ ├── index.html // 首页
│ ├── about.html // 关于我们
@@ -325,19 +275,33 @@ graph TB
### 2.1 后端技术栈
API服务: Node.js + Express.js + TypeScript + RESTful API
数据库: MySQL
缓存系统: Redis
数据库: MySQL 8.0 (包含RBAC权限管理表结构)
缓存系统: Redis Cluster
消息队列: RabbitMQ（用于异步处理）
文件存储: 腾讯云对象存储
实时通信: WebSocket（用于大屏数据推送和实时通知）
API文档: Swagger
实时通信: WebSocket（用于实时通知和聊天功能）
API文档: Swagger + OpenAPI 3.0
权限管理: JWT + RBAC (基于角色的访问控制)
### 2.2 前端技术栈
- 小程序框架：uni-app
- 开发语言：JavaScript/TypeScript
- UI框架：WeUI
- 状态管理：Redux
- 构建工具：Webpack
- 包管理：npm/yarn
#### 微信小程序技术栈
- **开发框架**: uni-app
- **开发语言**: JavaScript/TypeScript
- **UI框架**: WeUI
- **状态管理**: Redux
- **构建工具**: Webpack
- **包管理**: npm/yarn
#### 后台管理系统技术栈 (Vue.js 3 + TypeScript + Ant Design Vue + Pinia)
- **核心框架**: Vue.js 3.3.0 (Composition API + `<script setup>`语法)
- **开发语言**: TypeScript 5.0.0 (严格模式 + 完整类型系统)
- **UI组件库**: Ant Design Vue 4.0.0 (企业级UI设计规范)
- **状态管理**: Pinia 2.1.0 (轻量级、类型安全的Vue状态管理)
- **路由管理**: Vue Router 4.x (支持TypeScript的类型安全路由)
- **构建工具**: Vite 4.x (快速的开发服务器和热重载)
- **包管理**: npm/yarn
- **代码规范**: ESLint + Prettier (统一的代码风格和质量)
- **测试框架**: Vitest + Vue Test Utils (单元测试和组件测试)
### 2.3 官网技术栈
- 核心技术：HTML5 + Bootstrap
@@ -346,7 +310,8 @@ API文档: Swagger
- 包管理：npm/yarn
### 2.3 数据库选型
- 主数据库：MySQL 8.0
- 主数据库：MySQL 5.7
- 权限管理：RBAC模型 (包含roles、permissions、role_permissions、user_roles表)
### 2.4 缓存选型
- 分布式缓存：Redis Cluster
@@ -366,6 +331,7 @@ API文档: Swagger
- 生态丰富：npm生态系统庞大，可快速集成各种第三方库
- 全栈统一：前后端均可使用JavaScript/TypeScript，降低开发成本
- 轻量级：Express.js是一个轻量级的Web框架，灵活性高
- RBAC支持：完善的权限管理中间件生态，支持JWT和RBAC权限控制
- **劣势**：
- CPU密集型任务处理能力较弱
- 回调地狱问题（TypeScript可有效缓解）
@@ -381,6 +347,19 @@ API文档: Swagger
- 平台限制：某些平台特定功能需要特殊处理
- 复杂度：多端兼容可能带来额外的复杂性
**后台管理系统 (Vue.js 3 + TypeScript + Ant Design Vue + Pinia)**
- **优势**：
- **类型安全**: TypeScript提供编译时类型检查，减少运行时错误
- **开发体验**: Vue 3 Composition API + `<script setup>`语法提供更好的代码组织和复用
- **企业级UI**: Ant Design Vue提供专业的企业级UI组件和设计规范
- **状态管理**: Pinia提供轻量级、类型安全的状态管理方案，替代Vuex
- **构建性能**: Vite构建工具提供极快的开发服务器启动和热重载
- **代码质量**: ESLint + Prettier确保代码风格统一和质量
- **测试覆盖**: Vitest + Vue Test Utils支持完整的单元测试和组件测试
- **劣势**：
- 学习曲线: TypeScript和新的Composition API需要一定的学习成本
- 包体积: 类型系统和完整工具链会增加最终的包体积
#### 官网技术栈选型理由
**HTML5 + Bootstrap**
@@ -395,14 +374,15 @@ API文档: Swagger
#### 数据库选型理由
**MySQL 8.0**
**MySQL 5.7**
- **优势**：
- 成熟稳定：关系型数据库，事务支持完善
- 生态丰富：社区活跃，文档齐全
- 性能优化：MySQL 8.0在性能方面有显著提升
- 广泛兼容：MySQL 5.7在生产环境中广泛使用，兼容性好
- **劣势**：
- 水平扩展性相对较弱
- 复杂查询性能可能不如专门的分析型数据库
- 缺少MySQL 8.0的一些新特性
#### 缓存选型理由
@@ -440,6 +420,7 @@ API文档: Swagger
外网:
├── uni-app前端用户 --- HTTPS --> API网关
├── 官网用户 --- HTTPS --> Nginx反向代理 --> 官网系统
├── 后台管理系统用户 --- HTTPS --> API网关 (Vue 3 + TypeScript + Ant Design Vue + Pinia)
└── 第三方支付平台 <-- 支付回调 --- 后端服务
腾讯云服务器:
@@ -447,8 +428,11 @@ API文档: Swagger
│ ├── 静态资源服务
│ └── SSR渲染服务 (Nuxt.js)
├── API网关 --> 后端服务
├── 后端服务 --> MySQL数据库
├── 后端服务 --> Redis缓存
│ ├── 用户端API服务 (小程序接口)
│ ├── 管理端API服务 (后台管理接口 - Vue 3 + TypeScript + Ant Design Vue + Pinia)
│ └── 公共服务 (认证、权限等)
├── 后端服务 --> MySQL数据库 (包含RBAC权限表)
├── 后端服务 --> Redis缓存 (会话和权限缓存)
├── 后端服务 --> RabbitMQ消息队列
└── 后端服务 --监控--> Prometheus监控 --> Grafana
|--> ELK Stack
@@ -492,12 +476,14 @@ API文档: Swagger
- 实施自动扩缩容策略，根据负载动态调整服务实例数量
#### 数据安全风险
- **风险描述**：系统涉及用户个人信息、支付信息等敏感数据，存在数据泄露风险。
- **应对策略**：
- **风险描述**: 系统涉及用户个人信息、支付信息等敏感数据，存在数据泄露风险。管理员后台权限控制不当可能导致数据泄露。
- **应对策略**:
- 对敏感数据进行加密存储（AES/RSA算法）
- 实施严格的访问控制和身份认证机制
- 采用RBAC权限模型，严格控制管理员操作权限
- 定期进行安全审计和渗透测试
- 遵循GDPR等数据保护法规要求
- 管理员操作日志记录和审计
### 4.2 业务风险
@@ -509,12 +495,13 @@ API文档: Swagger
- 制定限流和降级策略，保证核心功能稳定运行
#### 商家服务质量风险
- **风险描述**：商家用户提供的服务质量和用户体验直接影响平台声誉。
- **应对策略**：
- **风险描述**: 商家用户提供的服务质量和用户体验直接影响平台声誉。管理员审核不严可能导致低质量商家入驻。
- **应对策略**:
- 建立商家资质审核机制
- 实施用户评价体系，公开服务评价
- 建立投诉处理机制，及时处理用户反馈
- 对低质量商家实施警告、限流或清退措施
- 管理员审核流程标准化和权限分级
### 4.3 运维风险