Edu/packages/shared-ts/contracts/graphql/parent-bff.graphql

# parent-bff GraphQL Schema（SDL 契约，对齐 02-architecture-design.md §4.2）
#
# 本文件是 parent-bff GraphQL 端点的契约唯一源（single source of truth）。
# - 前端 parent-portal 引用本文件生成 TypeScript 类型
# - 后端 parent-bff 引用本文件加载为 GraphQLSchema
# - CI 强制检测 breaking change（与 main 分支对比）
#
# 仲裁依据：
# - U3：GraphQL P2 立即引入（parent-bff P4 直接用 GraphQL，不走 REST 过渡）
# - C1：错误码前缀 BFF_PARENT_
# - U4：BFF 豁免 @RequirePermission，仅校验 x-user-id + ChildGuard
# - 02 §9 #5：depth ≤ 7 / cost ≤ 1000
#
# 版本：v2（32 Query + 6 Mutation，对齐 parent-portal 全部 operations）

scalar DateTime
scalar JSON

# ============ Legacy Types ============

type Parent {
  id: ID!
  email: String!
  name: String!
  avatar: String
  roles: [String!]!
  permissions: [String!]
  dataScope: DataScope!
  schoolId: ID
}

enum DataScope {
  SELF
  CHILDREN
  CLASS
  GRADE
  SCHOOL
  DISTRICT
  ALL
}

type ViewportItem {
  key: String!
  label: String!
  route: String!
  icon: String
  sortOrder: String!
  requiredPermission: String
}

type Child {
  id: ID!
  name: String!
  grade: String!
  class: ClassInfo!
  lastGrade: Grade
  grades(page: Int = 1, pageSize: Int = 20, subject: String): GradePage!
  homework: [Homework!]!
  exams: [Exam!]!
  analytics: ChildAnalytics!
}

type ClassInfo {
  id: ID!
  name: String!
  gradeId: String!
}

type Grade {
  id: ID!
  examId: ID!
  examTitle: String!
  subject: String!
  score: Float!
  rank: Int
  gradedAt: DateTime!
}

type GradePage {
  items: [Grade!]!
  pagination: Pagination!
}

type Pagination {
  page: Int!
  pageSize: Int!
  total: Int!
}

type Homework {
  id: ID!
  title: String!
  classId: ID!
  dueDate: DateTime!
  status: HomeworkStatus!
  submittedAt: DateTime
}

enum HomeworkStatus {
  NOT_SUBMITTED
  SUBMITTED
  GRADED
  OVERDUE
}

type Exam {
  id: ID!
  title: String!
  classId: ID!
  status: ExamStatus!
  examDate: DateTime!
  publishedAt: DateTime
}

enum ExamStatus {
  DRAFT
  PUBLISHED
  IN_PROGRESS
  GRADING
  SCORED
  ARCHIVED
}

type ChildAnalytics {
  childId: ID!
  weakness: [WeaknessTopic!]!
  trend: [TrendPoint!]!
  classRank: Int
  classAverage: Float
}

type WeaknessTopic {
  knowledgePointId: ID!
  name: String!
  subject: String!
  masteryRate: Float!
}

type TrendPoint {
  date: DateTime!
  score: Float!
  subject: String
}

type Notification {
  id: ID!
  type: NotificationType!
  title: String!
  content: String!
  read: Boolean!
  childId: ID
  createdAt: DateTime!
}

enum NotificationType {
  SYSTEM
  EXAM
  HOMEWORK
  GRADE
  ATTENDANCE
  ANNOUNCEMENT
}

type NotificationPreferences {
  channels: [NotificationChannel!]!
  eventTypes: NotificationEventTypes!
}

enum NotificationChannel {
  APP
  SMS
  EMAIL
  WECHAT
}

type NotificationEventTypes {
  gradeReleased: Boolean!
  homeworkGraded: Boolean!
  examPublished: Boolean!
  attendanceAlert: Boolean!
  schoolAnnouncement: Boolean!
}

