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

重构动物认领页面和导航菜单，统一使用SVG图标并优化交互体验

Browse Source
This commit is contained in:
ylweng
2025-09-21 21:12:27 +08:00
parent 467a4ead10
commit 14aca938de
64 changed files with 25067 additions and 18256 deletions
Download Patch File Download Diff File Expand all files Collapse all files

851
docs/后端管理需求文档.md Normal file
View File

@@ -0,0 +1,851 @@
# 解班客后端管理需求文档
## 1. 项目概述
### 1.1 系统定位
后端管理系统是解班客平台的核心服务层，负责提供所有业务逻辑处理、数据管理、API服务以及与第三方系统的集成。系统采用RESTful API架构，为前端应用、小程序和管理后台提供统一的数据服务。
### 1.2 核心职责
- 提供完整的API服务接口
- 处理业务逻辑和数据验证
- 管理用户认证和权限控制
- 集成第三方服务（支付、短信、地图等）
- 确保数据安全和系统稳定性
### 1.3 技术架构
- **运行环境**：Node.js 18+
- **Web框架**：Express.js
- **数据库**：MySQL 8.0 + Redis 6.0
- **认证方式**：JWT + Passport
- **API文档**：Swagger/OpenAPI
## 2. 用户管理模块
### 2.1 用户认证服务
#### 2.1.1 微信登录
```
POST /api/auth/wechat/login
功能：微信小程序登录
参数：
- code: 微信授权码
- encryptedData: 加密用户信息
- iv: 初始向量
返回：JWT token和用户基本信息
```
#### 2.1.2 手机号验证
```
POST /api/auth/phone/verify
功能：发送手机验证码
参数：
- phone: 手机号码
- type: 验证类型（register/login/reset）
POST /api/auth/phone/login
功能：手机号验证码登录
参数：
- phone: 手机号码
- code: 验证码
```
#### 2.1.3 Token管理
```
POST /api/auth/refresh
功能：刷新访问令牌
参数：
- refreshToken: 刷新令牌
POST /api/auth/logout
功能：用户登出
参数：
- token: 访问令牌
```
### 2.2 用户信息管理
#### 2.2.1 用户资料
```
GET /api/users/profile
功能：获取用户详细信息
PUT /api/users/profile
功能：更新用户资料
参数：
- nickname: 昵称
- avatar: 头像URL
- gender: 性别
- birthday: 生日
- location: 所在地
- bio: 个人简介
- interests: 兴趣标签
```
#### 2.2.2 实名认证
```
POST /api/users/identity/verify
功能：提交实名认证
参数：
- realName: 真实姓名
- idCard: 身份证号
- idCardFront: 身份证正面照
- idCardBack: 身份证背面照
GET /api/users/identity/status
功能：查询认证状态
```
#### 2.2.3 用户设置
```
PUT /api/users/settings
功能：更新用户设置
参数：
- privacy: 隐私设置
- notification: 通知设置
- security: 安全设置
GET /api/users/settings
功能：获取用户设置
```
### 2.3 用户关系管理
#### 2.3.1 关注功能
```
POST /api/users/{userId}/follow
功能：关注用户
DELETE /api/users/{userId}/follow
功能：取消关注
GET /api/users/following
功能：获取关注列表
GET /api/users/followers
功能：获取粉丝列表
```
#### 2.3.2 黑名单管理
```
POST /api/users/{userId}/block
功能：拉黑用户
DELETE /api/users/{userId}/block
功能：取消拉黑
GET /api/users/blocked
功能：获取黑名单列表
```
## 3. 活动管理模块
### 3.1 活动发布管理
#### 3.1.1 活动创建
```
POST /api/activities
功能：创建新活动
参数：
- title: 活动标题
- description: 活动描述
- type: 活动类型
- startTime: 开始时间
- endTime: 结束时间
- location: 活动地点
- maxParticipants: 最大参与人数
- fee: 活动费用
- requirements: 参与要求
- images: 活动图片
- tags: 活动标签
```
#### 3.1.2 活动编辑
```
PUT /api/activities/{activityId}
功能：编辑活动信息
DELETE /api/activities/{activityId}
功能：删除活动
PATCH /api/activities/{activityId}/status
功能：更新活动状态
参数：
- status: 活动状态（draft/published/cancelled/completed）
```
### 3.2 活动搜索和筛选
#### 3.2.1 活动列表
```
GET /api/activities
功能：获取活动列表
参数：
- page: 页码
- limit: 每页数量
- type: 活动类型
- location: 地理位置
- startDate: 开始日期
- endDate: 结束日期
- priceMin: 最低价格
- priceMax: 最高价格
- keyword: 关键词搜索
- sort: 排序方式
```
#### 3.2.2 活动详情
```
GET /api/activities/{activityId}
功能：获取活动详细信息
GET /api/activities/{activityId}/participants
功能：获取活动参与者列表
GET /api/activities/nearby
功能：获取附近活动
参数：
- latitude: 纬度
- longitude: 经度
- radius: 搜索半径
```
### 3.3 活动报名管理
#### 3.3.1 报名流程
```
POST /api/activities/{activityId}/join
功能：报名参加活动
参数：
- message: 报名留言
- emergencyContact: 紧急联系人
GET /api/activities/{activityId}/join/status
功能：查询报名状态
DELETE /api/activities/{activityId}/join
功能：取消报名
```
#### 3.3.2 报名审核
```
PUT /api/activities/{activityId}/participants/{userId}/approve
功能：审核通过报名
PUT /api/activities/{activityId}/participants/{userId}/reject
功能：拒绝报名
参数：
- reason: 拒绝原因
GET /api/activities/my/applications
功能：获取我的报名记录
GET /api/activities/my/created
功能：获取我创建的活动
```
## 4. 动物认领模块
### 4.1 动物信息管理
#### 4.1.1 动物档案
```
POST /api/animals
功能：添加动物信息
参数：
- name: 动物名称
- type: 动物类型
- breed: 品种
- age: 年龄
- gender: 性别
- weight: 体重
- health: 健康状况
- description: 描述
- images: 动物照片
- farmId: 所属农场ID
- price: 认领价格
```
#### 4.1.2 动物状态管理
```
PUT /api/animals/{animalId}
功能：更新动物信息
PATCH /api/animals/{animalId}/status
功能：更新动物状态
参数：
- status: 状态（available/adopted/reserved/unavailable）
GET /api/animals
功能：获取动物列表
参数：
- type: 动物类型
- status: 状态筛选
- farmId: 农场筛选
- priceMin: 最低价格
- priceMax: 最高价格
```
### 4.2 认领流程管理
#### 4.2.1 认领申请
```
POST /api/animals/{animalId}/adopt
功能：提交认领申请
参数：
- reason: 认领原因
- experience: 养殖经验
- visitPlan: 探访计划
- duration: 认领期限
GET /api/adoptions/my
功能：获取我的认领记录
GET /api/adoptions/{adoptionId}
功能：获取认领详情
```
#### 4.2.2 认领审核
```
PUT /api/adoptions/{adoptionId}/approve
功能：审核通过认领
PUT /api/adoptions/{adoptionId}/reject
功能：拒绝认领申请
参数：
- reason: 拒绝原因
POST /api/adoptions/{adoptionId}/contract
功能：生成认领合同
```
### 4.3 农场管理
#### 4.3.1 农场信息
```
POST /api/farms
功能：添加农场信息
参数：
- name: 农场名称
- address: 农场地址
- description: 农场描述
- contact: 联系方式
- facilities: 设施介绍
- images: 农场照片
GET /api/farms
功能：获取农场列表
GET /api/farms/{farmId}/animals
功能：获取农场动物列表
```
#### 4.3.2 探访管理
```
POST /api/farms/{farmId}/visits
功能：预约农场探访
参数：
- visitDate: 探访日期
- visitTime: 探访时间
- visitors: 探访人数
- purpose: 探访目的
GET /api/visits/my
功能：获取我的探访记录
PUT /api/visits/{visitId}/confirm
功能：确认探访预约
```
## 5. 商家服务模块
### 5.1 商家入驻管理
#### 5.1.1 入驻申请
```
POST /api/merchants/apply
功能：提交入驻申请
参数：
- businessName: 商家名称
- businessType: 商家类型
- contactPerson: 联系人
- contactPhone: 联系电话
- businessLicense: 营业执照
- address: 经营地址
- description: 商家描述
- qualifications: 资质证明
```
#### 5.1.2 入驻审核
```
GET /api/merchants/applications
功能：获取入驻申请列表
PUT /api/merchants/applications/{applicationId}/approve
功能：审核通过入驻
PUT /api/merchants/applications/{applicationId}/reject
功能：拒绝入驻申请
参数：
- reason: 拒绝原因
```
### 5.2 商家信息管理
#### 5.2.1 商家资料
```
GET /api/merchants/profile
功能：获取商家资料
PUT /api/merchants/profile
功能：更新商家资料
参数：
- businessName: 商家名称
- description: 商家描述
- logo: 商家Logo
- images: 商家图片
- businessHours: 营业时间
- contactInfo: 联系信息
```
#### 5.2.2 商家状态
```
PATCH /api/merchants/{merchantId}/status
功能：更新商家状态
参数：
- status: 状态（active/inactive/suspended）
GET /api/merchants
功能：获取商家列表
参数：
- type: 商家类型
- status: 状态筛选
- location: 地理位置
```
### 5.3 商品服务管理
#### 5.3.1 商品管理
```
POST /api/merchants/products
功能：添加商品
参数：
- name: 商品名称
- category: 商品分类
- price: 商品价格
- description: 商品描述
- images: 商品图片
- stock: 库存数量
- specifications: 商品规格
PUT /api/merchants/products/{productId}
功能：更新商品信息
DELETE /api/merchants/products/{productId}
功能：删除商品
```
#### 5.3.2 订单管理
```
GET /api/merchants/orders
功能：获取商家订单列表
PUT /api/merchants/orders/{orderId}/confirm
功能：确认订单
PUT /api/merchants/orders/{orderId}/ship
功能：发货
参数：
- trackingNumber: 快递单号
- carrier: 快递公司
PUT /api/merchants/orders/{orderId}/complete
功能：完成订单
```
## 6. 支付系统模块
### 6.1 支付接口
#### 6.1.1 微信支付
```
POST /api/payments/wechat/create
功能：创建微信支付订单
参数：
- orderId: 订单ID
- amount: 支付金额
- description: 支付描述
- openid: 用户openid
POST /api/payments/wechat/notify
功能：微信支付回调处理
GET /api/payments/wechat/query/{orderId}
功能：查询支付状态
```
#### 6.1.2 支付宝支付
```
POST /api/payments/alipay/create
功能：创建支付宝支付订单
POST /api/payments/alipay/notify
功能：支付宝支付回调处理
GET /api/payments/alipay/query/{orderId}
功能：查询支付状态
```
### 6.2 订单管理
#### 6.2.1 订单创建
```
POST /api/orders
功能：创建订单
参数：
- type: 订单类型（activity/product/adoption）
- items: 订单项目
- amount: 订单金额
- paymentMethod: 支付方式
- deliveryAddress: 配送地址
GET /api/orders/{orderId}
功能：获取订单详情
GET /api/orders/my
功能：获取我的订单列表
```
#### 6.2.2 订单状态管理
```
PATCH /api/orders/{orderId}/status
功能：更新订单状态
参数：
- status: 订单状态
POST /api/orders/{orderId}/refund
功能：申请退款
参数：
- reason: 退款原因
- amount: 退款金额
PUT /api/orders/{orderId}/refund/approve
功能：审核退款申请
```
### 6.3 财务管理
#### 6.3.1 账户管理
```
GET /api/wallet/balance
功能：获取账户余额
POST /api/wallet/recharge
功能：账户充值
参数：
- amount: 充值金额
- paymentMethod: 支付方式
POST /api/wallet/withdraw
功能：申请提现
参数：
- amount: 提现金额
- bankAccount: 银行账户
```
#### 6.3.2 交易记录
```
GET /api/transactions
功能：获取交易记录
参数：
- type: 交易类型
- startDate: 开始日期
- endDate: 结束日期
- status: 交易状态
GET /api/transactions/{transactionId}
功能：获取交易详情
```
## 7. 消息通知模块
### 7.1 消息系统
#### 7.1.1 站内消息
```
POST /api/messages
功能：发送站内消息
参数：
- receiverId: 接收者ID
- type: 消息类型
- title: 消息标题
- content: 消息内容
GET /api/messages
功能：获取消息列表
参数：
- type: 消息类型
- status: 读取状态
PUT /api/messages/{messageId}/read
功能：标记消息已读
```
#### 7.1.2 推送通知
```
POST /api/notifications/push
功能：发送推送通知
参数：
- userIds: 用户ID列表
- title: 通知标题
- content: 通知内容
- type: 通知类型
GET /api/notifications/settings
功能：获取通知设置
PUT /api/notifications/settings
功能：更新通知设置
```
### 7.2 短信服务
#### 7.2.1 验证码短信
```
POST /api/sms/verification
功能：发送验证码短信
参数：
- phone: 手机号码
- type: 验证类型
- template: 短信模板
POST /api/sms/verify
功能：验证短信验证码
参数：
- phone: 手机号码
- code: 验证码
```
#### 7.2.2 通知短信
```
POST /api/sms/notification
功能：发送通知短信
参数：
- phone: 手机号码
- template: 短信模板
- params: 模板参数
GET /api/sms/records
功能：获取短信发送记录
```
### 7.3 邮件服务
#### 7.3.1 邮件发送
```
POST /api/emails/send
功能：发送邮件
参数：
- to: 收件人邮箱
- subject: 邮件主题
- content: 邮件内容
- template: 邮件模板
GET /api/emails/templates
功能：获取邮件模板列表
POST /api/emails/templates
功能：创建邮件模板
```
## 8. 文件管理模块
### 8.1 文件上传
#### 8.1.1 图片上传
```
POST /api/files/images/upload
功能：上传图片文件
参数：
- file: 图片文件
- type: 图片类型（avatar/product/activity等）
- compress: 是否压缩
POST /api/files/images/batch
功能：批量上传图片
参数：
- files: 图片文件数组
```
#### 8.1.2 文档上传
```
POST /api/files/documents/upload
功能：上传文档文件
参数：
- file: 文档文件
- type: 文档类型
GET /api/files/{fileId}
功能：获取文件信息
DELETE /api/files/{fileId}
功能：删除文件
```
### 8.2 文件管理
#### 8.2.1 文件列表
```
GET /api/files
功能：获取文件列表
参数：
- type: 文件类型
- userId: 用户ID
- page: 页码
- limit: 每页数量
GET /api/files/storage/usage
功能：获取存储使用情况
```
#### 8.2.2 文件处理
```
POST /api/files/images/resize
功能：图片尺寸调整
参数：
- fileId: 文件ID
- width: 宽度
- height: 高度
POST /api/files/images/watermark
功能：添加水印
参数：
- fileId: 文件ID
- watermark: 水印内容
```
## 9. 数据统计模块
### 9.1 用户统计
#### 9.1.1 用户数据
```
GET /api/statistics/users/overview
功能：获取用户概览统计
GET /api/statistics/users/growth
功能：获取用户增长统计
参数：
- startDate: 开始日期
- endDate: 结束日期
- granularity: 统计粒度（day/week/month）
GET /api/statistics/users/activity
功能：获取用户活跃度统计
```
#### 9.1.2 用户行为
```
GET /api/statistics/users/behavior
功能：获取用户行为统计
POST /api/statistics/events/track
功能：记录用户行为事件
参数：
- event: 事件名称
- properties: 事件属性
- userId: 用户ID
```
### 9.2 业务统计
#### 9.2.1 活动统计
```
GET /api/statistics/activities/overview
功能：获取活动概览统计
GET /api/statistics/activities/popular
功能：获取热门活动统计
GET /api/statistics/activities/conversion
功能：获取活动转化率统计
```
#### 9.2.2 交易统计
```
GET /api/statistics/transactions/overview
功能：获取交易概览统计
GET /api/statistics/transactions/revenue
功能：获取收入统计
GET /api/statistics/merchants/performance
功能：获取商家业绩统计
```
## 10. 系统管理模块
### 10.1 配置管理
#### 10.1.1 系统配置
```
GET /api/system/config
功能：获取系统配置
PUT /api/system/config
功能：更新系统配置
参数：
- key: 配置键
- value: 配置值
- description: 配置描述
GET /api/system/config/{key}
功能：获取指定配置项
```
#### 10.1.2 参数管理
```
GET /api/system/parameters
功能：获取系统参数列表
PUT /api/system/parameters/{key}
功能：更新系统参数
参数：
- value: 参数值
```
### 10.2 日志管理
#### 10.2.1 操作日志
```
GET /api/system/logs/operations
功能：获取操作日志
参数：
- userId: 用户ID
- action: 操作类型
- startDate: 开始日期
- endDate: 结束日期
POST /api/system/logs/operations
功能：记录操作日志
参数：
- action: 操作类型
- resource: 操作资源
- details: 操作详情
```
#### 10.2.2 错误日志
```
GET /api/system/logs/errors
功能：获取错误日志
POST /api/system/logs/errors
功能：记录错误日志
参数：
- level: 错误级别
- message: 错误消息
- stack: 错误堆栈
- context: 错误上下文
```
### 10.3 监控管理
#### 10.3.1 系统监控
```
GET /api/system/health
功能：系统健康检查
GET /api/system/metrics
功能：获取系统指标
参数：
- metric: 指标类型
- timeRange: 时间范围
GET /api/system/status
功能：获取系统状态
```
#### 10.3.2 性能监控
```
GET /api/system/performance
功能：获取性能数据
GET /api/system/performance/api
功能：获取API性能统计
GET /api/system/performance/database
功能：获取数据库性能统计
```