@octo-cyber/quiz-engine 0.5.0

package/web/services/attempt-service.ts

@@ -0,0 +1,53 @@
+import { api } from '@octo-cyber/ui/services/api-client'
+import type { ApiResponse } from '@octo-cyber/ui/types/common'
+import type { QuizAttempt, QuizAnswer, AttemptDetail, PaginatedResponse } from '../types/quiz'
+
+export const attemptApi = {
+  async start(examId: string): Promise<QuizAttempt> {
+    const res = await api.post<ApiResponse<QuizAttempt>>('/api/v1/quiz/attempts/start', { examId })
+    return res.data
+  },
+
+  async submit(
+    attemptId: string,
+    answers: Array<{ questionId: string; userAnswer: string | string[] | null }>,
+    timeUsedSeconds?: number,
+  ): Promise<QuizAttempt> {
+    const res = await api.post<ApiResponse<QuizAttempt>>(
+      `/api/v1/quiz/attempts/${attemptId}/submit`,
+      { answers, timeUsedSeconds },
+    )
+    return res.data
+  },
+
+  async getDetail(attemptId: string): Promise<AttemptDetail> {
+    const res = await api.get<ApiResponse<AttemptDetail>>(`/api/v1/quiz/attempts/${attemptId}`)
+    return res.data
+  },
+
+  async listByExam(examId: string, params: Record<string, string> = {}): Promise<PaginatedResponse<QuizAttempt>> {
+    const res = await api.get<ApiResponse<PaginatedResponse<QuizAttempt>>>(
+      `/api/v1/quiz/exams/${examId}/attempts`,
+      { params },
+    )
+    return res.data
+  },
+
+  async listMine(params: Record<string, string> = {}): Promise<PaginatedResponse<QuizAttempt>> {
+    const res = await api.get<ApiResponse<PaginatedResponse<QuizAttempt>>>('/api/v1/quiz/my/attempts', { params })
+    return res.data
+  },
+
+  async gradeAnswer(answerId: string, score: number, feedback?: string): Promise<QuizAnswer> {
+    const res = await api.put<ApiResponse<QuizAnswer>>(
+      `/api/v1/quiz/answers/${answerId}/grade`,
+      { score, feedback },
+    )
+    return res.data
+  },
+
+  async finalizeGrading(attemptId: string): Promise<QuizAttempt> {
+    const res = await api.post<ApiResponse<QuizAttempt>>(`/api/v1/quiz/attempts/${attemptId}/finalize`, {})
+    return res.data
+  },
+}

package/web/services/category-service.ts

@@ -0,0 +1,26 @@
+import { api } from '@octo-cyber/ui/services/api-client'
+import type { ApiResponse } from '@octo-cyber/ui/types/common'
+import type { QuizCategory } from '../types/quiz'
+
+const BASE = '/api/v1/quiz/categories'
+
+export const categoryApi = {
+  async list(): Promise<QuizCategory[]> {
+    const res = await api.get<ApiResponse<QuizCategory[]>>(BASE)
+    return res.data
+  },
+
+  async create(data: Partial<QuizCategory>): Promise<QuizCategory> {
+    const res = await api.post<ApiResponse<QuizCategory>>(BASE, data)
+    return res.data
+  },
+
+  async update(id: string, data: Partial<QuizCategory>): Promise<QuizCategory> {
+    const res = await api.put<ApiResponse<QuizCategory>>(`${BASE}/${id}`, data)
+    return res.data
+  },
+
+  async delete(id: string): Promise<void> {
+    await api.delete(`${BASE}/${id}`)
+  },
+}

package/web/services/exam-service.ts

