import {
  Body,
  Controller,
  Get,
  Param,
  Post,
  ValidationPipe,
  UsePipes,
  HttpCode,
  HttpStatus,
} from '@nestjs/common';
import {
  ApiTags,
  ApiOperation,
  ApiParam,
  ApiResponse,
  ApiBody,
} from '@nestjs/swagger';
import { StudentService } from './student.service';
import { StudentLoginDto } from './dto/student-login-dto';

/**
 * StudentController - Controller for student-related operations
 *
 * This controller handles endpoints for student authentication and profile
 * management. It provides a clean API for student-specific functionality
 * separate from general user or admin operations.
 *
 * All routes are at the root level as defined by the empty @Controller decorator.
 *
 * @example
 * // Student profile endpoint
 * GET /profile/12345
 *
 * @example
 * // Student login endpoint
 * POST /login
 * Body: { "login_by": "1", "country_iso3_code": "IND", "mobile": "9876543210", "password": "Pass@123" }
 */
@ApiTags('Student') // Groups endpoints under 'Student' in Swagger UI
@Controller('') // Empty controller path means routes are at root level
export class StudentController {
  /**
   * Creates an instance of StudentController
   *
   * @param studentService - StudentService for business logic
   */
  constructor(private readonly studentService: StudentService) {}

  /**
   * Get student full profile
   *
   * Retrieves comprehensive profile information for a specific student.
   * Typically includes personal details, academic information, enrollment
   * status, and other student-specific data.
   *
   * Security considerations:
   * - Should validate that the requesting user has permission to view the profile
   * - Consider implementing role-based access control
   * - Never expose sensitive information (passwords, payment details, etc.)
   *
   * @param id - Student identifier (typically database ID)
   * @returns Complete student profile data
   *
   * @throws 404 - Student not found
   * @throws 403 - Insufficient permissions to view profile
   *
   * @example
   * GET /profile/12345
   */
  @Get('profile/:id')
  @ApiOperation({
    summary: 'Get student full profile',
    description:
      'Retrieve comprehensive profile information for a specific student',
  })
  @ApiParam({
    name: 'id',
    description: 'Student ID',
    example: 12345,
    type: Number,
  })
  @ApiResponse({
    status: 200,
    description: 'Student profile retrieved successfully',
    schema: {
      example: {
        id: 12345,
        name: 'John Doe',
        email: 'john.doe@example.com',
        mobile: '+919876543210',
        enrollment_date: '2024-01-15',
        courses: ['Mathematics 101', 'Physics 201'],
        // ... other profile data
      },
    },
  })
  @ApiResponse({ status: 404, description: 'Student not found' })
  @ApiResponse({ status: 403, description: 'Insufficient permissions' })
  getStudentFullProfile(@Param('id') id: number) {
    return this.studentService.getStudentFullProfile(id);
  }

  /**
   * Student login
   *
   * Authenticates a student using one of multiple login methods
   * (mobile, email, or UID). Returns authentication tokens and
   * basic user information upon successful login.
   *
   * Validation features:
   * - Automatic validation of StudentLoginDto using ValidationPipe
   * - Conditional field validation based on login_by method
   * - Password validation against stored hash
   * - Account status checks (active, verified, etc.)
   *
   * @param body - Login credentials (login method, identifier, password)
   * @returns Authentication tokens and basic student info
   *
   * @throws 400 - Invalid request data (validation failed)
   * @throws 401 - Invalid credentials
   * @throws 403 - Account inactive or suspended
   *
   * @example
   * POST /login
   * Body: {
   *   "login_by": "1",
   *   "country_iso3_code": "IND",
   *   "mobile": "9876543210",
   *   "password": "Pass@123"
   * }
   */
  @Post('login')
  @HttpCode(HttpStatus.OK) // Explicitly set 200 OK for login success
  @ApiOperation({
    summary: 'Student login',
    description:
      'Authenticate student using mobile, email, or UID with password',
  })
  @ApiBody({
    type: StudentLoginDto,
    description: 'Login credentials with method-specific identifier',
    examples: {
      mobileLogin: {
        summary: 'Mobile login example',
        value: {
          login_by: '1',
          country_iso3_code: 'IND',
          mobile: '9876543210',
          password: 'Pass@123',
        },
      },
      emailLogin: {
        summary: 'Email login example',
        value: {
          login_by: '2',
          email: 'student@example.com',
          password: 'Pass@123',
        },
      },
    },
  })
  @ApiResponse({
    status: 200,
    description: 'Login successful',
    schema: {
      example: {
        access_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
        refresh_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
        expires_in: 3600,
        student: {
          id: 12345,
          name: 'John Doe',
          email: 'john.doe@example.com',
        },
      },
    },
  })
  @ApiResponse({ status: 400, description: 'Invalid request data' })
  @ApiResponse({ status: 401, description: 'Invalid credentials' })
  @ApiResponse({ status: 403, description: 'Account inactive or suspended' })
  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
  login(@Body() body: StudentLoginDto) {
    return this.studentService.login(body);
  }

  /**
   * Potential future endpoints:
   *
   * @Get('dashboard/:id')
   * getStudentDashboard(@Param('id') id: number) {
   *   return this.studentService.getDashboardData(id);
   * }
   *
   * @Patch('profile/:id')
   * updateStudentProfile(@Param('id') id: number, @Body() updateDto: UpdateStudentDto) {
   *   return this.studentService.updateProfile(id, updateDto);
   * }
   *
   * @Get('courses/:id')
   * getStudentCourses(@Param('id') id: number) {
   *   return this.studentService.getEnrolledCourses(id);
   * }
   *
   * @Post('logout')
   * logout(@Body() logoutDto: LogoutDto) {
   *   return this.studentService.logout(logoutDto);
   * }
   */
}
