# Assessment Management Module

## Overview

The **Assessment Management Module** provides a comprehensive, generic assessment engine for the ACoreX Platform. It supports multiple assessment types including questionnaires, surveys, checklists, tests, and evaluations with advanced features like multi-responder support, conditional logic, scoring systems, and timer management.

---

## Features

### 🎯 Core Capabilities

- **Question Bank**: Reusable question library with metadata, categories, and tags
- **Dynamic Widget Support**: Questions use metadata plugin for flexible answer types
- **Assessment Templates**: Create questionnaires with sections and conditional logic
- **Multiple Assessment Types**: Questionnaires, surveys, checklists, tests, evaluations
- **Publication Modes**: Assigned (specific users), Open (anyone with link), Embedded (in other modules)
- **Multi-Responder**: Support for collaborative responses with role-based permissions
- **Timer Support**: Countdown, elapsed, scheduled, and no-timer modes
- **Scoring System**: Points-based, weighted, formula-based, or no scoring
- **Conditional Logic**: Skip logic, branching, dynamic visibility
- **Real-time Tracking**: Progress tracking, time spent, completion percentage

### 🔌 Plugin Integration

- **Category Plugin**: Organize questions and questionnaires in hierarchical categories
- **Tags Plugin**: Tag questions and questionnaires for better searchability
- **History Plugin**: Track all changes and modifications
- **Lock Plugin**: Prevent concurrent edits
- **Compare Plugin**: Compare different versions
- **Archive Plugin**: Archive old questionnaires
- **Attachments Plugin**: Attach supporting documents
- **Color Plugin**: Visual coding for questionnaires
- **Meta-Data Plugin**: Dynamic widget configuration for questions

---

## Module Structure

### Entities

#### 1. **QuestionBankItem**

Central repository for reusable questions with metadata-driven widget configuration.

**Plugins**: `category`, `tags`, `history`, `lock`, `compare`, `archive`

**Key Features**:

- Dynamic widget configuration via `interface` property (widget-field-configurator)
- Scoring configuration (points, weighted, formula)
- Difficulty levels (easy, medium, hard)
- Estimated time per question
- Auto-scoring with correct answers

#### 2. **Questionnaire**

Assessment template with embedded sections and questions (value objects).

**Plugins**: `history`, `attachments`, `category`, `tags`, `lock`, `archive`, `color`

**Key Features**:

- Multiple assessment types (questionnaire, survey, checklist, test, evaluation)
- Embedded sections and items (not separate entities)
- **Pre-questionnaire**: Welcome screen before questions (rich text, multi-language)
- **Post-questionnaire**: Review step before submit, summary screen after submit
- Scoring profiles (cumulative, weighted, formula)
- Grading scales (A-F, custom)
- Timer and navigation settings
- Question randomization
- Progress bar configuration

**Pre/Post Summary Placeholders** (for `postSummaryContent`):

| Placeholder       | Description                    |
|:------------------|:-------------------------------|
| `{{score}}`       | Score percentage (0-100)       |
| `{{passFail}}`    | Pass/fail label                |
| `{{totalQuestions}}` | Total question count      |
| `{{answeredCount}}`  | Number of answered questions |

**Value Objects**:

- **Sections**: Logical grouping with visibility conditions and scoring weights
- **QuestionnaireItems**: References to QuestionBankItem with overrides

#### 3. **Publication**

Published instance of a questionnaire with access control and timing.

**Plugins**: `history`

**Key Features**:

- Publication modes (assigned, open, embedded)
- User/role assignment for multi-responder scenarios
- Validity windows (validFrom/validTo)
- Timer modes (countdown, elapsed, scheduled, none)
- Access codes for open mode
- Multiple submission settings
- Result visibility control (immediate, after deadline, on approval, never)
- Review/approval requirements

#### 4. **ResponseSession**

User's assessment attempt with progress and scoring.

**Plugins**: `history`, `attachments`

**Key Features**:

- Multi-responder support (primary + collaborators)
- Status tracking (not-started, in-progress, completed, abandoned, under-review)
- Time tracking (started, paused, resumed, completed)
- Progress percentage
- Scoring results (total, max, percentage, grade, pass/fail)
- Review and approval workflow

