jiebanke/docs/detailed_design.md

# 结伴客系统详细设计文档

## 1. 数据库设计

### 1.1 ER图

```mermaid
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 | 更新时间 |

#### 商家表 (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 |  | 结束时间 |

## 2. API设计

### 2.1 用户服务API

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

#### 获取用户信息
- **URL**: `GET /api/v1/users/profile`
- **请求头**: `Authorization: Bearer {token}`
- **响应**:
  ```json
  {
    "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}`
- **请求参数**:
  ```json
  {
    "nickname": "新昵称",
    "gender": "female",
    "birthday": "1995-01-01",
    "phone": "13900139000",
    "email": "new@example.com"
  }
  ```
- **响应**:
  ```json
  {
    "code": 0,
    "message": "success",
    "data": {}
  }
  ```

### 2.2 旅行服务API

#### 创建旅行计划
- **URL**: `POST /api/v1/travels/plans`
- **请求头**: `Authorization: Bearer {token}`
- **请求参数**:
  ```json
  {
    "destination": "目的地",
    "start_date": "2023-10-01",
    "end_date": "2023-10-07",
    "budget": 5000.00,
    "interests": "徒步,摄影",
    "visibility": "public"
  }
  ```
- **响应**:
  ```json
  {
    "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`
- **响应**:
  ```json
  {
    "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`
- **响应**:
  ```json
  {
    "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=羊驼`
- **响应**:
  ```json
  {
    "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}`
- **请求参数**:
  ```json
  {
    "price_paid": 1000.00
  }
  ```
- **响应**:
  ```json
  {
    "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`
- **响应**:
  ```json
  {
    "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}`
- **请求参数**:
  ```json
  {
    "merchant_type": "farm_owner",
    "business_name": "XX农场",
    "business_license": "https://example.com/license.jpg",
    "contact_person": "张三",
    "contact_phone": "13800138000",
    "address": "北京市朝阳区XX路XX号",
    "description": "专业养殖羊驼的农场"
  }
  ```
- **响应**:
  ```json
  {
    "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}`
- **请求参数**:
  ```json
  {
    "name": "羊驼认领体验",
    "description": "提供一个月的羊驼认领体验服务",
    "price": 1000.00,
    "image_url": "https://example.com/product.jpg",
    "category": "animal_claim",
    "status": "available"
  }
  ```
- **响应**:
  ```json
  {
    "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`
- **响应**:
  ```json
  {
    "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`
- **请求参数**:
  ```json
  {
    "business_name": "XX农场",
    "contact_person": "张三",
    "contact_phone": "13800138000",
    "email": "zhangsan@example.com",
    "description": "专业养殖羊驼的农场"
  }
  ```
- **响应**:
  ```json
  {
    "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`
- **响应**:
  ```json
  {
    "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`
- **响应**:
  ```json
  {
    "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 旅行结伴流程

```mermaid
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 动物认领流程

```mermaid
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 商家服务流程

```mermaid
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: 发送通知
```