/**
 * Model.ts
 * 后端数据模型定义文件
 * 定义所有数据库实体模型，作为前后端开发的参考标准
 */

// ============================================================
// 基础审计字段 (所有模型通用)
// ============================================================

/**
 * 基础实体接口
 * 所有业务模型都应继承此接口，包含数据追踪所需的基础字段
 */
export interface BaseEntity {
    /** 全局唯一标识符 (GUID) */
    id: string;

    /** 创建时间 */
    createdAt: Date;

    /** 创建人ID */
    createdBy: string;

    /** 最后修改时间 */
    updatedAt: Date;

    /** 最后修改人ID */
    updatedBy: string;

    /** 是否已软删除 */
    isDeleted: boolean;
}

// ============================================================
// 1. 身份与权限模块
// ============================================================

/**
 * 用户实体
 * 统一的用户账户，包含学生、老师、管理员等不同角色
 */
export interface ApplicationUser extends BaseEntity {
    /** 真实姓名 */
    realName: string;

    /** 学号/工号 */
    studentId: string;

    /** 头像URL */
    avatarUrl: string;

    /** 性别：Male | Female | Unknown */
    gender: 'Male' | 'Female' | 'Unknown';

    /** 当前所属学校ID（冗余字段，用于快速确定用户主要归属） */
    currentSchoolId: string;

    /** 账号状态：Active | Disabled */
    accountStatus: 'Active' | 'Disabled';

    /** 邮箱（可选） */
    email?: string;

    /** 手机号（可选） */
    phone?: string;

    /** 个人简介 */
    bio?: string;
}

// ============================================================
// 2. 组织架构模块
// ============================================================

/**
 * 学校实体
 */
export interface School extends BaseEntity {
    /** 学校名称 */
    name: string;

    /** 行政区划代码（省市区） */
    regionCode: string;

    /** 详细地址 */
    address: string;
}

/**
 * 年级实体
 */
export interface Grade extends BaseEntity {
    /** 所属学校ID */
    schoolId: string;

    /** 年级名称 */
    name: string;

    /** 排序序号（用于前端显示顺序，如1=初一，2=初二） */
    sortOrder: number;

    /** 入学年份（用于每年自动计算年级名称） */
    enrollmentYear: number;
}

/**
 * 班级实体
 */
export interface Class extends BaseEntity {
    /** 所属年级ID */
    gradeId: string;

    /** 班级名称 */
    name: string;

    /** 邀请码（6位唯一字符） */
    inviteCode: string;

    /** 班主任ID */
    headTeacherId: string;
}

/**
 * 班级成员实体
 */
export interface ClassMember extends BaseEntity {
    /** 关联班级ID */
    classId: string;

    /** 关联用户ID */
    userId: string;

    /** 班内角色：Student | Teacher | HeadTeacher */
    roleInClass: 'Student' | 'Teacher' | 'HeadTeacher';

    /** 班级名片（用户在该班级显示的别名，如"张三-课代表"） */
    displayName?: string;
}

// ============================================================
// 3. 教材与知识图谱模块
// ============================================================

/**
 * 学科实体
 */
export interface Subject extends BaseEntity {
    /** 学科名称 */
    name: string;

    /** 学科代码（英文简写，如 MATH_JUNIOR） */
    code: string;

    /** 图标（可选） */
    icon?: string;
}

/**
 * 教材实体
 */
export interface Textbook extends BaseEntity {
    /** 所属学科ID */
    subjectId: string;

    /** 教材名称 */
    name: string;

    /** 封面图URL */
    coverUrl: string;

    /** 出版社 */
    publisher: string;

    /** 版本年份 */
    versionYear: string;
}

/**
 * 单元实体
 */
export interface TextbookUnit extends BaseEntity {
    /** 所属教材ID */
    textbookId: string;

    /** 单元名称 */
    name: string;

    /** 排序序号 */
    sortOrder: number;
}

/**
 * 课/小节实体
 */
export interface TextbookLesson extends BaseEntity {
    /** 所属单元ID */
    unitId: string;

    /** 课名称 */
    name: string;

    /** 排序序号 */
    sortOrder: number;
}

/**
 * 知识点实体
 */
export interface KnowledgePoint extends BaseEntity {
    /** 挂载课节ID（说明这个知识点是在哪一课学的） */
    lessonId: string;

    /** 父知识点ID（支持知识点的大点套小点结构，可选） */
    parentKnowledgePointId?: string;

    /** 知识点名称 */
    name: string;

    /** 难度系数（1-5星） */
    difficulty: number;

    /** 描述/口诀 */
    description?: string;
}

// ============================================================
// 4. 题库资源模块
// ============================================================

/**
 * 题目实体
 */
export interface Question extends BaseEntity {
    /** 所属学科ID */
    subjectId: string;

    /** 题干内容（HTML格式，包含文字、公式和图片链接） */
    content: string;

    /** 选项配置（JSON结构，存储选项内容） */
    optionsConfig?: string;

    /** 题目类型：SingleChoice | MultipleChoice | TrueFalse | FillBlank | Subjective */
    questionType: 'SingleChoice' | 'MultipleChoice' | 'TrueFalse' | 'FillBlank' | 'Subjective';

