微搭低代码实战训练营课后资料包(三)接口文档

目录

1 用户管理

1.1 用户注册与会员开通接口文档

此接口用于处理新用户的注册,并自动创建对应的会员记录。它会检查并防止基于 openid 的重复用户注册。


1. 接口名称

registerUserAndCreateMembership (或根据平台约定,例如 用户注册并开通会员)


2. 请求参数 (params)

参数类型必填描述示例
openidstring用户在第三方平台的唯一标识符(例如,微信 openid)。"oPENiD1234567890"
phonestring用户的手机号码。"13800138000"
nicknamestring用户的昵称。"张三"
avtarURLstring用户头像的URL。"https://example.com/avatar.jpg"

3. 响应参数

参数类型描述
codenumber操作成功时为 0 (SUCCESS)。其他 ErrorCode 值表示错误。
messagestring描述信息,尤其在错误时提供具体错误原因。
dataobject注册成功时包含 userIdmemberId
data.userIdstring新创建的用户记录的唯一ID。
data.memberIdstring新创建的会员记录的唯一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)

参数类型必填描述示例
openidstring用户在第三方平台的唯一标识符(例如,微信 openid)。"oPENiD1234567890"

3. 响应参数

参数类型描述
codenumber操作成功时为 0 (SUCCESS)。其他 ErrorCode 值表示错误。
messagestring描述信息,尤其在错误时提供具体错误原因。
userInfoobject登录成功时返回的用户基本信息。
memberInfoobject登录成功时返回的用户会员信息。

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)

参数类型必填描述示例
openidstring用户在第三方平台的唯一标识符(例如,微信 openid)。"oPENiD1234567890"
serviceIdstring要收藏的服务的唯一ID。"srv12345ABC"

3. 响应参数

参数类型描述
codenumber操作成功时为 0 (SUCCESS)。其他 ErrorCode 值表示错误。
messagestring描述信息,尤其在错误时提供具体错误原因。
dataobject收藏成功时包含 favoriteId
data.favoriteIdstring新创建的收藏记录的唯一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)

参数类型必填描述示例
openidstring用户在第三方平台的唯一标识符(例如,微信 openid)。"oPENiD1234567890"
workerIdstring被点赞的工人的唯一ID。"workerABC789"
userIdstring点赞用户的唯一ID(与 openid 关联的用户ID)。"userXYZ456"

3. 响应参数

参数类型描述
codenumber操作成功时为 0 (SUCCESS)。其他 ErrorCode 值表示错误。
messagestring描述信息,尤其在错误时提供具体错误原因。
dataobject点赞成功时包含 likeId
data.likeIdstring新创建的点赞记录的唯一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)

参数类型必填描述示例
userIdstring进行充值操作的用户ID。"user123XYZ"
memberIdstring要充值的会员账户ID。"memberABC789"
amountnumber充值的金额,必须为正数。100.00
paymentMethodstring支付方式(例如:"WeChatPay""Alipay"等)。"WeChatPay"

3. 响应参数

参数类型描述
codenumber操作成功时为 0 (SUCCESS)。其他 ErrorCode 值表示错误。
messagestring描述信息,尤其在错误时提供具体错误原因。
dataobject充值成功时返回的数据。
data.rechargeIdstring新创建的充值记录的唯一ID。
data.newBalancenumber充值后会员账户的最新余额。
data.rechargeTimenumber充值操作发生的时间戳(毫秒)。

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)

参数类型必填描述示例
memberIdstring要扣减余额的会员账户ID。"memberABC789"
orderIdstring与本次扣减相关的订单ID。"orderXYZ001"
deductionAmountnumber需要扣减的金额,必须为正数。50.00
openidstring用户的OpenID,用于记录扣减详情(非必填但推荐)。"oPENiD1234567890"

3. 响应参数

参数类型描述
codenumber操作成功时为 0 (SUCCESS)。其他 ErrorCode 值表示错误。
messagestring描述信息,尤其在错误时提供具体错误原因。
dataobject扣减成功时返回的数据。
data.deductionRecordIdstring新创建的余额扣减记录的唯一ID。
data.newBalancenumber扣减后会员账户的最新余额。
data.deductionTimenumber扣减操作发生的时间戳(毫秒)。
data.orderStatusstring扣减成功后订单的最新状态,例如 "已支付"

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)

