# 解班客后端管理需求文档 ## 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 功能：获取数据库性能统计 ```