Source: Router/functionTemplate.js

// @ts-check
/**
 * @import {ExpressRequestAuthorized, ExpressResponse} from '../types.js'
 */
/**
 * @module functionTemplate
 * @description Function/Office Template Management Router
 *
 * This router provides comprehensive endpoints for managing function templates (offices/roles)
 * within the member management system. Function templates define standard roles, responsibilities,
 * and permissions that can be assigned to members within groups.
 *
 * Key Features:
 * - Template creation and management for offices/functions
 * - Permission and qualification requirements
 * - Gender and group restrictions
 * - Voting rights and hierarchical permissions
 * - Template-based role assignments
 * - Integration with achievement/qualification system
 *
 * Business Rules:
 * - All offices must be created from predefined templates
 * - Templates can have gender restrictions (male, female, or neutral)
 * - Templates can be restricted to specific group types or hierarchies
 * - Templates can include qualification requirements
 * - Templates can grant voting rights at different organizational levels
 * - Templates support both permanent and temporary role assignments
 *
 * @requires express - Web framework for routing
 * @requires @/utils/authChecks - Authentication and authorization utilities
 * @requires @/utils/requestLogger - Request logging middleware
 * @requires ./functionTemplate/controller - Function template business logic controller
 */
import express from 'express';
import { checkAdmin } from '../utils/authChecks.js';
import { requestUpdateLogger, errorLoggerRead } from '../utils/requestLogger.js';
import * as functionTemplateController from './functionTemplate/controller.js';

const api = express.Router();

// Create or update function template
/**
 * @route PUT /api/kpe20/function/
 * @group Function Template Management
 * @description Create a new function template or update an existing one
 * @param {object} body - Function template data
 * @param {string} body.title - Function title/name (required)
 * @param {string} [body.description] - Function description
 * @param {string} [body.genderRestriction] - Gender restriction (M=Male, F=Female, N=Neutral)
 * @param {string} [body.groupRestriction] - Group type restriction
 * @param {object[]} [body.qualifications] - Required qualifications
 * @param {object} [body.permissions] - Associated permissions
 * @param {boolean} [body.votingRights] - Whether this function grants voting rights
 * @param {string} [body.votingLevel] - Voting level (local, regional, national)
 * @param {object} [body.additionalData] - Additional template configuration




 * @example
 * PUT /api/kpe20/function/
 * Body: {
 *   "title": "Team Captain",
 *   "description": "Leads team activities and represents the team",
 *   "genderRestriction": "N",
 *   "votingRights": true,
 *   "votingLevel": "local"
 * }
  * @returns {Object} Response object
 * @property {boolean} .success - Whether the operation was successful
 * @property {object} .result - Created/updated function template
 * @property {string} .result.UID - Function template UUID
 */
// @ts-ignore
api.put('/', requestUpdateLogger, checkAdmin, functionTemplateController.insertFunctionTemplate);

// Delete function template
/**
 * @route DELETE /api/kpe20/function/:UID
 * @group Function Template Management
 * @description Delete a function template and optionally reassign existing function assignments
 * @param {string} UID - UUID of the function template to delete
 * @param {object} [body] - Deletion options
 * @param {string} [body.reassignToUID] - UUID of template to reassign existing functions to




 * @example
 * DELETE /api/kpe20/function/UUID-template-123
 * Body: {"reassignToUID": "UUID-new-template"}
  * @returns {Object} Response object
 * @property {boolean} .success - Whether the deletion was successful
 * @property {number} .reassigned - Number of functions reassigned (if applicable)
 * @property {number} .removed - Number of functions removed
 */
// @ts-ignore
api.delete('/:UID', requestUpdateLogger, checkAdmin, functionTemplateController.deleteFunctionTemplate);

// Get jobs associated with a specific function template
/**
 * @route GET /api/kpe20/function/jobs/:UID
 * @group Function Template Management
 * @description Get all current job assignments based on a specific function template
 * @param {string} UID - UUID of the function template
 * @param {boolean} [activeOnly] - Return only active assignments (default: true)







 * @example
 * GET /api/kpe20/function/jobs/UUID-template-123
  * @returns {Object} Response object
 * @property {boolean} .success - Whether the request was successful
 * @property {object[]} .result - Array of job assignments
 * @property {string} .result[].personName - Name of person holding the job
 * @property {string} .result[].groupName - Group where the job is held
 * @property {string} .result[].startDate - Job start date
 * @property {string} .result[].endDate - Job end date (if applicable)
 */
// @ts-ignore
api.get('/jobs/:UID', functionTemplateController.getJobsByFunctionTemplate);

// Get all function template names and UIDs for the organization
/**
 * @route GET /api/kpe20/function/
 * @group Function Template Management
 * @description Get a list of all function templates (names and UIDs only)
 * @param {string} [category] - Filter by category if templates are categorized
 * @param {boolean} [activeOnly] - Return only active templates (default: true)






 * @example
 * GET /api/kpe20/function/
  * @returns {Object} Response object
 * @property {boolean} .success - Whether the request was successful
 * @property {object[]} .result - Array of function templates
 * @property {string} .result[].UID - Template UUID
 * @property {string} .result[].title - Template title
 * @property {string} .result[].category - Template category (if applicable)
 */
// @ts-ignore
api.get('/', functionTemplateController.getFunctionTemplates);



export default api;