jiebanke/docs/database-design.md

# 结伴客系统数据库设计文档

## 1. 数据库概览

### 1.1 数据库配置

#### 测试环境
- **主机**: 192.168.0.240
- **端口**: 3306
- **用户名**: root
- **密码**: aiot$Aiot123
- **数据库**: jiebandata

#### 生产环境
- **主机**: 129.211.213.226
- **端口**: 9527
- **用户名**: root
- **密码**: aiotAiot123!
- **数据库**: jiebandata

### 1.2 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
    
    ADMINS ||--o{ ADMIN_LOGS : creates
    
    USERS {
        int id PK
        string openid
        string nickname
        string avatar
        string gender
        date birthday
        string phone
        string email
        datetime created_at
        datetime updated_at
    }
    
    ADMINS {
        int id PK
        string username
        string password
        string email
        string nickname
        string avatar
        enum role
        tinyint status
        timestamp last_login
        timestamp created_at
        timestamp 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
    }
    
    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
    }
    
    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
    }
    
    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
    }
```

## 2. 核心表结构设计

### 2.1 用户表 (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 | 更新时间 |

### 2.2 管理员表 (admins)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 管理员ID |
| username | VARCHAR(50) | UNIQUE, NOT NULL | 管理员用户名 |
| password | VARCHAR(255) | NOT NULL | 密码(bcrypt加密) |
| email | VARCHAR(100) | UNIQUE | 邮箱地址 |
| nickname | VARCHAR(100) |  | 昵称 |
| avatar | VARCHAR(255) |  | 头像URL |
| role | ENUM('super_admin', 'admin', 'operator') | NOT NULL | 角色 |
| status | TINYINT | DEFAULT 1 | 状态(1:启用, 0:禁用) |
| last_login | TIMESTAMP |  | 最后登录时间 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |

**注意**: 管理员默认密码为 'admin123'，使用 bcrypt 加密存储

### 2.3 商家表 (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 | 更新时间 |

### 2.4 订单表 (orders)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 订单ID |
| user_id | INT | FOREIGN KEY, NOT NULL | 用户ID |
| merchant_id | INT | FOREIGN KEY, NOT NULL | 商家ID |
| order_number | VARCHAR(50) | UNIQUE, NOT NULL | 订单编号 |
| total_amount | DECIMAL(10,2) | NOT NULL | 订单总金额 |
| status | ENUM('pending', 'paid', 'shipped', 'completed', 'cancelled') | NOT NULL | 订单状态 |
| delivery_address | VARCHAR(255) |  | 配送地址 |
| ordered_at | DATETIME | NOT NULL | 下单时间 |
| completed_at | DATETIME |  | 完成时间 |

### 2.5 商品表 (products)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 商品ID |
| merchant_id | INT | FOREIGN KEY, NOT NULL | 商家ID |
| name | VARCHAR(100) | NOT NULL | 商品名称 |
| description | TEXT |  | 商品描述 |
| price | DECIMAL(10,2) | NOT NULL | 商品价格 |
| image_url | VARCHAR(255) |  | 商品图片URL |
| category | VARCHAR(50) | NOT NULL | 商品分类 |
| status | ENUM('active', 'inactive', 'deleted') | NOT NULL | 商品状态 |
| created_at | DATETIME | NOT NULL | 创建时间 |
| updated_at | DATETIME | NOT NULL | 更新时间 |

## 3. 后台管理系统API接口规范

### 3.1 接口统一格式

#### 请求格式
- **Base URL**: http://localhost:3100/api/v1
- **认证**: Bearer Token (需要认证的接口)
- **Content-Type**: application/json

#### 响应格式
```json
{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {
    // 具体数据
  },
  "pagination": {
    // 分页信息(列表接口)
  }
}
```

### 3.2 通用状态码
| 状态码 | 描述 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

### 3.3 管理员接口

#### 3.3.1 管理员登录
- **Endpoint**: POST /admin/auth/login
- **认证要求**: 无
- **请求体**:
```json
{
  "username": "admin",
  "password": "password123"
}
```

#### 3.3.2 获取管理员信息
- **Endpoint**: GET /admin/auth/profile
- **认证要求**: Bearer Token

#### 3.3.3 更新管理员信息
- **Endpoint**: PUT /admin/auth/profile
- **认证要求**: Bearer Token

#### 3.3.4 修改密码
- **Endpoint**: PUT /admin/auth/password
- **认证要求**: Bearer Token

### 3.4 用户管理接口

#### 3.4.1 获取用户列表
- **Endpoint**: GET /admin/users
- **认证要求**: Bearer Token
- **查询参数**: page, limit, username, user_type, status

#### 3.4.2 获取用户详情
- **Endpoint**: GET /admin/users/{id}
- **认证要求**: Bearer Token

#### 3.4.3 更新用户状态
- **Endpoint**: PUT /admin/users/{id}/status
- **认证要求**: Bearer Token

### 3.5 商家管理接口

#### 3.5.1 获取商家列表
- **Endpoint**: GET /admin/merchants
- **认证要求**: Bearer Token
- **查询参数**: page, limit, business_name, status

#### 3.5.2 审核商家申请
- **Endpoint**: PUT /admin/merchants/{id}/approve
- **认证要求**: Bearer Token

#### 3.5.3 拒绝商家申请
- **Endpoint**: PUT /admin/merchants/{id}/reject
- **认证要求**: Bearer Token

### 3.6 订单管理接口

#### 3.6.1 获取订单列表
- **Endpoint**: GET /admin/orders
- **认证要求**: Bearer Token
- **查询参数**: page, limit, order_no, status

#### 3.6.2 更新订单状态
- **Endpoint**: PUT /admin/orders/{id}/status
- **认证要求**: Bearer Token

## 4. 数据库初始化脚本

### 4.1 创建管理员用户
```sql
INSERT INTO admins (username, password, email, nickname, role, status) 
VALUES 
('superadmin', '$2b$10$rOzJq...', 'superadmin@jiebanke.com', '超级管理员', 'super_admin', 1),
('admin', '$2b$10$rOzJq...', 'admin@jiebanke.com', '管理员', 'admin', 1),
('operator', '$2b$10$rOzJq...', 'operator@jiebanke.com', '操作员', 'operator', 1);
```

### 4.2 创建测试用户
```sql
INSERT INTO users (openid, nickname, gender, phone, email) 
VALUES 
('wx1234567890', '测试用户1', 'male', '13800138000', 'test1@example.com'),
('wx0987654321', '测试用户2', 'female', '13800138001', 'test2@example.com');
```

### 4.3 创建测试商家
```sql
INSERT INTO merchants (user_id, merchant_type, business_name, contact_person, contact_phone, status) 
VALUES 
(1, 'flower_shop', '鲜花小店', '张老板', '13800138002', 'approved'),
(2, 'farm_owner', '快乐农场', '李农场主', '13800138003', 'approved');
```

## 5. 数据库维护

### 5.1 备份策略
- 每日全量备份
- 每小时增量备份
- 备份保留30天

### 5.2 性能优化
- 为常用查询字段创建索引
- 定期分析慢查询日志
- 数据库连接池配置优化

### 5.3 安全措施
- 定期更换数据库密码
- 限制数据库访问IP
- 启用SSL加密连接