From be2865a4b2892318637ab5df641d0bbeae6a0b55 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EB=AF=BC=ED=97=8C?= <min815371@gmail.com>
Date: Tue, 7 Jul 2026 15:15:07 +0900
Subject: [PATCH] =?UTF-8?q?docs(common):=20=EA=B3=B5=ED=86=B5=20=EC=9D=91?=
 =?UTF-8?q?=EB=8B=B5=20=EB=B4=89=ED=88=AC=20+=20healthz=20=EC=84=A4?=
 =?UTF-8?q?=EB=AA=85=20=EB=B3=B4=EA=B0=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- gmodel: ErrorInfo(success/code/desc) + Res_WebPacketProtocol(result/msg)
  에 description 추가 → 모든 Res_* 응답의 공통 봉투가 Swagger 에 채워짐.
- router: /healthz 에 summary/description 추가(유일하게 설명 없던 오퍼레이션).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 backend/common/models/gmodel.py | 10 +++++-----
 backend/router/router.py        |  7 ++++++-
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/backend/common/models/gmodel.py b/backend/common/models/gmodel.py
index 36d3ab9..e59400a 100644
--- a/backend/common/models/gmodel.py
+++ b/backend/common/models/gmodel.py
@@ -15,9 +15,9 @@ class StructModel:
 class ErrorInfo(BaseModel, StructModel):
     """모든 응답에 공통으로 실리는 결과 정보. result.success / code / desc 로 내려간다."""
 
-    success: Optional[bool] = True
-    code: Optional[int] = ErrorType.SUCCESS.value
-    desc: Optional[str] = ErrorType.SUCCESS.name
+    success: Optional[bool] = Field(True, description="처리 성공 여부 (성공 시 true)")
+    code: Optional[int] = Field(ErrorType.SUCCESS.value, description="결과 코드 (ErrorType, 0=성공)")
+    desc: Optional[str] = Field(ErrorType.SUCCESS.name, description="결과 코드 이름 (ErrorType.name)")
 
     def SetResult(self, enum: ErrorType):
         if enum is not None:
@@ -41,8 +41,8 @@ class Req_WebPacketProtocol(WebPacketProtocol):
 
 class Res_WebPacketProtocol(WebPacketProtocol):
     # default_factory 로 인스턴스마다 새 ErrorInfo 를 생성한다 (mutable default 공유 방지).
-    result: ErrorInfo = Field(default_factory=ErrorInfo)
-    msg: Optional[str] = None
+    result: ErrorInfo = Field(default_factory=ErrorInfo, description="공통 처리 결과 (성공 여부/코드/설명)")
+    msg: Optional[str] = Field(None, description="부가 메시지 (선택)")
 
 
 class UserInfo(StructModel):
diff --git a/backend/router/router.py b/backend/router/router.py
index 57bd7e1..a249da6 100644
--- a/backend/router/router.py
+++ b/backend/router/router.py
@@ -50,7 +50,12 @@ async def log_time(request: Request, call_next):
     return response
 
 
-@app.get(path="/healthz", responses={404: {"description": "Not found"}})
+@app.get(
+    path="/healthz",
+    summary="헬스체크",
+    description="서버 기동 시각(API_SERVER_START_TIME)을 반환하는 헬스체크 엔드포인트.",
+    responses={404: {"description": "Not found"}},
+)
 async def healthz():
     return API_SERVER_START_TIME