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

484
docs/admin-design.md Normal file
View File

@@ -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 | 优化数据统计功能 |

1469
docs/api-documentation.md
View File

File diff suppressed because it is too large Load Diff

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 运维风险

160
docs/detailed_design.md
View File

@@ -231,6 +231,123 @@ erDiagram
| created_at | DATETIME | NOT NULL | 创建时间 |
| updated_at | DATETIME | NOT NULL | 更新时间 |
### 管理员相关表
#### ROLES 表（角色表）
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 角色ID |
| name | VARCHAR(50) | UNIQUE, NOT NULL | 角色名称 |
| description | TEXT | | 角色描述 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
**数据示例**:
- super_admin: 超级管理员，拥有系统所有权限
- admin: 普通管理员，拥有部分管理权限
- content_manager: 内容管理员，负责内容审核和管理
#### PERMISSIONS 表（权限表）
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 权限ID |
| name | VARCHAR(100) | UNIQUE, NOT NULL | 权限名称 |
| description | TEXT | | 权限描述 |
| module | VARCHAR(50) | NOT NULL | 所属模块 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
**权限列表**:
- user:manage - 用户管理权限
- role:manage - 角色管理权限
- permission:manage - 权限管理权限
- content:review - 内容审核权限
- content:publish - 内容发布权限
- data:view - 数据查看权限
- data:export - 数据导出权限
- system:config - 系统配置权限
#### ROLE_PERMISSIONS 表（角色权限关联表）
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 关联ID |
| role_id | INT | FOREIGN KEY REFERENCES roles(id) | 角色ID |
| permission_id | INT | FOREIGN KEY REFERENCES permissions(id) | 权限ID |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
#### USER_ROLES 表（用户角色关联表）
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 关联ID |
| user_id | BIGINT | FOREIGN KEY REFERENCES users(id) | 用户ID |
| role_id | INT | FOREIGN KEY REFERENCES roles(id) | 角色ID |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
### 权限分配关系
```mermaid
erDiagram
USERS ||--o{ USER_ROLES : has
ROLES ||--o{ USER_ROLES : assigned_to
ROLES ||--o{ ROLE_PERMISSIONS : has
PERMISSIONS ||--o{ ROLE_PERMISSIONS : granted_to
USERS {
bigint id
varchar username
varchar email
enum status
timestamp created_at
}
ROLES {
int id
varchar name
text description
timestamp created_at
}
PERMISSIONS {
int id
varchar name
varchar module
text description
timestamp created_at
}
USER_ROLES {
bigint id
bigint user_id
int role_id
timestamp created_at
}
ROLE_PERMISSIONS {
bigint id
int role_id
int permission_id
timestamp created_at
}
```
### 管理员功能说明
1. **用户管理模块**: 查看用户列表、管理用户状态、用户数据分析
2. **内容管理模块**: 内容审核、内容发布管理、违规内容处理
3. **数据统计模块**: 系统数据查看、数据导出、运营报表生成
4. **权限管理模块**: 角色管理、权限分配、用户权限设置
### 安全设计
- 管理员登录采用JWT令牌认证
- 接口权限基于RBAC模型控制
- 敏感操作记录审计日志
- 密码采用bcrypt加密存储
#### 商家表 (merchants)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
@@ -289,6 +406,49 @@ erDiagram
| claimed_at | DATETIME | NOT NULL | 认领时间 |
| ended_at | DATETIME | | 结束时间 |
#### 管理员操作日志表 (admin_operation_logs)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 日志ID |
| admin_id | BIGINT | FOREIGN KEY REFERENCES users(id), NOT NULL | 管理员ID |
| admin_name | VARCHAR(50) | NOT NULL | 管理员姓名 |
| module | VARCHAR(50) | NOT NULL | 操作模块 |
| operation | VARCHAR(100) | NOT NULL | 操作类型 |
| target_id | VARCHAR(100) | | 目标对象ID |
| target_type | VARCHAR(50) | | 目标对象类型 |
| request_method | VARCHAR(10) | | 请求方法 |
| request_url | VARCHAR(500) | | 请求URL |
| request_params | TEXT | | 请求参数 |
| ip_address | VARCHAR(45) | | IP地址 |
| user_agent | VARCHAR(500) | | 用户代理 |
| status | ENUM('success', 'failed') | NOT NULL | 操作状态 |
| error_message | TEXT | | 错误信息 |
| execution_time | INT | | 执行时间(ms) |
| created_at | DATETIME | NOT NULL | 创建时间 |
**操作类型示例**:
- user:create - 创建用户
- user:update - 更新用户
- user:delete - 删除用户
- role:create - 创建角色
- role:update - 更新角色
- role:delete - 删除角色
- permission:assign - 分配权限
- content:review - 内容审核
- content:publish - 内容发布
- data:export - 数据导出
- system:config - 系统配置
**目标对象类型示例**:
- user - 用户
- role - 角色
- permission - 权限
- content - 内容
- merchant - 商家
- animal - 动物
- travel_plan - 旅行计划
- order - 订单
## 2. API设计
### 2.1 用户服务API

