using FoodLabeling.Application.Contracts.Dtos.Common;
using FoodLabeling.Application.Contracts.Dtos.Partner;
using Microsoft.AspNetCore.Mvc;
using Volo.Abp.Application.Dtos;
using Volo.Abp.Application.Services;

namespace FoodLabeling.Application.Contracts.IServices;

/// <summary>
/// 合作伙伴管理接口（fl_partner）
/// </summary>
public interface IPartnerAppService : IApplicationService
{
    /// <summary>
    /// 合作伙伴分页列表（与导出使用相同筛选条件）
    /// </summary>
    /// <remarks>
    /// 数据范围（按登录 Token）：
    /// <list type="bullet">
    /// <item>管理员（角色码 <c>admin</c>、用户名为 <c>admin</c> 或权限 <c>*:*:*</c>）：可查看全部公司；</item>
    /// <item>其它角色：仅可查看当前用户在 <c>userlocation</c> 中绑定门店所属的合作伙伴（<c>location.Partner</c> 与 <c>fl_partner</c> 按名称或 Id 匹配）。</item>
    /// </list>
    /// </remarks>
    /// <param name="input">分页与筛选；SkipCount 为页码（从 1 起）</param>
    /// <returns>分页数据</returns>
    /// <response code="200">成功</response>
    /// <response code="400">参数错误</response>
    /// <response code="500">服务器错误</response>
    Task<PagedResultWithPageDto<PartnerGetListOutputDto>> GetListAsync(PartnerGetListInputVo input);

    /// <summary>
    /// 合作伙伴详情
    /// </summary>
    /// <param name="id">主键（Guid，与 <c>fl_partner.Id</c> 一致；约定路由 <c>{id:guid}</c>，避免与 <c>export-pdf</c> 等路径冲突）</param>
    /// <returns>详情</returns>
    /// <response code="200">成功</response>
    /// <response code="400">Id 无效</response>
    /// <response code="500">服务器错误</response>
    Task<PartnerGetOutputDto> GetAsync(Guid id);

    /// <summary>
    /// 新增合作伙伴
    /// </summary>
    /// <param name="input">名称、联系信息、地址、启用状态</param>
    /// <returns>新建后的详情</returns>
    /// <remarks>
    /// 示例请求：
    /// ```json
    /// {
    ///   "partnerName": "Global Foods Inc.",
    ///   "contactEmail": "admin@globalfoods.com",
    ///   "phoneNumber": "+1 (555) 100-2000",
    ///   "street": "123 Main St",
    ///   "city": "New York",
    ///   "stateCode": "NY",
    ///   "country": "USA",
    ///   "zipCode": "10001",
    ///   "state": true
    /// }
    /// ```
    /// 地址中的州/省请传 <c>stateCode</c>（如 NY）；<c>state</c>（boolean）表示是否启用。
    /// </remarks>
    /// <response code="200">成功</response>
    /// <response code="400">校验失败</response>
    /// <response code="500">服务器错误</response>
    Task<PartnerGetOutputDto> CreateAsync(PartnerCreateInputVo input);

    /// <summary>
    /// 编辑合作伙伴
    /// </summary>
    /// <param name="id">主键 Id</param>
    /// <param name="input">名称、联系信息、地址、启用状态（字段同新增）</param>
    /// <returns>更新后的详情</returns>
    /// <response code="200">成功</response>
    /// <response code="400">校验失败或记录不存在</response>
    /// <response code="500">服务器错误</response>
    Task<PartnerGetOutputDto> UpdateAsync(Guid id, PartnerUpdateInputVo input);

    /// <summary>
    /// 删除合作伙伴（逻辑删除）
    /// </summary>
    /// <param name="id">主键 Id</param>
    /// <response code="200">成功</response>
    /// <response code="400">Id 无效或记录不存在</response>
    /// <response code="500">服务器错误</response>
    Task DeleteAsync(Guid id);

    /// <summary>
    /// 按当前列表筛选条件批量导出合作伙伴为 PDF（Account Management「Company」页签；不分页，上限 5000 条）
    /// </summary>
    /// <param name="input">与列表相同的 Keyword、State；分页字段忽略</param>
    /// <returns>PDF 文件流</returns>
    /// <remarks>
    /// 筛选条件与数据范围需与 <see cref="GetListAsync"/> 完全一致（含 Token 权限：管理员全部公司，其它角色仅绑定门店所属公司；见 PartnerScopeHelper）。
    /// </remarks>
    /// <response code="200">成功返回 application/pdf</response>
    /// <response code="400">参数错误</response>
    /// <response code="500">服务器错误</response>
    Task<IActionResult> ExportPdfAsync(PartnerGetListInputVo input);
}