backend/src/main/java/com/gpt/geumpumtabackend/study/api/StudySessionApi.java at 408cc2c0123f962858a74009a02062e71b262184 · Geumpumta/backend · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
package com.gpt.geumpumtabackend.study.api;

import com.gpt.geumpumtabackend.global.aop.AssignUserId;
import com.gpt.geumpumtabackend.global.config.swagger.SwaggerApiFailedResponse;
import com.gpt.geumpumtabackend.global.config.swagger.SwaggerApiResponses;
import com.gpt.geumpumtabackend.global.config.swagger.SwaggerApiSuccessResponse;
import com.gpt.geumpumtabackend.global.exception.ExceptionType;
import com.gpt.geumpumtabackend.global.response.ResponseBody;
import com.gpt.geumpumtabackend.study.dto.request.HeartBeatRequest;
import com.gpt.geumpumtabackend.study.dto.request.StudyEndRequest;
import com.gpt.geumpumtabackend.study.dto.request.StudyStartRequest;
import com.gpt.geumpumtabackend.study.dto.response.HeartBeatResponse;
import com.gpt.geumpumtabackend.study.dto.response.StudySessionResponse;
import com.gpt.geumpumtabackend.study.dto.response.StudyStartResponse;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import org.springframework.http.ResponseEntity;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;

@Tag(name = "학습 세션 API", description = """
    금오공대 캠퍼스 내에서만 사용할 수 있는 학습 타이머 기능을 제공합니다.


    📋 **사용 흐름:**
    1. `GET /api/v1/study` - 오늘 총 학습 시간 조회
    2. `POST /api/v1/study/start` - 학습 시작 (Wi-Fi 검증 필수)
    3. `POST /api/v1/study/heart-beat` - 30초마다 연결 상태 확인
    4. `POST /api/v1/study/end` - 학습 종료

    ⚠️ **중요사항:**
    - 모든 API는 캠퍼스 Wi-Fi 연결 시에만 작동
    - 하트비트 중단시 90초 후 자동 세션 종료
    """)
public interface StudySessionApi {

    @Operation(
            summary = "오늘의 학습 시간 조회",
            description = """
            사용자의 오늘 하루 총 학습 시간을 조회합니다.

            📊 **반환 정보:**
            - 오늘 00:00부터 현재까지의 누적 학습 시간 (밀리초)
            """
    )
    @ApiResponse(content = @Content(schema = @Schema(implementation = StudySessionResponse.class)))
    @SwaggerApiResponses(
            success = @SwaggerApiSuccessResponse(
                    response = StudySessionResponse.class,
                    description = "오늘의 학습 시간 조회 성공"),
            errors = {
                    @SwaggerApiFailedResponse(ExceptionType.NEED_AUTHORIZED),
                    @SwaggerApiFailedResponse(ExceptionType.USER_NOT_FOUND)
            }
    )
    @GetMapping
    @AssignUserId
    @PreAuthorize("isAuthenticated() and hasRole('USER')")
    ResponseEntity<ResponseBody<StudySessionResponse>> getTodayStudySession(
            @Parameter(hidden = true) Long userId
    );

