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. 支付安全：
|
||
- 支持多种支付方式
|
||
- 大额支付需要短信验证
|
||
- 支付前进行风险评估 |