# 从 pydantic 导入 BaseModel（模型基类）和 ConfigDict（模型配置）
from pydantic import BaseModel, ConfigDict
# 导入日期类型，用于 birthday、enrollment_date 等字段
from datetime import date
# 导入 Optional，用于声明可选字段（可为 None）
from typing import Optional
# 从自定义枚举模块导入学生状态、性别、学历层次枚举
from enums import StudentStatusEnum, GenderEnum, EducationLevelEnum

# Optional 类型层面的声明，告诉 Pydantic：这个字段可以是 None

# ========================     学生        ==========================
# 学生信息请求体：用于新增/修改学生时的入参校验
class stu_info_req(BaseModel):
    student_id: str                 # 学号
    student_name: str               # 学生姓名
    gender: GenderEnum              # 性别（枚举：0=女，1=男）
    id_card: str                    # 身份证号码
    birthday: date                  # 出生日期
    ethnicity: str                  # 民族
    region_id: str                  # 籍贯地区编码
    phone: str                      # 手机号码
    graduation_school: str          # 毕业学校
    major: str                      # 就读专业
    class_id: str                   # 所在班级
    enrollment_date: date           # 入学日期
    graduation_date: date           # 毕业日期
    student_status: StudentStatusEnum  # 学籍状态（枚举：0=在读，1=休学，2=退学，3=毕业，4=结业）
    education_level: EducationLevelEnum  # 学历层次（枚举：1=大专，2=本科，3=硕士，4=博士）

# 学生信息响应体：用于查询学生时的出参序列化
class stu_info_resp(BaseModel):
    student_id: str                 # 学号
    student_name: str               # 学生姓名
    gender: GenderEnum              # 性别
    id_card: str                    # 身份证号码
    birthday: Optional[date] = None         # 出生日期（可空）
    ethnicity: Optional[str] = None         # 民族（可空）
    region_id: Optional[str] = None         # 籍贯地区编码（可空）
    phone: Optional[str] = None             # 手机号码（可空）
    graduation_school: Optional[str] = None # 毕业学校（可空）
    major: str                      # 就读专业
    class_id: str                   # 所在班级
    enrollment_date: Optional[date] = None  # 入学日期（可空）
    graduation_date: Optional[date] = None  # 毕业日期（可空）
    student_status: StudentStatusEnum       # 学籍状态
    education_level: EducationLevelEnum     # 学历层次

    # 配置：允许从 ORM 对象属性中读取数据（配合 from_attributes=True）
    model_config = ConfigDict(from_attributes=True)

# 学生信息增删改操作的统一响应体
class stu_info_add_resp(BaseModel):
    code: int                       # 状态码，200 表示成功
    message: Optional[str] = None   # 提示信息（可空）

# ========================     地区        ==========================
# 地区维度表 添加请求体：用于新增地区时的入参校验
class region_req(BaseModel):
    code: str                       # 地区编码
    province: str                   # 省 / 直辖市
    city: str                       # 市
    district: str                   # 区 / 县

# 地区维度表 修改请求体：所有字段均可选，code 不在修改范围内
class region_update_req(BaseModel):
    province: Optional[str] = None  # 省 / 直辖市（可选）
    city: Optional[str] = None      # 市（可选）
    district: Optional[str] = None  # 区 / 县（可选）

# 地区维度 响应体：用于查询地区时的出参序列化
class region_resp(BaseModel):
    code: str                       # 地区编码
    province: str                   # 省 / 直辖市
    city: str                       # 市
    district: str                   # 区 / 县

    # 配置：允许从 ORM 对象属性中读取数据
    model_config = ConfigDict(from_attributes=True)

# 地区增删改操作的统一响应体
class region_add_resp(BaseModel):
    code: int                       # 状态码，200 表示成功
    message: Optional[str] = None   # 提示信息（可空）