// docs/src/route/admin.js

/**
 * @swagger
 * tags:
 *   - name: Admin
 *     description: Admin management endpoints
 *   - name: Users
 *     description: User management
 *   - name: Statistics
 *     description: Platform statistics
 *   - name: Swaps
 *     description: Swap management
 *   - name: Issues
 *     description: Reported issues
 *   - name: Transactions
 *     description: Transaction management
 *   - name: Activity
 *     description: Recent activity
 */

/**
 * @swagger
 * components:
 *   securitySchemes:
 *     bearerAuth:
 *       type: http
 *       scheme: bearer
 *       bearerFormat: JWT
 *   schemas:
 *     Pagination:
 *       type: object
 *       properties:
 *         totalItems:
 *           type: integer
 *         totalPages:
 *           type: integer
 *         currentPage:
 *           type: integer
 *         itemsPerPage:
 *           type: integer
 *         hasNextPage:
 *           type: boolean
 *         hasPreviousPage:
 *           type: boolean
 *     UserBasic:
 *       type: object
 *       properties:
 *         id:
 *           type: string
 *         firstName:
 *           type: string
 *         lastName:
 *           type: string
 *         email:
 *           type: string
 *         phone:
 *           type: string
 *         role:
 *           type: string
 *         createdAt:
 *           type: string
 *           format: date-time
 *     User:
 *       allOf:
 *         - $ref: '#/components/schemas/UserBasic'
 *         - type: object
 *           properties:
 *             verified:
 *               type: boolean
 *             suspended:
 *               type: boolean
 *             suspensionReason:
 *               type: string
 *             updatedAt:
 *               type: string
 *               format: date-time
 *             address:
 *               type: string
 *             accountNumber:
 *               type: string
 *             bankName:
 *               type: string
 *             bankCode:
 *               type: string
 *             uid:
 *               type: string
 *     ProductBasic:
 *       type: object
 *       properties:
 *         id:
 *           type: string
 *         name:
 *           type: string
 *         price:
 *           type: number
 *         swappable:
 *           type: boolean
 *         createdAt:
 *           type: string
 *           format: date-time
 *         user:
 *           $ref: '#/components/schemas/UserBasic'
 *     Swap:
 *       type: object
 *       properties:
 *         id:
 *           type: string
 *         status:
 *           type: string
 *           enum: [pending, accepted, rejected, completed]
 *         amount:
 *           type: number
 *         createdAt:
 *           type: string
 *           format: date-time
 *         product:
 *           $ref: '#/components/schemas/ProductBasic'
 *         user:
 *           $ref: '#/components/schemas/UserBasic'
 *     SwapExtended:
 *       type: object
 *       properties:
 *         id:
 *           type: string
 *         totalAmount:
 *           type: number
 *         createdAt:
 *           type: string
 *           format: date-time
 *         user:
 *           $ref: '#/components/schemas/UserBasic'
 *         products:
 *           type: array
 *           items:
 *             $ref: '#/components/schemas/ProductBasic'
 *     Issue:
 *       type: object
 *       properties:
 *         id:
 *           type: string
 *         rating:
 *           type: integer
 *         comment:
 *           type: string
 *         createdAt:
 *           type: string
 *           format: date-time
 *         user:
 *           $ref: '#/components/schemas/UserBasic'
 *     Transaction:
 *       type: object
 *       properties:
 *         id:
 *           type: string
 *         amount:
 *           type: number
 *         status:
 *           type: string
 *           enum: [pending, success, failed]
 *         createdAt:
 *           type: string
 *           format: date-time
 *         sender:
 *           $ref: '#/components/schemas/UserBasic'
 *         receiver:
 *           $ref: '#/components/schemas/UserBasic'
 *     Statistics:
 *       type: object
 *       properties:
 *         totalUsers:
 *           type: integer
 *         activeSwaps:
 *           type: integer
 *         itemsListed:
 *           type: integer
 *         reportedIssues:
 *           type: integer
 *         totalTransactions:
 *           type: integer
 *         transactionVolume:
 *           type: number
 *         recentOrders:
 *           type: integer
 *     Activity:
 *       type: object
 *       properties:
 *         recentSignups:
 *           type: array
 *           items:
 *             $ref: '#/components/schemas/UserBasic'
 *         recentListings:
 *           type: array
 *           items:
 *             $ref: '#/components/schemas/ProductBasic'
 *         completedSwaps:
 *           type: array
 *           items:
 *             $ref: '#/components/schemas/SwapExtended'
 */


/**
 * @swagger
 * /api/admin/login:
 *   post:
 *     summary: Admin login
 *     tags: [Admin]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - email
 *               - password
 *             properties:
 *               email:
 *                 type: string
 *                 example: admin@example.com
 *               password:
 *                 type: string
 *                 example: secret123
 *     responses:
 *       200:
 *         description: Successful login
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 token:
 *                   type: string
 *                 user:
 *                   type: object
 *                   properties:
 *                     name:
 *                       type: string
 *                     email:
 *                       type: string
 *                     role:
 *                       type: string
 *       400:
 *         description: Invalid credentials or user role
 *       404:
 *         description: Account not found
 *       500:
 *         description: Internal server error
 */


