aiotagro/jiebanke

Fork 0

Files

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

2025-09-21 21:12:27 +08:00

16 KiB

Raw Blame History

解班客后端管理需求文档

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
功能：获取数据库性能统计

16 KiB Raw Blame History Unescape Escape

解班客后端管理需求文档

1. 项目概述

1.1 系统定位

1.2 核心职责

1.3 技术架构

2. 用户管理模块

2.1 用户认证服务

2.1.1 微信登录

2.1.2 手机号验证

2.1.3 Token管理

2.2 用户信息管理

2.2.1 用户资料

2.2.2 实名认证

2.2.3 用户设置

2.3 用户关系管理

2.3.1 关注功能

2.3.2 黑名单管理

3. 活动管理模块

3.1 活动发布管理

3.1.1 活动创建

3.1.2 活动编辑

3.2 活动搜索和筛选

3.2.1 活动列表

3.2.2 活动详情

3.3 活动报名管理

3.3.1 报名流程

3.3.2 报名审核

4. 动物认领模块

4.1 动物信息管理

4.1.1 动物档案

4.1.2 动物状态管理

4.2 认领流程管理

4.2.1 认领申请

4.2.2 认领审核

4.3 农场管理

4.3.1 农场信息

4.3.2 探访管理

5. 商家服务模块

5.1 商家入驻管理

5.1.1 入驻申请

5.1.2 入驻审核

5.2 商家信息管理

5.2.1 商家资料

5.2.2 商家状态

5.3 商品服务管理

5.3.1 商品管理

5.3.2 订单管理

6. 支付系统模块

6.1 支付接口

6.1.1 微信支付

6.1.2 支付宝支付

6.2 订单管理

6.2.1 订单创建

6.2.2 订单状态管理

6.3 财务管理

6.3.1 账户管理

6.3.2 交易记录

7. 消息通知模块

7.1 消息系统

7.1.1 站内消息

7.1.2 推送通知

7.2 短信服务

7.2.1 验证码短信

7.2.2 通知短信

7.3 邮件服务

7.3.1 邮件发送

8. 文件管理模块

8.1 文件上传

8.1.1 图片上传

8.1.2 文档上传

8.2 文件管理

8.2.1 文件列表

8.2.2 文件处理

9. 数据统计模块

9.1 用户统计

9.1.1 用户数据

9.1.2 用户行为

9.2 业务统计

9.2.1 活动统计

16 KiB

Raw Blame History