package cn.ppdxzz.service;

import cn.ppdxzz.domain.Visitor;

import java.io.InputStream;
import java.util.List;

/**
 * Description:访客服务接口，定义了访客管理相关的服务方法
 * 该接口作为业务逻辑层与外部交互的契约，规定了一系列用于访客信息管理的方法签名，
 * 具体的实现类需要按照这些方法定义来实现相应的业务逻辑，实现类通常会调用数据访问层的方法来完成具体操作，
 * 并且可以被更上层的控制器层等调用，以实现对访客相关功能的处理。
 *
 * @Date: 2020/2/18 18:27
 * @Author: PeiChen
 */
public interface VisitorService {

    /**
     * 添加新的访客记录
     * 该方法用于向系统中添加新的访客信息，接收一个包含访客详细信息的Visitor对象作为参数，
     * 若在添加过程中出现如数据库插入失败、数据验证不通过等错误情况，则抛出异常，由调用者进行相应处理。
     *
     * @param visitor 访客对象，包含访客的详细信息，例如访客的姓名、学号、联系方式、访问地址、来访时间、离开时间、来访原因等属性，
     *                这些信息将被保存到对应的存储介质（通常是数据库）中，形成一条新的访客记录。
     * @throws Exception 如果添加过程中发生错误，比如数据库连接异常、插入操作违反数据库约束等情况，则抛出异常，
     *                   以便调用该方法的上层代码（如控制器层）能够捕获并进行适当的错误处理，例如给用户返回错误提示信息等。
     */
    void add(Visitor visitor) throws Exception;

    /**
     * 查找所有访客记录，并分页显示
     * 该方法用于查询所有的访客记录，并按照指定的分页参数进行分页展示，返回包含访客记录的列表，
     * 如果在查询过程中出现如数据库查询语句执行错误、分页插件配置问题等错误情况，则抛出异常。
     *
     * @param page 当前页码，用于指定要获取第几页的数据，是一个正整数，通过该参数结合每页显示的记录数可以确定具体的分页查询范围，
     *             例如，page为1表示获取第一页的数据。
     * @param size 每页显示的记录数，用于控制每页展示多少条访客记录，同样是一个正整数，例如，size为10表示每页展示10条访客记录，
     *             它与当前页码配合实现对大量访客记录的分页查询功能。
     * @return 包含访客记录的列表，返回的列表中的元素为Visitor对象，每个对象代表一条访客记录，包含了访客的各项详细信息，
     *         例如访客的个人基本信息以及访问相关的时间、地点、原因等信息，这些记录是按照分页要求从所有访客记录中筛选出来的。
     * @throws Exception 如果查询过程中发生错误，比如数据库查询失败、分页相关的逻辑出现问题等情况，则抛出异常，
     *                   由调用该方法的上层代码（如控制器层）进行异常处理，例如给用户展示相应的错误提示页面等。
     */
    List<Visitor> findAll(int page, int size) throws Exception;

    /**
     * 根据关键字进行搜索，并分页显示搜索结果
     * 该方法用于根据给定的关键字在所有访客记录中进行模糊搜索，并按照指定的分页参数展示搜索结果，返回符合条件的访客记录列表，
     * 在搜索或分页过程中若出现错误情况，例如数据库查询语法错误、关键字格式不符合要求等，则抛出异常。
     *
     * @param page 当前页码，用于确定要获取第几页的搜索结果，通过与每页显示记录数配合来定位具体的分页数据范围，
     *             其取值通常为正整数，代表相应的页码数。
     * @param size 每页显示的记录数，用于限定每页展示的符合搜索条件的访客记录数量，也是正整数，与当前页码共同作用实现分页搜索功能，
     *             比如设置为20表示每页最多展示20条符合关键字搜索的访客记录。
     * @param keyword 搜索关键字，是一个字符串类型的值，用于在访客记录的多个字段（如姓名、学号、联系方式、访问地址等）中进行模糊匹配查找，
     *                只要访客记录的相应字段中包含该关键字内容，就会被作为符合条件的记录筛选出来，例如，关键字为"张三"，则会查找出姓名包含"张三"的所有访客记录。
     * @return 包含搜索结果的访客记录列表，返回的列表中的元素为Visitor对象，每个对象对应一条满足关键字模糊搜索条件的访客记录，
     *         这些记录包含了访客完整的详细信息，并且是按照分页要求进行展示的，方便用户查看和浏览搜索到的访客信息。
     * @throws Exception 如果搜索过程中发生错误，比如数据库查询出现语法错误、根据关键字构造查询语句时出现问题、分页设置不合理等情况，
     *                   则抛出异常，由调用该方法的上层代码（如控制器层）进行相应的异常处理，例如给用户提示搜索失败等信息。
     */
    List<Visitor> search(int page, int size, String keyword) throws Exception;

