187 lines
3.9 KiB
Plaintext
187 lines
3.9 KiB
Plaintext
|
生活服务模块接口文档
|
|||
|
|
================
|
|||
|
|
|
|||
|
|
基础信息
|
|||
|
|
-------
|
|||
|
|
- 基础路径: /api/v1/services
|
|||
|
|
- 请求方式: REST
|
|||
|
|
- 数据格式: JSON
|
|||
|
|
- 认证方式: Bearer Token
|
|||
|
|
|
|||
|
|
数据结构
|
|||
|
|
-------
|
|||
|
|
|
|||
|
|
Service 服务对象:
|
|||
|
|
{
|
|||
|
|
id: number, // 服务ID
|
|||
|
|
name: string, // 服务名称
|
|||
|
|
description: string, // 服务描述
|
|||
|
|
icon: string, // 图标
|
|||
|
|
color: string, // 主题色
|
|||
|
|
types?: Array<{ // 服务类型
|
|||
|
|
label: string, // 类型名称
|
|||
|
|
value: string // 类型值
|
|||
|
|
}>
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
ServiceOrder 服务订单:
|
|||
|
|
{
|
|||
|
|
id: number, // 订单ID
|
|||
|
|
serviceId: number, // 服务ID
|
|||
|
|
type: string, // 服务类型
|
|||
|
|
date: string, // 预约日期
|
|||
|
|
time: string, // 预约时间
|
|||
|
|
address: string, // 服务地址
|
|||
|
|
status: string, // 订单状态
|
|||
|
|
notes?: string, // 备注说明
|
|||
|
|
price: number, // 服务价格
|
|||
|
|
worker?: { // 服务人员信息
|
|||
|
|
id: number,
|
|||
|
|
name: string,
|
|||
|
|
phone: string,
|
|||
|
|
avatar: string,
|
|||
|
|
rating: number
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
GroupBuyItem 团购商品:
|
|||
|
|
{
|
|||
|
|
id: number, // 商品ID
|
|||
|
|
title: string, // 商品标题
|
|||
|
|
description: string, // 商品描述
|
|||
|
|
image: string, // 商品图片
|
|||
|
|
price: number, // 团购价
|
|||
|
|
originalPrice: number, // 原价
|
|||
|
|
participants: number, // 参与人数
|
|||
|
|
target: number, // 目标人数
|
|||
|
|
endTime: string, // 结束时间
|
|||
|
|
status: string // 状态
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
Bill 账单对象:
|
|||
|
|
{
|
|||
|
|
id: number, // 账单ID
|
|||
|
|
title: string, // 账单标题
|
|||
|
|
amount: number, // 金额
|
|||
|
|
dueDate: string, // 截止日期
|
|||
|
|
type: string, // 账单类型
|
|||
|
|
status: string, // 支付状态
|
|||
|
|
icon: string, // 图标
|
|||
|
|
color: string // 主题色
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
API 接口
|
|||
|
|
-------
|
|||
|
|
|
|||
|
|
1. 获取服务列表
|
|||
|
|
GET /api/v1/services
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": [
|
|||
|
|
{
|
|||
|
|
"id": 1,
|
|||
|
|
"name": "家政服务",
|
|||
|
|
"description": "专业保洁、护理等服务",
|
|||
|
|
"icon": "House",
|
|||
|
|
"color": "#409EFF",
|
|||
|
|
"types": [
|
|||
|
|
{
|
|||
|
|
"label": "日常保洁",
|
|||
|
|
"value": "cleaning"
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
2. 创建服务订单
|
|||
|
|
POST /api/v1/services/orders
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
{
|
|||
|
|
"serviceId": 1,
|
|||
|
|
"type": "cleaning",
|
|||
|
|
"date": "2024-03-21",
|
|||
|
|
"time": "09:00",
|
|||
|
|
"address": "幸福小区1号楼2单元301",
|
|||
|
|
"notes": "需要带清洁工具"
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
3. 获取订单列表
|
|||
|
|
GET /api/v1/services/orders
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|||
|
|
| status | string | 否 | 订单状态 |
|
|||
|
|
|
|||
|
|
4. 取消订单
|
|||
|
|
POST /api/v1/services/orders/{id}/cancel
|
|||
|
|
|
|||
|
|
5. 获取团购列表
|
|||
|
|
GET /api/v1/services/group-buy
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|||
|
|
| status | string | 否 | 团购状态 |
|
|||
|
|
|
|||
|
|
6. 参与团购
|
|||
|
|
POST /api/v1/services/group-buy/{id}/join
|
|||
|
|
|
|||
|
|
7. 获取账单列表
|
|||
|
|
GET /api/v1/services/bills
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|||
|
|
| status | string | 否 | 支付状态 |
|
|||
|
|
|
|||
|
|
8. 支付账单
|
|||
|
|
POST /api/v1/services/bills/{id}/pay
|
|||
|
|
|
|||
|
|
9. 批量支付账单
|
|||
|
|
POST /api/v1/services/bills/batch-pay
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
{
|
|||
|
|
"ids": [1, 2, 3]
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
错误码说明
|
|||
|
|
--------
|
|||
|
|
| 错误码 | 说明 |
|
|||
|
|
| 200 | 成功 |
|
|||
|
|
| 400 | 请求参数错误 |
|
|||
|
|
| 401 | 未授权 |
|
|||
|
|
| 403 | 禁止访问 |
|
|||
|
|
| 404 | 资源不存在 |
|
|||
|
|
| 500 | 服务器内部错误 |
|
|||
|
|
|
|||
|
|
注意事项
|
|||
|
|
-------
|
|||
|
|
1. 订单状态说明：
|
|||
|
|
- pending: 待确认
|
|||
|
|
- confirmed: 已确认
|
|||
|
|
- processing: 进行中
|
|||
|
|
- completed: 已完成
|
|||
|
|
- cancelled: 已取消
|
|||
|
|
|
|||
|
|
2. 团购状态说明：
|
|||
|
|
- ongoing: 进行中
|
|||
|
|
- upcoming: 即将开始
|
|||
|
|
- ended: 已结束
|
|||
|
|
|
|||
|
|
3. 账单状态说明：
|
|||
|
|
- unpaid: 待支付
|
|||
|
|
- paid: 已支付
|
|||
|
|
|
|||
|
|
4. 服务时间限制：
|
|||
|
|
- 提前24小时预约
|
|||
|
|
- 服务时间段：8:00-18:00
|
|||
|
|
- 节假日服务需加收50%费用
|
|||
|
|
|
|||
|
|
5. 支付安全：
|
|||
|
|
- 支持多种支付方式
|
|||
|
|
- 大额支付需要短信验证
|
|||
|
|
- 支付前进行风险评估
|