// @ts-check
/**
* @import {ExpressRequestAuthorized, ExpressResponse} from '../types.js'
*/
/**
* @module group
* @description Group Management Router
*
* This router provides comprehensive endpoints for managing hierarchical group structures
* within organizations. Groups form the backbone of the member management system,
* supporting complex organizational hierarchies with gender and age stage restrictions.
*
* Key Features:
* - Hierarchical group creation and management
* - Gender-specific and age-stage group restrictions
* - Permission-based access control
* - Group membership and relationship tracking
* - Historical data management with backdating support
*
* Business Rules:
* - Groups can have gender restrictions (Male, Female, Mixed, Combined)
* - Groups can have age stage restrictions (Children, Youth, Adults, etc.)
* - Users can only manage groups within their permission scope
* - Group hierarchies support unlimited nesting depth
* - Combined groups are virtual views of multiple groups
*
* @requires express - Web framework for routing
* @requires @/utils/authChecks - Authentication and authorization utilities
* @requires @/utils/requestLogger - Request logging middleware
* @requires ./group/controller - Group business logic controller
*/
import express from 'express';
import { checkAdmin, checkObjectAdmin, checkVisible } from '../utils/authChecks.js';
import { requestUpdateLogger, readLogger } from '../utils/requestLogger.js';
import * as groupController from './group/controller.js';
const api = express();
// Create or update a group - parameter should be UIDparent according to OpenAPI
/**
* @route PUT /api/kpe20/group/:UIDparent
* @group Group Management
* @description Create a new group as a child of the specified parent group
* @param {string} UIDparent - UUID of the parent group
* @param {object} body - Group creation data
* @param {string} body.name - Group name
* @param {string} [body.genderGroup] - Gender restriction (M=Male, F=Female, B=Mixed, C=Combined)
* @param {string} [body.stage] - Age stage restriction
* @param {string} [body.location] - Geographic location
* @param {object} [body.config] - Additional configuration
* @example
* PUT /api/kpe20/group/UUID-parent-123
* Body: {"name": "Junior Team A", "genderGroup": "M", "stage": "Junioren"}
* @returns {Object} Response object
* @property {boolean} .success - Whether the operation was successful
* @property {object} .result - Created group data with UID
*/
// @ts-ignore
api.put('/:UIDparent', requestUpdateLogger, checkObjectAdmin, groupController.putGroup);
// Update group (alternative endpoint)
/**
* @route POST /api/kpe20/group/:UID
* @group Group Management
* @description Update an existing group's information
* @param {string} UID - UUID of the group to update
* @param {object} body - Updated group data
* @param {string} [body.name] - New group name
* @param {string} [body.genderGroup] - Updated gender restriction
* @param {string} [body.stage] - Updated age stage restriction
* @param {string} [body.location] - Updated location
* @param {object} [body.config] - Updated configuration
* @example
* POST /api/kpe20/group/UUID-group-456
* Body: {"name": "Senior Team A", "stage": "Senioren"}
* @returns {Object} Response object
* @property {boolean} .success - Whether the update was successful
* @property {object} .result - Updated group data
*/
// @ts-ignore
api.post('/:UID', requestUpdateLogger, checkObjectAdmin, groupController.updateGroup);
// Delete a group - parameter should be UID according to OpenAPI
/**
* @route DELETE /api/kpe20/group/:UID
* @group Group Management
* @description Delete a group and optionally move members to another group
* @param {string} UID - UUID of the group to delete
* @param {object} [body] - Deletion options
* @param {string} [body.moveToUID] - UUID of group to move members to
* @example
* DELETE /api/kpe20/group/UUID-group-789
* Body: {"moveToUID": "UUID-destination-group"}
* @returns {Object} Response object
* @property {boolean} .success - Whether the deletion was successful
* @property {number} .movedMembers - Number of members moved (if applicable)
*/
// @ts-ignore
api.delete('/:UID', requestUpdateLogger, checkObjectAdmin, groupController.deleteGroup);
// Get group details
/**
* @route GET /api/kpe20/group/:UID
* @group Group Management
* @description Get detailed information about a specific group
* @param {string} UID - UUID of the group to retrieve
* @example
* GET /api/kpe20/group/UUID-group-123
* @returns {Object} Response object
* @property {boolean} .success - Whether the request was successful
* @property {object} .result - Complete group data including hierarchy info
* @property {string} .result.name - Group name
* @property {string} .result.genderGroup - Gender restriction
* @property {string} .result.stage - Age stage restriction
* @property {string} .result.location - Geographic location
* @property {object} .result.parent - Parent group information
* @property {object[]} .result.children - Child groups array
* @property {number} .result.memberCount - Number of direct members
*/
// @ts-ignore
api.get('/:UID', checkVisible, readLogger, groupController.getGroup);
// Get minimum backdate timestamp for a group
/**
* @route GET /api/kpe20/group/minTimestamp/:UID
* @group Group Management
* @description Get the minimum timestamp for historical data in this group
* Used to determine the earliest date for which historical member data is available
* @param {string} UID - UUID of the group
* @example
* GET /api/kpe20/group/minTimestamp/UUID-group-123
* Response: {"success": true, "result": 1609459200000}
* @returns {Object} Response object
* @property {boolean} .success - Whether the request was successful
* @property {number} .result - Unix timestamp in milliseconds
*/
// @ts-ignore
api.get('/minTimestamp/:UID', checkVisible, readLogger, groupController.minTimestamp);
// Check if current user is admin for the group - requires authentication
/**
* @route GET /api/kpe20/group/admin/:UID
* @group Group Management
* @description Check if the current user has admin privileges for the specified group
* @param {string} UID - UUID of the group to check
* @example
* GET /api/kpe20/group/admin/UUID-group-123
* Response: {"success": true, "result": true}
* @returns {Object} Response object
* @property {boolean} .success - Whether the request was successful
* @property {boolean} .result - Whether user has admin rights for this group
*/
// @ts-ignore
api.get('/admin/:UID', checkVisible, groupController.checkGroupAdmin);
export default api;