参数类型必填描述示例
serviceIdobject服务ID对象,包含 _id 字段。{ _id: "srv789ABC" }
userIdobject用户ID对象,包含 _id 字段。{ _id: "user123XYZ" }
serviceDateTimenumber服务预约的日期时间戳(毫秒)。1678886400000 (表示 2023-03-15 00:00:00 UTC)
descriptionstring订单的服务描述或备注。"需要深度清洁厨房和浴室。"
imagesarray<string>订单相关的图片URL数组。["url1", "url2"]
contactNamestring订单联系人姓名。"李明"
contactPhonestring订单联系人电话。"13912345678"
totalAmountnumber订单的总金额。200.50
specstring服务的规格或额外要求。"标准版"
openidstring用户在第三方平台的唯一标识符(例如,微信 openid)。"oPENiD1234567890"

3. 响应参数

参数类型描述
codenumber操作成功时为 0 (SUCCESS)。其他 ErrorCode 值表示错误。
messagestring描述信息,尤其在错误时提供具体错误原因。
dataobject订单创建成功时返回的数据。
data.orderIdstring新创建的订单的唯一ID。
data.totalAmountnumber订单的总金额。
data.statusstring订单的当前状态(例如,"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)

参数类型必填描述示例
orderIdstring要派发的订单的唯一ID。"orderXYZ001"
dispatchMethodstring派单方式,可以是 "auto" (自动派单) 或 "manual" (手动派单)。"manual"
targetWorkerIdstring目标技师的唯一ID。当 dispatchMethod"manual" 时必填。"workerABC789"
operatorIdstring操作派单的管理人员或系统ID。"admin001"

3. 响应参数

参数类型描述
codenumber操作成功时为 0 (SUCCESS)。其他 ErrorCode 值表示错误。
messagestring描述信息,尤其在错误时提供具体错误原因。
dataobject派单成功时返回的更新后的订单信息。
data.orderIdstring订单ID。
data.statusstring订单的最新状态。
data.dispatchStatusstring订单的最新派单状态。
data.assignedWorkerIdobject被指派技师的ID对象,如果已指派。
data.dispatchTimenumber订单派发的时间戳。
(其他订单字段)

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)

参数类型必填描述示例
orderIdstring要接受的订单的唯一ID。"orderXYZ001"
workerIdstring执行接单操作的工人(技师)的唯一ID。"workerABC789"

3. 响应参数

参数类型描述
codenumber操作成功时为 0 (SUCCESS)。其他 ErrorCode 值表示错误。
messagestring描述信息,尤其在错误时提供具体错误原因。
dataobject接单成功时返回的更新后的订单信息。
data.orderIdstring订单ID。
data.statusstring订单的最新主状态(应为 ACCEPTED)。
data.dispatchStatusstring订单的最新派单状态(应为 DISPATCHED_ACCEPTED)。
data.assignedWorkerIdobject被指派技师的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)

参数类型必填描述示例
orderIdstringobject要评价的订单的唯一ID。可以是普通字符串ID,也可以是包含 _id 字段的对象。"orderABC123"
userIdstringobject提交评价的用户唯一ID。可以是普通字符串ID,也可以是包含 _id 字段的对象。"userXYZ456"
overallRatingnumber整体服务评分 (1-5星)。5
serviceQualityRatingnumber服务质量评分 (1-5星)。4
serviceAttitudeRatingnumber服务态度评分 (1-5星)。5
professionalismRatingnumber专业程度评分 (1-5星)。4
punctualityRatingnumber准时程度评分 (1-5星)。5
reviewContentstring可选。评价的文字内容。"非常满意,服务周到!"
reviewPhotosArray<string>可选。评价照片的URL数组。["photo1.jpg", "photo2.png"]
isAnonymousboolean可选。是否匿名评价 (默认为 false)。true

3. 响应参数

参数类型描述
codenumber操作成功时为 0 (SUCCESS)。其他 ErrorCode 值表示错误。
messagestring描述信息,尤其在错误时提供具体错误原因。
dataobject评价成功后返回的更新后的订单信息。
data.orderIdstring订单ID。
data.statusstring订单的最新主状态(应为 COMPLETED)。
data.dispatchStatusstring订单的最新派单状态(应为 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)

参数类型必填描述示例
phonestring用户注册时使用的手机号码。"13812345678"

3. 响应参数

参数类型描述
codenumber操作成功时为 0 (SUCCESS)。其他 ErrorCode 值表示错误。
messagestring描述信息,尤其在错误时提供具体错误原因。
workerInfoobject登录成功时返回的用户(工人)详细信息。

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, 消息: "系统异常,请稍后再试"

5 状态图

在这里插入图片描述

6 序列图

在这里插入图片描述

7 组件图

在这里插入图片描述

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

低代码布道师

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值