1 用户管理
1.1 用户注册与会员开通接口文档
此接口用于处理新用户的注册,并自动创建对应的会员记录。它会检查并防止基于 openid 的重复用户注册。
1. 接口名称
registerUserAndCreateMembership
(或根据平台约定,例如 用户注册并开通会员
)
2. 请求参数 (params
)
参数 | 类型 | 必填 | 描述 | 示例 |
---|---|---|---|---|
openid | string | 是 | 用户在第三方平台的唯一标识符(例如,微信 openid)。 | "oPENiD1234567890" |
phone | string | 否 | 用户的手机号码。 | "13800138000" |
nickname | string | 否 | 用户的昵称。 | "张三" |
avtarURL | string | 否 | 用户头像的URL。 | "https://example.com/avatar.jpg" |
3. 响应参数
参数 | 类型 | 描述 |
---|---|---|
code | number | 操作成功时为 0 (SUCCESS )。其他 ErrorCode 值表示错误。 |
message | string | 描述信息,尤其在错误时提供具体错误原因。 |
data | object | 注册成功时包含 userId 和 memberId 。 |
data.userId | string | 新创建的用户记录的唯一ID。 |
data.memberId | string | 新创建的会员记录的唯一ID。 |
4. 错误码
此接口使用以下自定义错误码:
0
:SUCCESS
- 操作成功完成。1001
:PARAM_ERROR
- 缺少或参数无效。1003
:SYSTEM_ERROR
- 服务器发生意外错误。1004
:USER_EXISTS
- 已存在使用该 openid 的用户。
5. 逻辑伪代码
函数 用户注册并开通会员(参数, 上下文):
// 提取参数
定义 openid 为 参数.openid
定义 phone 为 参数.phone
定义 nickname 为 参数.nickname
定义 avtarURL 为 参数.avtarURL
// 1. 验证必要参数
如果 openid 为空 则
返回 结果: 错误码.参数错误, 消息: '参数错误,openid 缺失'
尝试执行:
// 2. 检查用户是否已存在
查询 用户数据模型 "xx_users"
使用方法 "wedaGetRecordsV2"
条件: openid 等于 openid
返回总数
每页大小: 1
当前页码: 1
将结果保存为 现有用户查询结果
如果 现有用户查询结果.总数 大于 0 则
返回 结果: 错误码.用户已存在, 消息: '用户已存在,请直接登录'
// 3. 创建新用户记录
创建 用户数据模型 "xx_users"
使用方法 "wedaCreateV2"
数据:
openid: openid
phone: phone
nickname: nickname
avtarURL: avtarURL
status: "1" (默认状态为正常)
将结果保存为 新用户创建结果
定义 userId 为 新用户创建结果.id
// 4. 创建新会员记录并关联用户
创建 会员数据模型 "xx_members"
使用方法 "wedaCreateV2"
数据:
userId: { _id: userId } (关联刚刚创建的用户ID)
level: "1" (默认会员等级)
status: "1" (默认状态为正常)
points: 0 (初始积分)
balance: 0 (初始余额)
将结果保存为 会员创建结果
定义 memberId 为 会员创建结果.id
// 5. 注册成功,返回用户ID和会员ID
返回 结果: 错误码.成功, 数据: 用户ID: userId, 会员ID: memberId
捕获 (错误):
记录日志 "用户注册错误:", 错误
返回 结果: 错误码.系统错误, 消息: "系统错误: " + 错误.信息
1.2 用户登录接口文档
此接口用于用户通过 openid
进行登录,并获取用户的基本信息和会员信息。
1. 接口名称
userLoginWithOpenId
(或根据平台约定,例如 用户登录
)
2. 请求参数 (params
)
参数 | 类型 | 必填 | 描述 | 示例 |
---|---|---|---|---|
openid | string | 是 | 用户在第三方平台的唯一标识符(例如,微信 openid)。 | "oPENiD1234567890" |
3. 响应参数
参数 | 类型 | 描述 |
---|---|---|
code | number | 操作成功时为 0 (SUCCESS )。其他 ErrorCode 值表示错误。 |
message | string | 描述信息,尤其在错误时提供具体错误原因。 |
userInfo | object | 登录成功时返回的用户基本信息。 |
memberInfo | object | 登录成功时返回的用户会员信息。 |
4. 错误码
此接口使用以下自定义错误码:
0
:SUCCESS
- 操作成功完成。1001
:PARAM_ERROR
- 缺少或参数无效。1002
:NOT_FOUND
- 用户未找到(未注册)。1003
:SYSTEM_ERROR
- 服务器发生意外错误。
5. 逻辑伪代码
函数 用户登录(参数, 上下文):
// 提取参数
定义 openid 为 参数.openid
// 1. 验证必要参数
如果 openid 为空 则
返回 结果: 错误码.参数错误, 消息: "参数错误,openid 缺失"
尝试执行:
// 2. 根据 openid 查询用户信息
查询 用户数据模型 "xx_users"
使用方法 "wedaGetRecordsV2"
条件: openid 等于 openid
返回所有主字段
返回总数
每页大小: 1
当前页码: 1
将结果保存为 用户查询结果
如果 用户查询结果.总数 等于 0 则
返回 结果: 错误码.未找到, 消息: "用户未注册,请先注册再登录"
定义 user 为 用户查询结果.记录列表 的第一个元素
// 3. 根据用户ID查询会员信息
查询 会员数据模型 "xx_members"
使用方法 "wedaGetRecordsV2"
条件: userId 等于 user._id
返回所有主字段
返回总数
每页大小: 1
当前页码: 1
将结果保存为 会员查询结果
定义 memberInfo 为 会员查询结果.记录列表 的第一个元素
// 4. 登录成功,返回用户信息和会员信息
返回 结果: 错误码.成功, 消息: "用户登录成功", 用户信息: user, 会员信息: memberInfo
捕获 (错误):
记录日志 "用户登录错误:", 错误
返回 结果: 错误码.系统错误, 消息: "系统异常,请稍后再试"
1.3 服务收藏接口文档
此接口用于用户收藏特定服务。它会检查服务是否已被收藏,避免重复收藏。
1. 接口名称
addServiceToFavorites
(或根据平台约定,例如 添加服务收藏
)
2. 请求参数 (params
)
参数 | 类型 | 必填 | 描述 | 示例 |
---|---|---|---|---|
openid | string | 是 | 用户在第三方平台的唯一标识符(例如,微信 openid)。 | "oPENiD1234567890" |
serviceId | string | 是 | 要收藏的服务的唯一ID。 | "srv12345ABC" |
3. 响应参数
参数 | 类型 | 描述 |
---|---|---|
code | number | 操作成功时为 0 (SUCCESS )。其他 ErrorCode 值表示错误。 |
message | string | 描述信息,尤其在错误时提供具体错误原因。 |
data | object | 收藏成功时包含 favoriteId 。 |
data.favoriteId | string | 新创建的收藏记录的唯一ID。 |
4. 错误码
此接口使用以下自定义错误码:
0
:SUCCESS
- 操作成功完成。1001
:PARAM_ERROR
- 缺少或参数无效。1003
:SYSTEM_ERROR
- 服务器发生意外错误。1006
:ALREADY_FAVORITED
- 该服务已被用户收藏。
5. 逻辑伪代码
函数 添加服务收藏(参数, 上下文):
// 提取参数
定义 openid 为 参数.openid
定义 serviceId 为 参数.serviceId
// 1. 参数校验
如果 openid 为空 或 serviceId 为空 则
返回 结果: 错误码.参数错误, 消息: '参数错误,openid 或 serviceId 缺失'
尝试执行:
// 2. 检查是否已收藏
查询 收藏数据模型 "favorites"
使用方法 "wedaGetRecordsV2"
条件: openid 等于 openid 并且 serviceId 等于 serviceId
返回所有主字段
返回总数
每页大小: 1
当前页码: 1
将结果保存为 现有收藏查询结果
如果 现有收藏查询结果.总数 大于 0 则
返回 结果: 错误码.已收藏, 消息: '该服务已收藏'
// 3. 创建新收藏记录
创建 收藏数据模型 "favorites"
使用方法 "wedaCreateV2"
数据:
openid: openid
serviceId: {_id: serviceId} (关联服务ID)
created_at: 当前时间戳 (记录收藏时间)
将结果保存为 新收藏创建结果
定义 favoriteId 为 新收藏创建结果.id
// 4. 返回成功结果
返回 结果: 错误码.成功, 数据: 收藏ID: favoriteId, 消息: '收藏成功'
捕获 (错误):
记录日志 "添加收藏错误:", 错误
返回 结果: 错误码.系统错误, 消息: "系统错误: " + 错误.信息
1.4 工人点赞接口文档
此接口用于用户对特定工人进行点赞操作。它会检查用户是否已对该工人点赞,避免重复点赞,并在成功点赞后更新工人的点赞总数。
1. 接口名称
addWorkerLike
(或根据平台约定,例如 工人点赞
)
2. 请求参数 (params
)
参数 | 类型 | 必填 | 描述 | 示例 |
---|---|---|---|---|
openid | string | 是 | 用户在第三方平台的唯一标识符(例如,微信 openid)。 | "oPENiD1234567890" |
workerId | string | 是 | 被点赞的工人的唯一ID。 | "workerABC789" |
userId | string | 是 | 点赞用户的唯一ID(与 openid 关联的用户ID)。 | "userXYZ456" |
3. 响应参数
参数 | 类型 | 描述 |
---|---|---|
code | number | 操作成功时为 0 (SUCCESS )。其他 ErrorCode 值表示错误。 |
message | string | 描述信息,尤其在错误时提供具体错误原因。 |
data | object | 点赞成功时包含 likeId 。 |
data.likeId | string | 新创建的点赞记录的唯一ID。 |
4. 错误码
此接口使用以下自定义错误码:
0
:SUCCESS
- 操作成功完成。1001
:PARAM_ERROR
- 缺少或参数无效。1003
:SYSTEM_ERROR
- 服务器发生意外错误。1007
:ALREADY_LIKED
- 该工人已被用户点赞。
5. 逻辑伪代码
函数 工人点赞(参数, 上下文):
// 提取参数
定义 openid 为 参数.openid
定义 workerId 为 参数.workerId
定义 userId 为 参数.userId
// 1. 参数校验
如果 openid 为空 或 workerId 为空 或 userId 为空 则
返回 结果: 错误码.参数错误, 消息: '参数错误,openid 或 workerId 或 userId 缺失'
尝试执行:
// 2. 检查是否已点赞
查询 点赞记录数据模型 "like_record"
使用方法 "wedaGetRecordsV2"
条件: openid 等于 openid 并且 worker_id 等于 workerId
返回所有主字段
返回总数
每页大小: 1
当前页码: 1
将结果保存为 现有like结果
如果 现有like结果.总数 大于 0 则
返回 结果: 错误码.已点赞, 消息: '该工人已点赞'
// 3. 创建新点赞记录
创建 点赞记录数据模型 "like_record"
使用方法 "wedaCreateV2"
数据:
openid: openid
worker_id: {_id: workerId} (关联工人ID)
liker_id: {_id: userId} (关联点赞用户ID)
将结果保存为 新点赞结果
定义 likeId 为 新点赞结果.id
// 4. 获取该工人的所有点赞数量
查询 点赞记录数据模型 "like_record"
使用方法 "wedaGetRecordsV2"
条件: worker_id 关联 _id 等于 workerId
返回所有主字段
返回总数
将结果保存为 点赞列表结果
定义 likeCount 为 点赞列表结果.总数
// 5. 更新工人表的点赞次数
更新 工人数据模型 "worker"
使用方法 "wedaUpdateV2"
条件: _id 等于 workerId
数据:
like_count: likeCount
将结果保存为 更新工人结果
// 6. 返回成功结果
返回 结果: 错误码.成功, 数据: 点赞ID: likeId, 消息: '点赞成功'
捕获 (错误):
记录日志 "点赞错误:", 错误
返回 结果: 错误码.系统错误, 消息: "系统错误: " + 错误.信息
2 会员管理
2.1 会员余额充值接口文档
此接口用于用户对其会员账户进行余额充值。它会校验充值参数,查询会员信息,创建充值记录,并更新会员账户余额。
1. 接口名称
rechargeMemberBalance
(或根据平台约定,例如 会员充值
)
2. 请求参数 (params
)
参数 | 类型 | 必填 | 描述 | 示例 |
---|---|---|---|---|
userId | string | 是 | 进行充值操作的用户ID。 | "user123XYZ" |
memberId | string | 是 | 要充值的会员账户ID。 | "memberABC789" |
amount | number | 是 | 充值的金额,必须为正数。 | 100.00 |
paymentMethod | string | 是 | 支付方式(例如:"WeChatPay" 、"Alipay" 等)。 | "WeChatPay" |
3. 响应参数
参数 | 类型 | 描述 |
---|---|---|
code | number | 操作成功时为 0 (SUCCESS )。其他 ErrorCode 值表示错误。 |
message | string | 描述信息,尤其在错误时提供具体错误原因。 |
data | object | 充值成功时返回的数据。 |
data.rechargeId | string | 新创建的充值记录的唯一ID。 |
data.newBalance | number | 充值后会员账户的最新余额。 |
data.rechargeTime | number | 充值操作发生的时间戳(毫秒)。 |
4. 错误码
此接口使用以下自定义错误码:
0
:SUCCESS
- 操作成功完成。1001
:PARAM_ERROR
- 缺少或参数无效。1002
:NOT_FOUND
- 泛指未找到(此处未直接使用)。1003
:SYSTEM_ERROR
- 服务器发生意外错误。1005
:USER_NOT_EXISTS
- 用户不存在(此处未直接使用,但为通用码)。1006
:MEMBER_NOT_EXISTS
- 会员记录不存在。1007
:INVALID_AMOUNT
- 充值金额无效,必须为正数。
5. 逻辑伪代码
函数 会员余额充值(参数, 上下文):
记录日志 '充值API入参:', 参数
// 1. 解析并校验参数
定义 userId 为 参数.userId
定义 memberId 为 参数.memberId
定义 amount 为 参数.amount
定义 paymentMethod 为 参数.paymentMethod
如果 userId 为空 则
返回 结果: 错误码.参数错误, 消息: '用户ID不能为空'
如果 memberId 为空 则
返回 结果: 错误码.参数错误, 消息: '会员ID不能为空'
如果 amount 不是数字 或 amount 小于等于 0 则
返回 结果: 错误码.无效金额, 消息: '充值金额必须为正数'
如果 paymentMethod 为空 则
返回 结果: 错误码.参数错误, 消息: '支付方式不能为空'
尝试执行:
// 2. 查询会员详情
查询 会员数据模型 "xx_members"
使用方法 "wedaGetItemV2"
条件: _id 等于 memberId
返回所有主字段
将结果保存为 会员查询结果
// 检查会员是否存在
如果 会员查询结果 为空 或 会员查询结果 不是对象 或 会员查询结果.id 为空 则
返回 结果: 错误码.会员不存在, 消息: '会员记录不存在'
定义 currentBalance 为 会员查询结果.余额 或 0
// 3. 创建充值记录
创建 充值记录数据模型 "recharge_records"
使用方法 "wedaCreateV2"
数据:
user_id: {_id: userId} (关联用户ID)
member_id: {_id: memberId} (关联会员ID)
recharge_amount: amount
payment_method: paymentMethod
recharge_time: 当前时间戳
将结果保存为 充值结果
// 4. 更新会员余额
更新 会员数据模型 "xx_members"
使用方法 "wedaUpdateV2"
数据:
balance: currentBalance + amount
条件: _id 等于 memberId
将结果保存为 更新结果
// 5. 返回成功结果
返回 结果: 错误码.成功, 数据: 充值ID: 充值结果.id, 新余额: currentBalance + amount, 充值时间: 当前时间戳, 消息: '充值成功'
捕获 (错误):
记录日志 '充值API错误:', 错误
返回 结果: 错误码.系统错误, 消息: "系统错误: " + 错误.信息
2.2 会员余额扣减接口文档
此接口用于从会员账户余额中扣除指定金额,通常用于订单支付。它会校验参数、检查会员余额和订单状态,然后执行扣减并更新相关记录。
1. 接口名称
deductMemberBalance
(或根据平台约定,例如 会员余额扣减
)
2. 请求参数 (params
)
参数 | 类型 | 必填 | 描述 | 示例 |
---|---|---|---|---|
memberId | string | 是 | 要扣减余额的会员账户ID。 | "memberABC789" |
orderId | string | 是 | 与本次扣减相关的订单ID。 | "orderXYZ001" |
deductionAmount | number | 是 | 需要扣减的金额,必须为正数。 | 50.00 |
openid | string | 否 | 用户的OpenID,用于记录扣减详情(非必填但推荐)。 | "oPENiD1234567890" |
3. 响应参数
参数 | 类型 | 描述 |
---|---|---|
code | number | 操作成功时为 0 (SUCCESS )。其他 ErrorCode 值表示错误。 |
message | string | 描述信息,尤其在错误时提供具体错误原因。 |
data | object | 扣减成功时返回的数据。 |
data.deductionRecordId | string | 新创建的余额扣减记录的唯一ID。 |
data.newBalance | number | 扣减后会员账户的最新余额。 |
data.deductionTime | number | 扣减操作发生的时间戳(毫秒)。 |
data.orderStatus | string | 扣减成功后订单的最新状态,例如 "已支付" 。 |
4. 错误码
此接口使用以下自定义错误码:
0
:SUCCESS
- 操作成功完成。1001
:PARAM_ERROR
- 缺少或参数无效。1002
:NOT_FOUND
- 泛指未找到(此处未直接使用)。1003
:SYSTEM_ERROR
- 服务器发生意外错误。1005
:USER_NOT_EXISTS
- 用户不存在(未直接使用)。1006
:MEMBER_NOT_EXISTS
- 会员记录不存在。1007
:INVALID_AMOUNT
- 扣减金额无效,必须为正数。1008
:INSUFFICIENT_BALANCE
- 会员余额不足,无法完成扣减。1009
:ORDER_NOT_EXISTS
- 订单记录不存在。1010
:ORDER_ALREADY_PAID
- 订单已支付或已处理,无法重复扣减。
5. 逻辑伪代码
函数 会员余额扣减(参数, 上下文):
记录日志 '余额扣减API入参:', 参数
// 1. 解析并校验参数
定义 memberId 为 参数.memberId
定义 orderId 为 参数.orderId
定义 deductionAmount 为 参数.deductionAmount
定义 openid 为 参数.openid
如果 memberId 为空 则
返回 结果: 错误码.参数错误, 消息: '会员ID不能为空'
如果 orderId 为空 则
返回 结果: 错误码.参数错误, 消息: '订单ID不能为空'
如果 deductionAmount 不是数字 或 deductionAmount 小于等于 0 则
返回 结果: 错误码.无效金额, 消息: '扣减金额必须为正数'
尝试执行:
// 2. 查询会员详情,检查余额是否充足
查询 会员数据模型 "xx_members"
使用方法 "wedaGetItemV2"
条件: _id 等于 memberId
返回所有主字段
将结果保存为 会员查询结果
// 检查会员是否存在
如果 会员查询结果 为空 或 会员查询结果 不是对象 或 会员查询结果.id 为空 则
返回 结果: 错误码.会员不存在, 消息: '会员记录不存在'
定义 currentBalance 为 会员查询结果.余额 或 0
// 检查余额是否充足
如果 currentBalance 小于 deductionAmount 则
返回 结果: 错误码.余额不足, 消息: '余额不足,无法完成扣减'
// 3. 查询订单详情,确保订单存在且未支付
查询 订单数据模型 "orders"
使用方法 "wedaGetItemV2"
条件: _id 等于 orderId
返回所有主字段
将结果保存为 订单查询结果
// 检查订单是否存在
如果 订单查询结果 为空 或 订单查询结果 不是对象 或 订单查询结果.id 为空 则
返回 结果: 错误码.订单不存在, 消息: '订单记录不存在'
// 检查订单状态(假设 '1' 为未支付状态)
如果 订单查询结果.状态 不等于 '1' 则
返回 结果: 错误码.订单已支付, 消息: '订单已支付或已处理,无法重复扣减'
// 4. 创建余额扣减记录
创建 余额扣减记录数据模型 "balance_deduction_record"
使用方法 "wedaCreateV2"
数据:
memberId: {_id: memberId} (关联会员ID)
orderId: {_id: orderId} (关联订单ID)
deduction_amount: deductionAmount
deduction_time: 当前时间戳
openid: openid
将结果保存为 扣减记录结果
// 5. 更新会员余额
定义 newBalance 为 currentBalance - deductionAmount
更新 会员数据模型 "xx_members"
使用方法 "wedaUpdateV2"
数据:
balance: newBalance
条件: _id 等于 memberId
将结果保存为 更新会员结果
// 6. 更新订单状态为已支付
更新 订单数据模型 "orders"
使用方法 "wedaUpdateV2"
数据:
paymentStatus: "2" (支付状态:已支付)
status: "2" (订单状态:已完成/已支付,根据实际定义)
dispatchStatus: "1" (派单状态:待派单,根据实际定义)
payment_time: 当前时间戳
payment_method: "3" (支付方式:余额支付,根据实际定义)
条件: _id 等于 orderId
将结果保存为 更新订单结果
// 7. 返回成功结果
返回 结果: 错误码.成功, 数据: 扣减记录ID: 扣减记录结果.id, 新余额: newBalance, 扣减时间: 当前时间戳, 订单状态: "已支付", 消息: '余额扣减成功'
捕获 (错误):
记录日志 '余额扣减API错误:', 错误
返回 结果: 错误码.系统错误, 消息: "系统错误: " + 错误.信息
3 订单管理
3.1 创建订单接口文档
此接口用于用户创建新的服务订单。它会验证必要的订单信息,并在数据库中创建订单记录,返回新订单的详情。
1. 接口名称
createOrder
(或根据平台约定,例如 创建服务订单
)
2. 请求参数 (params
)
参数 | 类型 | 必填 | 描述 | 示例 |
---|---|---|---|---|
serviceId | object | 是 | 服务ID对象,包含 _id 字段。 | { _id: "srv789ABC" } |
userId | object | 是 | 用户ID对象,包含 _id 字段。 | { _id: "user123XYZ" } |
serviceDateTime | number | 是 | 服务预约的日期时间戳(毫秒)。 | 1678886400000 (表示 2023-03-15 00:00:00 UTC) |
description | string | 否 | 订单的服务描述或备注。 | "需要深度清洁厨房和浴室。" |
images | array<string> | 否 | 订单相关的图片URL数组。 | ["url1", "url2"] |
contactName | string | 是 | 订单联系人姓名。 | "李明" |
contactPhone | string | 是 | 订单联系人电话。 | "13912345678" |
totalAmount | number | 是 | 订单的总金额。 | 200.50 |
spec | string | 否 | 服务的规格或额外要求。 | "标准版" |
openid | string | 否 | 用户在第三方平台的唯一标识符(例如,微信 openid)。 | "oPENiD1234567890" |
3. 响应参数
参数 | 类型 | 描述 |
---|---|---|
code | number | 操作成功时为 0 (SUCCESS )。其他 ErrorCode 值表示错误。 |
message | string | 描述信息,尤其在错误时提供具体错误原因。 |
data | object | 订单创建成功时返回的数据。 |
data.orderId | string | 新创建的订单的唯一ID。 |
data.totalAmount | number | 订单的总金额。 |
data.status | string | 订单的当前状态(例如,"1" 代表待付款)。 |
4. 错误码
此接口使用以下自定义错误码:
0
:SUCCESS
- 操作成功完成。1001
:PARAM_ERROR
- 缺少或参数无效。1002
:NOT_FOUND
- 服务或地址未找到(在此代码中未直接使用,但为通用码)。1003
:SYSTEM_ERROR
- 服务器发生意外错误。
5. 逻辑伪代码
函数 创建订单(参数, 上下文):
// 提取参数
定义 serviceId 为 参数.serviceId
定义 userId 为 参数.userId
定义 serviceDateTime 为 参数.serviceDateTime
定义 description 为 参数.description
定义 images 为 参数.images
定义 contactName 为 参数.contactName
定义 contactPhone 为 参数.contactPhone
定义 totalAmount 为 参数.totalAmount
定义 spec 为 参数.spec
定义 openid 为 参数.openid
// 1. 参数验证
如果 userId 为空 或 serviceId 为空 或 serviceDateTime 为空 或 contactName 为空 或 contactPhone 为空 则
返回 结果: 错误码.参数错误, 消息: '必填参数缺失'
尝试执行:
// 2. 创建订单记录
创建 订单数据模型 "orders"
使用方法 "wedaCreateV2"
数据:
userId: { _id: userId._id } (关联用户ID)
serviceId: { _id: serviceId._id } (关联服务ID)
serviceDateTime: serviceDateTime (服务预约日期时间)
description: description (如果为空则为 '')
images: images (如果为空则为 [])
contactName: contactName (联系人姓名)
contactPhone: contactPhone (联系电话)
totalAmount: totalAmount (订单总金额)
status: '1' (初始状态:待付款)
paymentStatus: '1' (初始支付状态:待支付)
spec: spec (服务规格)
openid: openid
将结果保存为 订单创建结果
定义 orderId 为 订单创建结果.id
// 3. 返回创建成功的订单信息
返回 结果: 错误码.成功,
数据: 订单ID: orderId, 总金额: totalAmount, 状态: '1',
消息: '订单创建成功'
捕获 (错误):
记录日志 "创建订单错误:", 错误
返回 结果: 错误码.系统错误, 消息: "系统错误: " + 错误.信息
3.2 派发订单接口文档
此接口用于将服务订单派发给技师,支持自动派单和手动指定技师两种方式。它会验证订单状态和技师信息,更新订单状态,并记录派发日志。
1. 接口名称
dispatchOrder
(或根据平台约定,例如 派发服务订单
)
2. 请求参数 (params
)
参数 | 类型 | 必填 | 描述 | 示例 |
---|---|---|---|---|
orderId | string | 是 | 要派发的订单的唯一ID。 | "orderXYZ001" |
dispatchMethod | string | 是 | 派单方式,可以是 "auto" (自动派单) 或 "manual" (手动派单)。 | "manual" |
targetWorkerId | string | 否 | 目标技师的唯一ID。当 dispatchMethod 为 "manual" 时必填。 | "workerABC789" |
operatorId | string | 否 | 操作派单的管理人员或系统ID。 | "admin001" |
3. 响应参数
参数 | 类型 | 描述 |
---|---|---|
code | number | 操作成功时为 0 (SUCCESS )。其他 ErrorCode 值表示错误。 |
message | string | 描述信息,尤其在错误时提供具体错误原因。 |
data | object | 派单成功时返回的更新后的订单信息。 |
data.orderId | string | 订单ID。 |
data.status | string | 订单的最新状态。 |
data.dispatchStatus | string | 订单的最新派单状态。 |
data.assignedWorkerId | object | 被指派技师的ID对象,如果已指派。 |
data.dispatchTime | number | 订单派发的时间戳。 |
… | … | (其他订单字段) |
4. 错误码
此接口使用以下自定义错误码:
0
:SUCCESS
- 操作成功完成。1001
:PARAM_ERROR
- 缺少或参数无效。1002
:NOT_FOUND
- 订单或指派的技师未找到。1003
:SYSTEM_ERROR
- 服务器发生意外错误。1004
:INVALID_ORDER_STATUS
- 订单当前状态或派单状态不允许进行派单操作。
5. 逻辑伪代码
函数 派发订单(参数, 上下文):
// 提取参数
定义 orderId 为 参数.orderId
定义 targetWorkerId 为 参数.targetWorkerId
定义 dispatchMethod 为 参数.dispatchMethod
定义 operatorId 为 参数.operatorId
// 1. 参数验证
如果 orderId 为空 或 dispatchMethod 为空 则
返回 结果: 错误码.参数错误, 消息: '必填参数缺失: orderId, dispatchMethod'
如果 dispatchMethod 等于 'manual' 并且 targetWorkerId 为空 则
返回 结果: 错误码.参数错误, 消息: '手动派单时 targetWorkerId 必填'
尝试执行:
// 2. 根据 orderId 查找订单
查询 订单数据模型 "orders"
使用方法 "wedaGetItemV2"
条件: _id 等于 orderId
返回所有主字段
将结果保存为 订单结果
定义 order 为 订单结果
如果 order 为空 并且 订单结果的键数量为 0 则
返回 结果: 错误码.未找到, 消息: '订单未找到'
// 3. 验证订单 status 和 dispatchStatus 是否允许派单
定义 允许状态列表 为 ['2'] // 待接单
定义 允许派单状态列表 为 ['1', '4'] // 待派单, 技师已拒绝
如果 允许状态列表 不包含 order.status 或者 允许派单状态列表 不包含 order.dispatchStatus 则
返回 结果: 错误码.无效订单状态, 消息: "订单当前状态或派单状态不允许派单。当前状态: " + order.status + ", 派单状态: " + order.dispatchStatus
// 查找技师信息 (如果需要填充技师姓名)
定义 assignedWorkerName 为 ''
如果 targetWorkerId 不为空 则
查询 技师数据模型 "worker"
使用方法 "wedaGetItemV2"
条件: _id 等于 targetWorkerId
返回所有主字段
将结果保存为 技师结果
如果 技师结果 为空 并且 技师结果的键数量为 0 则
返回 结果: 错误码.未找到, 消息: '指派的技师未找到'
assignedWorkerName 为 技师结果.姓名 或 ''
// 4. 更新订单主表的 dispatchStatus
定义 更新参数 =
dispatchStatus: '2' (已派单)
assignedWorkerId: 如果 targetWorkerId 不为空则 {_id: targetWorkerId} 否则 空值
dispatchTime: 当前时间戳
更新 订单数据模型 "orders"
使用方法 "wedaUpdateV2"
数据: 更新参数
条件: _id 等于 orderId
// 5. 在 order_status_logs 子表插入一条 订单已派发 的日志记录
定义 logDescription 为 "订单已派发给技师 " + (assignedWorkerName 或 '(未指定技师)') + "。派单方式: " + (如果 dispatchMethod 等于 'manual' 则 '手动' 否则 '自动')
定义 operator 为 如果 dispatchMethod 等于 'manual' 则 '客服' 否则 '系统'
创建 订单状态日志数据模型 "order_status_logs"
使用方法 "wedaCreateV2"
数据:
orderId: {_id: orderId} (关联订单)
eventType: '3' (对应 '已派单' 状态)
eventDescription: logDescription
operatorRole: operator
timestamp: 当前时间戳
operatorId: operatorId
// 6. 通知被指派的技师有新订单 (这里仅作示意,实际需要集成消息推送服务)
如果 targetWorkerId 不为空 则
打印日志 "通知技师 " + targetWorkerId + " 有新订单: " + orderId
// 实际可能调用通知服务,例如 context.callModel 通知服务或使用消息队列等
// 7. 返回派单结果和更新后的订单信息
// 重新查询订单以获取最新完整信息
查询 订单数据模型 "orders"
使用方法 "wedaGetItemV2"
条件: _id 等于 orderId
返回所有主字段
将结果保存为 更新后的订单结果
返回 结果: 错误码.成功, 消息: '订单派发成功', 数据: 更新后的订单结果
捕获 (错误):
记录日志 "派发订单错误:", 错误
返回 结果: 错误码.系统错误, 消息: "系统错误: " + 错误.信息
3.3 工人接单接口文档
此接口允许工人接受被派发给他们的服务订单。它会严格校验订单和派工记录的状态,确保只有符合条件的订单才能被接受,并更新订单主表和记录状态日志。
1. 接口名称
workerAcceptOrder
(或根据平台约定,例如 工人接单
)
2. 请求参数 (params
)
参数 | 类型 | 必填 | 描述 | 示例 |
---|---|---|---|---|
orderId | string | 是 | 要接受的订单的唯一ID。 | "orderXYZ001" |
workerId | string | 是 | 执行接单操作的工人(技师)的唯一ID。 | "workerABC789" |
3. 响应参数
参数 | 类型 | 描述 |
---|---|---|
code | number | 操作成功时为 0 (SUCCESS )。其他 ErrorCode 值表示错误。 |
message | string | 描述信息,尤其在错误时提供具体错误原因。 |
data | object | 接单成功时返回的更新后的订单信息。 |
data.orderId | string | 订单ID。 |
data.status | string | 订单的最新主状态(应为 ACCEPTED )。 |
data.dispatchStatus | string | 订单的最新派单状态(应为 DISPATCHED_ACCEPTED )。 |
data.assignedWorkerId | object | 被指派技师的ID对象。 |
… | … | (其他订单字段) |
4. 错误码
此接口使用以下自定义错误码:
0
:SUCCESS
- 操作成功完成。1001
:PARAM_ERROR
- 缺少或参数无效。1002
:NOT_FOUND
- 订单未找到。1003
:SYSTEM_ERROR
- 服务器发生意外错误。1004
:INVALID_ORDER_STATUS
- 订单当前主状态不允许接单(订单必须处于“待接单”状态)。1007
:INVALID_WORKER_STATUS
- 工人派工记录状态不允许接单(此代码中未直接使用,但为通用码)。INVALID_DISPATCH_STATUS
(此为代码中新增错误码): 订单当前派单状态不允许接单(订单派单状态必须为“已派发待接单”)。
5. 状态枚举
为了更好地理解接口逻辑,以下是相关状态枚举的定义:
订单主状态 (orders.status
)
'1'
:PENDING_PAYMENT
(待付款)'2'
:PENDING_ACCEPTANCE
(待接单 - 已支付,等待派发;或已派发但工人尚未接单/已拒绝)'3'
:ACCEPTED
(已接单 - 工人已接受订单)'4'
:IN_SERVICE
(服务中)'5'
:PENDING_REVIEW
(待评价)'6'
:COMPLETED
(已完成)'7'
:CANCELED
(已取消)'8'
:REFUNDED
(已退款)
订单派单状态 (orders.dispatchStatus
)
'1'
:PENDING_DISPATCH
(待派单)'2'
:DISPATCHED_PENDING_ACCEPTANCE
(已派发待接单)'3'
:DISPATCHED_ACCEPTED
(已派发已接单)'4'
:DISPATCHED_REJECTED
(已派发已拒单)
工人操作状态 (order_assignments.worker_status
- 未直接使用但在注释中提及)
'1'
:PENDING_ACCEPTANCE
(待接单)'2'
:ACCEPTED
(已接单)'3'
:REJECTED
(已拒单)'4'
:ON_THE_WAY
(在路上)'5'
:IN_PROGRESS
(进行中)'6'
:COMPLETED
(已完成)
6. 逻辑伪代码
函数 工人接单(参数, 上下文):
// 提取参数
定义 orderId 为 参数.orderId
定义 workerId 为 参数.workerId
// 1. 参数验证
如果 orderId 为空 或 workerId 为空 则
返回 结果: 错误码.参数错误, 消息: '必填参数缺失: orderId, workerId'
尝试执行:
// 2. 查找订单的当前主状态和派单状态
查询 订单数据模型 "orders"
使用方法 "wedaGetItemV2"
条件: _id 等于 orderId
选择: 所有主字段, 派单状态, 被指派工人ID
将结果保存为 order
如果 order 为空 或 order 的键数量为 0 则
返回 结果: 错误码.未找到, 消息: '订单未找到'
// 3. 验证订单的主状态是否允许接单
如果 order.status 不等于 ORDER_STATUS_ENUM.PENDING_ACCEPTANCE (即 '2') 则
返回 结果: 错误码.无效订单状态, 消息: "订单当前主状态不允许接单。订单必须处于“待接单”状态。当前状态码: " + order.status
// 4. 验证订单的派单状态
定义 currentDispatchStatus 为 order.dispatchStatus
如果 currentDispatchStatus 不等于 DISPATCH_STATUS_ENUM.DISPATCHED_PENDING_ACCEPTANCE (即 '2') 则
返回 结果: 错误码.INVALID_DISPATCH_STATUS, 消息: "订单当前派单状态不允许接单。订单派单状态必须为“已派发待接单”。当前状态码: " + currentDispatchStatus
// 5. 更新 `orders` (订单主表) 的状态和派单状态
定义 updateOrderParams =
status: ORDER_STATUS_ENUM.ACCEPTED (更新为 '3' - 已接单)
dispatchStatus: DISPATCH_STATUS_ENUM.DISPATCHED_ACCEPTED (更新为 '3' - 已派发已接单)
acceptanceTime: 当前时间戳 (记录接单时间)
更新 订单数据模型 "orders"
使用方法 "wedaUpdateV2"
数据: updateOrderParams
条件: _id 等于 orderId
// 6. 在 `order_status_logs` (订单状态日志表) 插入日志记录
定义 logDescription 为 "工人 (ID: " + workerId + ") 已接单。订单主状态由 \"" + order.status + "\" 变为 \"" + ORDER_STATUS_ENUM.ACCEPTED + "\",派单状态由 \"" + currentDispatchStatus + "\" 变为 \"" + DISPATCH_STATUS_ENUM.DISPATCHED_ACCEPTED + "\"。"
创建 订单状态日志数据模型 "order_status_logs"
使用方法 "wedaCreateV2"
数据:
orderId: {_id: orderId} (关联订单)
eventType: '4' (事件类型:已接单)
eventDescription: logDescription
operatorRole: '3' (操作角色:工人)
operatorId: workerId (操作人ID为工人ID)
timestamp: 当前时间戳
// 7. 通知客服或其他相关方订单已被接单
打印日志 "订单 " + orderId + " 已被工人 " + workerId + " 接单。"
// 实际应用中可能需要发送消息通知客服或客户
// 8. 返回接单结果
重新查询 订单数据模型 "orders" (获取更新后的订单信息)
使用方法 "wedaGetItemV2"
条件: _id 等于 orderId
选择: 所有主字段, 被指派工人ID, 派单状态
将结果保存为 updatedOrder
返回 结果: 错误码.成功, 消息: '订单接单成功', 数据: updatedOrder
捕获 (错误):
打印错误日志 "acceptOrder 错误:", 错误
返回 结果: 错误码.系统错误, 消息: "系统错误: " + 错误.信息
3.4 提交订单评价接口文档
此接口允许用户对已完成的服务订单提交评价。它会验证输入参数,确保订单处于可评价状态,创建新的评价记录,更新相关服务和技师的平均评分,最后将订单标记为“已完成”。
1. 接口名称
submitOrderReview
(或根据您的平台约定,例如 提交服务评价
)
2. 请求参数 (params
)
参数 | 类型 | 必填 | 描述 | 示例 |
---|---|---|---|---|
orderId | string 或 object | 是 | 要评价的订单的唯一ID。可以是普通字符串ID,也可以是包含 _id 字段的对象。 | "orderABC123" |
userId | string 或 object | 是 | 提交评价的用户唯一ID。可以是普通字符串ID,也可以是包含 _id 字段的对象。 | "userXYZ456" |
overallRating | number | 是 | 整体服务评分 (1-5星)。 | 5 |
serviceQualityRating | number | 是 | 服务质量评分 (1-5星)。 | 4 |
serviceAttitudeRating | number | 是 | 服务态度评分 (1-5星)。 | 5 |
professionalismRating | number | 是 | 专业程度评分 (1-5星)。 | 4 |
punctualityRating | number | 是 | 准时程度评分 (1-5星)。 | 5 |
reviewContent | string | 否 | 可选。评价的文字内容。 | "非常满意,服务周到!" |
reviewPhotos | Array<string> | 否 | 可选。评价照片的URL数组。 | ["photo1.jpg", "photo2.png"] |
isAnonymous | boolean | 否 | 可选。是否匿名评价 (默认为 false )。 | true |
3. 响应参数
参数 | 类型 | 描述 |
---|---|---|
code | number | 操作成功时为 0 (SUCCESS )。其他 ErrorCode 值表示错误。 |
message | string | 描述信息,尤其在错误时提供具体错误原因。 |
data | object | 评价成功后返回的更新后的订单信息。 |
data.orderId | string | 订单ID。 |
data.status | string | 订单的最新主状态(应为 COMPLETED )。 |
data.dispatchStatus | string | 订单的最新派单状态(应为 DISPATCHED_COMPLETED )。 |
… | … | (其他相关订单字段) |
4. 错误码
此接口使用以下自定义错误码:
0
:SUCCESS
- 操作成功完成。1001
:PARAM_ERROR
- 参数缺失或无效(例如,评分不完整,评分不在1-5范围)。1002
:NOT_FOUND
- 订单、关联服务或工人未找到。1003
:SYSTEM_ERROR
- 发生通用系统错误。1004
:INVALID_ORDER_STATUS
- 订单当前主状态不允许评价(订单必须处于“待评价”状态)。
5. 状态枚举
为了更好地理解接口逻辑,以下是相关状态枚举的定义:
订单主状态 (orders.status
)
'1'
:PENDING_PAYMENT
(待付款)'2'
:PENDING_ACCEPTANCE
(待接单)'3'
:ACCEPTED
(已接单)'4'
:IN_SERVICE
(服务中)'5'
:PENDING_REVIEW
(待评价 - 服务已完成,等待用户评价)'6'
:COMPLETED
(已完成 - 用户已评价或已过评价期)'7'
:CANCELED
'8'
:REFUNDED
订单派单状态 (orders.dispatchStatus
)
'1'
:PENDING_DISPATCH
'2'
:DISPATCHED_PENDING_ACCEPTANCE
'3'
:DISPATCHED_ACCEPTED
'4'
:DISPATCHED_REJECTED
'5'
:DISPATCHED_COMPLETED
(派单已完成 - 工人已完成服务)
6. 逻辑流程 (伪代码)
函数 submitOrderReview(params, context):
从 params 中提取 orderId, userId, overallRating, serviceQualityRating, serviceAttitudeRating, professionalismRating, punctualityRating, reviewContent, reviewPhotos, isAnonymous。
如果 orderId 或 userId 是对象,则从中提取 _id。
// 1. 参数验证
如果 必填参数 (orderId, userId, 所有评分) 有任何缺失或未定义:
返回 错误码.PARAM_ERROR, 消息: '必填参数缺失或无效。'
验证所有评分是否介于 1 和 5 之间:
如果任何评分 < 1 或 > 5:
返回 错误码.PARAM_ERROR, 消息: '评分必须在1到5之间。'
初始化 order, service 和 provider 为空。
尝试执行:
// 2. 查找订单详情并验证其状态
通过 orderId 查询 "orders" 集合,选择所有主字段、serviceId 和 assignedWorkerId。
将结果存储到 order。
如果 order 未找到或为空:
返回 错误码.NOT_FOUND, 消息: '订单未找到。'
如果 order.status 不等于 ORDER_STATUS_ENUM.PENDING_REVIEW ('5'):
返回 错误码.INVALID_ORDER_STATUS, 消息: '订单当前状态不允许评价。订单必须处于“待评价”状态。当前状态码: ' + order.status
从 order 中提取 serviceId 和 providerId(假设它们是引用类型,取其 _id)。
如果 serviceId 或 providerId 缺失:
返回 错误码.SYSTEM_ERROR, 消息: '订单关联的服务或工人信息不完整。'
// 3. 查找服务信息(用于后续更新其平均评分)
通过 serviceId 查询 "xx_services" 集合,选择 _id, avg_rating, total_reviews。
将结果存储到 service。
// 4. 查找服务提供者(工人)信息(用于后续更新其平均评分)
通过 providerId 查询 "worker" 集合,选择 _id, avg_rating, total_reviews。
将结果存储到 provider。
如果 service 或 provider 未找到或为空:
返回 错误码.NOT_FOUND, 消息: '关联的服务或服务提供者未找到。'
// 5. 将新的评价记录插入 `Reviews` 表
创建 newReviewData 对象,包含所有评价详情,并关联 orderId, userId, serviceId, providerId。
设置 review_date 为当前时间戳。
调用 "Reviews" 模型使用 "wedaCreateV2" 方法并传入 newReviewData。
// 6. 更新 `worker` 表:重新计算并更新工人的平均评分和总评价数
查询 "Reviews" 集合,获取与此 providerId 相关的所有评价,仅选择 "overall_rating",并获取总计数。
将结果存储到 providerReviews。
计算 newProviderAvgRating 和 newProviderTotalReviews(所有 overall_rating 的总和 / 计数)。
调用 "worker" 模型使用 "wedaUpdateV2" 方法更新 provider 的 avg_rating 和 total_reviews。
// 7. 更新 `xx_services` 表:重新计算并更新服务的平均评分和总评价数
查询 "Reviews" 集合,获取与此 serviceId 相关的所有评价,仅选择 "overall_rating",并获取总计数。
将结果存储到 serviceReviews。
计算 newServiceAvgRating 和 newServiceTotalReviews(所有 overall_rating 的总和 / 计数)。
调用 "xx_services" 模型使用 "wedaUpdateV2" 方法更新 service 的 avg_rating 和 total_reviews。
// 8. 更新 `orders` (订单主表) 状态为“已完成”
设置 updateOrderParams:
status: ORDER_STATUS_ENUM.COMPLETED ('6')
dispatchStatus: DISPATCH_STATUS_ENUM.DISPATCHED_COMPLETED ('5')
completionTime: 当前时间戳
调用 "orders" 模型使用 "wedaUpdateV2" 方法,通过 orderId 更新订单及 updateOrderParams。
// 9. 将日志条目插入 `order_status_logs` 表
构造 logDescription 详细说明状态变化。
创建日志数据,包含 orderId, eventType ('10' 表示评价), eventDescription, operatorRole ('1' 表示用户), operatorId (userId), timestamp。
调用 "order_status_logs" 模型使用 "wedaCreateV2" 方法并传入日志数据。
// 10. 返回成功结果及更新后的订单信息
再次通过 orderId 查询 "orders" 模型,获取最新的更新后的订单,选择所有主字段、status 和 dispatchStatus。
将结果存储到 updatedOrder。
返回 错误码.SUCCESS, 消息: '订单评价成功', 数据: updatedOrder。
捕获 (错误):
记录 "submitReview error:" 和 错误。
返回 错误码.SYSTEM_ERROR, 消息: "系统错误: " + 错误.message。
4 工人管理
4.1 用户登录接口文档
此接口用于用户通过手机号进行登录。它会根据提供的手机号查询用户信息,并返回登录结果。
1. 接口名称
userLoginByPhone
(或根据您的平台约定,例如 用户手机号登录
)
2. 请求参数 (params
)
参数 | 类型 | 必填 | 描述 | 示例 |
---|---|---|---|---|
phone | string | 是 | 用户注册时使用的手机号码。 | "13812345678" |
3. 响应参数
参数 | 类型 | 描述 |
---|---|---|
code | number | 操作成功时为 0 (SUCCESS )。其他 ErrorCode 值表示错误。 |
message | string | 描述信息,尤其在错误时提供具体错误原因。 |
workerInfo | object | 登录成功时返回的用户(工人)详细信息。 |
4. 错误码
此接口使用以下自定义错误码:
0
:SUCCESS
- 操作成功完成。1001
:PARAM_ERROR
- 参数错误,通常指phone
参数缺失。1002
:NOT_FOUND
- 用户未找到,表示该手机号尚未注册。1003
:SYSTEM_ERROR
- 通用系统错误,表示服务器内部发生异常。
5. 逻辑流程 (伪代码)
函数 userLoginByPhone(params, context):
// 提取入参
定义 phone 为 params.phone
// 1. 参数验证
如果 phone 为空:
返回 结果: 错误码.PARAM_ERROR, 消息: "参数错误,电话缺失"
尝试执行:
// 2. 根据手机号查询用户信息
调用 context.callModel 方法:
数据模型名称: 'worker'
方法名称: 'wedaGetRecordsV2'
参数:
过滤条件:
其中 phone 等于传入的 phone
选择字段: 所有主字段
获取总数: true
每页大小: 1
页码: 1
将结果保存为 result。
// 3. 验证用户是否存在
如果 result.total 等于 0 (表示未找到记录):
返回 结果: 错误码.NOT_FOUND, 消息: "用户未注册,请先注册再登录"
// 4. 用户存在,返回用户信息
定义 worker 为 result.records 的第一个元素。
返回 结果: 错误码.SUCCESS, 消息: "用户登录成功", workerInfo: worker
捕获 (错误):
返回 结果: 错误码.SYSTEM_ERROR, 消息: "系统异常,请稍后再试"