package com.seer.teach.common.service;

import com.seer.teach.common.entity.CityEntity;
import com.seer.teach.common.entity.ProvinceEntity;
import com.seer.teach.common.resp.AddressIdResp;
import com.seer.teach.common.resp.CityResp;

import jakarta.servlet.http.HttpServletRequest;
import java.util.List;

/**
 *
 * <p>
 *
 * </p >
 *
 * @author Captain
 * @since 2025-11-22 10:16
 */
public interface RegionAddressService {

    /**
     * 根据省份ID获取省份信息
     *
     * @param provinceId 省份ID
     * @return 省份实体对象
     */
    ProvinceEntity getProvinceById(Integer provinceId);

    /**
     * 根据城市ID获取省份信息
     *
     * @param cityId 城市ID
     * @return 省份实体对象
     */
    ProvinceEntity getProvinceByCityId(Integer cityId);

    /**
     * 根据城市ID获取城市信息
     *
     * @param cityId 城市ID，不能为空
     * @return 返回对应的城市实体对象，如果未找到则返回null
     */
    CityEntity getCityById(Integer cityId);

    /**
     * 根据城市名称获取城市信息
     *
     * @param cityName 城市名称
     * @return 城市实体对象
     */
    CityEntity getCityByCityName(String cityName);

    /**
     * 根据省份ID获取该省份下的所有城市列表
     *
     * @param provinceId 省份ID
     * @return 城市实体对象列表
     */
    List<CityEntity> getCitysByProvinceId(Integer provinceId);

    /**
     * 根据省份ID获取城市列表
     *
     * @param provinceId 省份ID
     * @return 城市响应对象列表
     */
    List<CityResp> getCitiesByProvinceId(Integer provinceId);

    /**
     * 根据HTTP请求获取地址ID信息
     *
     * @param ipAddress HTTP请求对象，包含客户端请求信息
     * @return AddressIdResp 地址ID响应对象，包含地址相关的ID信息
     */
    AddressIdResp getAddressId(String ipAddress);

    /**
     * 获取客户端IP地址
     *
     * @param request HTTP请求对象，用于获取客户端IP信息
     * @return 返回客户端的真实IP地址字符串
     */
    String getIpAddress(HttpServletRequest request);

    /**
     * 获取所有省份
     * @return 所有省份
     */
    List<ProvinceEntity> getAllProvinces();

    /**
     * 获取所有城市
     * @return 所有城市
     */
    List<CityEntity> getAllCitys();
}