/**
 * @swagger
 * /api/admin/add:
 *   post:
 *     summary: Add a new admin or superadmin
 *     tags: [Admin]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - email
 *               - password
 *               - role
 *             properties:
 *               email:
 *                 type: string
 *                 example: newadmin@example.com
 *               password:
 *                 type: string
 *                 example: strongPassword123
 *               role:
 *                 type: string
 *                 enum: [admin, superadmin]
 *                 example: admin
 *     responses:
 *       200:
 *         description: Admin created successfully
 *       400:
 *         description: Missing fields, invalid role, or account already exists
 *       500:
 *         description: Internal server error
 */






/**
 * @swagger
 * /api/admin/users/all:
 *   get:
 *     summary: Get all users with pagination and filtering
 *     tags: [Users]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *         description: Page number
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 10
 *         description: Items per page
 *       - in: query
 *         name: search
 *         schema:
 *           type: string
 *         description: Search term (name, email, phone)
 *       - in: query
 *         name: verified
 *         schema:
 *           type: boolean
 *         description: Filter by verification status
 *       - in: query
 *         name: suspended
 *         schema:
 *           type: boolean
 *         description: Filter by suspension status
 *       - in: query
 *         name: role
 *         schema:
 *           type: string
 *           enum: [user, admin, superadmin]
 *         description: Filter by user role
 *       - in: query
 *         name: startDate
 *         schema:
 *           type: string
 *           format: date
 *         description: Start date for filtering (YYYY-MM-DD)
 *       - in: query
 *         name: endDate
 *         schema:
 *           type: string
 *           format: date
 *         description: End date for filtering (YYYY-MM-DD)
 *       - in: query
 *         name: sortBy
 *         schema:
 *           type: string
 *         description: Field to sort by
 *       - in: query
 *         name: sortOrder
 *         schema:
 *           type: string
 *           enum: [asc, desc]
 *         description: Sort order (asc/desc)
 *     responses:
 *       200:
 *         description: List of users with pagination info
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 users:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/User'
 *                 pagination:
 *                   $ref: '#/components/schemas/Pagination'
 *       401:
 *         description: Unauthorized - Admin access required
 *       500:
 *         description: Server error
 */

/**
 * @swagger
 * /api/admin/users/{id}:
 *   get:
 *     summary: Get user details by ID
 *     tags: [Users]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *         description: User ID
 *     responses:
 *       200:
 *         description: User details
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 *       401:
 *         description: Unauthorized - Admin access required
 *       404:
 *         description: User not found
 *       500:
 *         description: Server error
 */

/**
 * @swagger
 * /api/admin/statistics:
 *   get:
 *     summary: Get platform statistics
 *     tags: [Statistics]
 *     security:
 *       - bearerAuth: []
 *     responses:
 *       200:
 *         description: Platform statistics
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 statistics:
 *                   $ref: '#/components/schemas/Statistics'
 *       401:
 *         description: Unauthorized - Admin access required
 *       500:
 *         description: Server error
 */

/**
 * @swagger
 * /api/admin/swaps/active:
 *   get:
 *     summary: Get active swaps
 *     tags: [Swaps]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *         description: Page number
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 10
 *         description: Items per page
 *     responses:
 *       200:
 *         description: List of active swaps
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 swaps:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/Swap'
 *                 pagination:
 *                   $ref: '#/components/schemas/Pagination'
 *       401:
 *         description: Unauthorized - Admin access required
 *       500:
 *         description: Server error
 */

/**
 * @swagger
 * /api/admin/issues/reported:
 *   get:
 *     summary: Get reported issues
 *     tags: [Issues]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *         description: Page number
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 10
 *         description: Items per page
 *     responses:
 *       200:
 *         description: List of reported issues
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 issues:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/Issue'
 *                 pagination:
 *                   $ref: '#/components/schemas/Pagination'
 *       401:
 *         description: Unauthorized - Admin access required
 *       500:
 *         description: Server error
 */

/**
 * @swagger
 * /api/admin/transactions/recent:
 *   get:
 *     summary: Get recent transactions
 *     tags: [Transactions]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *         description: Page number
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 10
 *         description: Items per page
 *     responses:
 *       200:
 *         description: List of transactions
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 transactions:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/Transaction'
 *                 pagination:
 *                   $ref: '#/components/schemas/Pagination'
 *       401:
 *         description: Unauthorized - Admin access required
 *       500:
 *         description: Server error
 */

/**
 * @swagger
 * /api/admin/activity/recent:
 *   get:
 *     summary: Get recent activity
 *     tags: [Activity]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 10
 *         description: Number of items to return
 *       - in: query
 *         name: days
 *         schema:
 *           type: integer
 *           default: 7
 *         description: Number of days to look back
 *     responses:
 *       200:
 *         description: Recent activity data
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/Activity'
 *       401:
 *         description: Unauthorized - Admin access required
 *       500:
 *         description: Server error
 */

