王明 / Food-Labeling-Management-Platform

  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);
  }