type DashboardData {
  parent: Parent
  children: [Child!]!
  viewports: [ViewportItem!]!
  unreadNotifications: Int!
  degraded: Boolean!
}

# ============ Extended Types（v2 新增） ============

type ChildBrief {
  id: ID!
  name: String!
  grade: String!
  classId: ID
  className: String
  avatar: String
}

type ChildSummary {
  childId: ID!
  avgScore: Float
  classRank: Int
  classSize: Int
  attendanceRate: Float
  pendingHomeworkCount: Int!
  recentGradeTrend: Float
  recentScores: [ChildGrade!]!
  upcomingEvents: [UpcomingEvent!]!
}

type UpcomingEvent {
  id: ID!
  type: String!
  title: String!
  dueDate: DateTime!
}

type ChildDetail {
  childId: ID!
  basicInfo: ChildBasicInfo!
  todaySchedule: [JSON!]!
  weeklySchedule: [JSON!]!
  homeworkSummary: HomeworkSummary!
  gradeSummary: GradeSummary!
  examResults: ExamResultSummary!
}

type ChildBasicInfo {
  name: String!
  avatar: String
  grade: String!
  className: String!
  schoolName: String!
  relation: String!
}

type HomeworkSummary {
  pendingCount: Int!
  overdueCount: Int!
  submittedCount: Int!
  gradedCount: Int!
}

type GradeSummary {
  avgScore: Float!
  classRank: Int
  classSize: Int
  trend: Float
}

type ExamResultSummary {
  upcoming: Int!
  completed: Int!
  avgScore: Float
}

type ChildGrade {
  examId: ID!
  examName: String!
  examDate: DateTime!
  subject: String!
  studentScore: Float!
  classAverage: Float
  classMax: Float
  classMin: Float
  gradeLevel: String
}

type ChildHomework {
  id: ID!
  title: String!
  subject: String!
  className: String!
  assignedDate: DateTime!
  dueDate: DateTime!
  status: String!
  score: Float
  maxScore: Float
  feedback: String
}

type ChildExam {
  id: ID!
  name: String!
  subject: String!
  status: String!
  startsAt: DateTime!
  expiresAt: DateTime
  durationSeconds: Int
  questionCount: Int
  totalScore: Float
  submittedAt: DateTime
}

type AttendanceRecord {
  id: ID!
  date: DateTime!
  status: String!
  checkInTime: DateTime
  checkOutTime: DateTime
  note: String
}

type ExamResult {
  examId: ID!
  childId: ID!
  score: Float
  rank: Int
  subjectScores: [SubjectScore!]!
  feedback: String
}

type SubjectScore {
  subject: String!
  score: Float!
  fullScore: Float!
}

type ChildClass {
  id: ID!
  name: String!
  homeroomTeacher: String
  studentCount: Int
  grade: String!
  year: String
}

type ReportCard {
  childId: ID!
  academicYearId: ID!
  semester: Int!
  subjects: [ReportCardSubject!]!
  overallComment: String
  classRank: Int
}

type ReportCardSubject {
  subject: String!
  score: Float!
  grade: String!
  teacherComment: String
}

type GrowthArchive {
  childId: ID!
  subject: String
  dataPoints: [GrowthDataPoint!]!
}

type GrowthDataPoint {
  date: DateTime!
  category: String!
  title: String!
  description: String!
  evidence: String
}

type WeaknessItem {
  id: ID!
  knowledgePoint: String!
  masteryLevel: Float!
  subject: String!
  recommendation: String
}

type ChildTrend {
  childId: ID!
  period: TrendPeriod!
  dataPoints: [TrendDataPoint!]!
}

type TrendDataPoint {
  date: DateTime!
  score: Float!
  subject: String
}

type LearningPathItem {
  id: ID!
  title: String!
  subject: String!
  order: Int!
  masteryLevel: Float!
  resources: [String!]!
}

type ErrorBookStats {
  childId: ID!
  totalCount: Int!
  newCount: Int!
  learningCount: Int!
  masteredCount: Int!
  dueReviewCount: Int!
  masteredRate: Float!
}

