/**
 * 帖子 Repository 接口
 * 定义帖子数据访问的抽象
 */

import type { Post, PostImage, PostStatus } from '../../../core/entities/Post';

// ==================== 请求/响应类型 ====================

/**
 * 获取帖子列表参数
 */
export interface GetPostsParams {
  /** 分页 - 页码（从1开始） */
  page?: number;
  /** 分页 - 每页数量 */
  pageSize?: number;
  /** 游标 - 用于无限滚动加载 */
  cursor?: string;
  /** 帖子类型筛选（可选）：follow, hot, latest */
  post_type?: 'follow' | 'hot' | 'latest';
  /** 频道ID过滤 */
  channelId?: string;
  /** 作者ID过滤 */
  authorId?: string;
  /** 标签过滤 */
  tags?: string[];
  /** 状态过滤 */
  status?: PostStatus;
  /** 排序字段 */
  sortBy?: 'createdAt' | 'likesCount' | 'commentsCount' | 'viewsCount';
  /** 排序方向 */
  sortOrder?: 'asc' | 'desc';
  /** 是否只获取置顶帖子 */
  pinnedOnly?: boolean;
}

/**
 * 创建帖子数据
 */
export interface CreatePostData {
  /** 帖子标题 */
  title: string;
  /** 帖子内容 */
  content: string;
  /** 图片列表 */
  images?: PostImage[];
  /** 所属频道ID */
  channelId?: string;
  /** 标签列表 */
  tags?: string[];
  /** 帖子状态 */
  status?: PostStatus;
}

/**
 * 更新帖子数据
 */
export interface UpdatePostData {
  /** 帖子标题 */
  title?: string;
  /** 帖子内容 */
  content?: string;
  /** 图片列表 */
  images?: PostImage[];
  /** 标签列表 */
  tags?: string[];
  /** 帖子状态 */
  status?: PostStatus;
  /** 是否置顶 */
  isPinned?: boolean;
}

/**
 * 帖子列表结果
 */
export interface PostsResult {
  /** 帖子列表 */
  posts: Post[];
  /** 是否有更多数据 */
  hasMore: boolean;
  /** 下一页游标 */
  nextCursor?: string;
  /** 总数（如果支持） */
  total?: number;
}

/**
 * 搜索帖子参数
 */
export interface SearchPostsParams {
  /** 搜索关键词 */
  keyword: string;
  /** 分页 - 页码 */
  page?: number;
  /** 分页 - 每页数量 */
  pageSize?: number;
  /** 搜索范围：标题、内容、或全部 */
  scope?: 'title' | 'content' | 'all';
  /** 频道ID过滤 */
  channelId?: string;
}

// ==================== Repository 接口 ====================

export interface IPostRepository {
  // ==================== 帖子查询 ====================

  /**
   * 获取帖子列表
   * @param params 查询参数
   * @returns 帖子列表结果
   */
  getPosts(params?: GetPostsParams): Promise<PostsResult>;

  /**
   * 获取单个帖子详情
   * @param id 帖子ID
   * @returns 帖子实体，不存在则返回null
   */
  getPostById(id: string): Promise<Post | null>;

  /**
   * 获取用户发布的帖子列表
   * @param userId 用户ID
   * @param params 查询参数
   * @returns 帖子列表结果
   */
  getPostsByUser(userId: string, params?: GetPostsParams): Promise<PostsResult>;

  /**
   * 搜索帖子
   * @param params 搜索参数
   * @returns 帖子列表结果
   */
  searchPosts(params: SearchPostsParams): Promise<PostsResult>;

  // ==================== 帖子操作 ====================

  /**
   * 创建帖子
   * @param data 创建帖子数据
   * @returns 创建的帖子实体
   */
  createPost(data: CreatePostData): Promise<Post>;

  /**
   * 更新帖子
   * @param id 帖子ID
   * @param data 更新数据
   * @returns 更新后的帖子实体
   */
  updatePost(id: string, data: UpdatePostData): Promise<Post>;

  /**
   * 删除帖子
   * @param id 帖子ID
   */
  deletePost(id: string): Promise<void>;

  // ==================== 互动操作 ====================

  /**
   * 点赞帖子
   * @param id 帖子ID
   * @returns 更新后的帖子实体
   */
  likePost(id: string): Promise<Post>;

  /**
   * 取消点赞
   * @param id 帖子ID
   * @returns 更新后的帖子实体
   */
  unlikePost(id: string): Promise<Post>;

  /**
   * 收藏帖子
   * @param id 帖子ID
   * @returns 更新后的帖子实体
   */
  favoritePost(id: string): Promise<Post>;

  /**
   * 取消收藏
   * @param id 帖子ID
   * @returns 更新后的帖子实体
   */
  unfavoritePost(id: string): Promise<Post>;
}
