Night-Fragrance/nightFragrance-massage/src/main/java/com/ylx/massage/service/TJsService.java

package com.ylx.massage.service;

import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.baomidou.mybatisplus.extension.service.IService;
import com.ylx.massage.domain.TJs;
import com.ylx.massage.domain.vo.TJsVo;


import java.util.List;

/**
 * 技师信息业务服务接口
 * <p>
 * 该接口定义了技师管理的核心业务操作，包括：
 * <ul>
 *   <li>技师注册与申请：技师通过微信小程序提交申请材料</li>
 *   <li>审核流程：管理员审核技师资信，通过/驳回/拉黑</li>
 *   <li>上岗管理：技师上下岗打卡，记录在线时长</li>
 *   <li>位置服务：维护技师地理位置，用于距离计算和订单分配</li>
 *   <li>状态管理：服务状态、上岗状态、审核状态的流转控制</li>
 *   <li>通知推送：微信模板消息推送（审核结果、新订单通知等）</li>
 * </ul>
 * </p>
 * <p>
 * 业务流程说明：
 * <pre>
 * 1. 技师注册流程：
 *    用户提交申请 → 填写基本信息/上传资质证书 → 等待审核 → 审核通过 → 标记为新技师
 *
 * 2. 上岗接单流程：
 *    审核通过 → 申请上岗 → 上岗打卡(nStatus2=0, nStatus=0) → 开始接单 → 服务中(nStatus=1) → 完成服务 → 继续接单
 *    ↓
 *    下岗打卡(nStatus2=-1, nStatus=2) → 停止接单
 *
 * 3. 审核状态流转：
 *    待审核(nTong=0) → 审核通过(nTong=1) → 可以上岗
 *                  → 审核驳回(nTong=2) → 修改资料重新提交
 *                  → 拉黑(nTong=3) → 无法接单
 *
 * 4. 服务状态流转：
 *    可服务(nStatus=0) → 服务中(nStatus=1) → 可服务(nStatus=0)
 *    不可服务(nStatus=2) → 上岗后变为可服务
 * </pre>
 * </p>
 *
 * @author ylx
 * @version 1.0
 * @since 2024-01-01
 * @see com.ylx.massage.domain.TJs
 * @see com.ylx.massage.service.impl.TJsServiceImpl
 */
public interface TJsService extends IService<TJs> {

    /**
     * 分页查询技师列表（管理后台）
     * <p>
     * 支持多条件组合查询，包括：
     * <ul>
     *   <li>昵称或电话模糊查询</li>
     *   <li>服务项目筛选</li>
     *   <li>城市筛选</li>
     *   <li>审核状态筛选</li>
     *   <li>上岗状态筛选</li>
     *   <li>免车费条件筛选</li>
     * </ul>
     * </p>
     *
     * @param page 分页对象
     * @param param 查询条件封装对象
     * @return 分页结果，包含符合条件的技师列表
     */
    Page<TJs> getAll(Page<TJs> page, TJsVo param);

    /**
     * 技师申请注册（微信小程序端）
     * <p>
     * 业务规则：
     * <ul>
     *   <li>检查微信号是否已申请（通过OpenID去重）</li>
     *   <li>初始化技师信息：评分5星、服务数0、佣金比例10%</li>
     *   <li>设置初始状态：不可服务、未上岗、待审核</li>
     *   <li>不允许重复申请，否则抛出异常</li>
     * </ul>
     * </p>
     *
     * @param js 技师实体对象，包含基本信息和资质证书
     * @return true-申请成功，false-申请失败
     * @throws ServiceException 当微信号已申请时抛出异常
     */
    boolean addJs(TJs js);

    /**
     * 根据技师ID查询详情（微信小程序端）
     * <p>
     * 查询内容包括：
     * <ul>
     *   <li>技师基本信息（头像、昵称、评分、服务数等）</li>
     *   <li>可提供的服务项目列表（按价格排序）</li>
     *   <li>用户评价列表（最新10条）</li>
     *   <li>当前用户是否收藏该技师</li>
     *   <li>技师与用户的距离</li>
     * </ul>
     * </p>
     *
     * @param jsId 技师ID
     * @param openId 当前用户的微信OpenID（用于判断收藏状态）
     * @return 技师详情对象，包含关联的项目和评价信息；如果技师不存在返回null
     * @throws ServiceException 当技师ID为空时抛出异常
     */
    TJs getByJsId(String jsId, String openId);

    /**
     * 微信小程序端更新技师信息
     * <p>
     * 支持更新内容：
     * <ul>
     *   <li>基本信息：姓名、电话、地址</li>
     *   <li>资质证书：身份证、健康证、资格证等</li>
     *   <li>服务配置：可服务项目、免车费公里数</li>
     *   <li>位置信息：经纬度坐标（用于距离计算）</li>
     *   <li>个人简介：自我介绍文字</li>
     * </ul>
     * </p>
     * <p>
     * 注意：如果技师曾被驳回，更新后会重置为待审核状态
     * </p>
     *
     * @param js 技师实体对象，包含需要更新的字段
     * @return true-更新成功，false-更新失败
     */
    boolean wxUpdateJs(TJs js);