    /** 难度等级（1-5，默认为1） */
    difficulty: number;

    /** 标准答案（文本或JSON格式） */
    answer: string;

    /** 解析（HTML格式） */
    explanation?: string;

    /** 来源（如"2023海淀期末"） */
    source?: string;
}

/**
 * 题目-知识点关联实体
 */
export interface QuestionKnowledge extends BaseEntity {
    /** 关联题目ID */
    questionId: string;

    /** 关联知识点ID */
    knowledgePointId: string;

    /** 考察权重（0-100，表示该题目考察这个知识点的比重） */
    weight: number;
}

// ============================================================
// 5. 试卷工程模块
// ============================================================

/**
 * 试卷实体
 */
export interface Exam extends BaseEntity {
    /** 所属学科ID */
    subjectId: string;

    /** 试卷标题 */
    title: string;

    /** 总分 */
    totalScore: number;

    /** 建议时长（分钟） */
    suggestedDuration: number;

    /** 总题数 */
    totalQuestions: number;

    /** 状态：Draft | Published */
    status: 'Draft' | 'Published';
}

/**
 * 试卷结构节点实体（可嵌套）
 * 支持树形结构，既可以是分组节点，也可以是题目节点
 */
export interface ExamNode extends BaseEntity {
    /** 所属试卷ID */
    examId: string;

    /** 父节点ID（用于分组，如"第一部分 选择题"是父节点） */
    parentNodeId?: string;

    /** 节点类型：Group | Question */
    nodeType: 'Group' | 'Question';

    /** 关联题目ID（如果是题目节点） */
    questionId?: string;

    /** 设定分数（这道题在这张卷子里算多少分） */
    score: number;

    /** 排序序号（题号或分组顺序） */
    sortOrder: number;

    /** 描述（如果是分组节点，可以写"阅读理解"等说明） */
    description?: string;

    /** 子节点（前端使用，后端查询时填充） */
    children?: ExamNode[];
}

// ============================================================
// 6. 教学执行模块
// ============================================================

/**
 * 作业发布实体
 */
export interface Assignment extends BaseEntity {
    /** 使用试卷ID */
    examId: string;

    /** 发布人ID */
    publisherId: string;

    /** 作业名称 */
    title: string;

    /** 开始时间 */
    startTime: Date;

    /** 截止时间 */
    endTime: Date;

    /** 配置项（JSON格式，存储如"是否允许补交"、"考完是否立即出分"等开关） */
    configOptions?: string;

    /** 应交人数 */
    expectedSubmissions: number;

    /** 实交人数 */
    actualSubmissions: number;
}

/**
 * 学生提交记录实体
 */
export interface StudentSubmission extends BaseEntity {
    /** 所属作业ID */
    assignmentId: string;

    /** 学生ID */
    studentId: string;

    /** 当前状态：Pending | InProgress | Submitted | Graded */
    status: 'Pending' | 'InProgress' | 'Submitted' | 'Graded';

    /** 最终得分 */
    finalScore?: number;

    /** 提交时间 */
    submitTime?: Date;

    /** 耗时（秒） */
    timeSpent?: number;
}

/**
 * 答题详情实体
 */
export interface SubmissionDetail extends BaseEntity {
    /** 所属提交ID */
    submissionId: string;

    /** 对应试卷节点ID（说明这是哪一道题的答案） */
    examNodeId: string;

    /** 学生答案（文本或图片URL） */
    studentAnswer?: string;

    /** 批改数据（JSON格式，存储老师在Canvas画板上的红笔轨迹、圈阅痕迹） */
    gradingData?: string;

    /** 本题得分 */
    score?: number;

    /** 判题结果：Correct | Incorrect | Partial */
    judgement?: 'Correct' | 'Incorrect' | 'Partial';

    /** 老师评语 */
    teacherComment?: string;
}

// ============================================================
// 辅助类型定义
// ============================================================

/**
 * 性别枚举
 */
export enum Gender {
    Male = 'Male',
    Female = 'Female',
    Unknown = 'Unknown'
}

/**
 * 账号状态枚举
 */
export enum AccountStatus {
    Active = 'Active',
    Disabled = 'Disabled'
}

/**
 * 班级角色枚举
 */
export enum ClassRole {
    Student = 'Student',
    Teacher = 'Teacher',
    HeadTeacher = 'HeadTeacher'
}

/**
 * 题目类型枚举
 */
export enum QuestionType {
    SingleChoice = 'SingleChoice',
    MultipleChoice = 'MultipleChoice',
    TrueFalse = 'TrueFalse',
    FillBlank = 'FillBlank',
    Subjective = 'Subjective'
}

/**
 * 试卷状态枚举
 */
export enum ExamStatus {
    Draft = 'Draft',
    Published = 'Published'
}

/**
 * 节点类型枚举
 */
export enum NodeType {
    Group = 'Group',
    Question = 'Question'
}

/**
 * 提交状态枚举
 */
export enum SubmissionStatus {
    Pending = 'Pending',
    InProgress = 'InProgress',
    Submitted = 'Submitted',
    Graded = 'Graded'
}

/**
 * 判题结果枚举
 */
export enum JudgementResult {
    Correct = 'Correct',
    Incorrect = 'Incorrect',
    Partial = 'Partial'
}