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

- 更新了动物数据结构和相关类型定义 - 优化了动物列表、详情、创建、更新和删除接口 - 新增了更新动物状态接口 - 移除了与认领记录相关的接口 -调整了 API 响应结构
2025-08-31 00:45:46 +08:00
parent 0cad74b06f
commit 8e5295b572
111 changed files with 15290 additions and 1972 deletions
--- a/docs/admin-design.md
+++ b/docs/admin-design.md
@@ -0,0 +1,484 @@
+# 结伴客系统后台管理设计文档
+
+## 1. 概述
+
+### 1.1 设计目标
+为结伴客系统提供功能完善、安全可靠的后台管理系统，支持系统管理员对用户、内容、商家、数据等进行全面管理。
+
+### 1.2 设计原则
+- **安全性**: 采用RBAC权限控制，操作日志记录，敏感操作二次确认
+- **易用性**: 界面简洁直观，操作流程清晰
+- **扩展性**: 模块化设计，支持功能扩展
+- **性能**: 支持大数据量操作，响应快速
+
+## 2. 系统架构
+
+### 2.1 技术栈
+- **前端**: Vue 3 + TypeScript + Element Plus
+- **后端**: Spring Boot + MySQL + Redis
+- **认证**: JWT + RBAC权限控制
+- **部署**: Docker + Nginx
+
+### 2.2 模块划分
+```
+后台管理系统
+├── 认证模块
+├── 用户管理模块
+├── 内容管理模块
+├── 商家管理模块
+├── 数据统计模块
+├── 权限管理模块
+├── 系统配置模块
+└── 操作日志模块
+```
+
+## 3. 功能模块设计
+
+### 3.1 认证模块
+#### 3.1.1 登录功能
+- 管理员账号密码登录
+- JWT Token认证
+- 登录状态保持
+- 安全退出
+
+#### 3.1.2 权限验证
+- 接口级别权限控制
+- 页面级别权限控制
+- 按钮级别权限控制
+
+### 3.2 用户管理模块
+#### 3.2.1 用户列表
+- 分页显示用户信息
+- 搜索过滤功能
+- 用户状态管理
+- 用户详情查看
+
+#### 3.2.2 用户操作
+- 启用/禁用用户
+- 重置用户密码
+- 查看用户行为日志
+
+### 3.3 内容管理模块
+#### 3.3.1 内容审核
+- 待审核内容列表
+- 内容详情查看
+- 审核通过/拒绝
+- 批量审核操作
+
+#### 3.3.2 内容管理
+- 已发布内容管理
+- 违规内容处理
+- 内容统计分析
+
+### 3.4 商家管理模块
+#### 3.4.1 商家审核
+- 商家入驻申请列表
+- 商家资质审核
+- 审核结果通知
+
+#### 3.4.2 商家管理
+- 商家信息管理
+- 商家状态控制
+- 商家数据统计
+
+### 3.5 数据统计模块
+#### 3.5.1 系统概览
+- 用户统计数据
+- 订单统计数据
+- 内容统计数据
+- 商家统计数据
+
+#### 3.5.2 趋势分析
+- 用户增长趋势
+- 订单趋势分析
+- 收入趋势分析
+- 数据图表展示
+
+#### 3.5.3 数据导出
+- CSV格式导出
+- Excel格式导出
+- 自定义时间范围
+
+### 3.6 权限管理模块
+#### 3.6.1 角色管理
+- 角色列表查看
+- 角色创建/编辑
+- 角色权限分配
+- 角色删除
+
+#### 3.6.2 权限管理
+- 权限列表查看
+- 权限分组管理
+- 权限分配
+
+#### 3.6.3 用户角色分配
+- 用户角色管理
+- 批量角色分配
+- 角色权限验证
+
+### 3.7 系统配置模块
+#### 3.7.1 基础配置
+- 网站基本信息
+- 系统参数配置
+- 上传文件配置
+- 邮件短信配置
+
+#### 3.7.2 配置管理
+- 配置项列表
+- 配置值修改
+- 配置分组管理
+- 配置版本控制
+
+### 3.8 操作日志模块
+#### 3.8.1 日志查询
+- 操作日志列表
+- 高级搜索功能
+- 日志详情查看
+
+#### 3.8.2 日志分析
+- 操作频率统计
+- 异常操作检测
+- 安全审计报告
+
+## 4. 数据库设计
+
+### 4.1 核心表结构
+#### 4.1.1 管理员表 (admins)
+```sql
+CREATE TABLE admins (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    username VARCHAR(50) NOT NULL UNIQUE,
+    password VARCHAR(255) NOT NULL,
+    email VARCHAR(100),
+    real_name VARCHAR(50),
+    avatar VARCHAR(255),
+    status ENUM('active', 'inactive') DEFAULT 'active',
+    last_login_at DATETIME,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+```
+
+#### 4.1.2 角色表 (roles)
+```sql
+CREATE TABLE roles (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    name VARCHAR(50) NOT NULL UNIQUE,
+    description VARCHAR(255),
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+```
+
+#### 4.1.3 权限表 (permissions)
+```sql
+CREATE TABLE permissions (
+    id VARCHAR(50) PRIMARY KEY,
+    name VARCHAR(50) NOT NULL,
+    description VARCHAR(255),
+    category VARCHAR(50),
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+#### 4.1.4 角色权限表 (role_permissions)
+```sql
+CREATE TABLE role_permissions (
+    role_id BIGINT NOT NULL,
+    permission_id VARCHAR(50) NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (role_id, permission_id),
+    FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE,
+    FOREIGN KEY (permission_id) REFERENCES permissions(id) ON DELETE CASCADE
+);
+```
+
+#### 4.1.5 管理员角色表 (admin_roles)
+```sql
+CREATE TABLE admin_roles (
+    admin_id BIGINT NOT NULL,
+    role_id BIGINT NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (admin_id, role_id),
+    FOREIGN KEY (admin_id) REFERENCES admins(id) ON DELETE CASCADE,
+    FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE
+);
+```
+
+#### 4.1.6 管理员操作日志表 (admin_operation_logs)
+```sql
+CREATE TABLE admin_operation_logs (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    admin_id BIGINT NOT NULL,
+    admin_name VARCHAR(50) NOT NULL,
+    module VARCHAR(50) NOT NULL,
+    operation VARCHAR(100) NOT NULL,
+    target_id VARCHAR(100),
+    target_type VARCHAR(50),
+    request_method VARCHAR(10),
+    request_url VARCHAR(500),
+    request_params TEXT,
+    ip_address VARCHAR(45),
+    user_agent VARCHAR(500),
+    status ENUM('success', 'failed') NOT NULL,
+    error_message TEXT,
+    execution_time INT,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    INDEX idx_admin_id (admin_id),
+    INDEX idx_module (module),
+    INDEX idx_operation (operation),
+    INDEX idx_status (status),
+    INDEX idx_created_at (created_at)
+);
+```
+
+#### 4.1.7 系统配置表 (system_configs)
+```sql
+CREATE TABLE system_configs (
+    id VARCHAR(50) PRIMARY KEY,
+    name VARCHAR(100) NOT NULL,
+    value TEXT NOT NULL,
+    type ENUM('string', 'number', 'boolean', 'text', 'json') DEFAULT 'string',
+    group_name VARCHAR(50) DEFAULT 'general',
+    description VARCHAR(255),
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    INDEX idx_group (group_name)
+);
+```
+
+### 4.2 数据关系图
+```mermaid
+erDiagram
+    admins ||--o{ admin_roles : has
+    roles ||--o{ admin_roles : assigned
+    roles ||--o{ role_permissions : has
+    permissions ||--o{ role_permissions : included
+    admins ||--o{ audit_logs : creates
+    
+    admins {
+        bigint id
+        varchar username
+        varchar password
+        varchar email
+        varchar real_name
+        varchar avatar
+        enum status
+        datetime last_login_at
+        datetime created_at
+        datetime updated_at
+    }
+    
+    roles {
+        bigint id
+        varchar name
+        varchar description
+        datetime created_at
+        datetime updated_at
+    }
+    
+    permissions {
+        varchar id
+        varchar name
+        varchar description
+        varchar category
+        datetime created_at
+    }
+```
+
+## 5. API接口设计
+
+### 5.1 认证接口
+- `POST /admin/auth/login` - 管理员登录
+- `GET /admin/auth/me` - 获取当前管理员信息
+- `POST /admin/auth/logout` - 退出登录
+- `POST /admin/auth/refresh` - 刷新Token
+
+### 5.2 用户管理接口
+- `GET /admin/users` - 获取用户列表
+- `GET /admin/users/{id}` - 获取用户详情
+- `PUT /admin/users/{id}/status` - 更新用户状态
+
+### 5.3 内容管理接口
+- `GET /admin/contents` - 获取内容列表
+- `GET /admin/contents/{id}` - 获取内容详情
+- `PUT /admin/contents/{id}/review` - 审核内容
+- `POST /admin/contents/batch-review` - 批量审核内容
+
+### 5.4 商家管理接口
+- `GET /admin/merchant-applications` - 获取商家申请列表
+- `PUT /admin/merchant-applications/{id}/review` - 审核商家申请
+- `GET /admin/merchants` - 获取商家列表
+- `PUT /admin/merchants/{id}/status` - 更新商家状态
+
+### 5.5 数据统计接口
+- `GET /admin/statistics` - 获取系统统计数据
+- `GET /admin/statistics/trend` - 获取数据趋势
+- `GET /admin/export/{type}` - 导出数据
+
+### 5.6 权限管理接口
+- `GET /admin/roles` - 获取角色列表
+- `POST /admin/roles` - 创建角色
+- `PUT /admin/roles/{id}` - 更新角色
+- `DELETE /admin/roles/{id}` - 删除角色
+- `GET /admin/permissions` - 获取权限列表
+- `POST /admin/users/{userId}/roles` - 分配用户角色
+
+### 5.7 系统配置接口
+- `GET /admin/system-configs` - 获取系统配置
+- `PUT /admin/system-configs/{id}` - 更新系统配置
+- `POST /admin/system-configs/batch-update` - 批量更新配置
+
+### 5.8 操作日志接口
+- `GET /admin/operation-logs` - 获取操作日志列表
+- `GET /admin/operation-logs/{id}` - 获取操作日志详情
+- `GET /admin/operation-logs/export` - 导出操作日志
+- `GET /admin/operation-logs/statistics` - 获取操作统计
+
+## 6. 安全设计
+
+### 6.1 认证安全
+- JWT Token认证机制
+- Token过期时间设置
+- 密码加密存储（BCrypt）
+- 登录失败次数限制
+
+### 6.2 权限安全
+- RBAC权限控制模型
+- 接口级别权限验证
+- 数据访问权限控制
+
+### 6.3 操作安全
+- 敏感操作二次确认
+- 操作日志记录
+- IP地址限制
+- 操作频率限制
+
+### 6.4 数据安全
+- SQL注入防护
+- XSS攻击防护
+- CSRF攻击防护
+- 数据加密传输（HTTPS）
+
+## 7. 性能优化
+
+### 7.1 数据库优化
+- 合理的索引设计
+- 查询性能优化
+- 分页查询支持
+- 数据库连接池
+
+### 7.2 缓存优化
+- Redis缓存应用
+- 热点数据缓存
+- 缓存更新策略
+- 缓存失效机制
+
+### 7.3 接口优化
+- 接口响应时间优化
+- 批量操作支持
+- 异步处理机制
+- 数据压缩传输
+
+## 8. 部署方案
+
+### 8.1 环境划分
+- 开发环境（Development）
+- 测试环境（Testing）
+- 预生产环境（Staging）
+- 生产环境（Production）
+
+### 8.2 部署架构
+```
+负载均衡 (Nginx)
+├── 后台管理前端 (Vue)
+├── 后端API服务 (Spring Boot)
+├── 数据库集群 (MySQL)
+└── 缓存集群 (Redis)
+```
+
+### 8.3 监控告警
+- 应用性能监控
+- 错误日志监控
+- 数据库监控
+- 系统资源监控
+
+## 9. 测试策略
+
+### 9.1 单元测试
+- 业务逻辑测试
+- 服务层测试
+- 工具类测试
+
+### 9.2 集成测试
+- API接口测试
+- 数据库操作测试
+- 权限验证测试
+
+### 9.3 性能测试
+- 并发用户测试
+- 响应时间测试
+- 负载能力测试
+
+### 9.4 安全测试
+- 权限绕过测试
+- SQL注入测试
+- XSS攻击测试
+
+## 10. 维护计划
+
+### 10.1 日常维护
+- 日志文件清理
+- 数据库备份
+- 系统监控
+- 性能优化
+
+### 10.2 版本发布
+- 版本控制策略
+- 发布流程规范
+- 回滚机制
+- 版本兼容性
+
+### 10.3 故障处理
+- 故障响应流程
+- 问题排查指南
+- 恢复方案
+- 事后总结
+
+## 附录
+
+### A. 权限列表
+| 权限ID | 权限名称 | 描述 | 分类 |
+|--------|----------|------|------|
+| user:view | 查看用户 | 允许查看用户列表和详情 | 用户管理 |
+| user:manage | 管理用户 | 允许修改用户状态和信息 | 用户管理 |
+| content:review | 审核内容 | 允许审核用户发布的内容 | 内容管理 |
+| content:publish | 发布内容 | 允许发布系统公告和内容 | 内容管理 |
+| data:view | 查看数据 | 允许查看系统统计数据 | 数据统计 |
+| data:export | 导出数据 | 允许导出系统数据 | 数据统计 |
+| role:manage | 管理角色 | 允许管理角色和权限 | 权限管理 |
+| merchant:approve | 审核商家 | 允许审核商家入驻申请 | 商家管理 |
+| system:config | 系统配置 | 允许修改系统配置参数 | 系统管理 |
+| audit:view | 查看日志 | 允许查看操作日志 | 日志管理 |
+| audit:export | 导出日志 | 允许导出操作日志 | 日志管理 |
+| audit:statistics | 日志统计 | 允许查看操作日志统计 | 日志管理 |
+
+### B. 错误码说明
+| 错误码 | 说明 | 处理建议 |
+|--------|------|----------|
+| 200 | 成功 | 操作成功 |
+| 201 | 创建成功 | 资源创建成功 |
+| 400 | 请求错误 | 检查请求参数 |
+| 401 | 未授权 | 需要登录认证 |
+| 403 | 禁止访问 | 权限不足 |
+| 404 | 资源不存在 | 检查资源ID |
+| 409 | 资源冲突 | 资源已存在 |
+| 429 | 请求过多 | 降低请求频率 |
+| 500 | 服务器错误 | 联系管理员 |
+
+### C. 版本历史
+| 版本 | 日期 | 说明 |
+|------|------|------|
+| v1.0 | 2025-01-01 | 初始版本发布 |
+| v1.1 | 2025-02-01 | 新增权限管理功能 |
+| v1.2 | 2025-03-01 | 优化数据统计功能 |