# 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:
```typescript
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.