@@ -0,0 +1,31 @@
+import { api } from '@octo-cyber/ui/services/api-client'
+import type { ApiResponse } from '@octo-cyber/ui/types/common'
+import type { QuizExam, PaginatedResponse } from '../types/quiz'
+
+const BASE = '/api/v1/quiz/exams'
+
+export const examApi = {
+  async list(params: Record<string, string> = {}): Promise<PaginatedResponse<QuizExam>> {
+    const res = await api.get<ApiResponse<PaginatedResponse<QuizExam>>>(BASE, { params })
+    return res.data
+  },
+
+  async get(id: string): Promise<QuizExam> {
+    const res = await api.get<ApiResponse<QuizExam>>(`${BASE}/${id}`)
+    return res.data
+  },
+
+  async create(data: Partial<QuizExam>): Promise<QuizExam> {
+    const res = await api.post<ApiResponse<QuizExam>>(BASE, data)
+    return res.data
+  },
+
+  async update(id: string, data: Partial<QuizExam>): Promise<QuizExam> {
+    const res = await api.put<ApiResponse<QuizExam>>(`${BASE}/${id}`, data)
+    return res.data
+  },
+
+  async delete(id: string): Promise<void> {
+    await api.delete(`${BASE}/${id}`)
+  },
+}

package/web/services/paper-service.ts

@@ -0,0 +1,50 @@
+import { api } from '@octo-cyber/ui/services/api-client'
+import type { ApiResponse } from '@octo-cyber/ui/types/common'
+import type { QuizPaper, QuizPaperQuestion, PaperWithQuestions, PaginatedResponse } from '../types/quiz'
+
+const BASE = '/api/v1/quiz/papers'
+
+export const paperApi = {
+  async list(params: Record<string, string> = {}): Promise<PaginatedResponse<QuizPaper>> {
+    const res = await api.get<ApiResponse<PaginatedResponse<QuizPaper>>>(BASE, { params })
+    return res.data
+  },
+
+  async get(id: string): Promise<QuizPaper> {
+    const res = await api.get<ApiResponse<QuizPaper>>(`${BASE}/${id}`)
+    return res.data
+  },
+
+  async getWithQuestions(id: string): Promise<PaperWithQuestions> {
+    const res = await api.get<ApiResponse<PaperWithQuestions>>(`${BASE}/${id}/questions`)
+    return res.data
+  },
+
+  async create(data: Partial<QuizPaper>): Promise<QuizPaper> {
+    const res = await api.post<ApiResponse<QuizPaper>>(BASE, data)
+    return res.data
+  },
+
+  async update(id: string, data: Partial<QuizPaper>): Promise<QuizPaper> {
+    const res = await api.put<ApiResponse<QuizPaper>>(`${BASE}/${id}`, data)
+    return res.data
+  },
+
+  async delete(id: string): Promise<void> {
+    await api.delete(`${BASE}/${id}`)
+  },
+
+  async addQuestion(paperId: string, questionId: string, score?: number): Promise<QuizPaperQuestion> {
+    const res = await api.post<ApiResponse<QuizPaperQuestion>>(`${BASE}/${paperId}/questions`, { questionId, score })
+    return res.data
+  },
+
+  async updateQuestion(paperId: string, questionId: string, data: Partial<QuizPaperQuestion>): Promise<QuizPaperQuestion> {
+    const res = await api.put<ApiResponse<QuizPaperQuestion>>(`${BASE}/${paperId}/questions/${questionId}`, data)
+    return res.data
+  },
+
+  async removeQuestion(paperId: string, questionId: string): Promise<void> {
+    await api.delete(`${BASE}/${paperId}/questions/${questionId}`)
+  },
+}

package/web/services/question-service.ts