    @Operation(
            summary = "학습 세션 시작",
            description = """
            새로운 학습 세션을 시작합니다. 캠퍼스 Wi-Fi 검증이 필수입니다.

            🔐 **Wi-Fi 검증 과정:**
            1. Gateway IP 검증 - 캠퍼스 게이트웨이 IP (172.30.64.1)와 일치하는지 확인
            2. IP 대역 검증 - 클라이언트 IP가 캠퍼스 범위(172.30.64.0/18) 내인지 확인

            💡 **보안 특징:**

            - Gateway IP는 점-십진 표기법 문자열로 전송 (예: "172.30.64.1")

            ✅ **성공 시:**
            - 새로운 학습 세션 생성
            - 세션 ID 반환 (하트비트에서 사용)

            ❌ **실패 사유:**
            - 캠퍼스 외부에서 접근
            - Wi-Fi 정보 불일치
            """
    )
    @ApiResponse(content = @Content(schema = @Schema(implementation = StudyStartResponse.class)))
    @SwaggerApiResponses(
            success = @SwaggerApiSuccessResponse(
                    response = StudyStartResponse.class,
                    description = "학습 세션 시작 성공"),
            errors = {
                    @SwaggerApiFailedResponse(ExceptionType.NEED_AUTHORIZED),
                    @SwaggerApiFailedResponse(ExceptionType.USER_NOT_FOUND),
                    @SwaggerApiFailedResponse(ExceptionType.WIFI_NOT_CAMPUS_NETWORK),
                    @SwaggerApiFailedResponse(ExceptionType.WIFI_VALIDATION_ERROR),
                    @SwaggerApiFailedResponse(ExceptionType.WIFI_INVALID_FORMAT)
            }
    )
    @PostMapping("/start")
    @AssignUserId
    @PreAuthorize("isAuthenticated() and hasRole('USER')")
    ResponseEntity<ResponseBody<StudyStartResponse>> startStudySession(
            @Valid @RequestBody StudyStartRequest request,
            @Parameter(hidden = true) Long userId
    );

    @Operation(
            summary = "학습 세션 종료",
            description = """
            현재 진행 중인 학습 세션을 종료합니다.

            📊 **종료 시 처리:**
            - 총 학습 시간 계산 및 저장
            - 세션 상태를 FINISHED로 변경
            - 랭킹 시스템에 반영 (다음 스케줄링 시)
            """
    )
    @SwaggerApiResponses(
            success = @SwaggerApiSuccessResponse(
                    description = "학습 세션 종료 성공"),
            errors = {
                    @SwaggerApiFailedResponse(ExceptionType.NEED_AUTHORIZED),
                    @SwaggerApiFailedResponse(ExceptionType.USER_NOT_FOUND),
                    @SwaggerApiFailedResponse(ExceptionType.STUDY_SESSION_NOT_FOUND)
            }
    )
    @PostMapping("/end")
    @AssignUserId
    @PreAuthorize("isAuthenticated() and hasRole('USER')")
    ResponseEntity<ResponseBody<Void>> endStudySession(
            @Valid @RequestBody StudyEndRequest request,
            @Parameter(hidden = true) Long userId
    );

    @Operation(
            summary = "하트비트 전송",
            description = """
            학습 중 연결 상태를 유지하기 위한 하트비트를 전송합니다.

            ⏱️ **전송 주기:** 30초마다 자동 전송 권장

            🔄 **동작 원리:**
            1. Wi-Fi 연결 상태 재검증 (Gateway IP + IP 대역 확인)
            2. 클라이언트 실제 IP 주소 재확인 (서버에서 추출)
            3.

            🚨 **실패 시 대응:**
            - Wi-Fi 연결 끊김: 재연결 후 다시 `/start` 호출
            - 세션 만료: 새로운 세션 시작 필요

            """
    )
    @SwaggerApiResponses(
            success = @SwaggerApiSuccessResponse(
                    description = "하트비트 전송 성공 - 세션 유지"),
            errors = {
                    @SwaggerApiFailedResponse(ExceptionType.NEED_AUTHORIZED),
                    @SwaggerApiFailedResponse(ExceptionType.USER_NOT_FOUND),
                    @SwaggerApiFailedResponse(ExceptionType.STUDY_SESSION_NOT_FOUND),
                    @SwaggerApiFailedResponse(ExceptionType.WIFI_NOT_CAMPUS_NETWORK),
                    @SwaggerApiFailedResponse(ExceptionType.WIFI_VALIDATION_ERROR)
            }
    )
    @PostMapping("/heart-beat")
    @AssignUserId
    @PreAuthorize("isAuthenticated() and hasRole('USER')")
    ResponseEntity<ResponseBody<HeartBeatResponse>> processHeartBeat(
            @Valid @RequestBody HeartBeatRequest heartBeatRequest,
            @Parameter(hidden = true) Long userId);
}