Merge pull request #317 from Pseudo-Lab/feat/certificate-number-format

feat(cert): Update certificate number format and verification ordering

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-2026DC", description="수료증 번호")
+    certificate_number: str = Field(..., example="A2025S10_0156", description="수료증 번호")
     issue_date: str = Field(..., example="2024-01-15", description="신청 날짜")
     certificate_status: CertificateStatus = Field(..., example=CertificateStatus.PENDING, description="발급 여부")
     season: int = Field(..., example=10, description="참여 기수")
@@ -44,7 +44,7 @@ class CertificateResponse(BaseModel):
 
 class CertificateVerifyRequest(BaseModel):
     """수료증 번호 확인 요청 모델"""
-    certificate_number: str = Field(..., example="CERT-2026DC", description="수료증 번호")
+    certificate_number: str = Field(..., example="A2025S10_0156", description="수료증 번호")
 
 
 class CertificateVerifyData(BaseModel):

cert/backend/src/services/certificate_service.py

@@ -1,5 +1,6 @@
 import logging
 import uuid
+import re
 from datetime import datetime
 from typing import Optional, List
 
@@ -35,6 +36,64 @@ def clear_cache():
 
 class CertificateService:
     """수료증 서비스"""    
+
+    @staticmethod
+    def _get_study_year(period: dict) -> int:
+        """스터디 기간에서 연도를 추출 (없으면 현재 연도 fallback)"""
+        for key in ("start", "end"):
+            raw_date = (period or {}).get(key)
+            if raw_date:
+                try:
+                    return datetime.fromisoformat(raw_date).year
+                except ValueError:
+                    # ISO 포맷이 아니면 연도만 파싱 시도
+                    year_part = raw_date.split("-", 1)[0]
+                    if year_part.isdigit():
+                        return int(year_part)
+        return datetime.now().year
+
+    @staticmethod
+    def _build_certificate_number(
+        study_year: int,
+        unique_identifier: str,
+        track_code: str,
+        season_code: str,
+        study_id: str,
+    ) -> str:
+        """수료증 번호 생성: {코드}{연도}{기수}-{스터디ID}{unique_id}"""
+        suffix = f"{study_id}{unique_identifier.upper()}"
+        return f"{track_code}{study_year}{season_code}-{suffix}"
+
+    @staticmethod
+    def _parse_project_code(project_code: str, season: int) -> tuple[str | None, str, str | None]:
+        """프로젝트 코드 파싱: CODE에서 트랙/기수/스터디ID 추출"""
+        track_code = None
+        season_code = f"S{season:02d}"
+        study_id = None
+
+        if not project_code:
+            return track_code, season_code, study_id
+
+        raw_code = project_code.strip()
+        if "-" in raw_code:
+            parts = raw_code.split("-", 1)
+        elif "_" in raw_code:
+            parts = raw_code.split("_", 1)
+        else:
+            parts = [raw_code]
+
+        if parts:
+            season_match = re.match(r"^S(\d+)$", parts[0], re.IGNORECASE)
+            if season_match:
+                season_code = f"S{int(season_match.group(1)):02d}"
+
+        target = parts[1] if len(parts) > 1 else raw_code
+        match = re.match(r"^([A-Za-z]+)(\d+)$", target)
+        if match:
+            track_code = match.group(1).upper()
+            study_id = match.group(2)
+
+        return track_code, season_code, study_id
 
     @staticmethod
     async def create_certificate(certificate_data: dict) -> CertificateResponse:
@@ -133,7 +192,7 @@ async def verify_certificate(file_bytes: bytes) -> dict:
                     "debug_text": watermark_text
                 }
 
-            # 수료증 번호 추출 (CERT-2026XX 포맷 기대)
+            # 수료증 번호 추출 (A2025S10-0156 포맷 기대)
             cert_number = ""
             if "_" in watermark_text:
                 cert_number = watermark_text.split("_")[1]
