package com.dne.ems.service;

import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

import com.dne.ems.dto.GridUpdateRequest;
import com.dne.ems.model.Grid;
import com.dne.ems.model.UserAccount;

import java.util.List;
import java.util.Optional;

/**
 * 网格服务接口，处理网格数据的查询和更新
 *
 * <p>主要功能：
 * <ul>
 *   <li>网格数据查询与过滤</li>
 *   <li>网格信息更新</li>
 * </ul>
 *
 * @author DNE开发团队
 * @version 1.0
 * @since 2025
 */
public interface GridService {

    /**
     * 获取所有网格的列表.
     * @return a list of all grids.
     */
    List<Grid> getAllGrids();

    /**
     * Finds a grid by its ID.
     * @param gridId the ID of the grid.
     * @return an Optional containing the grid if found.
     */
    Optional<Grid> getGridById(Long gridId);

    /**
     * Assigns a worker to a specific grid.
     * @param gridId the ID of the grid.
     * @param userId the ID of the user (worker).
     * @return the updated UserAccount of the worker.
     */
    UserAccount assignWorkerToGrid(Long gridId, Long userId);

    /**
     * Unassigns any worker from a specific grid.
     * @param gridId the ID of the grid.
     */
    void unassignWorkerFromGrid(Long gridId);

    /**
     * 获取网格分页列表，支持按城市和区县过滤
     *
     * <p>查询规则：
     * <ul>
     *   <li>支持按城市名称过滤</li>
     *   <li>支持按区县名称过滤</li>
     *   <li>返回分页结果</li>
     * </ul>
     *
     * @param cityName 城市名称过滤条件(可选)
     * @param districtName 区县名称过滤条件(可选)
     * @param pageable 分页参数
     * @return 网格分页列表
     */
    Page<Grid> getGrids(String cityName, String districtName, Pageable pageable);

    /**
     * 更新网格信息
     *
     * <p>更新规则：
     * <ul>
     *   <li>可更新障碍物状态</li>
     *   <li>可更新描述信息</li>
     * </ul>
     *
     * @param gridId 要更新的网格ID
     * @param request 包含更新数据的请求体
     * @return 更新后的网格实体
     * @throws jakarta.persistence.EntityNotFoundException 如果网格不存在
     */
    Grid updateGrid(Long gridId, GridUpdateRequest request);
}