dwindown/yellow-bank-soal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
yellow-bank-soal/ADMIN_UI_REDESIGN_PLAN.md
Dwindi Ramadhana 792f9b7483 refactor: redesign admin permalinks to RESTful paths 
- Replace fragile /admin/ai-playground and /admin/ai-generation routes
  with item-scoped /admin/questions/{id}/generate endpoints
- Add /admin/tryouts/{id}/questions route using Tryout primary key
  instead of composite query params (?tryout_id=X&website_id=Y)
- Fix variant detail and review-bulk endpoints to use scoped paths
- Update all internal links (dashboard, hierarchy, exams) to new routes
- Remove obsolete ai_playground_view/submit/save functions
2026-06-16 23:54:24 +07:00

701 lines
34 KiB
Markdown
Raw Permalink Blame History

# Admin UI Redesign Plan
> **Document Type:** UI/UX Improvement Plan
> **Current System:** IRT Bank Soal Admin
> **Date:** 2026-06-15
> **Status:** Draft for Review
---
## Executive Summary
The current admin interface is built from a **developer/system perspective** rather than a **human/admin perspective**. This plan outlines a complete redesign to make the admin dashboard intuitive, workflow-oriented, and human-readable.
### Current Problems
| Problem | Impact |
|---------|--------|
| Navigation uses technical terms | Admins don't understand menu labels |
| Multiple unrelated features in one view | Confusing, overwhelming |
| Data displayed in database terminology | Hard to interpret scores |
| No clear workflow guidance | Admin doesn't know what to do first |
| No contextual help | Unclear what each feature does |
| Mixed concern pages | AI + Questions + Calibration all on one page |
---
## Current State Analysis
### Current Navigation (System POV)
```
├── Dashboard (raw counts)
├── Websites (technical list)
├── Tryout Import (system term)
├── Data Hierarchy (developer term)
├── Basis Items (technical term)
├── Calibration Status (technical term)
├── Item Statistics (technical term)
├── Session Overview (technical term)
├── AI Playground (slang)
└── Password Info (unrelated)
```
### Current Issues
1. **Naming Problems:**
- "Basis Items" → Should be "Question Templates" or "Original Questions"
- "Data Hierarchy" → Should be "Data Overview" or "Website Structure"
- "Tryout Import" → Should be "Import Questions"
- "Calibration Status" → Should be "Question Quality" or "Difficulty Analysis"
- "AI Playground" → Should be "Generate AI Questions"
- "Session Overview" → Should be "Student Attempts"
2. **Dashboard Issues:**
- Shows raw database counts (Tryouts, Items, Sessions)
- No meaningful KPIs or actionable insights
- No visual indicators of system health
3. **Page Organization:**
- Too many technical terms on each page
- Tables show raw data without explanation
- No breadcrumbs or context
---
## Proposed Redesign
### New Navigation Structure (Human POV)
```
🎯 Dashboard (Home)
├── System Health Summary
├── Quick Actions
└── Recent Activity
📋 Questions Bank
├── All Questions (list + search)
├── Question Templates (basis items)
├── Import Questions (from Excel/JSON)
└── Question Quality (calibration status)
🤖 AI Generation
├── Generate New Questions
├── Review Generated Questions
└── Generation History
📊 Exams (Tryouts)
├── All Exams (list)
├── Exam Settings (scoring mode)
├── Student Attempts
└── Normalization Settings
📈 Reports
├── Student Performance Report
├── Item Analysis Report
├── Exam Comparison Report
└── Scheduled Reports
⚙️ Settings
├── Websites Management
├── Account Settings
└── System Info
```
### Navigation Mapping Table
| Current Menu | New Menu | Reason |
|-------------|----------|--------|
| Dashboard | 🎯 Dashboard | Home base |
| Websites | ⚙️ Settings > Websites | Configuration |
| Tryout Import | 📋 Questions > Import Questions | Workflow step |
| Data Hierarchy | ⚙️ Settings | Admin settings |
| Basis Items | 📋 Questions > Question Templates | Content management |
| Calibration Status | 📋 Questions > Question Quality | Quality assurance |
| Item Statistics | 📈 Reports > Item Analysis | Reporting |
| Session Overview | 📊 Exams > Student Attempts | Workflow |
| AI Playground | 🤖 AI Generation | Dedicated feature |
| Password Info | ⚙️ Settings > Account | Configuration |
---
## Detailed Page Redesigns
### 1. Dashboard (Home) — `GET /admin/dashboard`
**Current State:**
```python
# Shows raw counts
body = f"""
<p>Signed in as <strong>{admin}</strong>.</p>
<div class="grid">
<div class="stat">Tryouts<strong>{tryouts}</strong></div>
<div class="stat">Items<strong>{items}</strong></div>
<div class="stat">Sessions<strong>{sessions}</strong></div>
<div class="stat">Completed Sessions<strong>{completed}</strong></div>
</div>
<p><a href="/admin/ai-playground">Open AI Playground</a></p>
"""
```
**Proposed State:**
```
┌─────────────────────────────────────────────────────────────────┐
│ Good Morning, Admin! 👋 │
│ Last login: Today at 9:00 AM │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 📊 System Overview │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 5 Exams │ │ 450 │ │ 1,234 │ │ 89% │ │
│ │ Active │ │ Questions│ │ Students │ │ Avg Score│ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ⚠️ Attention Needed │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ⚡ 23 questions need calibration (do this first!) │ │
│ │ 📝 5 AI-generated questions pending review │ │
│ │ 📥 2 exam exports ready for download │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ 🚀 Quick Actions │
│ [Import Questions] [Generate AI] [View Reports] [Add Exam] │
│ │
│ 📈 Recent Activity │
│ • 12 students completed "UTBK 2024" in last hour │
│ • 3 new questions generated via AI │
│ • Calibration completed for "SIMAK UI" (95% ready) │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**Key Changes:**
- Human-readable greeting with time
- Meaningful metrics (not raw counts)
- Actionable alerts with urgency indicators
- Quick action buttons with clear labels
- Recent activity feed
---
### 2. Questions Bank — Questions List (`/admin/questions`)
**Current State:** Table with raw database fields
**Proposed State:**
```
┌─────────────────────────────────────────────────────────────────┐
│ 📋 Question Bank │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [Search: "matematika" ] [Filter ▼] [🔍] │
│ │
│ Showing 450 questions across 5 exams │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ☐ │ Q1 │ Berapakah hasil dari 2 + 2? │ │
│ │ │ │ ▸ Easy (p=0.85) | Used 234x | SIMAK UI │ │
│ ├────┼─────┼──────────────────────────────────────────────┤ │
│ │ ☐ │ Q5 │ Hitung integral dari x² dx... │ │
│ │ │ │ ▸ Medium (p=0.45) | Used 89x | UTBK 2024 │ │
│ ├────┼─────┼──────────────────────────────────────────────┤ │
│ │ ☐ │ Q12 │ Jelaskan teori evolusi... │ │
│ │ │ │ ▸ Hard (p=0.22) | Used 45x | ONM 2024 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ [Delete Selected] [Export Selected] [Edit Selected] │
│ │
│ 📄 Page 1 of 23 [<] [1] [2] [3] ... [>] │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**Key Changes:**
- Question preview in list (not just ID)
- Human-readable difficulty (Easy/Medium/Hard)
- Usage count (how many times used)
- Which exam it belongs to
- Visual indicators for difficulty colors
---
### 3. Question Templates — (`/admin/templates`)
**Current State:** "Basis Items" - confusing technical term
**Proposed State:**
```
┌─────────────────────────────────────────────────────────────────┐
│ 📝 Question Templates │
│ (Original questions used to generate AI variants) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Templates are your "master questions" that AI uses to │
│ create different versions with varying difficulty levels. │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 📝 Template #45: "Berapakah hasil dari 2 + 2?" │ │
│ │ AI Generated Variants: 12 (3 easy, 6 medium, 3 hard) │ │
│ │ [View All Variants] [Generate More] [Edit] │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ 📝 Template #89: "Hitung integral dari x² dx..." │ │
│ │ AI Generated Variants: 8 (2 easy, 4 medium, 2 hard) │ │
│ │ [View All Variants] [Generate More] [Edit] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ [+ Create New Template] │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**Key Changes:**
- Clear explanation of what templates are
- Visual representation of variants
- Easy action buttons
- "Create New Template" prominent
---
### 4. AI Generation — (`/admin/ai-generation`)
**Current State:** "AI Playground" - informal, confusing tabs
**Proposed State:**
```
┌─────────────────────────────────────────────────────────────────┐
│ 🤖 AI Question Generator │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Generate new question variants using AI. │
│ Select a template question and specify difficulty level. │
│ │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ 📝 Select Template │ │ 🎯 Target Difficulty │ │
│ │ [Dropdown: Questions]│ │ ○ Easy (p > 0.70) │ │
│ └──────────────────────┘ │ ● Medium (p ≈ 0.50) │ │
│ │ ○ Hard (p < 0.30) │ │
│ ┌──────────────────────┐ └──────────────────────┘ │
│ │ 📝 How many variants?│ │
│ │ [1] [3] [5] [10] │ ┌──────────────────────┐ │
│ └──────────────────────┘ │ 💬 Additional Notes │ │
│ │ [Optional context...] │ │
│ └──────────────────────┘ │
│ │
│ [🚀 Generate Questions] │
│ │
├─────────────────────────────────────────────────────────────────┤
│ 📋 Generated Questions (Pending Review) │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 🔄 Generating... 2 of 5 questions completed │ │
│ │ [████████░░] 60% │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ✅ Generated & Ready for Review: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ✓ Variant #123: "Berapakah hasil dari 3 + 4?" (Easy) │ │
│ │ [Preview] [Approve] [Regenerate] [Reject] │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ ✓ Variant #124: "Hitung hasil dari 5 + 6..." (Easy) │ │
│ │ [Preview] [Approve] [Regenerate] [Reject] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**Key Changes:**
- Clear, labeled sections
- Radio buttons for difficulty (not dropdown)
- Progress indicator during generation
- Clear action buttons (Approve/Reject/Regenerate)
- Explanation of what each option means
---
### 5. Question Quality (Calibration) — (`/admin/question-quality`)
**Current State:** "Calibration Status" - technical IRT terminology
**Proposed State:**
```
┌─────────────────────────────────────────────────────────────────┐
│ 📊 Question Quality Dashboard │
│ (Shows how well each question is "calibrated" for testing) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 📖 What is Question Quality? │
│ Questions become "calibrated" after many students answer them. │
│ Well-calibrated questions give accurate student scores. │
│ │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Overall Quality: ████████░░ 78% │
│ (78 out of 100 questions are ready for adaptive testing) │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 📋 By Exam │ │
│ │ │ │
│ │ UTBK 2024 ████████████ 95% ✓ Ready │ │
│ │ SIMAK UI █████████░░░ 72% ⚠️ Partial │ │
│ │ ONM 2024 ██████░░░░░░ 45% ❌ Needs more data│ │
│ │ PASIAD Selection ████████████ 100% ✓ Excellent │ │
│ │ │ │
│ │ [Run Calibration for All Exams] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ Questions Needing Attention: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ⚠️ Q45 - "Hitung integral..." only answered 12 times │ │
│ │ Need at least 100 answers to calibrate properly. │ │
│ │ Current estimate: p=0.42 (might change) │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ ❌ Q78 - "Teori relativitas..." has conflicting answers │ │
│ │ Check if correct answer is correct in database. │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**Key Changes:**
- Clear explanation of what calibration means
- Progress bars for visual understanding
- Status indicators (✓ Ready, ⚠️ Partial, ❌ Needs data)
- Specific recommendations for action
- User-friendly difficulty explanation
---
### 6. Student Attempts — (`/admin/student-attempts`)
**Current State:** "Session Overview" - raw database table
**Proposed State:**
```
┌─────────────────────────────────────────────────────────────────┐
│ 📊 Student Attempts │
│ (See how students performed on each exam) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Filter: [Select Exam ▼] [Status ▼] [Date Range ▼] [Search] │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 📋 UTBK 2024 Results │ │
│ │ │ │
│ │ Participants: 1,234 students │ │
│ │ Average Score (NM): 672 / 1000 │ │
│ │ Average Score (NN): 505 / 1000 │ │
│ │ Completion Rate: 98% (1,209 completed) │ │
│ │ │ │
│ │ Score Distribution: │ │
│ │ ▁▂▃▇█▇▃▂▁ (bell curve centered around 500) │ │
│ │ 200 300 400 500 600 700 800 900 1000 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ Recent Attempts: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 👤 John Doe (john@example.com) │ │
│ │ Exam: UTBK 2024 | Completed: Today, 2:30 PM │ │
│ │ Score: NM=720 (85th percentile) | NN=645 │ │
│ │ Correct: 28/30 | Time: 45 minutes │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ 👤 Jane Smith (jane@example.com) │ │
│ │ Exam: SIMAK UI | Completed: Today, 1:15 PM │ │
│ │ Score: NM=580 (45th percentile) | NN=485 │ │
│ │ Correct: 22/30 | Time: 52 minutes │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ [Export All Results] [View Detailed Report] [Schedule Report] │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**Key Changes:**
- Grouped by exam with summary stats
- Human-readable student info
- Percentile ranking
- Score distribution visualization
- Clear action buttons
---
### 7. Reports — (`/admin/reports`)
**Proposed State:**
```
┌─────────────────────────────────────────────────────────────────┐
│ 📈 Reports │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Generate detailed analysis reports for exams and students. │
│ │
│ ┌─────────────────────────┐ ┌─────────────────────────┐ │
│ │ 📊 Student Performance │ │ 📋 Item Analysis │ │
│ │ │ │ │ │
│ │ See individual student │ │ Analyze question │ │
│ │ scores, rankings, and │ │ difficulty, validity, │ │
│ │ detailed breakdowns. │ │ and discrimination. │ │
│ │ │ │ │ │
│ │ [Generate Report] │ │ [Generate Report] │ │
│ └─────────────────────────┘ └─────────────────────────┘ │
│ │
│ ┌─────────────────────────┐ ┌─────────────────────────┐ │
│ │ 📈 Exam Comparison │ │ 📅 Scheduled Reports │ │
│ │ │ │ │ │
│ │ Compare scores across │ │ Set up automatic │ │
│ │ different exams or │ │ weekly/monthly reports │ │
│ │ time periods. │ │ delivery. │ │
│ │ │ │ │ │
│ │ [Generate Report] │ │ [Manage Schedules] │ │
│ └─────────────────────────┘ └─────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**Key Changes:**
- Card-based layout with icons
- Clear description of each report type
- Visual cards instead of dropdowns
- Scheduled reports as first-class feature
---
## Implementation Phases
### Phase 1: Navigation Redesign (Foundation)
**Files to modify:**
- `app/admin_web.py` - Update `ADMIN_NAV_ITEMS`
- Create new route handlers
**Steps:**
1. Rename navigation items with human labels
2. Create new route structure
3. Implement breadcrumb system
4. Add help tooltips
**New Navigation Structure:**
```python
ADMIN_NAV_ITEMS = (
("Dashboard", "/admin/dashboard", ("/admin/dashboard",)),
("Questions", "/admin/questions", ("/admin/questions", "/admin/templates")),
("AI Generator", "/admin/ai-generation", ("/admin/ai-generation",)),
("Exams", "/admin/exams", ("/admin/exams", "/admin/student-attempts")),
("Reports", "/admin/reports", ("/admin/reports",)),
("Settings", "/admin/settings", ("/admin/settings",)),
)
```
---
### Phase 2: Dashboard Overhaul
**New Dashboard Components:**
1. Greeting with user name and time
2. System health cards (with meaningful metrics)
3. Action alerts section
4. Quick action buttons
5. Recent activity feed
**Files to modify:**
- `dashboard_view()` function
- `_render_admin_page()` for dashboard-specific layout
---
### Phase 3: Questions Section
**New Pages:**
1. `/admin/questions` - List all questions with search/filter
2. `/admin/questions/{id}` - Question detail view
3. `/admin/templates` - Question templates (formerly basis items)
4. `/admin/questions/import` - Import wizard
**Key UI Components:**
- Question preview cards
- Difficulty badges (Easy/Medium/Hard)
- Color-coded indicators
- Inline search
---
### Phase 4: AI Generation Section
**New Pages:**
1. `/admin/ai-generation` - Main generation interface
2. `/admin/ai-generation/review` - Review pending variants
3. `/admin/ai-generation/history` - Generation history
**Key UI Components:**
- Template selector with preview
- Difficulty radio buttons
- Generation progress bar
- Batch approve/reject actions
---
### Phase 5: Exams Section
**New Pages:**
1. `/admin/exams` - List all exams
2. `/admin/exams/{id}/settings` - Exam configuration
3. `/admin/student-attempts` - Student attempts list
4. `/admin/normalization` - Normalization settings
**Key UI Components:**
- Exam cards with status indicators
- Student attempt cards
- Score distribution visualization
---
### Phase 6: Reports Section
**New Pages:**
1. `/admin/reports` - Report dashboard
2. `/admin/reports/student-performance` - Student report
3. `/admin/reports/item-analysis` - Item report
4. `/admin/reports/exam-comparison` - Comparison report
5. `/admin/reports/scheduled` - Scheduled reports
**Key UI Components:**
- Report type cards
- Export format options
- Schedule configuration
---
## Technical Implementation Notes
### CSS Class Naming Convention
```css
/* Old: System POV */
.stat { }
.grid { }
.table-wrap { }
/* New: Human POV */
.dashboard-hero { }
.metric-card { }
.question-list { }
.difficulty-badge { }
.difficulty-easy { background: #dcfce7; }
.difficulty-medium { background: #fef3c7; }
.difficulty-hard { background: #fee2e2; }
```
### Helper Functions to Create
```python
# In admin_web.py
def _render_question_card(item: Item) -> str:
"""Render a human-readable question card."""
difficulty = _human_difficulty(item.ctt_p)
difficulty_color = _difficulty_color(item.ctt_p)
return f"""
<div class="question-card">
<div class="difficulty-badge {difficulty_color}">{difficulty}</div>
<div class="question-stem">{escape(item.stem[:100])}...</div>
<div class="question-meta">
Used {item.calibration_sample_size}x |
{item.tryout_id}
</div>
</div>
"""
def _human_difficulty(p_value: float | None) -> str:
"""Convert p-value to human-readable difficulty."""
if p_value is None:
return "Unknown"
if p_value > 0.70:
return "Easy"
elif p_value >= 0.30:
return "Medium"
else:
return "Hard"
def _difficulty_color(p_value: float | None) -> str:
"""Get color class for difficulty badge."""
if p_value is None:
return "difficulty-unknown"
if p_value > 0.70:
return "difficulty-easy"
elif p_value >= 0.30:
return "difficulty-medium"
else:
return "difficulty-hard"
```
### Responsive Design
```css
/* Mobile-friendly layout */
@media (max-width: 768px) {
.admin-layout {
flex-direction: column;
}
.sidebar-nav {
display: flex;
overflow-x: auto;
padding: 8px;
}
.metric-cards {
grid-template-columns: repeat(2, 1fr);
}
}
```
---
## Success Metrics
| Metric | Target |
|--------|--------|
| Time to complete common task | Reduce by 50% |
| Admin confusion score | < 2/5 |
| Support tickets about UI | Reduce by 80% |
| Feature discovery rate | > 90% can find features |
---
## Appendix: Terminology Mapping
| System Term | Human Term |
|------------|------------|
| Tryout | Exam / Test |
| Item | Question |
| Basis Item | Question Template / Original Question |
| Session | Student Attempt |
| Calibration | Question Quality / Difficulty Analysis |
| IRT | Adaptive Scoring |
| CTT | Standard Scoring |
| Bobot | Weight / Point Value |
| NM | Raw Score |
| NN | Normalized Score |
| p-value | Difficulty Score |
| Theta | Student Ability Score |
---
## Files to Modify
| File | Changes |
|------|---------|
| `app/admin_web.py` | Complete UI rewrite |
| `app/admin.py` | May need minor updates |
| `requirements.txt` | Add any new frontend deps (if needed) |
---
## Next Steps
1. [ ] Review and approve this plan
2. [ ] Prioritize phases (suggest starting with Phase 1 & 2)
3. [ ] Create mockups/wireframes for key pages
4. [ ] Implement Phase 1: Navigation & Dashboard
5. [ ] User testing with admin users
6. [ ] Iterate based on feedback
Reference in New Issue View Git Blame Copy Permalink