#### 5. **Collaborator**

Multi-responder participant in a ResponseSession.

**Key Features**:

- Role-based access (responder, supervisor, reviewer, observer)
- Granular permissions (canRespond, canOverride, canReview, canView)
- Optional section/question scope restrictions
- Activity tracking

#### 6. **ResponseEntry**

Individual answer record with override tracking.

**Key Features**:

- Responder identification and role
- Answer data (widget-specific JSON)
- Override tracking (who, when, why, original value)
- Scoring per question
- Time spent tracking
- Flag for review
- Notes and comments

---

## Usage Examples

### Creating a Question

```typescript
// Question with widget configuration
{
  title: "What is your name?",
  description: "Please enter your full name",
  categoryId: "personal-info-category-id",
  tags: ["personal", "required"],
  scoringType: "none",
  difficulty: "easy",
  estimatedTime: 30,
  interface: {
    type: "text-box",
    options: {
      placeholder: "Enter your name",
      maxLength: 100
    }
  }
}
```

### Creating a Questionnaire

```typescript
{
  title: "Employee Annual Survey 2025",
  type: "survey",
  sections: [
    {
      id: "section-1",
      title: "Personal Information",
      order: 1,
      scoringWeight: 0.3
    },
    {
      id: "section-2",
      title: "Job Satisfaction",
      order: 2,
      scoringWeight: 0.7,
      visibilityCondition: "{{ response['Q1'] === 'Yes' }}"
    }
  ],
  items: [
    {
      id: "item-1",
      sectionId: "section-1",
      questionBankItemId: "question-id-1",
      order: 1,
      isRequired: true
    },
    {
      id: "item-2",
      sectionId: "section-2",
      questionBankItemId: "question-id-2",
      order: 1,
      visibilityCondition: "{{ response['item-1'] === 'option-a' }}"
    }
  ],
  scoringType: "weighted",
  passingScore: 70
}
```

### Publishing an Assessment

```typescript
{
  questionnaireId: "survey-id",
  title: "Q1 2025 Employee Survey",
  mode: "assigned",
  assignedToUserIds: ["user-1", "user-2", "user-3"],
  validFrom: "2025-01-01T00:00:00Z",
  validTo: "2025-03-31T23:59:59Z",
  timerMode: "countdown",
  timeLimit: 1800, // 30 minutes
  allowMultipleSubmissions: false,
  showResults: "afterDeadline",
  requireReview: true
}
```

### Multi-Responder Scenario

```typescript
// Response session with multiple collaborators
{
  publicationId: "pub-id",
  primaryResponderId: "employee-id",
  collaborators: [
    {
      userId: "supervisor-id",
      role: "supervisor",
      canRespond: true,
      canOverride: true,
      canReview: true
    },
    {
      userId: "hr-manager-id",
      role: "reviewer",
      canRespond: false,
      canOverride: false,
      canReview: true,
      canView: true
    }
  ]
}

// Answer with override tracking
{
  questionnaireItemId: "item-1",
  responderId: "employee-id",
  responderRole: "responder",
  answer: "Initial answer",
  isOverridden: true,
  overriddenBy: "supervisor-id",
  overrideReason: "Corrected based on documentation review",
  originalAnswer: "Initial answer",
  answer: "Corrected answer"
}
```

---

## Assessment Types

### 1. **Questionnaire**

General-purpose data collection with flexible formatting.

**Use Cases**: Customer feedback, employee onboarding, data collection

### 2. **Survey**

Opinion and satisfaction measurement.

**Use Cases**: Employee satisfaction, customer surveys, market research

### 3. **Checklist**

Task completion verification.

**Use Cases**: Safety inspections, compliance checks, process verification

### 4. **Test**

Knowledge assessment with auto-scoring.

**Use Cases**: Training exams, certification tests, skill assessments

### 5. **Evaluation**

Performance and quality assessment.

**Use Cases**: Employee evaluations, performance reviews, 360 feedback

---

## Scoring Systems

### None

No scoring - pure data collection.

### Cumulative

Sum of all points from answered questions.

### Weighted

