Files
jiebanke/docs/detailed_design.md
ylweng 8e5295b572 refactor(backend): 重构动物相关 API 接口
- 更新了动物数据结构和相关类型定义
- 优化了动物列表、详情、创建、更新和删除接口
- 新增了更新动物状态接口
- 移除了与认领记录相关的接口
-调整了 API 响应结构
2025-08-31 00:45:46 +08:00

24 KiB

结伴客系统详细设计文档

2.3 数据库配置

2.3.1 测试环境

  • 主机: 192.168.0.240 (MySQL主机地址)
  • 端口: 3306 (MySQL端口)
  • 用户名: root
  • 密码: aiot$Aiot123
  • 数据库: jiebandata

2.3.2 生产环境

  • 主机: 129.211.213.226
  • 端口: 9527
  • 用户名: root
  • 密码: aiotAiot123!
  • 数据库: jiebandata

1. 数据库设计

1.1 ER图

erDiagram
    USERS ||--o{ TRAVEL_PLANS : creates
    USERS ||--o{ ANIMAL_CLAIMS : claims
    USERS ||--o{ MESSAGES : sends
    USERS ||--o{ ORDERS : places
    USERS ||--o{ REVIEWS : writes
    
    MERCHANTS ||--o{ PRODUCTS : sells
    MERCHANTS ||--o{ ORDERS : processes
    MERCHANTS ||--o{ ACTIVITIES : organizes
    MERCHANTS ||--o{ ANIMALS : manages
    
    TRAVEL_PLANS ||--o{ TRAVEL_MATCHES : matches
    
    ANIMALS ||--o{ ANIMAL_CLAIMS : claimed
    ANIMALS ||--o{ ANIMAL_UPDATES : updates
    
    PRODUCTS ||--o{ ORDER_ITEMS : contains
    
    ORDERS ||--o{ ORDER_ITEMS : contains
    ORDERS ||--o{ PAYMENTS : has
    
    ACTIVITIES ||--o{ ACTIVITY_REGISTRATIONS : registers
    
    USERS {
        int id PK
        string openid
        string nickname
        string avatar
        string gender
        date birthday
        string phone
        string email
        datetime created_at
        datetime updated_at
    }
    
    MERCHANTS {
        int id PK
        int user_id FK
        string merchant_type
        string business_name
        string business_license
        string contact_person
        string contact_phone
        string address
        string description
        string status
        datetime created_at
        datetime updated_at
    }
    
    TRAVEL_PLANS {
        int id PK
        int user_id FK
        string destination
        date start_date
        date end_date
        decimal budget
        string interests
        string visibility
        datetime created_at
        datetime updated_at
    }
    
    TRAVEL_MATCHES {
        int id PK
        int plan_id FK
        int matched_plan_id FK
        decimal match_score
        datetime created_at
    }
    
    ANIMALS {
        int id PK
        int merchant_id FK
        string name
        string species
        string breed
        date birth_date
        string personality
        string farm_location
        decimal price
        string status
        datetime created_at
        datetime updated_at
    }
    
    ANIMAL_CLAIMS {
        int id PK
        int user_id FK
        int animal_id FK
        decimal price_paid
        string agreement_url
        string status
        datetime claimed_at
        datetime ended_at
    }
    
    ANIMAL_UPDATES {
        int id PK
        int animal_id FK
        string update_type
        string content
        string media_url
        datetime created_at
    }
    
    PRODUCTS {
        int id PK
        int merchant_id FK
        string name
        string description
        decimal price
        string image_url
        string category
        string status
        datetime created_at
        datetime updated_at
    }
    
    ORDERS {
        int id PK
        int user_id FK
        int merchant_id FK
        string order_number
        decimal total_amount
        string status
        string delivery_address
        datetime ordered_at
        datetime completed_at
    }
    
    ORDER_ITEMS {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
        decimal unit_price
    }
    
    PAYMENTS {
        int id PK
        int order_id FK
        string payment_method
        string transaction_id
        decimal amount
        string status
        datetime paid_at
    }
    
    MESSAGES {
        int id PK
        int sender_id FK
        int receiver_id FK
        string content
        string status
        datetime sent_at
    }
    
    REVIEWS {
        int id PK
        int user_id FK
        int merchant_id FK
        int order_id FK
        int rating
        string comment
        datetime created_at
    }
    
    ACTIVITIES {
        int id PK
        int merchant_id FK
        string title
        string description
        string activity_type
        datetime start_time
        datetime end_time
        string location
        decimal fee
        int max_participants
        string status
        datetime created_at
        datetime updated_at
    }
    
    ACTIVITY_REGISTRATIONS {
        int id PK
        int activity_id FK
        int user_id FK
        string status
        datetime registered_at
    }

1.2 核心表结构设计

用户表 (users)

字段名 类型 约束 描述
id INT PRIMARY KEY, AUTO_INCREMENT 用户ID
openid VARCHAR(64) UNIQUE, NOT NULL 微信openid
nickname VARCHAR(50) NOT NULL 用户昵称
avatar VARCHAR(255) 用户头像URL
gender ENUM('male', 'female', 'other') 性别
birthday DATE 生日
phone VARCHAR(20) UNIQUE 手机号码
email VARCHAR(100) UNIQUE 邮箱地址
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 创建时间

权限分配关系

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)

字段名 类型 约束 描述
id INT PRIMARY KEY, AUTO_INCREMENT 商家ID
user_id INT FOREIGN KEY, NOT NULL 关联的用户ID
merchant_type ENUM('flower_shop', 'activity_organizer', 'farm_owner') NOT NULL 商家类型
business_name VARCHAR(100) NOT NULL 商家名称
business_license VARCHAR(255) 营业执照图片URL
contact_person VARCHAR(50) NOT NULL 联系人
contact_phone VARCHAR(20) NOT NULL 联系电话
address VARCHAR(255) 地址
description TEXT 商家介绍
status ENUM('pending', 'approved', 'rejected', 'suspended') NOT NULL 商家状态
created_at DATETIME NOT NULL 创建时间
updated_at DATETIME NOT NULL 更新时间

旅行计划表 (travel_plans)

字段名 类型 约束 描述
id INT PRIMARY KEY, AUTO_INCREMENT 计划ID
user_id INT FOREIGN KEY, NOT NULL 用户ID
destination VARCHAR(100) NOT NULL 目的地
start_date DATE NOT NULL 开始日期
end_date DATE NOT NULL 结束日期
budget DECIMAL(10,2) NOT NULL 预算
interests TEXT 兴趣偏好
visibility ENUM('public', 'friends', 'private') NOT NULL 可见范围
created_at DATETIME NOT NULL 创建时间
updated_at DATETIME NOT NULL 更新时间

动物表 (animals)

字段名 类型 约束 描述
id INT PRIMARY KEY, AUTO_INCREMENT 动物ID
merchant_id INT FOREIGN KEY, NOT NULL 关联的农场商家ID
name VARCHAR(50) NOT NULL 动物名称
species VARCHAR(50) NOT NULL 动物种类
breed VARCHAR(50) 品种
birth_date DATE 出生日期
personality TEXT 性格特点
farm_location VARCHAR(255) 农场位置
price DECIMAL(10,2) NOT NULL 认领价格
status ENUM('available', 'claimed', 'unavailable') NOT NULL 状态
created_at DATETIME NOT NULL 创建时间
updated_at DATETIME NOT NULL 更新时间

动物认领表 (animal_claims)

字段名 类型 约束 描述
id INT PRIMARY KEY, AUTO_INCREMENT 认领ID
user_id INT FOREIGN KEY, NOT NULL 用户ID
animal_id INT FOREIGN KEY, NOT NULL 动物ID
price_paid DECIMAL(10,2) NOT NULL 支付金额
agreement_url VARCHAR(255) 电子协议URL
status ENUM('active', 'ended', 'cancelled') NOT NULL 认领状态
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

用户登录

  • URL: POST /api/v1/users/login
  • 请求参数:
    {
      "code": "微信登录凭证"
    }
    
  • 响应:
    {
      "code": 0,
      "message": "success",
      "data": {
        "token": "用户token",
        "user": {
          "id": 1,
          "openid": "openid",
          "nickname": "用户昵称",
          "avatar": "头像URL"
        }
      }
    }
    

获取用户信息

  • URL: GET /api/v1/users/profile
  • 请求头: Authorization: Bearer {token}
  • 响应:
    {
      "code": 0,
      "message": "success",
      "data": {
        "id": 1,
        "openid": "openid",
        "nickname": "用户昵称",
        "avatar": "头像URL",
        "gender": "male",
        "birthday": "1990-01-01",
        "phone": "13800138000",
        "email": "user@example.com"
      }
    }
    

更新用户信息

  • URL: PUT /api/v1/users/profile
  • 请求头: Authorization: Bearer {token}
  • 请求参数:
    {
      "nickname": "新昵称",
      "gender": "female",
      "birthday": "1995-01-01",
      "phone": "13900139000",
      "email": "new@example.com"
    }
    
  • 响应:
    {
      "code": 0,
      "message": "success",
      "data": {}
    }
    

2.2 旅行服务API

创建旅行计划

  • URL: POST /api/v1/travels/plans
  • 请求头: Authorization: Bearer {token}
  • 请求参数:
    {
      "destination": "目的地",
      "start_date": "2023-10-01",
      "end_date": "2023-10-07",
      "budget": 5000.00,
      "interests": "徒步,摄影",
      "visibility": "public"
    }
    
  • 响应:
    {
      "code": 0,
      "message": "success",
      "data": {
        "id": 1,
        "user_id": 1,
        "destination": "目的地",
        "start_date": "2023-10-01",
        "end_date": "2023-10-07",
        "budget": 5000.00,
        "interests": "徒步,摄影",
        "visibility": "public",
        "created_at": "2023-09-01T12:00:00Z"
      }
    }
    

获取旅行计划列表

  • URL: GET /api/v1/travels/plans
  • 请求头: Authorization: Bearer {token}
  • 查询参数: page=1&size=10&visibility=public
  • 响应:
    {
      "code": 0,
      "message": "success",
      "data": {
        "list": [
          {
            "id": 1,
            "user_id": 1,
            "destination": "目的地",
            "start_date": "2023-10-01",
            "end_date": "2023-10-07",
            "budget": 5000.00,
            "interests": "徒步,摄影",
            "visibility": "public",
            "created_at": "2023-09-01T12:00:00Z"
          }
        ],
        "pagination": {
          "page": 1,
          "size": 10,
          "total": 1
        }
      }
    }
    

匹配旅行伙伴

  • URL: GET /api/v1/travels/matches
  • 请求头: Authorization: Bearer {token}
  • 查询参数: plan_id=1&page=1&size=10
  • 响应:
    {
      "code": 0,
      "message": "success",
      "data": {
        "list": [
          {
            "id": 2,
            "user_id": 2,
            "destination": "目的地",
            "start_date": "2023-10-02",
            "end_date": "2023-10-08",
            "budget": 4500.00,
            "interests": "徒步,美食",
            "match_score": 0.85
          }
        ],
        "pagination": {
          "page": 1,
          "size": 10,
          "total": 1
        }
      }
    }
    

2.3 动物认领服务API

获取可认领动物列表

  • URL: GET /api/v1/animals
  • 请求头: Authorization: Bearer {token}
  • 查询参数: page=1&size=10&species=羊驼
  • 响应:
    {
      "code": 0,
      "message": "success",
      "data": {
        "list": [
          {
            "id": 1,
            "merchant_id": 1,
            "name": "小羊驼",
            "species": "羊驼",
            "breed": "苏利羊驼",
            "birth_date": "2020-01-01",
            "personality": "温顺可爱",
            "farm_location": "XX农场",
            "price": 1000.00,
            "status": "available"
          }
        ],
        "pagination": {
          "page": 1,
          "size": 10,
          "total": 1
        }
      }
    }
    

认领动物

  • URL: POST /api/v1/animals/{id}/claim
  • 请求头: Authorization: Bearer {token}
  • 请求参数:
    {
      "price_paid": 1000.00
    }
    
  • 响应:
    {
      "code": 0,
      "message": "success",
      "data": {
        "id": 1,
        "user_id": 1,
        "animal_id": 1,
        "price_paid": 1000.00,
        "agreement_url": "https://example.com/agreement.pdf",
        "status": "active",
        "claimed_at": "2023-09-01T12:00:00Z"
      }
    }
    

获取认领记录

  • URL: GET /api/v1/animals/claims
  • 请求头: Authorization: Bearer {token}
  • 查询参数: page=1&size=10&status=active
  • 响应:
    {
      "code": 0,
      "message": "success",
      "data": {
        "list": [
          {
            "id": 1,
            "user_id": 1,
            "animal_id": 1,
            "animal_name": "小羊驼",
            "price_paid": 1000.00,
            "status": "active",
            "claimed_at": "2023-09-01T12:00:00Z"
          }
        ],
        "pagination": {
          "page": 1,
          "size": 10,
          "total": 1
        }
      }
    }
    

2.4 商家服务API

商家注册

  • URL: POST /api/v1/merchants/register
  • 请求头: Authorization: Bearer {token}
  • 请求参数:
    {
      "merchant_type": "farm_owner",
      "business_name": "XX农场",
      "business_license": "https://example.com/license.jpg",
      "contact_person": "张三",
      "contact_phone": "13800138000",
      "address": "北京市朝阳区XX路XX号",
      "description": "专业养殖羊驼的农场"
    }
    
  • 响应:
    {
      "code": 0,
      "message": "success",
      "data": {
        "id": 1,
        "user_id": 1,
        "merchant_type": "farm_owner",
        "business_name": "XX农场",
        "business_license": "https://example.com/license.jpg",
        "contact_person": "张三",
        "contact_phone": "13800138000",
        "address": "北京市朝阳区XX路XX号",
        "description": "专业养殖羊驼的农场",
        "status": "pending",
        "created_at": "2023-09-01T12:00:00Z"
      }
    }
    

发布商品/服务

  • URL: POST /api/v1/merchants/products
  • 请求头: Authorization: Bearer {token}
  • 请求参数:
    {
      "name": "羊驼认领体验",
      "description": "提供一个月的羊驼认领体验服务",
      "price": 1000.00,
      "image_url": "https://example.com/product.jpg",
      "category": "animal_claim",
      "status": "available"
    }
    
  • 响应:
    {
      "code": 0,
      "message": "success",
      "data": {
        "id": 1,
        "merchant_id": 1,
        "name": "羊驼认领体验",
        "description": "提供一个月的羊驼认领体验服务",
        "price": 1000.00,
        "image_url": "https://example.com/product.jpg",
        "category": "animal_claim",
        "status": "available",
        "created_at": "2023-09-01T12:00:00Z"
      }
    }
    

获取商家订单

  • URL: GET /api/v1/merchants/orders
  • 请求头: Authorization: Bearer {token}
  • 查询参数: page=1&size=10&status=paid
  • 响应:
    {
      "code": 0,
      "message": "success",
      "data": {
        "list": [
          {
            "id": 1,
            "user_id": 2,
            "order_number": "ORD202309010001",
            "total_amount": 1000.00,
            "status": "paid",
            "ordered_at": "2023-09-01T12:00:00Z"
          }
        ],
        "pagination": {
          "page": 1,
          "size": 10,
          "total": 1
        }
      }
    }
    

2.5 官网系统API

提交商家入驻申请

  • URL: POST /api/v1/website/merchant/apply
  • 请求参数:
    {
      "business_name": "XX农场",
      "contact_person": "张三",
      "contact_phone": "13800138000",
      "email": "zhangsan@example.com",
      "description": "专业养殖羊驼的农场"
    }
    
  • 响应:
    {
      "code": 0,
      "message": "success",
      "data": {
        "id": 1,
        "business_name": "XX农场",
        "contact_person": "张三",
        "contact_phone": "13800138000",
        "email": "zhangsan@example.com",
        "description": "专业养殖羊驼的农场",
        "status": "pending",
        "created_at": "2023-09-01T12:00:00Z"
      }
    }
    

获取成功案例列表

  • URL: GET /api/v1/website/cases
  • 查询参数: page=1&size=10
  • 响应:
    {
      "code": 0,
      "message": "success",
      "data": {
        "list": [
          {
            "id": 1,
            "title": "XX农场成功入驻案例",
            "description": "XX农场通过平台实现了数字化转型",
            "image_url": "https://example.com/case1.jpg",
            "created_at": "2023-09-01T12:00:00Z"
          }
        ],
        "pagination": {
          "page": 1,
          "size": 10,
          "total": 1
        }
      }
    }
    
    "image_url": "https://example.com/product.jpg",
    "category": "animal_claim",
    "status": "available",
    "created_at": "2023-09-01T12:00:00Z"
    
    } }
    
    

获取商家订单

  • URL: GET /api/v1/merchants/orders
  • 请求头: Authorization: Bearer {token}
  • 查询参数: page=1&size=10&status=paid
  • 响应:
    {
      "code": 0,
      "message": "success",
      "data": {
        "list": [
          {
            "id": 1,
            "user_id": 2,
            "order_number": "ORD202309010001",
            "total_amount": 1000.00,
            "status": "paid",
            "ordered_at": "2023-09-01T12:00:00Z"
          }
        ],
        "pagination": {
          "page": 1,
          "size": 10,
          "total": 1
        }
      }
    }
    

3. 核心业务逻辑设计

3.1 旅行结伴流程

sequenceDiagram
    participant U as 用户
    participant TP as 旅行计划服务
    participant TM as 旅行匹配服务
    participant N as 通知服务
    
    U->>TP: 创建旅行计划
    TP->>TP: 保存计划
    TP-->>U: 返回计划详情
    
    U->>TM: 请求匹配旅行伙伴
    TM->>TM: 根据条件匹配
    TM-->>U: 返回匹配结果
    
    U->>U: 选择合适的伙伴
    U->>N: 发送结伴邀请
    N->>N: 发送通知给被邀请用户
    
    Note over U,N: 被邀请用户接受邀请后,
    Note over U,N: 系统创建结伴关系

3.2 动物认领流程

sequenceDiagram
    participant U as 用户
    participant A as 动物服务
    participant M as 商家服务
    participant P as 支付服务
    participant N as 通知服务
    
    U->>A: 浏览可认领动物
    A-->>U: 返回动物列表
    
    U->>A: 选择动物并认领
    A->>P: 创建支付订单
    P-->>U: 返回支付信息
    
    U->>P: 完成支付
    P->>P: 验证支付结果
    P->>A: 通知支付成功
    
    A->>A: 更新动物状态为已认领
    A->>M: 通知商家有新认领
    A->>N: 发送认领成功通知给用户
    
    M->>M: 更新商家统计信息
    N->>N: 发送通知

3.3 商家服务流程

sequenceDiagram
    participant U as 用户
    participant M as 商家服务
    participant P as 商品服务
    participant O as 订单服务
    participant Pay as 支付服务
    participant N as 通知服务
    
    U->>M: 申请成为商家
    M->>M: 审核商家资质
    M-->>U: 返回审核结果
    
    alt 审核通过
        U->>P: 发布商品/服务
        P->>P: 保存商品信息
        P-->>U: 返回商品详情
    end
    
    U->>P: 浏览商品
    P-->>U: 返回商品列表
    
    U->>O: 下单购买
    O->>Pay: 创建支付订单
    Pay-->>U: 返回支付信息
    
    U->>Pay: 完成支付
    Pay->>Pay: 验证支付结果
    Pay->>O: 通知支付成功
    
    O->>O: 更新订单状态
    O->>M: 通知商家有新订单
    O->>N: 发送购买成功通知给用户
    
    M->>M: 处理订单
    N->>N: 发送通知