    /**
     * 审核技师申请（管理后台）
     * <p>
     * 审核通过操作：
     * <ul>
     *   <li>将审核状态改为"已通过"(nTong=1)</li>
     *   <li>标记为新技师(nB2=1)，用于新人推荐</li>
     *   <li>记录注册时间</li>
     *   <li>将微信用户角色改为技师(role=1)</li>
     *   <li>发送微信模板消息通知技师</li>
     * </ul>
     * </p>
     * <p>
     * 审核驳回操作：
     * <ul>
     *   <li>将审核状态改为"已退回"(nTong=2)</li>
     *   <li>记录驳回原因</li>
     *   <li>发送微信模板消息通知技师</li>
     * </ul>
     * </p>
     *
     * @param js 技师实体对象，必须包含ID和审核状态(nTong)
     * @return true-审核成功，false-审核失败
     */
    boolean auditing(TJs js);

    /**
     * 更新技师地理位置信息
     * <p>
     * 将技师位置信息添加到Redis GEO中，用于：
     * <ul>
     *   <li>计算技师与用户的距离</li>
     *   <li>查找附近可用技师</li>
     *   <li>订单分配时的距离排序</li>
     * </ul>
     * </p>
     *
     * @param js 技师实体对象，必须包含ID和经纬度坐标
     * @return true-更新成功，false-更新失败
     * @throws ServiceException 当技师ID或地址为空时抛出异常
     */
    boolean updateLocation(TJs js);

    /**
     * 新订单通知（预留接口，当前未实现）
     * <p>
     * 当有新订单分配给技师时，发送微信模板消息通知：
     * <ul>
     *   <li>订单号</li>
     *   <li>用户电话</li>
     *   <li>用户名称</li>
     *   <li>服务时间</li>
     *   <li>服务地址</li>
     * </ul>
     * </p>
     *
     * @param openId 技师的微信OpenID
     */
    void newOrderNotification(String openId);

    /**
     * 技师上下岗打卡（微信小程序端）
     * <p>
     * 上岗操作(nStatus2=0)：
     * <ul>
     *   <li>将服务状态改为"可服务"(nStatus=0)</li>
     *   <li>记录签到时间和技师信息</li>
     *   <li>开始在线时长统计</li>
     * </ul>
     * </p>
     * <p>
     * 下岗操作(nStatus2=-1)：
     * <ul>
     *   <li>检查是否有服务中的订单（如有则不允许下岗）</li>
     *   <li>将服务状态改为"不可服务"(nStatus=2)</li>
     *   <li>记录下岗时间</li>
     *   <li>计算并保存本次在线时长（分钟）</li>
     * </ul>
     * </p>
     *
     * @param js 技师实体对象，必须包含ID和上岗状态(nStatus2)
     * @return true-操作成功，false-操作失败
     * @throws ServiceException 当技师ID为空或下岗时有服务中订单时抛出异常
     */
    boolean upPost(TJs js);

    /**
     * 发送审核结果通知（内部方法）
     * <p>
     * 通过微信公众号模板消息推送审核结果：
     * <ul>
     *   <li>审核通过：通知"可以接单"</li>
     *   <li>审核驳回：通知"请重新提交"</li>
     *   <li>包含审核时间和联系电话</li>
     * </ul>
     * </p>
     *
     * @param js 技师实体对象，包含OpenID和审核状态
     */
    void jsNotification(TJs js);

    /**
     * 拉黑/恢复技师（管理后台）
     * <p>
     * 拉黑操作(nTong=3)：
     * <ul>
     *   <li>检查是否有服务中的订单（如有则不允许拉黑）</li>
     *   <li>将审核状态改为"已拉黑"</li>
     *   <li>将服务状态改为"不可服务"</li>
     *   <li>将上岗状态改为"未上岗"</li>
     * </ul>
     * </p>
     * <p>
     * 恢复操作(nTong=0)：
     * <ul>
     *   <li>将审核状态改为"待审核"</li>
     *   <li>将服务状态改为"不可服务"</li>
     *   <li>需要重新审核通过后才能上岗</li>
     * </ul>
     * </p>
     *
     * @param js 技师实体对象，必须包含ID和审核状态(nTong)
     * @return true-操作成功，false-操作失败
     * @throws ServiceException 当技师ID或拉黑状态为空时抛出异常
     */
    boolean block(TJs js);

    /**
     * 管理后台新增技师
     * <p>
     * 与微信端注册的区别：
     * <ul>
     *   <li>直接设置为"已通过"审核状态</li>
     *   <li>默认值设置：评分5星、服务数0、佣金比例10%</li>
     *   <li>初始状态：不可服务、未上岗</li>
     *   <li>不触发微信通知</li>
     * </ul>
     * </p>
     * <p>
     * 用途：管理员直接录入技师信息，跳过审核流程
     * </p>
     *
     * @param js 技师实体对象，包含完整的基本信息
     * @return true-添加成功，false-添加失败
     */
    boolean pcAddJs(TJs js);
}