56
docs/development_plan.md
View File

@@ -137,7 +137,13 @@
- 数据加密与安全传输: 3人日
- API访问控制与权限管理: 2人日
**后端开发总工时: 70人日**
#### 2.1.5 管理员后台服务 (15人日)
- 用户管理服务: 3人日
- 内容审核服务: 4人日
- 数据统计服务: 4人日
- 权限管理服务: 4人日
**后端开发总工时: 85人日**
### 2.2 前端开发工时
@@ -162,7 +168,16 @@
- 订单管理页面: 4人日
- 评价管理页面: 3人日
**前端开发总工时: 55人日**
#### 2.2.4 管理员后台功能开发 (25人日)
- 管理员登录页面: 2人日
- 用户管理页面: 5人日
- 内容管理页面: 5人日
- 数据统计页面: 6人日
- 权限管理页面: 7人日
**前端开发总工时: 80人日**
**项目开发总工时: 85 + 80 + 10 + 27 + 31 = 233人日**
### 2.3 数据库开发工时
@@ -246,29 +261,33 @@
### 3.2 第二阶段：核心功能开发 (预计6周)
- **时间**: 第5-10周
- **目标**: 完成用户端核心功能开发
- **交付物**:
- **交付物**:
- 用户管理功能上线
- 旅行计划功能上线
- 旅行匹配功能上线
- 动物认领功能上线
- 社交互动功能上线
- **关键任务**:
- **关键任务**:
- 后端核心业务服务开发 (25人日)
- 前端用户端功能开发 (25人日)
- 支付服务集成 (5人日)
- 管理员后台服务开发 (8人日)
### 3.3 第三阶段：商家功能开发 (预计5周)
- **时间**: 第11-15周
- **目标**: 完成商家端功能开发
- **交付物**:
- **目标**: 完成商家端功能开发和管理员后台功能开发
- **交付物**:
- 商家认证功能上线
- 商品/服务管理功能上线
- 订单处理功能上线
- 评价反馈功能上线
- **关键任务**:
- 管理员后台功能上线
- **关键任务**:
- 后端商家服务开发 (20人日)
- 前端商家端功能开发 (20人日)
- 安全服务完善 (5人日)
- 管理员后台服务开发 (7人日)
- 管理员后台前端开发 (25人日)
### 3.4 第四阶段：官网系统开发 (预计4周)
- **时间**: 第16-19周
@@ -301,13 +320,13 @@
## 4. 资源分配建议
### 4.1 人员配置
- **后端开发工程师**: 3人
- **前端开发工程师**: 3人 (新增1名官网前端开发工程师)
- **后端开发工程师**: 3人 (其中1人专注管理员后台API开发)
- **前端开发工程师**: 4人 (2人负责小程序前端，1人负责官网前端，1人负责管理员后台前端)
- **数据库工程师**: 1人
- **运维工程师**: 1人
- **测试工程师**: 2人
- **产品经理**: 1人
- **UI/UX设计师**: 1人 (负责官网UI/UX设计)
- **UI/UX设计师**: 2人 (1人负责小程序UI/UX设计，1人负责管理员后台UI/UX设计)
### 4.2 技术资源
- **开发环境**: macOS/Linux开发机 x 8
@@ -317,17 +336,22 @@
- **项目管理**: Jira + Confluence
### 4.3 时间安排建议
- **总开发周期**: 22周 (约5.5个月)
- **并行开发**: 后端与前端可并行开发
- **总开发周期**: 25周 (约6个月，增加3周用于管理员后台开发)
- **并行开发**: 后端与前端可并行开发，管理员后台开发与核心功能开发并行
- **迭代周期**: 每2周一个迭代，每周进行代码评审
- **里程碑评审**: 每个阶段结束后进行里程碑评审
### 4.4 风险控制
- **技术风险**: 微服务架构复杂度高，需提前进行技术预研
- **人员风险**: 关键岗位需有备份人员
- **进度风险**: 预留2周缓冲时间应对不可预见问题
- **质量风险**: 引入自动化测试，保证代码质量
- **人员风险**: 关键岗位需有备份人员，特别是管理员后台开发人员
- **进度风险**: 预留3周缓冲时间应对不可预见问题（因新增管理员后台功能）
- **质量风险**: 引入自动化测试，保证代码质量，特别是权限管理模块
- **权限安全风险**: RBAC权限模型配置复杂，需严格测试权限控制逻辑
- **官网系统风险**:
- SEO优化效果不达预期
- 浏览器兼容性问题
- 响应式布局在不同设备上显示异常
- 响应式布局在不同设备上显示异常
- **管理员后台风险**:
- 权限控制漏洞可能导致数据泄露
- 操作日志记录不完整影响审计
- 数据统计准确性需要验证