@@ -0,0 +1,36 @@
+import { api } from '@octo-cyber/ui/services/api-client'
+import type { ApiResponse } from '@octo-cyber/ui/types/common'
+import type { QuizQuestion, PaginatedResponse, SmartGenerateRule } from '../types/quiz'
+
+const BASE = '/api/v1/quiz/questions'
+
+export const questionApi = {
+  async list(params: Record<string, string> = {}): Promise<PaginatedResponse<QuizQuestion>> {
+    const res = await api.get<ApiResponse<PaginatedResponse<QuizQuestion>>>(BASE, { params })
+    return res.data
+  },
+
+  async get(id: string): Promise<QuizQuestion> {
+    const res = await api.get<ApiResponse<QuizQuestion>>(`${BASE}/${id}`)
+    return res.data
+  },
+
+  async create(data: Partial<QuizQuestion>): Promise<QuizQuestion> {
+    const res = await api.post<ApiResponse<QuizQuestion>>(BASE, data)
+    return res.data
+  },
+
+  async update(id: string, data: Partial<QuizQuestion>): Promise<QuizQuestion> {
+    const res = await api.put<ApiResponse<QuizQuestion>>(`${BASE}/${id}`, data)
+    return res.data
+  },
+
+  async delete(id: string): Promise<void> {
+    await api.delete(`${BASE}/${id}`)
+  },
+
+  async smartGenerate(paperId: string, rules: SmartGenerateRule[]): Promise<{ added: number }> {
+    const res = await api.post<ApiResponse<{ added: number }>>(`${BASE}/smart-generate`, { paperId, rules })
+    return res.data
+  },
+}

package/web/services/statistics-service.ts

@@ -0,0 +1,28 @@
+import { api } from '@octo-cyber/ui/services/api-client'
+import type { ApiResponse } from '@octo-cyber/ui/types/common'
+import type { ExamStats, UserStats, RankingEntry } from '../types/quiz'
+
+export const statisticsApi = {
+  async getExamStats(examId: string): Promise<ExamStats> {
+    const res = await api.get<ApiResponse<ExamStats>>(`/api/v1/quiz/exams/${examId}/stats`)
+    return res.data
+  },
+
+  async getRanking(examId: string, limit = 20): Promise<RankingEntry[]> {
+    const res = await api.get<ApiResponse<RankingEntry[]>>(
+      `/api/v1/quiz/exams/${examId}/ranking`,
+      { params: { limit: String(limit) } },
+    )
+    return res.data
+  },
+
+  async getMyStats(): Promise<UserStats> {
+    const res = await api.get<ApiResponse<UserStats>>('/api/v1/quiz/my/stats')
+    return res.data
+  },
+
+  async getUserStats(userId: string): Promise<UserStats> {
+    const res = await api.get<ApiResponse<UserStats>>(`/api/v1/quiz/stats/user/${userId}`)
+    return res.data
+  },
+}

package/web/stores/quiz-store.ts

@@ -0,0 +1,31 @@
+import { create } from 'zustand'
+
+interface QuizStoreState {
+  questionFilter: string
+  setQuestionFilter: (f: string) => void
+  paperFilter: string
+  setPaperFilter: (f: string) => void
+  examFilter: string
+  setExamFilter: (f: string) => void
+  currentAttemptId: string | null
+  setCurrentAttemptId: (id: string | null) => void
+  /** Saved in-progress answers keyed by questionId */
+  draftAnswers: Record<string, string | string[]>
+  setDraftAnswer: (questionId: string, answer: string | string[]) => void
+  clearDraftAnswers: () => void
+}
+
+export const useQuizStore = create<QuizStoreState>((set) => ({
+  questionFilter: 'all',
+  setQuestionFilter: (f) => set({ questionFilter: f }),
+  paperFilter: 'all',
+  setPaperFilter: (f) => set({ paperFilter: f }),
+  examFilter: 'all',
+  setExamFilter: (f) => set({ examFilter: f }),
+  currentAttemptId: null,
+  setCurrentAttemptId: (id) => set({ currentAttemptId: id }),
+  draftAnswers: {},
+  setDraftAnswer: (questionId, answer) =>
+    set((s) => ({ draftAnswers: { ...s.draftAnswers, [questionId]: answer } })),
+  clearDraftAnswers: () => set({ draftAnswers: {} }),
+}))

package/web/types/quiz.ts

