feat(cert): add certificate authenticity check

Author: soohyunme

cert/backend/src/models/certificate.py

@@ -28,7 +28,7 @@ class CertificateData(BaseModel):
     id: str = Field(..., example="2533a2a2-eed5-81fa-9921-c14d2cd117b7", description="수료증 신청 페이지 ID")
     name: str = Field(..., example="홍길동", description="신청자 이름")
     recipient_email: str = Field(..., example="hong@example.com", description="수료자 이메일")
-    certificate_number: str = Field(..., example="CERT-2024-001", description="수료증 번호")
+    certificate_number: str = Field(..., example="CERT-2026DC", description="수료증 번호")
     issue_date: str = Field(..., example="2024-01-15", description="신청 날짜")
     certificate_status: CertificateStatus = Field(..., example=CertificateStatus.PENDING, description="발급 여부")
     season: int = Field(..., example=10, description="참여 기수")
@@ -42,6 +42,26 @@ class CertificateResponse(BaseModel):
     data: Optional[CertificateData] = Field(None, description="수료증 데이터")
 
 
+class CertificateVerifyRequest(BaseModel):
+    """수료증 번호 확인 요청 모델"""
+    certificate_number: str = Field(..., example="CERT-2026DC", description="수료증 번호")
+
+
+class CertificateVerifyData(BaseModel):
+    """수료증 번호 확인 데이터"""
+    name: str = Field(..., example="홍길동", description="신청자 이름")
+    course: str = Field(..., example="Wrapping Up Pseudolab", description="스터디명")
+    season: str = Field(..., example="10기", description="참여 기수")
+    issue_date: str = Field(..., example="2024-01-15", description="발급일")
+
+
+class CertificateVerifyResponse(BaseModel):
+    """수료증 번호 확인 응답"""
+    valid: bool = Field(..., example=True, description="확인 여부")
+    message: str = Field(..., example="수료증 확인에 성공했습니다.", description="결과 메시지")
+    data: Optional[CertificateVerifyData] = Field(None, description="수료증 정보")
+
+
 class ErrorResponse(BaseModel):
     """에러 응답 모델"""
     status: str = Field(..., example="fail", description="응답 상태")

cert/backend/src/routers/certificate.py

@@ -1,7 +1,13 @@
 from fastapi import APIRouter, HTTPException, Response, File, UploadFile
 
 from ..models.project import Project, ProjectsBySeasonResponse
-from ..models.certificate import CertificateCreate, CertificateResponse, ErrorResponse
+from ..models.certificate import (
+    CertificateCreate,
+    CertificateResponse,
+    CertificateVerifyRequest,
+    CertificateVerifyResponse,
+    ErrorResponse,
+)
 from ..services.certificate_service import CertificateService, ProjectService
 from ..constants.error_codes import ResponseStatus
 
@@ -107,3 +113,30 @@ async def verify_certificate(file: UploadFile = File(...)):
         import logging
         logging.error(f"검증 중 오류 발생: {e}")
         raise HTTPException(status_code=500, detail="파일 처리 중 오류가 발생했습니다.")
+
+@certificate_router.post(
+    "/verify-by-number",
+    response_model=CertificateVerifyResponse,
+    responses={
+        200: {
+            "description": "수료증 번호 확인 성공/실패",
+            "model": CertificateVerifyResponse
+        },
+        400: {
+            "description": "잘못된 요청",
+            "model": ErrorResponse
+        },
+        500: {
+            "description": "서버 내부 오류",
+            "model": ErrorResponse
+        }
+    }
+)
+async def verify_certificate_by_number(payload: CertificateVerifyRequest):
+    """수료증 번호로 수료 여부를 확인합니다."""
+    certificate_number = payload.certificate_number.strip()
+    if not certificate_number:
+        raise HTTPException(status_code=400, detail="수료증 번호를 입력해주세요.")
+
+    result = await CertificateService.verify_certificate_by_number(certificate_number)
+    return result

cert/backend/src/services/certificate_service.py

@@ -133,7 +133,7 @@ async def verify_certificate(file_bytes: bytes) -> dict:
                     "debug_text": watermark_text
                 }
 
-            # 수료증 번호 추출 (PSEUDOLAB_CERT-XXXX 포맷 기대)
+            # 수료증 번호 추출 (CERT-2026XX 포맷 기대)
             cert_number = ""
             if "_" in watermark_text:
                 cert_number = watermark_text.split("_")[1]
@@ -155,28 +155,7 @@ async def verify_certificate(file_bytes: bytes) -> dict:
                     "valid": False,
                     "message": f"수료증 번호({cert_number})에 해당하는 발급 기록을 찾을 수 없습니다."
                 }
