Module Update

docs/design/004_question_bank_implementation.md

@@ -0,0 +1,87 @@
+# 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.