@@ -0,0 +1,166 @@
+/** @octo-cyber/quiz-engine — frontend types */
+
+export interface QuizCategory {
+  id: string
+  name: string
+  parentId: string | null
+  description: string | null
+  sortOrder: number
+  createdAt: string
+  updatedAt: string
+}
+
+export interface QuizOption {
+  key: string
+  text: string
+}
+
+export type QuestionType = 'SINGLE_CHOICE' | 'MULTIPLE_CHOICE' | 'TRUE_FALSE' | 'FILL_BLANK' | 'ESSAY'
+
+export interface QuizQuestion {
+  id: string
+  categoryId: string | null
+  categoryName?: string | null
+  type: QuestionType
+  content: string
+  options: QuizOption[] | null
+  correctAnswer: string | string[] | null
+  explanation: string | null
+  difficulty: number
+  tags: string[] | null
+  defaultScore: number
+  useCount: number
+  createdBy: string | null
+  createdAt: string
+  updatedAt: string
+}
+
+export type PaperStatus = 'DRAFT' | 'PUBLISHED' | 'ARCHIVED'
+
+export interface QuizPaper {
+  id: string
+  title: string
+  description: string | null
+  totalScore: number
+  passingScore: number
+  timeLimit: number
+  status: PaperStatus
+  createdBy: string | null
+  createdAt: string
+  updatedAt: string
+}
+
+export interface QuizPaperQuestion {
+  id: string
+  paperId: string
+  questionId: string
+  score: number
+  sortOrder: number
+  sectionTitle: string | null
+  createdAt: string
+  questionDetail: QuizQuestion
+}
+
+export interface PaperWithQuestions {
+  paper: QuizPaper
+  questions: QuizPaperQuestion[]
+}
+
+export type ExamStatus = 'DRAFT' | 'SCHEDULED' | 'ONGOING' | 'ENDED' | 'CANCELLED'
+
+export interface QuizExam {
+  id: string
+  title: string
+  paperId: string
+  description: string | null
+  startTime: string | null
+  endTime: string | null
+  maxAttempts: number
+  shuffleQuestions: boolean
+  shuffleOptions: boolean
+  showAnswerAfterSubmit: boolean
+  status: ExamStatus
+  createdBy: string | null
+  createdAt: string
+  updatedAt: string
+}
+
+export type AttemptStatus = 'IN_PROGRESS' | 'SUBMITTED' | 'GRADED'
+
+export interface QuizAttempt {
+  id: string
+  examId: string
+  userId: string
+  startedAt: string
+  submittedAt: string | null
+  timeUsedSeconds: number
+  status: AttemptStatus
+  totalScore: number
+  isPassed: boolean
+  createdAt: string
+  updatedAt: string
+}
+
+export interface QuizAnswer {
+  id: string
+  attemptId: string
+  questionId: string
+  userAnswer: string | string[] | null
+  isCorrect: boolean | null
+  score: number
+  feedback: string | null
+  gradedBy: string | null
+  gradedAt: string | null
+  createdAt: string
+  updatedAt: string
+  questionDetail?: QuizQuestion
+}
+
+export interface AttemptDetail {
+  attempt: QuizAttempt
+  answers: Array<QuizAnswer & { questionDetail: QuizQuestion }>
+}
+
+export interface PaginatedResponse<T> {
+  items: T[]
+  total: number
+  page: number
+  pageSize: number
+}
+
+export interface ExamStats {
+  examId: string
+  title: string
+  totalAttempts: number
+  submittedAttempts: number
+  gradedAttempts: number
+  averageScore: number
+  highestScore: number
+  lowestScore: number
+  passRate: number
+  scoreDistribution: Array<{ range: string; count: number }>
+}
+
+export interface UserStats {
+  userId: string
+  totalAttempts: number
+  averageScore: number
+  highestScore: number
+  passCount: number
+  passRate: number
+  recentAttempts: QuizAttempt[]
+}
+
+export interface RankingEntry {
+  userId: string
+  score: number
+  rank: number
+}
+
+export interface SmartGenerateRule {
+  categoryId?: string | null
+  type?: QuestionType
+  difficulty?: number
+  count: number
+  scorePerQuestion?: number
+}