/**
 * @description 学习相关类型定义
 * @author yslg
 * @since 2025-10-15
 */

import type { BaseDTO } from '@/types';
import type { Tag } from '@/types/resource';


/**
 * 课程实体
 */
export interface Course extends BaseDTO {
  /** 课程唯一标识 */
  courseID?: string;
  /** 课程名称 */
  name?: string;
  /** 课程封面图片 */
  coverImage?: string;
  /** 课程描述 */
  description?: string;
  /** 课程内容 */
  content?: string;
  /** 课程时长（分钟） */
  duration?: number;
  /** 授课老师 */
  teacher?: string;
  /** 状态（0未上线 1已上线 2已下架） */
  status?: number;
  /** 浏览次数 */
  viewCount?: number;
  /** 学习人数 */
  learnCount?: number;
  /** 排序号 */
  orderNum?: number;
  /** 创建者 */
  creator?: string;
  /** 更新者 */
  updater?: string;
}

/**
 * 课程章节实体
 */
export interface CourseChapter extends BaseDTO {
  /** 章节ID */
  chapterID?: string;
  /** 课程ID */
  courseID?: string;
  /** 父章节ID */
  parentID?: string;
  /** 章节名称 */
  name?: string;
  /** 章节内容 */
  content?: string;
  /** 章节类型（1视频 2文档 3音频） */
  chapterType?: number;
  /** 资源ID */
  resourceID?: string;
  /** 视频URL */
  videoUrl?: string;
  /** 章节时长（分钟） */
  duration?: number;
  /** 排序号 */
  orderNum?: number;
  /** 创建者 */
  creator?: string;
  /** 更新者 */
  updater?: string;
}

/**
 * 课程标签关联实体
 * 
 * 说明：课程标签使用统一的标签系统（tb_tag表）
 * - 使用 tagType=2 表示课程分类标签
 * - 通过 resourceTagApi.getTagsByType(2) 或 resourceTagApi.getTagsByType(TagType.COURSE_CATEGORY) 获取课程分类标签
 * 
 * @see Tag - 标签实体定义
 * @see TagType - 标签类型枚举（COURSE_CATEGORY = 2）
 */
export interface CourseTag extends BaseDTO {
  /** 课程ID */
  courseID?: string;
  /** 标签ID（关联 tb_tag 表，tagType=2 的标签） */
  tagID?: string;
  /** 创建者 */
  creator?: string;
}

/**
 * 学习节点实体
 */
export interface CourseNode extends BaseDTO {
  /** 章节ID */
  chapterID?: string;
  /** 节点ID */
  nodeID?: string;
  /** 节点名称 */
  name?: string;
  /** 节点内容 */
  content?: string;
  /** 节点类型（0文章资源 1富文本 2其他上传文件） */
  nodeType?: number;
  /** 资源ID */
  resourceID?: string;
  /** 视频URL */
  videoUrl?: string;
  /** 节点时长（分钟） */
  duration?: number;
  /** 排序号 */
  orderNum?: number;
  /** 是否必修（1必修 0选修） */
  isRequired?: number;
  /** 创建者 */
  creator?: string;
  /** 更新者 */
  updater?: string;
}

/**
 * 课程项目VO - 统一的课程视图对象
 * 包含课程、章节、学习节点、学习记录的字段
 */
export interface CourseItemVO extends BaseDTO {
  // ========== 课程基本信息 ==========
  /** 课程ID */
  courseID?: string;
  /** 课程名称 */
  name?: string;
  /** 课程封面图片 */
  coverImage?: string;
  /** 课程描述 */
  description?: string;
  /** 课程时长（分钟） */
  duration?: number;
  /** 授课老师 */
  teacher?: string;
  /** 课程状态（0未上线 1已上线 2已下架） */
  status?: number;
  /** 浏览次数 */
  viewCount?: number;
  /** 学习人数 */
  learnCount?: number;
  /** 课程创建时间 */
  createTime?: string;