159
docs/requirements.md
View File

@@ -383,6 +383,68 @@
- 农场老板可以查看认领情况和认领者信息
- 农场老板可以设置认领费用和条件
### 3.11 管理员后台功能
#### 故事24：用户管理
**As a** 系统管理员
**I want to** 管理平台用户信息
**So that** 我可以维护平台用户质量和安全
**验收标准：**
- 管理员可以查看所有用户列表
- 管理员可以搜索和筛选用户（按注册时间、状态等）
- 管理员可以禁用/启用用户账号
- 管理员可以查看用户详细信息（注册信息、活动记录等）
- 管理员可以导出用户数据报表
#### 故事25：商家审核
**As a** 系统管理员
**I want to** 审核商家入驻申请
**So that** 我可以确保商家资质合规
**验收标准：**
- 管理员可以查看待审核的商家申请列表
- 管理员可以查看商家提交的资质证明材料
- 管理员可以批准或拒绝商家申请
- 系统会向商家发送审核结果通知
- 审核通过的商家账号自动激活
#### 故事26：内容审核
**As a** 系统管理员
**I want to** 审核用户发布的内容
**So that** 我可以维护平台内容质量
**验收标准：**
- 管理员可以查看待审核的内容列表（旅行计划、动态、评论等）
- 管理员可以审核并通过合规内容
- 管理员可以拒绝或删除违规内容
- 系统会记录审核操作日志
- 用户会收到内容审核结果通知
#### 故事27：数据统计
**As a** 系统管理员
**I want to** 查看平台运营数据
**So that** 我可以监控平台运营状况
**验收标准：**
- 管理员可以查看用户注册趋势图表
- 管理员可以查看订单和交易统计
- 管理员可以查看各功能模块使用情况
- 管理员可以导出数据报表
- 系统提供数据可视化仪表盘
#### 故事28：权限管理
**As a** 系统管理员
**I want to** 管理管理员账号权限
**So that** 我可以控制不同管理员的访问权限
**验收标准：**
- 管理员可以创建和管理其他管理员账号
- 管理员可以分配不同的权限角色
- 系统支持RBAC权限控制模型
- 权限变更会记录操作日志
- 管理员只能访问其权限范围内的功能
## 4. 非功能性需求
### 4.1 性能需求
@@ -401,6 +463,28 @@
### 4.3 兼容性需求
- 支持微信小程序平台
- 兼容不同屏幕尺寸的移动设备
- 管理员后台支持主流浏览器（Chrome、Firefox、Safari、Edge）
### 4.4 管理员后台特殊需求
#### 4.4.1 安全需求
- 管理员操作需要双重身份验证
- 敏感操作（用户封禁、资金操作等）需要二次确认
- 管理员登录IP地址限制和异常登录检测
- 操作日志完整记录且不可篡改
- 权限分级管理，不同角色管理员拥有不同操作权限
#### 4.4.2 性能需求
- 管理员后台页面加载时间不超过2秒
- 大数据量查询响应时间不超过5秒
- 支持同时在线管理员用户数50人
- 批量操作处理能力（如批量审核、批量导出）
#### 4.4.3 可靠性需求
- 关键管理操作支持事务回滚
- 系统异常时自动保存操作进度
- 数据备份和恢复机制
- 7×24小时运维监控
## 5. 优先级建议
@@ -426,6 +510,7 @@
- 活动组织者功能
- 农场老板功能
- 官网功能
- 管理员后台基础功能（用户管理、内容审核）
**Could Have（可以有）：**
- 视频监控功能
@@ -528,6 +613,52 @@
- 在线入驻申请表单
- 商家成功案例和收益数据展示
#### 管理员登录页面
- 管理员账号密码登录
- 双重身份验证
- 忘记密码功能
- 安全登录提示
#### 管理员仪表盘
- 平台运营数据概览（用户数、订单数、交易额等）
- 实时数据图表展示
- 待处理事项提醒（待审核商家、待审核内容等）
- 系统状态监控
#### 用户管理页面
- 用户列表展示（支持搜索和筛选）
- 用户详细信息查看
- 账号状态管理（启用/禁用）
- 用户行为记录查看
- 数据导出功能
#### 商家审核页面
- 待审核商家列表
- 商家资质材料查看
- 审核操作（通过/拒绝）
- 审核意见填写
- 审核历史记录
#### 内容审核页面
- 待审核内容列表（旅行计划、动态、评论等）
- 内容详情查看
- 批量审核功能
- 审核标准说明
- 违规内容处理记录
#### 数据统计页面
- 用户增长趋势图表
- 订单和交易统计分析
- 各功能模块使用情况统计
- 自定义报表生成
- 数据导出和下载
#### 权限管理页面
- 管理员账号列表
- 角色权限配置
- 操作日志查看
- 权限变更记录
#### 商品管理页面
- 商品列表展示
- 添加/编辑商品功能
@@ -572,6 +703,21 @@
5. 商家处理订单
6. 服务完成，用户评价
#### 管理员审核流程：
1. 商家/用户提交申请或内容
2. 系统将待审核项加入审核队列
3. 管理员登录后台查看待处理事项
4. 管理员审核申请/内容
5. 系统记录审核结果并通知申请人
6. 审核通过的内容/申请正式生效
#### 权限管理流程：
1. 超级管理员创建新的管理员账号
2. 分配相应的权限角色
3. 管理员使用分配的权限登录后台
4. 系统根据权限控制功能访问范围
5. 所有操作记录日志供审计使用
## 7. 验收标准
### 7.1 功能验收
@@ -586,4 +732,15 @@
### 7.3 安全验收
- 安全测试通过
- 用户隐私保护符合法规要求
- 用户隐私保护符合法规要求
- 管理员后台权限控制符合RBAC模型要求
- 操作日志完整且不可篡改
- 敏感操作二次确认机制正常工作
### 7.4 管理员后台专项验收
- 所有管理员功能用户故事验收标准均已满足
- 后台页面加载性能符合要求（≤2秒）
- 大数据量查询响应时间符合要求（≤5秒）
- 批量操作功能正常工作
- 数据导出功能完整可用
- 权限分级控制准确无误