# 结伴客系统详细设计文档 ## 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: 发送通知 ```