  // ========== 学习记录信息 ==========
  /** 学习记录ID */
  recordID?: string;
  /** 学习进度（0-100） */
  progress?: number;
  /** 是否完成 */
  isComplete?: boolean;
  /** 学习时长（秒） */
  learningDuration?: number;
  /** 最后学习时间 */
  lastLearnTime?: string;
  /** 完成时间 */
  completeTime?: string;

  // ========== 章节节点信息 ==========
  /** 章节ID（当此对象代表章节或节点时使用） */
  chapterID?: string;
  /** 节点ID（当此对象代表节点时使用） */
  nodeID?: string;
  /** 父级ID（章节的父章节ID） */
  parentID?: string;
  /** 节点类型（1视频 2文档 3音频 4图片 5链接） */
  nodeType?: number;
  /** 节点内容（富文本内容） */
  content?: string;
  /** 视频URL */
  videoUrl?: string;
  /** 资源ID */
  resourceID?: string;
  /** 排序号 */
  orderNum?: number;
  /** 是否必修（1必修 0选修） */
  isRequired?: number;

  // ========== 层级结构 ==========
  /** 章节列表（课程的章节列表，或章节的节点列表） */
  chapters?: CourseItemVO[];
  /** 章节节点映射（key: chapterID, value: 该章节下的节点列表） */
  chapterNodes?: Record<string, CourseItemVO[]>;
}

/**
 * 学习任务实体
 * 
 * 说明：学习任务分类使用统一的标签系统（tb_tag表）
 * - 使用 tagType=3 表示学习任务分类标签
 * - 通过 resourceTagApi.getTagsByType(3) 或 resourceTagApi.getTagsByType(TagType.LEARNING_TASK_CATEGORY) 获取学习任务分类标签
 * 
 * @see Tag - 标签实体定义
 * @see TagType - 标签类型枚举（LEARNING_TASK_CATEGORY = 3）
 */
export interface LearningTask extends BaseDTO {
  /** 任务唯一标识 */
  taskID?: string;
  /** 任务名称 */
  name?: string;
  /** 任务描述 */
  description?: string;
  /** 开始时间 */
  startTime?: string;
  /** 结束时间 */
  endTime?: string;
  /** 状态（0草稿 1进行中 2已结束） */
  status?: number;
  /** 创建者 */
  creator?: string;
  /** 更新者 */
  updater?: string;
}

/**
 * 学习记录实体
 */
export interface LearningRecord extends BaseDTO {
  /** 用户ID */
  userID?: string;
  /** 任务ID */
  taskID?: string;
  /** 资源类型（1资源 2课程 3章节） */
  resourceType?: number;
  /** 资源ID */
  resourceID?: string;
  /** 课程ID */
  courseID?: string;
  /** 章节ID */
  chapterID?: string;
  /** 节点ID */
  nodeID?: string;
  /** 学习时长（秒） */
  duration?: number;
  /** 学习进度（0-100） */
  progress?: number;
  /** 是否完成 */
  isComplete?: boolean;
  /** 完成时间 */
  completeTime?: string;
  /** 最后学习时间 */
  lastLearnTime?: string;
}

/**
 * 学习统计实体
 */
export interface LearningStatistics extends BaseDTO {
  /** 用户ID */
  userID?: string;
  /** 统计日期 */
  statisticsDate?: string;
  /** 学习时长（秒） */
  totalDuration?: number;
  /** 学习资源数 */
  resourceCount?: number;
  /** 完成任务数 */
  taskCount?: number;
  /** 获得积分 */
  points?: number;
}

/**
 * 任务用户关联实体
 */
export interface TaskUser extends BaseDTO {
  /** 任务ID */
  taskID?: string;
  /** 用户ID */
  userID?: string;
  /** 完成状态（0未完成 1已完成） */
  status?: number;
  /** 学习进度 */
  progress?: number;
  /** 完成时间 */
  completeTime?: string;
}

/**
 * 任务项实体（统一管理资源和课程）
 */
export interface TaskItem extends BaseDTO {
  /** 任务ID */
  taskID?: string;
  /** 项类型（1资源 2课程） */
  itemType?: number;
  /** 项ID（资源ID或课程ID） */
  itemID?: string;
  /** 是否必须完成 */
  required?: boolean;
  /** 排序号 */
  orderNum?: number;
  /** 创建者 */
  creator?: string;
  /** 更新者 */
  updater?: string;
}

