feat: 구글 스프레드시트 API MVP 구현

build.gradle

@@ -75,6 +75,13 @@ dependencies {
     // notification
     implementation 'com.google.firebase:firebase-admin:9.2.0'
 
+    // Google Sheets API
+    implementation 'com.google.apis:google-api-services-sheets:v4-rev20251110-2.0.0'
+    implementation 'com.google.auth:google-auth-library-oauth2-http:1.23.0'
+
+    // Google Drive API
+    implementation 'com.google.apis:google-api-services-drive:v3-rev20250723-2.0.0'
+
     // Gemini AI - using REST API directly (no SDK dependency)
 
     // test

src/main/java/gg/agit/konect/domain/club/controller/ClubMemberSheetApi.java

@@ -0,0 +1,51 @@
+package gg.agit.konect.domain.club.controller;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+
+import gg.agit.konect.domain.club.dto.ClubMemberSheetSyncResponse;
+import gg.agit.konect.domain.club.dto.ClubSheetIdUpdateRequest;
+import gg.agit.konect.domain.club.enums.ClubSheetSortKey;
+import gg.agit.konect.global.auth.annotation.UserId;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+
+@Tag(name = "(Normal) Club - Sheet")
+@RequestMapping("/clubs")
+public interface ClubMemberSheetApi {
+
+    @Operation(
+        summary = "구글 스프레드시트 ID 등록 / 수정",
+        description = "동아리에서 사용 중인 구글 스프레드시트 ID를 등록하거나 수정합니다. "
+            + "등록 시 AI(Claude Haiku)가 시트 상단 10행을 자동으로 분석하여 "
+            + "이름·학번·연락처 등 컬럼 위치를 파악하고, 이후 동기화 시 해당 컬럼에만 값을 채웁니다. "
+            + "시트 양식이 변경된 경우 이 API를 다시 호출하면 AI가 재분석합니다."
+    )
+    @PutMapping("/{clubId}/sheet")
+    ResponseEntity<Void> updateSheetId(
+        @PathVariable(name = "clubId") Integer clubId,
+        @Valid @RequestBody ClubSheetIdUpdateRequest request,
+        @UserId Integer requesterId
+    );
+
+    @Operation(
+        summary = "동아리 인명부 스프레드시트 동기화",
+        description = "등록된 구글 스프레드시트에 동아리 회원 인명부를 동기화합니다. "
+            + "sortKey로 정렬 기준(NAME, STUDENT_ID, POSITION, JOINED_AT)을 지정할 수 있으며, "
+            + "ascending으로 오름차순/내림차순을 설정합니다. "
+            + "가입 승인·탈퇴 시에도 자동으로 동기화됩니다."
+    )
+    @PostMapping("/{clubId}/members/sheet-sync")
+    ResponseEntity<ClubMemberSheetSyncResponse> syncMembersToSheet(
+        @PathVariable(name = "clubId") Integer clubId,
+        @RequestParam(name = "sortKey", defaultValue = "POSITION") ClubSheetSortKey sortKey,
+        @RequestParam(name = "ascending", defaultValue = "true") boolean ascending,
+        @UserId Integer requesterId
+    );
+}

src/main/java/gg/agit/konect/domain/club/controller/ClubMemberSheetController.java

@@ -0,0 +1,46 @@
+package gg.agit.konect.domain.club.controller;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import gg.agit.konect.domain.club.dto.ClubMemberSheetSyncResponse;
+import gg.agit.konect.domain.club.dto.ClubSheetIdUpdateRequest;
+import gg.agit.konect.domain.club.enums.ClubSheetSortKey;
+import gg.agit.konect.domain.club.service.ClubMemberSheetService;
+import gg.agit.konect.global.auth.annotation.UserId;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+
+@RestController
+@RequiredArgsConstructor
+@RequestMapping("/clubs")
+public class ClubMemberSheetController implements ClubMemberSheetApi {
+
+    private final ClubMemberSheetService clubMemberSheetService;
+
+    @Override
+    public ResponseEntity<Void> updateSheetId(
+        @PathVariable(name = "clubId") Integer clubId,
+        @Valid @RequestBody ClubSheetIdUpdateRequest request,
+        @UserId Integer requesterId
+    ) {
+        clubMemberSheetService.updateSheetId(clubId, requesterId, request);
+        return ResponseEntity.ok().build();
+    }
+
+    @Override
+    public ResponseEntity<ClubMemberSheetSyncResponse> syncMembersToSheet(
+        @PathVariable(name = "clubId") Integer clubId,
+        @RequestParam(name = "sortKey", defaultValue = "POSITION") ClubSheetSortKey sortKey,
+        @RequestParam(name = "ascending", defaultValue = "true") boolean ascending,
+        @UserId Integer requesterId
+    ) {
+        ClubMemberSheetSyncResponse response =
+            clubMemberSheetService.syncMembersToSheet(clubId, requesterId, sortKey, ascending);
+        return ResponseEntity.ok(response);
+    }
+}

src/main/java/gg/agit/konect/domain/club/controller/ClubSheetMigrationApi.java

@@ -0,0 +1,48 @@
+package gg.agit.konect.domain.club.controller;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+
+import gg.agit.konect.domain.club.dto.ClubMemberSheetSyncResponse;
+import gg.agit.konect.domain.club.dto.SheetImportRequest;
+import gg.agit.konect.domain.club.dto.SheetImportResponse;
+import gg.agit.konect.domain.club.dto.SheetMigrateRequest;
+import gg.agit.konect.global.auth.annotation.UserId;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+
+@Tag(name = "(Normal) Club - Sheet")
+@RequestMapping("/clubs")
+public interface ClubSheetMigrationApi {
+
+    @Operation(
+        summary = "기존 스프레드시트 → 팀 양식으로 이관",
+        description = "동아리가 기존에 사용하던 스프레드시트 URL을 제출하면, "
+            + "AI가 데이터를 분석하여 KONECT 팀이 마련한 표준 양식 파일로 복사합니다. "
+            + "새 파일은 기존 URL과 동일한 Google Drive 폴더에 생성됩니다. "
+            + "이후 동기화는 새로 생성된 파일 기준으로 진행됩니다."
+    )
+    @PostMapping("/{clubId}/sheet/migrate")
+    ResponseEntity<ClubMemberSheetSyncResponse> migrateSheet(
+        @PathVariable(name = "clubId") Integer clubId,
+        @Valid @RequestBody SheetMigrateRequest request,
+        @UserId Integer requesterId
+    );
+
+    @Operation(
+        summary = "기존 스프레드시트에서 사전 회원 가져오기",
+        description = "동아리가 기존에 관리하던 스프레드시트의 인명부를 읽어 "
+            + "DB에 사전 회원(ClubPreMember)으로 등록합니다. "
+            + "AI가 헤더를 자동 분석하며, 이미 등록된 회원(이름+학번 중복)은 건너뜁니다."
+    )
+    @PostMapping("/{clubId}/sheet/import")
+    ResponseEntity<SheetImportResponse> importPreMembers(
+        @PathVariable(name = "clubId") Integer clubId,
+        @Valid @RequestBody SheetImportRequest request,
+        @UserId Integer requesterId
+    );
+}

src/main/java/gg/agit/konect/domain/club/controller/ClubSheetMigrationController.java

@@ -0,0 +1,50 @@
+package gg.agit.konect.domain.club.controller;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import gg.agit.konect.domain.club.dto.ClubMemberSheetSyncResponse;
+import gg.agit.konect.domain.club.dto.SheetImportRequest;
+import gg.agit.konect.domain.club.dto.SheetImportResponse;
+import gg.agit.konect.domain.club.dto.SheetMigrateRequest;
+import gg.agit.konect.domain.club.service.SheetImportService;
+import gg.agit.konect.domain.club.service.SheetMigrationService;
+import gg.agit.konect.global.auth.annotation.UserId;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+
+@RestController
+@RequiredArgsConstructor
+@RequestMapping("/clubs")
+public class ClubSheetMigrationController implements ClubSheetMigrationApi {
+
+    private final SheetMigrationService sheetMigrationService;
+    private final SheetImportService sheetImportService;
+
+    @Override
+    public ResponseEntity<ClubMemberSheetSyncResponse> migrateSheet(
+        @PathVariable(name = "clubId") Integer clubId,
+        @Valid @RequestBody SheetMigrateRequest request,
+        @UserId Integer requesterId
+    ) {
+        String newSpreadsheetId = sheetMigrationService.migrateToTemplate(
+            clubId, requesterId, request.sourceSpreadsheetUrl()
+        );
+        return ResponseEntity.ok(ClubMemberSheetSyncResponse.of(0, newSpreadsheetId));
+    }
+
+    @Override
+    public ResponseEntity<SheetImportResponse> importPreMembers(
+        @PathVariable(name = "clubId") Integer clubId,
+        @Valid @RequestBody SheetImportRequest request,
+        @UserId Integer requesterId
+    ) {
+        int count = sheetImportService.importPreMembersFromSheet(
+            clubId, requesterId, request.spreadsheetId()
+        );
+        return ResponseEntity.ok(SheetImportResponse.of(count));
+    }
+}

src/main/java/gg/agit/konect/domain/club/dto/ClubMemberSheetSyncRequest.java

@@ -0,0 +1,14 @@
+package gg.agit.konect.domain.club.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotBlank;
+
+public record ClubMemberSheetSyncRequest(
+    @NotBlank(message = "스프레드시트 ID는 필수 입력입니다.")
+    @Schema(
+        description = "동기화 대상 구글 스프레드시트 ID (URL의 /d/{spreadsheetId}/ 부분)",
+        example = "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms"
+    )
+    String spreadsheetId
+) {
+}

src/main/java/gg/agit/konect/domain/club/dto/ClubMemberSheetSyncResponse.java

@@ -0,0 +1,19 @@
+package gg.agit.konect.domain.club.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+public record ClubMemberSheetSyncResponse(
+    @Schema(description = "동기화된 회원 수", example = "42")
+    int syncedMemberCount,
+
+    @Schema(
+        description = "동기화된 스프레드시트 URL",
+        example = "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms/edit"
+    )
+    String sheetUrl
+) {
+    public static ClubMemberSheetSyncResponse of(int syncedMemberCount, String spreadsheetId) {
+        String sheetUrl = "https://docs.google.com/spreadsheets/d/" + spreadsheetId + "/edit";
+        return new ClubMemberSheetSyncResponse(syncedMemberCount, sheetUrl);
+    }
+}

src/main/java/gg/agit/konect/domain/club/dto/ClubSheetIdUpdateRequest.java

@@ -0,0 +1,14 @@
+package gg.agit.konect.domain.club.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotBlank;
+
+public record ClubSheetIdUpdateRequest(
+    @NotBlank(message = "스프레드시트 ID는 필수 입력입니다.")
+    @Schema(
+        description = "등록할 구글 스프레드시트 ID (URL의 /d/{spreadsheetId}/ 부분)",
+        example = "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms"
+    )
+    String spreadsheetId
+) {
+}

src/main/java/gg/agit/konect/domain/club/dto/SheetImportRequest.java

@@ -0,0 +1,14 @@
+package gg.agit.konect.domain.club.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotBlank;
+
+public record SheetImportRequest(
+    @NotBlank
+    @Schema(
+        description = "인명부가 담긴 구글 스프레드시트 ID 또는 URL",
+        example = "1BxiMVs0XRA5..."
+    )
+    String spreadsheetId
+) {
+}

src/main/java/gg/agit/konect/domain/club/dto/SheetImportResponse.java

@@ -0,0 +1,9 @@
+package gg.agit.konect.domain.club.dto;
+
+public record SheetImportResponse(
+    int importedCount
+) {
+    public static SheetImportResponse of(int importedCount) {
+        return new SheetImportResponse(importedCount);
+    }
+}

src/main/java/gg/agit/konect/domain/club/dto/SheetMigrateRequest.java

@@ -0,0 +1,14 @@
+package gg.agit.konect.domain.club.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotBlank;
+
+public record SheetMigrateRequest(
+    @NotBlank
+    @Schema(
+        description = "동아리가 기존에 사용하던 구글 스프레드시트 URL",
+        example = "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5.../edit"
+    )
+    String sourceSpreadsheetUrl
+) {
+}

src/main/java/gg/agit/konect/domain/club/enums/ClubSheetSortKey.java

@@ -0,0 +1,8 @@
+package gg.agit.konect.domain.club.enums;
+
+public enum ClubSheetSortKey {
+    NAME,
+    STUDENT_ID,
+    POSITION,
+    JOINED_AT
+}

src/main/java/gg/agit/konect/domain/club/event/ClubMemberChangedEvent.java

@@ -0,0 +1,9 @@
+package gg.agit.konect.domain.club.event;
+
+public record ClubMemberChangedEvent(
+    Integer clubId
+) {
+    public static ClubMemberChangedEvent of(Integer clubId) {
+        return new ClubMemberChangedEvent(clubId);
+    }
+}

src/main/java/gg/agit/konect/domain/club/model/Club.java

@@ -84,6 +84,18 @@ public class Club extends BaseEntity {
     @Column(name = "is_application_enabled")
     private Boolean isApplicationEnabled;
 
+    @Column(name = "google_sheet_id", length = 255)
+    private String googleSheetId;
+
+    @Column(name = "sheet_column_mapping", columnDefinition = "JSON")
+    private String sheetColumnMapping;
+
+    @Column(name = "drive_folder_id", length = 255)
+    private String driveFolderId;
+
+    @Column(name = "template_spreadsheet_id", length = 255)
+    private String templateSpreadsheetId;
+
     @OneToOne(mappedBy = "club", fetch = LAZY, cascade = ALL, orphanRemoval = true)
     private ClubRecruitment clubRecruitment;
 
@@ -224,4 +236,16 @@ private void clearFeeInfo() {
         this.feeAccountNumber = null;
         this.feeAccountHolder = null;
     }
+
+    public void updateGoogleSheetId(String googleSheetId) {
+        this.googleSheetId = googleSheetId;
+    }
+
+    public void updateSheetColumnMapping(String sheetColumnMapping) {
+        this.sheetColumnMapping = sheetColumnMapping;
+    }
+
+    public void updateDriveFolderId(String driveFolderId) {
+        this.driveFolderId = driveFolderId;
+    }
 }