type WrongQuestion {
  id: ID!
  questionId: ID!
  subject: String!
  content: String!
  wrongAnswer: String!
  correctAnswer: String!
  addedAt: DateTime!
  status: String!
}

type WeakKp {
  id: ID!
  knowledgePoint: String!
  subject: String!
  masteryLevel: Float!
  recommendation: String
}

type MasterySummary {
  childId: ID!
  overallMastery: Float!
  subjectMastery: [SubjectMastery!]!
  totalKps: Int!
  masteredKps: Int!
}

type SubjectMastery {
  subject: String!
  mastery: Float!
  totalKps: Int!
  masteredKps: Int!
}

type DiagnosticReport {
  id: ID!
  childId: ID!
  subject: String!
  reportDate: DateTime!
  summary: String!
  recommendations: [String!]!
}

type PracticeStats {
  childId: ID!
  totalSessions: Int!
  completedSessions: Int!
  totalQuestionsAnswered: Int!
  overallAccuracy: Float!
}

type PracticeSession {
  id: ID!
  childId: ID!
  subject: String!
  startedAt: DateTime!
  completedAt: DateTime
  questionCount: Int!
  correctCount: Int!
  accuracy: Float!
}

type CoursePlan {
  id: ID!
  childId: ID!
  subject: String!
  title: String!
  startDate: DateTime!
  endDate: DateTime!
  progress: Float!
}

type CoursePlanDetail {
  id: ID!
  childId: ID!
  subject: String!
  title: String!
  startDate: DateTime!
  endDate: DateTime!
  progress: Float!
  lessons: [CoursePlanLesson!]!
}

type CoursePlanLesson {
  id: ID!
  title: String!
  date: DateTime!
  completed: Boolean!
}

type LessonPlan {
  id: ID!
  childId: ID!
  subject: String!
  title: String!
  date: DateTime!
  teacherName: String!
}

type LessonPlanDetail {
  id: ID!
  childId: ID!
  subject: String!
  title: String!
  date: DateTime!
  teacherName: String!
  objectives: [String!]!
  content: String!
  homework: String
}

type ElectiveCourse {
  id: ID!
  childId: ID!
  name: String!
  subject: String!
  teacher: String!
  schedule: String!
  selected: Boolean!
}

type LeaveRequestItem {
  id: ID!
  childId: ID!
  childName: String
  className: String
  type: String!
  startDate: DateTime!
  endDate: DateTime!
  reason: String!
  status: String!
  submittedAt: DateTime!
  reviewedAt: DateTime
  reviewerName: String
  reviewComment: String
}

type AcademicYear {
  id: ID!
  name: String!
  startDate: DateTime!
  endDate: DateTime!
  isCurrent: Boolean!
}

type MyNotification {
  id: ID!
  childId: ID
  eventType: String!
  title: String!
  body: String!
  read: Boolean!
  createdAt: DateTime!
  actionUrl: String
  pinned: Boolean!
}

type MyNotificationPreferences {
  parentId: ID!
  preferences: JSON!
  defaults: NotificationPreferencesDefaults!
  updatedAt: DateTime
}

type NotificationPreferencesDefaults {
  channels: [NotificationChannel!]!
  eventTypes: NotificationEventTypes!
}

type MarkAsReadResult {
  id: ID!
  read: Boolean!
}

type MarkAllAsReadResult {
  count: Int!
}

type SwitchChildResult {
  childId: ID!
  childName: String!
  selectedAt: DateTime!
}

type ExportChildGradesResult {
  downloadUrl: String!
  expiresAt: DateTime!
}

type UpdateNotificationPreferencesResult {
  parentId: ID!
  updatedAt: DateTime!
}

# ============ Query（32 个） ============