/**
 * 任务项视图对象（扩展了任务基本信息）
 */
export interface TaskItemVO extends LearningTask {
  /** 项类型（1资源 2课程） */
  itemType?: number;
  /** 课程ID */
  courseID?: string;
  /** 课程名称 */
  courseName?: string;
  /** 资源ID */
  resourceID?: string;
  /** 资源名称 */
  resourceName?: string;
  /** 用户ID */
  userID?: string;
  /** 用户名 */
  username?: string;
  deptID?: string;
  deptName?: string;
  parentID?: string;
  /** 是否必修 */
  required?: boolean;
  /** 排序号 */
  orderNum?: number;
  /** 任务状态 */
  status?: number;
  /** 学习进度（0-100） */
  progress?: number;
  /** 完成时间 */
  completeTime?: string;
  /** 封面图片（用于搜索结果展示） */
  coverImage?: string;
  /** 简介（用于搜索结果展示） */
  summary?: string;
  /** 作者（用于搜索结果展示） */
  author?: string;
  /** 浏览次数（用于搜索结果展示） */
  viewCount?: number;
  /** 发布时间（用于搜索结果展示） */
  publishTime?: Date | string;
}

/**
 * 任务视图对象（包含任务及关联的课程、资源、用户）
 */
export interface TaskVO extends BaseDTO {
  /** 学习任务基本信息 */
  learningTask: LearningTask;
  /** 任务关联的课程列表 */
  taskCourses: TaskItemVO[];
  /** 任务关联的资源列表 */
  taskResources: TaskItemVO[];
  /** 任务关联的用户列表 */
  taskUsers: TaskItemVO[];
  /** 任务关联的标签列表 */
  taskTags?: Tag[];
  /** 总任务数 */
  totalTaskNum?: number;
  /** 已完成任务数 */
  completedTaskNum?: number;
  /** 学习中任务数 */
  learningTaskNum?: number;
  /** 未开始任务数 */
  notStartTaskNum?: number;
  /** 任务状态 */
  taskStatus?: number;
}

/**
 * 学习计划实体
 */
export interface LearningPlan extends BaseDTO {
  /** 计划名称 */
  name?: string;
  /** 计划描述 */
  description?: string;
  /** 开始时间 */
  startTime?: string;
  /** 结束时间 */
  endTime?: string;
  /** 状态（0草稿 1进行中 2已结束） */
  status?: number;
  /** 创建者 */
  creator?: string;
}

/**
 * 学习进度统计
 */
export interface LearningProgress {
  /** 用户ID */
  userID?: string;
  /** 任务ID */
  taskID?: string;
  /** 总任务数 */
  totalTasks?: number;
  /** 已完成任务数 */
  completedTasks?: number;
  /** 完成百分比 */
  completionRate?: number;
  /** 学习时长 */
  totalDuration?: number;
}

/**
 * 学习记录统计
 */
export interface LearningRecordStatistics {
  /** 日期 */
  date?: string;
  /** 学习时长 */
  duration?: number;
  /** 学习资源数 */
  resourceCount?: number;
  /** 完成任务数 */
  taskCount?: number;
}

/**
 * 学习观看历史表
 */
export interface TbLearningHistory extends BaseDTO {
  /** 用户ID */
  userID?: string;
  /** 学习会话ID */
  historyID?: string;
  /** 资源类型（1资源/新闻 2课程 3章节 4节点） */
  resourceType?: number;
  /** 资源ID */
  resourceID?: string;
  /** 课程ID */
  courseID?: string;
  /** 章节ID */
  chapterID?: string;
  /** 节点ID */
  nodeID?: string;
  /** 关联任务ID */
  taskID?: string;
  /** 开始学习时间 */
  startTime?: string;
  /** 结束学习时间 */
  endTime?: string;
  /** 本次学习时长（秒） */
  duration?: number;
  /** 开始进度（0-100） */
  startProgress?: number;
  /** 结束进度（0-100） */
  endProgress?: number;
  /** 设备类型（web/mobile/app） */
  deviceType?: string;
  /** IP地址 */
  ipAddress?: string;
  /** 创建者 */
  creator?: string;
}

