/**
* @module achievement
* @description Achievement/Qualification Management Router
*
* This router provides comprehensive endpoints for managing member achievements and qualifications
* within the member management system. Achievements track certifications, training completions,
* licenses, and other qualifications that members earn over time.
*
* Key Features:
* - Achievement recording and management
* - Expiration and renewal tracking
* - Template-based achievement types
* - Qualification validation and verification
* - Historical achievement records
* - Automated renewal notifications
* - Integration with function/office requirements
*
* Business Rules:
* - Achievements are based on predefined templates
* - Achievements can have expiration dates requiring renewal
* - Multiple achievements of the same type can be held by one person
* - Achievements can be prerequisites for certain functions/offices
* - Historical records are maintained for all achievement changes
* - Automated processes can trigger renewal workflows
*
* @requires express - Web framework for routing
* @requires @/utils/requestLogger - Request logging middleware
* @requires ./achievement/controller - Achievement business logic controller
*/
import express from 'express';
import { requestUpdateLogger, readLogger } from '../utils/requestLogger.js';
import * as achievementController from './achievement/controller.js';
const api = express();
// Create or update achievement for member
/**
* @route PUT /api/kpe20/achievement/:member/:template
* @group Achievement Management
* @description Create a new achievement for a member or update an existing one
* @param {string} member - UUID of the member
* @param {string} template - UUID of the achievement template
* @param {object} body - Achievement data
* @param {string} [body.issueDate] - Date when achievement was issued (ISO format)
* @param {string} [body.expiryDate] - Date when achievement expires (ISO format)
* @param {string} [body.issuer] - Name/entity that issued the achievement
* @param {string} [body.certificateNumber] - Certificate/reference number
* @param {object} [body.verificationData] - Additional verification information
* @param {object} [body.additionalData] - Additional achievement-specific data
* @returns {object} Creation/update result
* @returns {boolean} .success - Whether the operation was successful
* @returns {object} .result - Created/updated achievement
* @returns {string} .result.UID - Achievement UUID
* @returns {boolean} .result.isNew - Whether a new achievement was created
* @example
* PUT /api/kpe20/achievement/UUID-member-123/UUID-template-456
* Body: {
* "issueDate": "2024-01-15",
* "expiryDate": "2027-01-15",
* "issuer": "National Training Center",
* "certificateNumber": "CERT-2024-001"
* }
*/
api.put('/:member/:template', requestUpdateLogger, achievementController.insertOrUpdateAchievement);
// Delete achievement
/**
* @route DELETE /api/kpe20/achievement/:UID
* @group Achievement Management
* @description Delete an achievement record
* @param {string} UID - UUID of the achievement to delete
* @returns {object} Deletion result
* @returns {boolean} .success - Whether the deletion was successful
* @returns {object} .result - Information about the deleted achievement
* @example
* DELETE /api/kpe20/achievement/UUID-achievement-123
*/
api.delete('/:UID', requestUpdateLogger, achievementController.deleteAchievement);
// Maintenance endpoint to check renewal of achievements
/**
* @route GET /api/kpe20/achievement/renewal
* @group Achievement Management
* @description Check for expired achievements and trigger renewal processes
* This endpoint is typically called by scheduled maintenance tasks
* @param {number} [daysAhead] - Check for expirations this many days in advance (default: 30)
* @returns {object} Renewal check results
* @returns {boolean} .success - Whether the check was successful
* @returns {object[]} .result.expired - Array of expired achievements
* @returns {object[]} .result.expiringSoon - Array of achievements expiring soon
* @returns {number} .result.notificationsSent - Number of renewal notifications sent
* @example
* GET /api/kpe20/achievement/renewal?daysAhead=60
*/
api.get('/renewal', requestUpdateLogger, achievementController.renewalMaintenance);
// Get specific achievement
/**
* @route GET /api/kpe20/achievement/:UID
* @group Achievement Management
* @description Get detailed information about a specific achievement
* @param {string} UID - UUID of the achievement
* @returns {object} Achievement information
* @returns {boolean} .success - Whether the request was successful
* @returns {object} .result - Complete achievement data
* @returns {string} .result.achievementType - Type of achievement
* @returns {string} .result.memberName - Name of the member
* @returns {string} .result.issueDate - Date when issued
* @returns {string} .result.expiryDate - Date when expires (if applicable)
* @returns {string} .result.status - Current status (active, expired, renewed)
* @returns {object} .result.verificationData - Verification information
* @example
* GET /api/kpe20/achievement/UUID-achievement-123
*/
api.get('/:UID', readLogger, achievementController.getAchievement);
// List achievements for a person
/**
* @route GET /api/kpe20/achievement/person/:UID
* @group Achievement Management
* @description Get all achievements held by a specific person
* @param {string} UID - UUID of the person
* @param {string} [status] - Filter by status (active, expired, all) (default: active)
* @param {string} [type] - Filter by achievement type/template
* @param {boolean} [includeExpired] - Include expired achievements (default: false)
* @returns {object} Person's achievements
* @returns {boolean} .success - Whether the request was successful
* @returns {object[]} .result - Array of person's achievements
* @returns {string} .result[].achievementType - Type of achievement
* @returns {string} .result[].issueDate - Date when issued
* @returns {string} .result[].expiryDate - Date when expires (if applicable)
* @returns {string} .result[].status - Current status
* @returns {boolean} .result[].renewalNeeded - Whether renewal is needed
* @example
* GET /api/kpe20/achievement/person/UUID-person-123?status=active
*/
api.get('/person/:UID', readLogger, achievementController.listAchievementsPerson);
export default api;