type Query {
  # Legacy（11 个）
  dashboard: DashboardData!
  viewports: [ViewportItem!]!
  me: Parent!
  children: [Child!]!
  child(childId: ID!): Child
  childGrades(
    childId: ID!
    page: Int = 1
    pageSize: Int = 20
    subject: String
  ): GradePage!
  childHomework(childId: ID!): [Homework!]!
  childExams(childId: ID!): [Exam!]!
  childAnalytics(childId: ID!, dateRange: DateRangeInput): ChildAnalytics!
  notifications(
    unreadOnly: Boolean
    page: Int = 1
    pageSize: Int = 20
  ): [Notification!]!
  notificationPreferences: NotificationPreferences!

  # Extended（21 个）
  currentUser: Parent!
  myChildren: [ChildBrief!]!
  childSummary(childId: ID!): ChildSummary
  childDetail(childId: ID!): ChildDetail
  childAttendance(
    childId: ID!
    startDate: DateTime!
    endDate: DateTime!
  ): [AttendanceRecord!]!
  childExamResult(childId: ID!, examId: ID!): ExamResult
  childClasses(childId: ID!): [ChildClass!]!
  childReportCard(
    childId: ID!
    academicYearId: ID!
    semester: Int!
  ): ReportCard
  childGrowthArchive(childId: ID!, subject: String): GrowthArchive!
  childWeakness(childId: ID!): [WeaknessItem!]!
  childTrend(childId: ID!, period: TrendPeriod!): ChildTrend!
  childLearningPath(childId: ID!): [LearningPathItem!]!
  childErrorBookStats(childId: ID!): ErrorBookStats!
  childTopWrongQuestions(childId: ID!, limit: Int): [WrongQuestion!]!
  childWeakKps(childId: ID!, limit: Int): [WeakKp!]!
  childMasterySummary(childId: ID!): MasterySummary!
  childDiagnosticReports(childId: ID!): [DiagnosticReport!]!
  childPracticeStats(childId: ID!): PracticeStats!
  childPracticeSessions(childId: ID!, limit: Int): [PracticeSession!]!
  childCoursePlans(childId: ID!): [CoursePlan!]!
  childCoursePlanDetail(childId: ID!, planId: ID!): CoursePlanDetail
  childLessonPlans(childId: ID!, subject: String): [LessonPlan!]!
  childLessonPlanDetail(childId: ID!, planId: ID!): LessonPlanDetail
  childElective(childId: ID!): [ElectiveCourse!]!
  childLeaveRequests(childId: ID!): [LeaveRequestItem!]!
  academicYears: [AcademicYear!]!
  myNotifications(unreadOnly: Boolean, limit: Int): [MyNotification!]!
  myNotificationPreferences: MyNotificationPreferences!
}

# ============ Mutation（6 个） ============

type Mutation {
  # Legacy（3 个）
  selectChild(childId: ID!): SelectChildResult!
  markNotificationRead(notificationId: ID!): Notification!
  updateNotificationPreferences(
    input: UpdateNotificationPreferencesInput!
  ): NotificationPreferences!

  # Extended（6 个新 mutation，覆盖前端全部操作）
  markAsRead(notificationId: ID!): MarkAsReadResult!
  markAllAsRead: MarkAllAsReadResult!
  switchChild(childId: ID!): SwitchChildResult!
  updateMyNotificationPreferences(
    parentId: ID!
    preferences: JSON!
    defaults: JSON
  ): UpdateNotificationPreferencesResult!
  createLeaveRequest(input: LeaveRequestInput!): LeaveRequestItem!
  exportChildGrades(childId: ID!, subject: String): ExportChildGradesResult!
}

# ============ Inputs ============

input DateRangeInput {
  start: DateTime!
  end: DateTime!
}

enum TrendPeriod {
  WEEK
  MONTH
  SEMESTER
  YEAR
}

input UpdateNotificationPreferencesInput {
  channels: [NotificationChannel!]!
  eventTypes: NotificationEventTypesInput!
}

input NotificationEventTypesInput {
  gradeReleased: Boolean
  homeworkGraded: Boolean
  examPublished: Boolean
  attendanceAlert: Boolean
  schoolAnnouncement: Boolean
}

input LeaveRequestInput {
  childId: ID!
  type: String!
  startDate: DateTime!
  endDate: DateTime!
  reason: String!
}

type SelectChildResult {
  childId: ID!
  selectedAt: DateTime!
  audited: Boolean!
}