-            
-            # Notion 결과 파싱
-            props = cert_page.get("properties", {})
-            
-            name = props.get("Name", {}).get("title", [{}])[0].get("plain_text", "알 수 없음")
-            course = props.get("Course Name", {}).get("rich_text", [{}])[0].get("plain_text", "알 수 없음")
-            season = props.get("Season", {}).get("select", {}).get("name", "알 수 없음")
-            issue_date = props.get("Issue Date", {}).get("date", {}).get("start", "알 수 없음")
-            status = props.get("Certificate Status", {}).get("status", {}).get("name", "알 수 없음")
-
-            return {
-                "valid": True,
-                "message": "수료증 진위 확인에 성공했습니다.",
-                "data": {
-                    "name": name,
-                    "course": course,
-                    "season": season,
-                    "issue_date": issue_date,
-                    "certificate_number": cert_number,
-                    "status": status
-                }
-            }
+            return CertificateService._build_verification_result(cert_page, cert_number)
 
         except Exception as e:
             if "워터마크를 찾을 수 없습니다" in str(e):
@@ -187,6 +166,49 @@ async def verify_certificate(file_bytes: bytes) -> dict:
                 "valid": False,
                 "message": "수료증 검증 처리 중 오류가 발생했습니다."
             }
+
+    @staticmethod
+    async def verify_certificate_by_number(certificate_number: str) -> dict:
+        """수료증 번호로 수료 여부 확인"""
+        try:
+            notion_client = NotionClient()
+            cert_page = await notion_client.get_certificate_by_number(certificate_number)
+
+            if not cert_page:
+                return {
+                    "valid": False,
+                    "message": f"수료증 번호({certificate_number})에 해당하는 발급 기록을 찾을 수 없습니다."
+                }
+
+            return CertificateService._build_verification_result(cert_page, certificate_number)
+        except Exception:
+            logger.exception("수료증 번호 확인 중 오류")
+            return {
+                "valid": False,
+                "message": "수료증 번호 확인 처리 중 오류가 발생했습니다."
+            }
+
+    @staticmethod
+    def _build_verification_result(cert_page: dict, certificate_number: str) -> dict:
+        """Notion 수료증 페이지 응답 포맷팅"""
+        props = cert_page.get("properties", {})
+
+        name = props.get("Name", {}).get("title", [{}])[0].get("plain_text", "알 수 없음")
+        course = props.get("Course Name", {}).get("rich_text", [{}])[0].get("plain_text", "알 수 없음")
+        season = props.get("Season", {}).get("select", {}).get("name", "알 수 없음")
+        issue_date = props.get("Issue Date", {}).get("date", {}).get("start", "알 수 없음")
+        status = props.get("Certificate Status", {}).get("status", {}).get("name", "알 수 없음")
+
+        return {
+            "valid": True,
+            "message": "수료증 확인에 성공했습니다.",
+            "data": {
+                "name": name,
+                "course": course,
+                "season": season,
+                "issue_date": issue_date
+            }
+        }
 
     @staticmethod
     async def _reissue_certificate(

cert/docs/api.md

@@ -101,4 +101,61 @@ URL : https://cert.pseudolab-devfactory/api/certs/create
     "message": "발급 처리 중 오류가 발생했습니다."
   }
 }
-```
+```
+
+---
+
+## 수료증 번호 확인
+수료증 번호로 여부를 확인합니다.
+
+HTTP Method : POST  
+URL : https://cert.pseudolab-devfactory/api/certs/verify-by-number
+
+### Request
+#### Header
+| 이름 | 내용        | 필수 |
+|--------|----------------|:--:|
+| Content-Type | `application/json` | O |
+
+#### Body
+| 이름 | 타입 | 설명 | 필수 |
+|---|---|---|:--:|
+| certificate_number | String | 수료증 번호 | O |
+
+### Response
+#### 성공/실패 공통
+| 이름 | 타입 | 설명 |
+|---|---|---|
+| valid | Boolean | 수료 여부 |
+| message | String | 결과 메세지 |
+| data | Object | 수료증 상세 (valid=true일 때) |
+
+### Example
+#### Request
+```json
+{
+  "certificate_number": "CERT-202418"
+}
+```
+
+#### 성공 응답
+```json
+{
+  "valid": true,
+  "message": "수료증 확인에 성공했습니다.",
+  "data": {
+    "name": "홍길동",
+    "course": "Wrapping Up Pseudolab",
+    "season": "10기",
+    "issue_date": "2024-01-15"
+  }
+}
+```
+
+#### 실패 응답 (발급 기록 없음)
+```json
+{
+  "valid": false,
+  "message": "수료증 번호(CERT-202618)에 해당하는 발급 기록을 찾을 수 없습니다."
+}
+```