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;
/**
* 技师信息业务服务接口
*
* 该接口定义了技师管理的核心业务操作，包括：
*
* - 技师注册与申请：技师通过微信小程序提交申请材料
* - 审核流程：管理员审核技师资信，通过/驳回/拉黑
* - 上岗管理：技师上下岗打卡，记录在线时长
* - 位置服务：维护技师地理位置，用于距离计算和订单分配
* - 状态管理：服务状态、上岗状态、审核状态的流转控制
* - 通知推送：微信模板消息推送（审核结果、新订单通知等）
*
*
*
* 业务流程说明：
*
* 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) → 上岗后变为可服务
*
*
*
* @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 {
/**
* 分页查询技师列表（管理后台）
*
* 支持多条件组合查询，包括：
*
* - 昵称或电话模糊查询
* - 服务项目筛选
* - 城市筛选
* - 审核状态筛选
* - 上岗状态筛选
* - 免车费条件筛选
*
*
*
* @param page 分页对象
* @param param 查询条件封装对象
* @return 分页结果，包含符合条件的技师列表
*/
Page getAll(Page page, TJsVo param);
/**
* 技师申请注册（微信小程序端）
*
* 业务规则：
*
* - 检查微信号是否已申请（通过OpenID去重）
* - 初始化技师信息：评分5星、服务数0、佣金比例10%
* - 设置初始状态：不可服务、未上岗、待审核
* - 不允许重复申请，否则抛出异常
*
*
*
* @param js 技师实体对象，包含基本信息和资质证书
* @return true-申请成功，false-申请失败
* @throws ServiceException 当微信号已申请时抛出异常
*/
boolean addJs(TJs js);
/**
* 根据技师ID查询详情（微信小程序端）
*
* 查询内容包括：
*
* - 技师基本信息（头像、昵称、评分、服务数等）
* - 可提供的服务项目列表（按价格排序）
* - 用户评价列表（最新10条）
* - 当前用户是否收藏该技师
* - 技师与用户的距离
*
*
*
* @param jsId 技师ID
* @param openId 当前用户的微信OpenID（用于判断收藏状态）
* @return 技师详情对象，包含关联的项目和评价信息；如果技师不存在返回null
* @throws ServiceException 当技师ID为空时抛出异常
*/
TJs getByJsId(String jsId, String openId);
/**
* 微信小程序端更新技师信息
*
* 支持更新内容：
*
* - 基本信息：姓名、电话、地址
* - 资质证书：身份证、健康证、资格证等
* - 服务配置：可服务项目、免车费公里数
* - 位置信息：经纬度坐标（用于距离计算）
* - 个人简介：自我介绍文字
*
*
*
* 注意：如果技师曾被驳回，更新后会重置为待审核状态
*
*
* @param js 技师实体对象，包含需要更新的字段
* @return true-更新成功，false-更新失败
*/
boolean wxUpdateJs(TJs js);
/**
* 审核技师申请（管理后台）
*
* 审核通过操作：
*
* - 将审核状态改为"已通过"(nTong=1)
* - 标记为新技师(nB2=1)，用于新人推荐
* - 记录注册时间
* - 将微信用户角色改为技师(role=1)
* - 发送微信模板消息通知技师
*
*
*
* 审核驳回操作：
*
* - 将审核状态改为"已退回"(nTong=2)
* - 记录驳回原因
* - 发送微信模板消息通知技师
*
*
*
* @param js 技师实体对象，必须包含ID和审核状态(nTong)
* @return true-审核成功，false-审核失败
*/
boolean auditing(TJs js);
/**
* 更新技师地理位置信息
*
* 将技师位置信息添加到Redis GEO中，用于：
*
* - 计算技师与用户的距离
* - 查找附近可用技师
* - 订单分配时的距离排序
*
*
*
* @param js 技师实体对象，必须包含ID和经纬度坐标
* @return true-更新成功，false-更新失败
* @throws ServiceException 当技师ID或地址为空时抛出异常
*/
boolean updateLocation(TJs js);
/**
* 新订单通知（预留接口，当前未实现）
*
* 当有新订单分配给技师时，发送微信模板消息通知：
*
* - 订单号
* - 用户电话
* - 用户名称
* - 服务时间
* - 服务地址
*
*
*
* @param openId 技师的微信OpenID
*/
void newOrderNotification(String openId);
/**
* 技师上下岗打卡（微信小程序端）
*
* 上岗操作(nStatus2=0)：
*
* - 将服务状态改为"可服务"(nStatus=0)
* - 记录签到时间和技师信息
* - 开始在线时长统计
*
*
*
* 下岗操作(nStatus2=-1)：
*
* - 检查是否有服务中的订单（如有则不允许下岗）
* - 将服务状态改为"不可服务"(nStatus=2)
* - 记录下岗时间
* - 计算并保存本次在线时长（分钟）
*
*
*
* @param js 技师实体对象，必须包含ID和上岗状态(nStatus2)
* @return true-操作成功，false-操作失败
* @throws ServiceException 当技师ID为空或下岗时有服务中订单时抛出异常
*/
boolean upPost(TJs js);
/**
* 发送审核结果通知（内部方法）
*
* 通过微信公众号模板消息推送审核结果：
*
* - 审核通过：通知"可以接单"
* - 审核驳回：通知"请重新提交"
* - 包含审核时间和联系电话
*
*
*
* @param js 技师实体对象，包含OpenID和审核状态
*/
void jsNotification(TJs js);
/**
* 拉黑/恢复技师（管理后台）
*
* 拉黑操作(nTong=3)：
*
* - 检查是否有服务中的订单（如有则不允许拉黑）
* - 将审核状态改为"已拉黑"
* - 将服务状态改为"不可服务"
* - 将上岗状态改为"未上岗"
*
*
*
* 恢复操作(nTong=0)：
*
* - 将审核状态改为"待审核"
* - 将服务状态改为"不可服务"
* - 需要重新审核通过后才能上岗
*
*
*
* @param js 技师实体对象，必须包含ID和审核状态(nTong)
* @return true-操作成功，false-操作失败
* @throws ServiceException 当技师ID或拉黑状态为空时抛出异常
*/
boolean block(TJs js);
/**
* 管理后台新增技师
*
* 与微信端注册的区别：
*
* - 直接设置为"已通过"审核状态
* - 默认值设置：评分5星、服务数0、佣金比例10%
* - 初始状态：不可服务、未上岗
* - 不触发微信通知
*
*
*
* 用途：管理员直接录入技师信息，跳过审核流程
*
*
* @param js 技师实体对象，包含完整的基本信息
* @return true-添加成功，false-添加失败
*/
boolean pcAddJs(TJs js);
}