/**
 * @swagger
 * /api/admin/signups/recent:
 *   get:
 *     summary: Get recent signups
 *     tags: [Activity]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *         description: Page number
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 10
 *         description: Items per page
 *       - in: query
 *         name: days
 *         schema:
 *           type: integer
 *           default: 30
 *         description: Number of days to look back
 *     responses:
 *       200:
 *         description: List of recent signups
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 signups:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/UserBasic'
 *                 pagination:
 *                   $ref: '#/components/schemas/Pagination'
 *       401:
 *         description: Unauthorized - Admin access required
 *       500:
 *         description: Server error
 */

/**
 * @swagger
 * /api/admin/listings/recent:
 *   get:
 *     summary: Get recent listings
 *     tags: [Activity]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *         description: Page number
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 10
 *         description: Items per page
 *       - in: query
 *         name: days
 *         schema:
 *           type: integer
 *           default: 30
 *         description: Number of days to look back
 *     responses:
 *       200:
 *         description: List of recent listings
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 listings:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/ProductBasic'
 *                 pagination:
 *                   $ref: '#/components/schemas/Pagination'
 *       401:
 *         description: Unauthorized - Admin access required
 *       500:
 *         description: Server error
 */

/**
 * @swagger
 * /api/admin/swaps/completed:
 *   get:
 *     summary: Get completed swaps
 *     tags: [Activity]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *         description: Page number
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 10
 *         description: Items per page
 *       - in: query
 *         name: days
 *         schema:
 *           type: integer
 *           default: 30
 *         description: Number of days to look back
 *     responses:
 *       200:
 *         description: List of completed swaps
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 swaps:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/SwapExtended'
 *                 pagination:
 *                   $ref: '#/components/schemas/Pagination'
 *       401:
 *         description: Unauthorized - Admin access required
 *       500:
 *         description: Server error
 */

/**
 * @swagger
 * /api/admin/users/{userId}/suspend:
 *   put:
 *     summary: Suspend or unsuspend an account
 *     tags: [Admin]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: userId
 *         required: true
 *         schema:
 *           type: string
 *         description: User ID to suspend/unsuspend
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               suspend:
 *                 type: boolean
 *                 description: True to suspend, false to unsuspend
 *                 required: true
 *               reason:
 *                 type: string
 *                 description: Reason for suspension
 *     responses:
 *       200:
 *         description: Account suspension status updated
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 message:
 *                   type: string
 *                 user:
 *                   $ref: '#/components/schemas/UserBasic'
 *       400:
 *         description: Invalid input
 *       401:
 *         description: Unauthorized - Admin access required
 *       403:
 *         description: Forbidden (trying to suspend admin as non-superadmin)
 *       404:
 *         description: User not found
 *       500:
 *         description: Server error
 */

/**
 * @swagger
 * /api/admin/users/{userId}/promote:
 *   put:
 *     summary: Promote user to admin
 *     tags: [Admin]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: userId
 *         required: true
 *         schema:
 *           type: string
 *         description: User ID to promote
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               adminRole:
 *                 type: string
 *                 enum: [admin, superadmin]
 *                 default: admin
 *                 description: Admin role (admin or superadmin)
 *     responses:
 *       200:
 *         description: User promoted successfully
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 message:
 *                   type: string
 *                 user:
 *                   $ref: '#/components/schemas/UserBasic'
 *       400:
 *         description: Invalid input
 *       401:
 *         description: Unauthorized - Admin access required
 *       403:
 *         description: Forbidden (trying to create superadmin as non-superadmin)
 *       404:
 *         description: User not found
 *       500:
 *         description: Server error
 */

/**
 * @swagger
 * /api/admin/users/{userId}/demote:
 *   put:
 *     summary: Remove admin privileges
 *     tags: [Admin]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: userId
 *         required: true
 *         schema:
 *           type: string
 *         description: Admin user ID to demote
 *     responses:
 *       200:
 *         description: Admin demoted successfully
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 message:
 *                   type: string
 *                 user:
 *                   $ref: '#/components/schemas/UserBasic'
 *       400:
 *         description: User is not an admin
 *       401:
 *         description: Unauthorized - Admin access required
 *       403:
 *         description: Forbidden (trying to demote as non-superadmin or self)
 *       404:
 *         description: User not found
 *       500:
 *         description: Server error
 */

/**
 * @swagger
 * /api/admin/users/{userId}:
 *   delete:
 *     summary: Delete user account
 *     tags: [Admin]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: userId
 *         required: true
 *         schema:
 *           type: string
 *         description: User ID to delete
 *     responses:
 *       200:
 *         description: Account deleted successfully
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 message:
 *                   type: string
 *                 userId:
 *                   type: string
 *       401:
 *         description: Unauthorized - Admin access required
 *       403:
 *         description: Forbidden (trying to delete admin or self)
 *       404:
 *         description: User not found
 *       500:
 *         description: Server error
 */