Weighted average based on section weights and question importance.

### Formula

Custom formula with section-level calculations:

```
(section1 * 0.3) + (section2 * 0.7)
```

---

## Timer Modes

### Countdown

Fixed time limit with countdown display. Assessment auto-submits when time expires.

### Elapsed

Tracks time spent without limits. Useful for monitoring but not enforcing.

### Scheduled

Assessment only available during specific time window (openFrom/openUntil).

### None

No time restrictions or tracking.

---

## Multi-Responder Roles

### Responder

Primary respondent who fills out the assessment.

**Permissions**: `canRespond: true`, `canView: true`

### Supervisor

Can fill answers and override responses from others.

**Permissions**: `canRespond: true`, `canOverride: true`, `canView: true`

### Reviewer

Can approve/reject responses but cannot modify answers.

**Permissions**: `canReview: true`, `canView: true`

### Observer

Read-only access to responses.

**Permissions**: `canView: true`

---

## Conditional Logic

### Visibility Conditions

Show/hide sections or questions based on previous answers:

```javascript
// Show section if Q1 answered "Yes"
visibilityCondition: "{{ response['Q1'] === 'Yes' }}";

// Show question if previous answer > 5
visibilityCondition: "{{ response['item-1'] > 5 }}";

// Multiple conditions
visibilityCondition: "{{ response['Q1'] === 'Yes' && response['Q2'] !== null }}";
```

### Required Conditions

Make questions required based on context:

```javascript
// Required if user selected "Other"
requiredCondition: "{{ response['category'] === 'other' }}";
```

---

## Integration Points

### With Other Modules

- **Security Management**: User authentication, RBAC for questionnaires
- **Organization Management**: Assign by department, team, position
- **Task Management**: Assessment as task with deadlines
- **Notification Management**: Reminders, completion notifications
- **Report Management**: Analytics and results visualization
- **Document Management**: Attach evidence, supporting documents
- **Workflow Management**: Approval workflows for responses
- **Data Management**: Category and tag organization
- **Training Management**: Link assessments to training courses

---

## Permissions

### Entity-Level Permissions

- `assessment-management.question-bank-item.view`
- `assessment-management.question-bank-item.create`
- `assessment-management.question-bank-item.update`
- `assessment-management.question-bank-item.delete`
- `assessment-management.questionnaire.view`
- `assessment-management.questionnaire.create`
- `assessment-management.questionnaire.update`
- `assessment-management.questionnaire.delete`
- `assessment-management.publication.view`
- `assessment-management.publication.create`
- `assessment-management.publication.update`
- `assessment-management.publication.delete`
- `assessment-management.response-session.view`
- `assessment-management.response-session.create`
- `assessment-management.response-session.update`
- `assessment-management.response-session.delete`

---

## Future Enhancements

- 🔮 Analytics Dashboard: Visual insights and reports
- 🎓 Certificate Generation: Auto-generate certificates on passing
- 📊 Bulk Import/Export: Import questions from Excel/CSV
- 🤖 AI Integration: Question generation, answer analysis
- 📴 Offline Support: Complete assessments offline with sync
- 🎥 Proctoring: Screen recording, webcam monitoring for tests
- 📱 Mobile App: Native mobile experience
- 🔗 API Integration: External system integration
- 📈 Advanced Analytics: Predictive analytics, trends

---

## Technical Details

### Module Name

`AssessmentManagement`

### Module Prefix

`AXM` (ACoreX Module)

### Icon

`fa-light fa-clipboard-list-check`

### Dependencies

- `@acorex/platform/common`
- `@acorex/platform/layout/entity`
- `@acorex/platform/layout/widget-core`
- `@acorex/modules/common`
- `@acorex/modules/data-management` (for metadata plugin)

---

## Development

### Entity Generation

All entities follow ACoreX entity patterns with proper CRUD operations, validation, and UI integration.

### Mock Data

Comprehensive mock data provided for all entities with realistic scenarios.

### Translations

Fully translated in English (en-US) and Persian (fa-IR).

---

## License

Part of the ACoreX Platform ecosystem.

---

## Support

For questions and support, contact the ACoreX Platform team.