@@ -264,7 +323,38 @@ async def _reissue_certificate(
                             break
 
 
-                existing_cert_number = f"CERT-{datetime.now().year}{participation_info['project_code']}{unique_identifier.upper()}"
+                study_year = CertificateService._get_study_year(participation_info.get("period", {}))
+                track_code, season_code, study_id = CertificateService._parse_project_code(
+                    participation_info.get("project_code", ""),
+                    certificate_data["season"],
+                )
+                if not track_code:
+                    track_code = "N"
+                if not study_id:
+                    study_index = await notion_client.get_study_order_index(
+                        season=certificate_data["season"],
+                        course_name=certificate_data["course_name"],
+                    )
+                    if study_index is None:
+                        message = "스터디 순서를 확인할 수 없어 수료증을 발급할 수 없습니다."
+                        logger.error(
+                            message,
+                            extra={
+                                "season": certificate_data["season"],
+                                "course_name": certificate_data["course_name"],
+                            },
+                        )
+                        raise Exception(message)
+                    else:
+                        study_id = f"{study_index:02d}" if study_index < 100 else str(study_index)
+
+                existing_cert_number = CertificateService._build_certificate_number(
+                    study_year=study_year,
+                    unique_identifier=unique_identifier,
+                    track_code=track_code,
+                    season_code=season_code,
+                    study_id=study_id,
+                )
                 logger.info(
                     "새로운 수료증 번호 생성",
                     extra={"certificate_number": existing_cert_number},
@@ -398,7 +488,38 @@ async def _create_new_certificate(
                 # fallback: Page ID의 마지막 5자리
                 unique_identifier = request_id.replace("-", "")[-5:]
 
-            certificate_number = f"CERT-{datetime.now().year}{participation_info['project_code']}{unique_identifier.upper()}"
+            study_year = CertificateService._get_study_year(participation_info.get("period", {}))
+            track_code, season_code, study_id = CertificateService._parse_project_code(
+                participation_info.get("project_code", ""),
+                certificate_data["season"],
+            )
+            if not track_code:
+                track_code = "N"
+            if not study_id:
+                study_index = await notion_client.get_study_order_index(
+                    season=certificate_data["season"],
+                    course_name=certificate_data["course_name"],
+                )
+                if study_index is None:
+                    message = "스터디 순서를 확인할 수 없어 수료증을 발급할 수 없습니다."
+                    logger.error(
+                        message,
+                        extra={
+                            "season": certificate_data["season"],
+                            "course_name": certificate_data["course_name"],
+                        },
+                    )
+                    raise Exception(message)
+                else:
+                    study_id = f"{study_index:02d}" if study_index < 100 else str(study_index)
+
+            certificate_number = CertificateService._build_certificate_number(
+                study_year=study_year,
+                unique_identifier=unique_identifier,
+                track_code=track_code,
+                season_code=season_code,
+                study_id=study_id,
+            )
             issue_date = datetime.now().strftime("%Y-%m-%d")
 
             # PDF 수료증 생성

cert/backend/src/utils/notion_client.py

@@ -1,4 +1,5 @@
 from datetime import datetime
+import re
 import json
 import logging
 import os
@@ -131,7 +132,7 @@ async def verify_user_participation(
                             completers = properties.get("수료자", {}).get("rich_text", [])
                             dropouts = properties.get("이탈자", {}).get("multi_select", [])
 
-                            code_prop = properties.get("코드", {}).get("rich_text", [])
+                            code_prop = properties.get("CODE", {}).get("rich_text", [])
                             project_code = code_prop[0].get("plain_text", "") if code_prop else ""
                             if not project_code:
                                 logger.warning(
@@ -684,6 +685,52 @@ def safe_get_text(prop_name: str, default: str = "") -> str:
             logger.exception("모든 프로젝트 조회 중 오류")
             return None
 
+    async def get_study_order_index(self, season: int, course_name: str) -> Optional[int]:
+        """기수 내 스터디 정렬 순서 기반 인덱스(1-based) 조회"""
+        all_projects = await self.get_all_projects()
+        if not all_projects:
+            return None
+
+        season_projects = [project for project in all_projects if project.season == season]
+        if not season_projects:
+            return None
+
+        def sort_key(name: str) -> tuple:
+            normalized = (name or "").strip()
+            if not normalized:
+                return (3, "")
+
+            first_char = normalized[0]
+            if first_char.isdigit():
+                match = re.match(r"^(\d+)", normalized)
+                number = int(match.group(1)) if match else 0
+                rest = normalized[match.end():] if match else normalized
+                return (0, number, rest)
+            if "A" <= first_char <= "Z" or "a" <= first_char <= "z":
+                return (1, normalized.casefold())
+            if "\uac00" <= first_char <= "\ud7a3":
+                return (2, normalized)
+            return (3, normalized)
+
+        sorted_projects = sorted(
+            season_projects,
+            key=lambda project: sort_key(project.name),
+        )
+
+        for index, project in enumerate(sorted_projects, start=1):
+            if project.name == course_name:
+                return index
+
+        for index, project in enumerate(sorted_projects, start=1):
+            if course_name and course_name in project.name:
+                return index
+
+        logger.warning(
+            "스터디 순서 조회 실패: 해당 코스명을 찾지 못했습니다.",
+            extra={"season": season, "course_name": course_name},
+        )
+        return None
+
     async def get_projects_by_season(self) -> Optional[ProjectsBySeasonResponse]:
         """기수별로 프로젝트 그룹화하여 조회"""
         try:
@@ -887,7 +934,17 @@ async def get_certificate_by_number(self, certificate_number: str) -> Optional[D
                 "rich_text": {
                     "equals": certificate_number
                 }
-            }
+            },
+            "sorts": [
+                {
+                    "property": "Issue Date",
+                    "direction": "descending"
+                },
+                {
+                    "timestamp": "created_time",
+                    "direction": "descending"
+                }
+            ]
         }
 
         try:

cert/backend/src/utils/pdf_generator.py

@@ -56,8 +56,8 @@ def __init__(self):
             "name": {"x": 299, "y": 1080 - 902 - 65, "font_size": 72, "char_space": -1.2},
         }
         self.metadata_positions = {
-            "certificate_number": {"x": 1030, "y": 140, "font_size": 18, "char_space": -0.2},
-            "issue_date": {"x": 1030, "y": 110, "font_size": 18, "char_space": -0.2},
+            "certificate_number": {"x": 1030, "y": 160, "font_size": 18, "char_space": -0.2},
+            "issue_date": {"x": 1030, "y": 130, "font_size": 18, "char_space": -0.2},
         }
 
         # 텍스트 설정

cert/docs/api.md

@@ -71,7 +71,7 @@ URL : https://cert.pseudolab-devfactory/api/certs/create
   "message": "수료증이 성공적으로 발급되었습니다. 🚀\n메일함을 확인해보세요.",
   "data": {
     "id": 1,
-    "certificate_number": "CERT-001"
+    "certificate_number": "A2025S10_0156"
     ...
   }
 }
@@ -134,7 +134,7 @@ URL : https://cert.pseudolab-devfactory/api/certs/verify-by-number
 #### Request
 ```json
 {
-  "certificate_number": "CERT-202418"
+  "certificate_number": "A2025S10_0156"
 }
 ```
 
@@ -156,6 +156,6 @@ URL : https://cert.pseudolab-devfactory/api/certs/verify-by-number
 ```json
 {
   "valid": false,
-  "message": "수료증 번호(CERT-202618)에 해당하는 발급 기록을 찾을 수 없습니다."
+  "message": "수료증 번호(A2025S10_0156)에 해당하는 발급 기록을 찾을 수 없습니다."
 }
 ```

cert/frontend/src/modules/Home/index.tsx

@@ -727,7 +727,7 @@ const ExportCertificateForm = () => {
                   }}
                   fullWidth
                   variant="outlined"
-                  placeholder="CERT-XXXXXX"
+                  placeholder="A2025S10_0156"
                   size="medium"
                 />
                 {/* <Typography variant="caption" sx={{ color: '#6b7280', display: 'block', mt: 1 }}>