    /**
     * 更新访客的离开时间
     * 该方法用于更新访客记录中的离开时间信息，接收访客的唯一标识符和离开时间作为参数，
     * 在更新操作过程中若遇到如数据库更新失败、参数不合法等错误情况，则抛出异常进行相应处理。
     *
     * @param id 访客的唯一标识符，用于在存储访客记录的介质（通常是数据库）中准确找到对应的访客记录，
     *           一般是一个具有唯一性的字符串值（例如使用UUID生成的唯一标识），与数据库表中的主键字段相对应，通过该标识可以唯一确定一条访客记录。
     * @param end_date 访客的离开时间，是一个表示日期时间的字符串，其格式通常需要与数据库中存储时间的格式保持一致（如常见的 "yyyy-MM-dd HH:mm:ss" 格式），
     *                 该值将被更新到数据库中对应访客记录的离开时间字段，用于准确记录访客离开的时间点，实现访客记录状态的更新。
     * @throws Exception 如果更新过程中发生错误，比如数据库连接异常、更新语句执行失败、传入的参数不符合要求等情况，则抛出异常，
     *                   由调用该方法的上层代码（如控制器层）进行异常处理，例如给用户提示更新失败等信息，并可以根据具体的业务需求进行相应的后续操作。
     */
    void logout(String id, String end_date) throws Exception;

    /**
     * 获取访客记录的输入流，通常用于导出数据
     * 该方法用于获取包含访客记录数据的输入流，一般是为了将访客记录导出到外部文件（如Excel文件等）而准备的，
     * 在获取输入流过程中若出现如文件读取失败、数据转换错误等情况，则抛出异常进行处理。
     *
     * @return 访客记录的输入流，返回的输入流指向包含访客记录数据的数据源（例如内存中的数据缓冲区或者实际的文件内容等），
     *         通过该输入流可以将访客记录数据传输到其他地方进行处理，比如在控制器层将其作为响应流发送给客户端，实现访客记录的导出功能，
     *         客户端接收到输入流后可以将其保存为本地文件或者进行其他相应的数据展示操作。
     * @throws Exception 如果获取输入流过程中发生错误，比如无法正确生成包含访客记录数据的流对象、读取相关数据资源时出现问题等情况，
     *                   则抛出异常，由调用该方法的上层代码（如实现类或者控制器层等）进行异常处理，例如给用户提示导出失败等信息。
     */
    InputStream getInputStream() throws Exception;

    /**
     * 获取访客日志记录，并分页显示
     * 该方法用于获取访客的日志记录信息，并按照指定的分页参数进行分页展示，返回包含访客日志记录的列表，
     * 如果在获取日志记录或者分页过程中出现错误情况，例如数据库查询错误、分页配置不当等，则抛出异常进行处理。
     *
     * @param page 当前页码，用于指定要获取第几页的访客日志记录数据，通过与每页显示记录数配合来确定具体的分页查询范围，
     *             其取值应为正整数，代表相应的页码位置，例如page为2表示获取第二页的访客日志记录。
     * @param size 每页显示的记录数，用于控制每页展示多少条访客日志记录，是一个正整数，与当前页码共同作用实现对访客日志记录的分页查询功能，
     *             例如设置size为15表示每页展示15条访客日志记录。
     * @return 包含访客日志记录的列表，返回的列表中的元素为Visitor对象，每个对象代表一条访客日志记录，包含了访客访问相关的详细信息，
     *         如来访时间、离开时间、来访原因等日志信息，这些记录是按照分页要求从所有访客日志记录中筛选出来的，方便用户查看和分析访客的访问历史情况。
     * @throws Exception 如果获取日志记录过程中发生错误，比如数据库查询语句执行失败、分页逻辑出现问题等情况，则抛出异常，
     *                   由调用该方法的上层代码（如控制器层）进行异常处理，例如给用户展示相应的错误提示页面等。
     */
    List<Visitor> log(int page, int size) throws Exception;

}