# 结伴客系统详细设计文档 ## 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图 ```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 | 更新时间 | ### 管理员相关表 #### 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 | 创建时间 | ### 权限分配关系 ```mermaid 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` - **请求参数**: ```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: 发送通知 ```