package cn.ppdxzz.dao;

import cn.ppdxzz.domain.Visitor;
import org.apache.ibatis.annotations.Insert;
import org.apache.ibatis.annotations.Param;
import org.apache.ibatis.annotations.Select;
import org.apache.ibatis.annotations.Update;
import org.springframework.stereotype.Repository;

import java.util.List;

/**
 * Description:访客持久层
 * 该接口定义了与访客数据访问相关的操作方法，通过MyBatis的注解方式来声明SQL语句，
 * 用于实现对数据库中访客信息表（visitors）的增、查、改等操作，每个方法对应不同的业务需求。
 *
 * @Date: 2020/2/18 16:27
 * @Author: PeiChen
 */
// 声明这是一个数据访问对象接口，在Spring框架中，使用 @Repository 注解标记该接口为数据访问层组件，便于进行依赖注入和管理
@Repository
public interface VisitorDao {

    /**
     * 登记到访信息
     * 该方法用于向数据库中插入访客的到访信息，通过MyBatis的 @Insert 注解定义插入操作的SQL语句，
     * 将访客对象中的各个属性值插入到对应的数据库表字段中。
     *
     * @param visitor 访客对象，包含访客的所有信息，如ID、姓名、学号、电话、访问地点、来访时间、离开时间、到访原因等，
     *                这些属性值将按照SQL语句中的占位符对应插入到数据库的visitors表中相应字段。
     * @throws Exception 抛出可能的异常，例如数据库连接异常、SQL执行异常等情况，由调用该方法的上层代码进行处理。
     */
    @Insert("insert into visitors(id,name,sno,phone,place,begin_date,end_date,visit_result) values(#{id},#{name},#{sno},#{phone},#{place},#{begin_date},#{end_date},#{visit_result})")
    void add(Visitor visitor) throws Exception;

    /**
     * 按时间晚的优先显示查询所有访客记录
     * 该方法用于从数据库中查询所有访客记录，并按照来访时间（begin_date）降序排列，即时间晚的访客记录优先显示，
     * 通过MyBatis的 @Select 注解定义查询操作的SQL语句，返回一个包含所有访客信息的列表。
     *
     * @return 返回访客记录列表，列表中的每个元素是一个Visitor对象，包含了从数据库中查询到的访客的各项详细信息。
     * @throws Exception 抛出可能的异常，如数据库查询出现问题、数据转换异常等，由调用者负责处理。
     */
    @Select("select * from visitors order by begin_date desc")
    List<Visitor> findAll() throws Exception;

    /**
     * 访客离开后修改离开时间（访客记录注销）
     * 该方法用于在访客离开后，更新数据库中对应访客记录的离开时间字段，通过MyBatis的 @Update 注解定义更新操作的SQL语句，
     * 根据访客的唯一标识（ID）找到对应的记录，并将离开时间（end_date）字段更新为指定的值。
     *
     * @param id 访客的唯一标识，用于在数据库中定位要更新的具体访客记录，对应visitors表中的id字段。
     * @param end_date 访客离开的时间，要更新到数据库中对应访客记录的end_date字段的值，该值通常是当前的系统时间。
     * @throws Exception 抛出可能的异常，比如数据库更新失败、参数传递错误等情况，由调用该方法的代码进行处理。
     */
    @Update("update visitors set end_date = #{end_date} where id = #{id}")
    void logout(@Param(value = "id") String id, @Param(value = "end_date") String end_date) throws Exception;

    /**
     * 根据关键字模糊查询访客记录，并按时间倒序排列
     * 该方法用于根据给定的关键字在数据库中对访客记录进行模糊查询，查询条件涵盖访客的多个字段（姓名、学号、电话等），
     * 只要这些字段中包含关键字的内容就会被匹配到，并且查询结果按照来访时间（begin_date）降序排列，
     * 通过MyBatis的 @Select 注解定义复杂的模糊查询操作的SQL语句，返回匹配关键字的访客记录列表。
     *
     * @param keyword 查询关键字，是一个字符串类型的值，用于在多个字段中进行模糊匹配查找符合条件的访客记录。
     * @return 返回匹配关键字的访客记录列表，列表中的元素为Visitor对象，包含了符合模糊查询条件的访客的详细信息。
     * @throws Exception 抛出可能的异常，像数据库查询语法错误、数据解析异常等情况，由调用者来处理这些异常情况。
     */
    @Select("select * from visitors where name like '%${keyword}%' or sno like '%${keyword}%' or phone like '%${keyword}%' or place like '%${keyword}%' or begin_date like '%${keyword}%' or end_date like '%${keyword}%' or visit_result like '%${keyword}%' order by begin_date desc ")
    List<Visitor> search(@Param(value = "keyword") String keyword) throws Exception;

}