Work Reporting Module - Solution Design

Purpose

Faculty members perform various types of professional work throughout the academic year. The Work Reporting Module provides:

1. Activity Tracking - Record scientific, methodological, and organizational work
2. Co-authorship Support - Track collaborative work across multiple authors
3. Rating Calculation - Compute performance ratings based on activity coefficients
4. Statistics & Reports - Generate reports at individual and department level

Business Value

• Replaces manual Excel-based reporting
• Enables fair, coefficient-based performance evaluation
• Provides transparency in rating calculations
• Supports academic year cycle with semester breakdown
• Facilitates data export for university reporting

Owners

• Product Owner: University Administration
• Development Team: NPP Portal Team

Flow Overview

Activity Submission Flow

┌─────────┐     ┌──────────┐     ┌─────────┐     ┌──────────┐
│ Teacher │────▶│   SPA    │────▶│   API   │────▶│    DB    │
└─────────┘     └──────────┘     └─────────┘     └──────────┘
     │               │                │                │
     │  1. Select activity type       │                │
     │──────────────▶│                │                │
     │               │ 2. GET /activity-details        │
     │               │───────────────▶│                │
     │               │◀───────────────│ (types + coefficients)
     │               │                │                │
     │  3. Fill form │                │                │
     │──────────────▶│                │                │
     │               │ 4. POST /activities             │
     │               │───────────────▶│                │
     │               │                │ 5. Validate    │
     │               │                │───────────────▶│
     │               │                │ 6. Create activity
     │               │                │ 7. Link co-authors
     │               │                │◀───────────────│
     │               │◀───────────────│                │
     │  8. Success   │                │                │
     │◀──────────────│                │                │

Rating Calculation Flow

Rating = Σ (Activity.coefficient × Activity.normTime)

Per Activity Type:
- Research Rating = Σ (RESEARCH activities × coefficients)
- Teaching Rating = Σ (TEACHING activities × coefficients)
- Service Rating = Σ (SERVICE activities × coefficients)

Total Rating = Research + Teaching + Service

Scope

In Scope

• Activity CRUD operations
• Activity type dictionary management (admin)
• Co-author management
• Year/semester filtering
• Individual teacher rating calculation
• Department statistics aggregation
• Public activity viewing (limited fields)
• Read-only mode (blocks edits during review period)
• Activity search and filtering
• Basic Excel export

Out of Scope

• Activity approval workflow (no Director approval step)
• File attachments for activities
• Activity templates/cloning
• Historical coefficient versioning
• Advanced analytics dashboards
• PDF report generation

Risk

Technical Risks

Stability Concerns

• Large activity lists may cause slow page loads (pagination required)
• Rating recalculation on every request may be slow (consider caching)
• Semester cutoff dates need configuration

Research

Coefficient Versioning

Question: Should coefficients be versioned per academic year?

Options:

1. Global coefficients (simplest)
2. Year-based coefficient snapshots
3. Full versioning with effective dates

Result: Option 1 for MVP. Coefficients rarely change. If needed, archive old activities before updating coefficients.

Rating Calculation Timing

Question: When to calculate ratings - on demand or pre-computed?

Options:

1. Calculate on every request (accurate but slow)
2. Scheduled batch recalculation
3. Event-driven recalculation (on activity change)

Result: Option 1 for MVP (simple). Monitor performance and add caching if needed.

API Endpoints

Activities

Activity Details (Dictionary)

Statistics

Public Activities

System

Activity Types

Research Activities (RESEARCH)

Examples:

• Publications in indexed journals (Scopus, WoS)
• Monographs and textbooks
• Patents and inventions
• Research grants
• Conference presentations
• PhD supervision

Teaching and Curriculum Development (TEACHING)

Examples:

• Curriculum development
• Teaching materials creation
• Lab manual writing
• E-learning course development
• Syllabus updates

Academic Service and Administration (SERVICE)

Examples:

• Committee membership
• Conference organization
• Student competitions supervision
• Department administration tasks
• External expert activities

Additional Requirements

Backend

• Activity entity with year/semester tracking
• ActivityDetails dictionary with coefficients
• UserActivity junction table for co-authorship
• Rating calculation service
• Read-only mode filter/interceptor
• Pagination for activity lists
• Full-text search on activity descriptions

Frontend

• Activity list with filters (year, semester, type)
• Activity creation form with type selection
• Co-author selection (search by name)
• Personal statistics dashboard
• Department statistics view (Director)
• Activity dictionary management (Admin)
• Read-only mode indicator
• Export to Excel button

Data Validation

Read-Only Mode

Purpose

During semester-end review periods, administrators lock the system to prevent modifications while evaluating activities.

Behavior

When enabled:

• All POST/PUT/DELETE on /activities return 403 Forbidden
• GET operations continue normally
• Admin endpoints remain functional
• Clear message displayed in UI

Implementation

@Component
public class ReadOnlyModeInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, ...) {
        if (readOnlyModeService.isEnabled() && isWriteOperation(request)) {
            if (!isAdminPath(request) && !isAdminUser()) {
                throw new ReadOnlyModeException("System is in read-only mode");
            }
        }
        return true;
    }
}

Additional Documentation

• ADR-001: Initial Architecture
• ERD: Main Schema
• Solution Design 001: Personal Account
• Test Design