CICD/docs/design/004_question_bank_implementation.md

Question Bank Module Implementation

1. Overview

The Question Bank module (src/modules/questions) is a core component for teachers to manage their examination resources. It implements a comprehensive CRUD interface with advanced filtering and batch operations.

Status: IMPLEMENTED
Date: 2025-12-23
Author: Senior Frontend Engineer

---

2. Architecture & Tech Stack

2.1 Vertical Slice Architecture

Following the project's architectural guidelines, all question-related logic is encapsulated within src/modules/questions:

• components/: UI components (Data Table, Dialogs, Filters)
• actions.ts: Server Actions for data mutation
• data-access.ts: Database query logic
• schema.ts: Zod schemas for validation
• types.ts: TypeScript interfaces

2.2 Key Technologies

• Data Grid: @tanstack/react-table for high-performance rendering.
• State Management: nuqs for URL-based state (filters, search).
• Forms: react-hook-form + zod + shadcn/ui form components.
• Validation: Strict server-side and client-side validation using Zod schemas.

---

3. Component Design

3.1 QuestionDataTable (question-data-table.tsx)

• Features: Pagination, Sorting, Row Selection.
• Performance: Uses React.memo compatible patterns where possible (though useReactTable itself is not memoized).
• Responsiveness: Mobile-first design with horizontal scroll for complex columns.

3.2 QuestionColumns (question-columns.tsx)

Custom cell renderers for rich data display:

• Type Badge: Color-coded badges for different question types (Single Choice, Multiple Choice, etc.).
• Difficulty: Visual indicator with color (Green -> Red) and numerical value.
• Actions: Dropdown menu for Edit, Delete, View Details, and Copy ID.

3.3 Create/Edit Dialog (create-question-dialog.tsx)

A unified dialog component for both creating and editing questions.

• Dynamic Fields: Shows/hides "Options" field based on question type.
• Interactive Options: Allows adding/removing/reordering options for choice questions.
• Optimistic UI: Shows loading states during submission.

3.4 Filters (question-filters.tsx)

• URL Sync: All filter states (Search, Type, Difficulty) are synced to URL parameters.
• Debounce: Search input uses debounce to prevent excessive requests.
• Server Filtering: Filtering logic is executed on the server side (currently simulated in page.tsx, ready for DB integration).

---

4. Implementation Details

4.1 Data Flow

1. Read: page.tsx (Server Component) fetches data based on searchParams.
2. Write: Client components invoke Server Actions (simulated) -> Revalidate Path -> UI Updates.
3. Filter: User interaction -> Update URL -> Server Component Re-render -> New Data.

4.2 Type Safety

A shared Question interface ensures consistency across the stack:

export interface Question {
  id: string;
  content: any; // Rich text structure
  type: QuestionType;
  difficulty: number;
  // ... relations
}

4.3 UI/UX Standards

• Empty States: Custom EmptyState component when no data matches.
• Loading States: Skeleton screens for table loading.
• Feedback: Sonner toasts for success/error notifications.
• Confirmation: AlertDialog for destructive actions (Delete).

---

5. Next Steps

• Integrate with real Database (replace Mock Data).
• Implement Rich Text Editor (Slate.js / Tiptap) for question content.
• Add "Batch Import" functionality.
• Implement "Tags" management for Knowledge Points.