세션 계약 SSOT 정리

apps/api/app/routes/sessions.py

@@ -31,6 +31,7 @@ from ..store import InProcSession, TurnRecord, store
 router = APIRouter(prefix="/sessions", tags=["sessions"])
 
 TheoryMode = Literal["humanistic", "cbt", "integrative"]
+StageLabel = Literal["라포", "탐색", "개입", "정리"]
 EndStateValue = str | int | float | bool | None | dict[str, float]
 
 
@@ -43,7 +44,7 @@ class SessionStartResponse(BaseModel):
     session_id: str
     case_id: str
     session_no: int
-    stage: str
+    stage: StageLabel
     effective_openness: float
     recall_summary: Optional[str] = None
     degraded: bool = False
@@ -61,7 +62,7 @@ class CrisisResourceResponse(BaseModel):
 
 class TurnResponse(BaseModel):
     turn_seq: int
-    stage: str
+    stage: StageLabel
     effective_openness: float
     client_reply: Optional[str] = None
     safety_flagged: bool = False
@@ -83,7 +84,7 @@ class LearnerSessionSummary(BaseModel):
     persona_name: str
     session_no: int
     status: Literal["active", "ended"]
-    stage: str
+    stage: StageLabel
     turn_count: int
     learner_turn_count: int
     client_turn_count: int
@@ -100,7 +101,7 @@ class LearnerSessionsResponse(BaseModel):
 class SessionDetailTurn(BaseModel):
     turn_seq: int
     speaker: Literal["learner", "client"]
-    stage: str
+    stage: StageLabel
     text: str
     created_at: str
 
@@ -112,7 +113,7 @@ class SessionDetailResponse(BaseModel):
     persona_name: str
     theory_mode: str
     status: Literal["active", "ended"]
-    stage: str
+    stage: StageLabel
     effective_openness: float
     started_at: str
     ended_at: str | None = None

apps/web/src/lib/api.gen.ts

@@ -1305,8 +1305,11 @@ export interface components {
             session_id: string;
             /** Session No */
             session_no: number;
-            /** Stage */
-            stage: string;
+            /**
+             * Stage
+             * @enum {string}
+             */
+            stage: "라포" | "탐색" | "개입" | "정리";
             /** Started At */
             started_at: string;
             /**
@@ -1762,8 +1765,11 @@ export interface components {
             review_ready: boolean;
             /** Session Id */
             session_id: string;
-            /** Stage */
-            stage: string;
+            /**
+             * Stage
+             * @enum {string}
+             */
+            stage: "라포" | "탐색" | "개입" | "정리";
             /** Started At */
             started_at: string;
             /**
@@ -1785,8 +1791,11 @@ export interface components {
              * @enum {string}
              */
             speaker: "learner" | "client";
-            /** Stage */
-            stage: string;
+            /**
+             * Stage
+             * @enum {string}
+             */
+            stage: "라포" | "탐색" | "개입" | "정리";
             /** Text */
             text: string;
             /** Turn Seq */
@@ -1941,8 +1950,11 @@ export interface components {
             session_id: string;
             /** Session No */
             session_no: number;
-            /** Stage */
-            stage: string;
+            /**
+             * Stage
+             * @enum {string}
+             */
+            stage: "라포" | "탐색" | "개입" | "정리";
         };
         /** TeacherDashboardResponse */
         TeacherDashboardResponse: {
@@ -2207,8 +2219,11 @@ export interface components {
              * @default false
              */
             safety_flagged: boolean;
-            /** Stage */
-            stage: string;
+            /**
+             * Stage
+             * @enum {string}
+             */
+            stage: "라포" | "탐색" | "개입" | "정리";
             /** Turn Seq */
             turn_seq: number;
         };

apps/web/src/lib/api.ts

@@ -165,7 +165,7 @@ export const authApi = {
   withdrawConsent: () => api.del<ConsentResponse>("/auth/consent"),
 };
 
-export type SessionStage = "라포" | "탐색" | "개입" | "정리";
+export type SessionStage = ApiSchema<"SessionStartResponse">["stage"];
 
 /** GET /personas — personas.py PersonaSummary */
 export type PersonaSummary = ApiSchema<"PersonaSummary">;
@@ -178,15 +178,7 @@ export type PersonaDraftPayload = ApiSchema<"PersonaDraftPayload">;
 export type PersonaDraftDetail = ApiSchema<"PersonaDraftDetail">;
 
 /** POST /sessions — sessions.py SessionStartResponse */
-export interface SessionStartResponse {
-  session_id: string;
-  case_id: string;
-  session_no: number;
-  stage: SessionStage;
-  effective_openness: number;
-  recall_summary: string | null;
-  degraded: boolean;
-}
+export type SessionStartResponse = ApiSchema<"SessionStartResponse">;
 
 /** POST /sessions/{id}/turn — sessions.py TurnResponse */
 export type TurnResponse = ApiSchema<"TurnResponse">;
@@ -201,20 +193,7 @@ export type LearnerSessionsResponse = ApiSchema<"LearnerSessionsResponse">;
 
 export type SessionDetailTurn = ApiSchema<"SessionDetailTurn">;
 
-export interface SessionDetailResponse {
-  session_id: string;
-  case_id: string;
-  persona_code: string;
-  persona_name: string;
-  theory_mode: string;
-  status: "active" | "ended";
-  stage: SessionStage;
-  effective_openness: number;
-  started_at: string;
-  ended_at: string | null;
-  turns: SessionDetailTurn[];
-  review_ready: boolean;
-}
+export type SessionDetailResponse = ApiSchema<"SessionDetailResponse">;
 
 export type ReviewClient = ApiSchema<"ReviewClient">;
 export type ReviewTechnique = ApiSchema<"ReviewTechnique">;

apps/web/src/pages/Session.tsx

@@ -587,7 +587,7 @@ export default function Session() {
         setStage(detail.stage);
         setOpenness(detail.effective_openness);
         setUtterances(
-          detail.turns.map((turn) => ({
+          (detail.turns ?? []).map((turn) => ({
             id: nextId(),
             speaker: turn.speaker === "client" ? "client" : "learner",
             text: turn.text,