/**
 * 学习统计明细表
 */
export interface TbLearningStatisticsDetail extends BaseDTO {
  /** 用户ID */
  userID?: string;
  /** 统计日期 */
  statDate?: string;
  /** 资源类型（1资源/新闻 2课程 3章节） */
  resourceType?: number;
  /** 资源ID */
  resourceID?: string;
  /** 课程ID */
  courseID?: string;
  /** 章节ID */
  chapterID?: string;
  /** 学习时长（秒） */
  totalDuration?: number;
  /** 学习次数 */
  learnCount?: number;
  /** 是否完成 */
  isComplete?: boolean;
  /** 完成时间 */
  completeTime?: string;
  /** 创建者 */
  creator?: string;
  /** 更新者 */
  updater?: string;
}

/**
 * 学习历史响应VO
 */
export interface LearningHistoryVO {
  /** 历史记录ID */
  id?: string;
  /** 用户ID */
  userID?: string;
  /** 用户名称（关联查询） */
  userName?: string;
  /** 学习会话ID */
  sessionID?: string;
  /** 资源类型（1资源/新闻 2课程 3章节 4节点） */
  resourceType?: number;
  /** 资源类型名称 */
  resourceTypeName?: string;
  /** 资源ID */
  resourceID?: string;
  /** 资源标题（关联查询） */
  resourceTitle?: string;
  /** 课程ID */
  courseID?: string;
  /** 课程名称（关联查询） */
  courseName?: string;
  /** 章节ID */
  chapterID?: string;
  /** 章节名称（关联查询） */
  chapterName?: string;
  /** 节点ID */
  nodeID?: string;
  /** 节点名称（关联查询） */
  nodeName?: string;
  /** 关联任务ID */
  taskID?: string;
  /** 任务名称（关联查询） */
  taskName?: string;
  /** 开始学习时间 */
  startTime?: string;
  /** 结束学习时间 */
  endTime?: string;
  /** 本次学习时长（秒） */
  duration?: number;
  /** 学习时长（格式化后，如：1小时20分钟） */
  durationFormatted?: string;
  /** 开始进度（0-100） */
  startProgress?: number;
  /** 结束进度（0-100） */
  endProgress?: number;
  /** 设备类型 */
  deviceType?: string;
  /** 创建时间 */
  createTime?: string;
}

/**
 * 学习统计明细VO
 */
export interface LearningStatisticsDetailVO {
  /** 统计日期 */
  statDate?: string;
  /** 资源类型（1资源/新闻 2课程 3章节） */
  resourceType?: number;
  /** 资源类型名称 */
  resourceTypeName?: string;
  /** 资源ID */
  resourceID?: string;
  /** 资源标题 */
  resourceTitle?: string;
  /** 课程ID */
  courseID?: string;
  /** 课程名称 */
  courseName?: string;
  /** 章节ID */
  chapterID?: string;
  /** 章节名称 */
  chapterName?: string;
  /** 学习时长（秒） */
  totalDuration?: number;
  /** 学习时长（格式化） */
  totalDurationFormatted?: string;
  /** 学习次数 */
  learnCount?: number;
  /** 是否完成 */
  isComplete?: boolean;
  /** 完成时间 */
  completeTime?: string;
}

/**
 * 学习统计响应VO
 */
export interface LearningStatisticsVO {
  /** 用户ID */
  userID?: string;
  /** 统计周期（day/week/month） */
  period?: string;
  /** 总学习时长（秒） */
  totalDuration?: number;
  /** 总学习时长（格式化） */
  totalDurationFormatted?: string;
  /** 学习天数 */
  learnDays?: number;
  /** 学习资源数量 */
  resourceCount?: number;
  /** 学习课程数量 */
  courseCount?: number;
  /** 学习次数 */
  learnCount?: number;
  /** 完成数量 */
  completeCount?: number;
  /** 平均每天学习时长（秒） */
  avgDailyDuration?: number;
  /** 学习明细列表 */
  details?: LearningStatisticsDetailVO[];
}