diff --git a/상태전의 STATUS 가이드.md b/상태전의 STATUS 가이드.md
new file mode 100644
index 0000000..80a5214
--- /dev/null
+++ b/상태전의 STATUS 가이드.md
@@ -0,0 +1,964 @@
+# POST /api/train/status/{uuid} - 상태 전이 다이어그램 완전 가이드
+
+> **프론트엔드 표시 방법 및 상태 제어 API 포함**
+
+---
+
+## 📊 1. DB 테이블 상태 필드
+
+### 1.1 **Job 테이블** (`tb_model_train_job`)
+| 필드명 | 설명 | 가능한 값 | UI 표시명 |
+|--------|------|-----------|-----------|
+| `status_cd` | Job 실행 상태 | `QUEUED`, `RUNNING`, `SUCCESS`, `FAILED`, `STOPPED`, `CANCELED` | 대기중, 실행중, 성공, 실패, 중단됨, 취소 |
+| `exit_code` | 종료 코드 | 정수 (0: 정상, -1: 중단, 기타: 에러) | - |
+| `error_message` | 에러 메시지 | 문자열 | 에러 상세 내용 |
+| `finished_dttm` | 완료 시간 | timestamp | YYYY-MM-DD HH:mm:ss |
+
+### 1.2 **Model Master 테이블** (`tb_model_master`)
+| 필드명 | 설명 | 가능한 값 | UI 표시명 |
+|--------|------|-----------|-----------|
+| `status_cd` | 전체 모델 상태 | `READY`, `IN_PROGRESS`, `COMPLETED`, `STOPPED`, `ERROR` | 대기, 진행중, 완료, 중단됨, 오류 |
+| `step1_state` | Step1(학습) 상태 | `READY`, `IN_PROGRESS`, `COMPLETED`, `STOPPED`, `ERROR` | 대기, 진행중, 완료, 중단됨, 오류 |
+| `step2_state` | Step2(테스트) 상태 | `READY`, `IN_PROGRESS`, `COMPLETED`, `STOPPED`, `ERROR` | 대기, 진행중, 완료, 중단됨, 오류 |
+| `step1_strt_dttm` | Step1 시작 시간 | timestamp | YYYY-MM-DD HH:mm:ss |
+| `step1_end_dttm` | Step1 종료 시간 | timestamp | YYYY-MM-DD HH:mm:ss |
+| `step2_strt_dttm` | Step2 시작 시간 | timestamp | YYYY-MM-DD HH:mm:ss |
+| `step2_end_dttm` | Step2 종료 시간 | timestamp | YYYY-MM-DD HH:mm:ss |
+| `step1_metric_save_yn` | Step1 메트릭 저장 여부 | `true`, `false` | - |
+| `step2_metric_save_yn` | Step2 메트릭 저장 여부 | `true`, `false` | - |
+| `current_attempt_id` | 현재 실행 중인 Job ID | Long | - |
+| `best_epoch` | 최적 에폭 | Integer | Best Epoch: {값} |
+| `last_error` | 마지막 에러 메시지 | 문자열 | 에러 상세 내용 |
+
+---
+
+## 🎨 2. 프론트엔드 API 응답 및 표시
+
+### 2.1 모델 목록 조회 API
+
+**엔드포인트**: `GET /api/models/list`
+
+**요청 파라미터**:
+```json
+{
+ "status": "IN_PROGRESS", // "", "IN_PROGRESS", "COMPLETED"
+ "modelNo": "G1", // "G1", "G2", "G3", "G4"
+ "page": 0,
+ "size": 20
+}
+```
+
+**응답 예시**:
+```json
+{
+ "success": true,
+ "data": {
+ "content": [
+ {
+ "id": 123,
+ "uuid": "e22181eb-2ac4-4100-9941-d06efce25c49",
+ "modelVer": "v1.0.0",
+ "statusCd": "IN_PROGRESS",
+ "statusName": "진행중",
+ "step1Status": "COMPLETED",
+ "step1StatusName": "완료",
+ "step2Status": "IN_PROGRESS",
+ "step2StatusName": "진행중",
+ "step1StrtDttm": "2026-04-05 10:30:00",
+ "step1EndDttm": "2026-04-05 12:45:00",
+ "step1Duration": "2시간 15분 0초",
+ "step2StrtDttm": "2026-04-05 12:50:00",
+ "step2EndDttm": null,
+ "step2Duration": null,
+ "modelNo": "G1",
+ "trainType": "GENERAL",
+ "trainTypeName": "일반",
+ "currentAttemptId": 456,
+ "memo": "테스트 학습"
+ }
+ ],
+ "totalElements": 100,
+ "totalPages": 5
+ }
+}
+```
+
+### 2.2 프론트엔드 표시 예시
+
+#### 📋 **모델 목록 테이블**
+
+| 모델 번호 | 버전 | 전체 상태 | 학습(Step1) | 테스트(Step2) | 학습 시간 | 테스트 시간 | 작업 |
+|----------|------|----------|------------|------------|----------|----------|------|
+| G1 | v1.0.0 | 🟢 진행중 | ✅ 완료 (2시간 15분) | 🔄 진행중 | 2026-04-05 10:30 ~ 12:45 | 2026-04-05 12:50 ~ | [취소] |
+| G2 | v1.0.1 | ✅ 완료 | ✅ 완료 (1시간 30분) | ✅ 완료 (45분) | 2026-04-04 14:00 ~ 15:30 | 2026-04-04 15:35 ~ 16:20 | [결과보기] |
+| G3 | v1.0.2 | ⚠️ 중단됨 | ⚠️ 중단됨 | - | 2026-04-03 09:00 ~ | - | [재시작] [이어하기] |
+| G4 | v1.0.3 | ❌ 오류 | ❌ 오류 | - | 2026-04-02 11:00 ~ | - | [재시작] |
+
+#### 🎯 **상태별 UI 컬러 가이드**
+
+```javascript
+// 상태별 배지 색상 매핑
+const STATUS_COLORS = {
+ 'READY': { bg: '#e3f2fd', text: '#1976d2', icon: '⏸️' }, // 파란색 - 대기
+ 'IN_PROGRESS': { bg: '#e8f5e9', text: '#388e3c', icon: '🔄' }, // 녹색 - 진행중
+ 'COMPLETED': { bg: '#f1f8e9', text: '#689f38', icon: '✅' }, // 연두색 - 완료
+ 'STOPPED': { bg: '#fff3e0', text: '#f57c00', icon: '⚠️' }, // 주황색 - 중단됨
+ 'ERROR': { bg: '#ffebee', text: '#d32f2f', icon: '❌' } // 빨간색 - 오류
+};
+
+// 상태명 한글 변환
+const STATUS_NAMES = {
+ 'READY': '대기',
+ 'IN_PROGRESS': '진행중',
+ 'COMPLETED': '완료',
+ 'STOPPED': '중단됨',
+ 'ERROR': '오류'
+};
+
+// React 컴포넌트 예시
+function StatusBadge({ statusCd }) {
+ const { bg, text, icon } = STATUS_COLORS[statusCd] || {};
+ const name = STATUS_NAMES[statusCd] || statusCd;
+
+ return (
+
+ {icon} {name}
+
+ );
+}
+```
+
+#### 📊 **상세 진행 상황 표시**
+
+```javascript
+// Step별 진행률 계산
+function ModelProgressBar({ model }) {
+ const steps = [
+ {
+ name: '학습 (Step1)',
+ status: model.step1Status,
+ statusName: model.step1StatusName,
+ startTime: model.step1StrtDttm,
+ endTime: model.step1EndDttm,
+ duration: model.step1Duration
+ },
+ {
+ name: '테스트 (Step2)',
+ status: model.step2Status,
+ statusName: model.step2StatusName,
+ startTime: model.step2StrtDttm,
+ endTime: model.step2EndDttm,
+ duration: model.step2Duration
+ }
+ ];
+
+ return (
+
+ {steps.map((step, index) => (
+
+
+ {step.name}
+
+
+
+ {step.startTime && (
+ <>
+ 시작: {step.startTime}
+ {step.endTime && ~ 종료: {step.endTime}}
+ {step.duration && (소요시간: {step.duration})}
+
+ )}
+
+ {step.status === 'IN_PROGRESS' && (
+
+ )}
+
+ ))}
+
+ {canRun && (
+
+ )}
+
+ {canCancel && (
+
+ )}
+
+ {canRestart && (
+
+ )}
+
+ {canResume && (
+
+ )}
+
+ {canTest && (
+
+ )}
+
+ {canCancelTest && (
+
+ )}
+
+ {canViewResult && (
+
+ )}
+
+ );
+}
+```
+
+### 6.2 API 호출 함수
+
+```javascript
+import axios from 'axios';
+
+const API_BASE = '/api/train';
+
+// 학습 실행
+async function runTrain(uuid) {
+ try {
+ const response = await axios.post(`${API_BASE}/run/${uuid}`);
+ if (response.data.success) {
+ alert('학습이 시작되었습니다.');
+ refreshModelList(); // 목록 갱신
+ }
+ } catch (error) {
+ alert('학습 실행 실패: ' + error.message);
+ }
+}
+
+// 학습 취소
+async function cancelTrain(uuid) {
+ if (!confirm('학습을 취소하시겠습니까?')) return;
+
+ try {
+ const response = await axios.post(`${API_BASE}/cancel/${uuid}`);
+ if (response.data.success) {
+ alert('학습이 취소되었습니다.');
+ refreshModelList();
+ }
+ } catch (error) {
+ alert('학습 취소 실패: ' + error.message);
+ }
+}
+
+// 학습 재실행
+async function restartTrain(uuid) {
+ if (!confirm('처음부터 다시 학습을 시작하시겠습니까?')) return;
+
+ try {
+ const response = await axios.post(`${API_BASE}/restart/${uuid}`);
+ if (response.data.success) {
+ alert('학습이 재시작되었습니다.');
+ refreshModelList();
+ }
+ } catch (error) {
+ alert('학습 재시작 실패: ' + error.message);
+ }
+}
+
+// 학습 이어하기
+async function resumeTrain(uuid) {
+ if (!confirm('중단된 지점부터 학습을 이어가시겠습니까?')) return;
+
+ try {
+ const response = await axios.post(`${API_BASE}/resume/${uuid}`);
+ if (response.data.success) {
+ alert('학습이 재개되었습니다.');
+ refreshModelList();
+ }
+ } catch (error) {
+ alert('학습 이어하기 실패: ' + error.message);
+ }
+}
+
+// 테스트 실행
+async function runTest(uuid, epoch) {
+ if (!confirm(`Epoch ${epoch}으로 테스트를 실행하시겠습니까?`)) return;
+
+ try {
+ const response = await axios.post(`${API_BASE}/test/run/${epoch}/${uuid}`);
+ if (response.data.success) {
+ alert('테스트가 시작되었습니다.');
+ refreshModelList();
+ }
+ } catch (error) {
+ alert('테스트 실행 실패: ' + error.message);
+ }
+}
+
+// 테스트 취소
+async function cancelTest(uuid) {
+ if (!confirm('테스트를 취소하시겠습니까?')) return;
+
+ try {
+ const response = await axios.post(`${API_BASE}/test/cancel/${uuid}`);
+ if (response.data.success) {
+ alert('테스트가 취소되었습니다.');
+ refreshModelList();
+ }
+ } catch (error) {
+ alert('테스트 취소 실패: ' + error.message);
+ }
+}
+
+// 학습 상태 확인 (폴링용)
+async function checkTrainStatus(uuid) {
+ try {
+ const response = await axios.post(`${API_BASE}/status/${uuid}`);
+ return response.data.success;
+ } catch (error) {
+ console.error('상태 확인 실패:', error);
+ return false;
+ }
+}
+```
+
+### 6.3 주기적 상태 업데이트 (폴링)
+
+```javascript
+import { useEffect, useState } from 'react';
+
+function ModelMonitor({ uuid }) {
+ const [isPolling, setIsPolling] = useState(false);
+
+ useEffect(() => {
+ let intervalId;
+
+ // 진행 중인 모델만 폴링
+ if (isPolling) {
+ intervalId = setInterval(async () => {
+ const success = await checkTrainStatus(uuid);
+ if (success) {
+ refreshModelList(); // 상태 업데이트 후 목록 갱신
+ }
+ }, 10000); // 10초마다 상태 확인
+ }
+
+ return () => {
+ if (intervalId) clearInterval(intervalId);
+ };
+ }, [uuid, isPolling]);
+
+ // 모델 상태에 따라 폴링 활성화/비활성화
+ useEffect(() => {
+ const shouldPoll = model.statusCd === 'IN_PROGRESS';
+ setIsPolling(shouldPoll);
+ }, [model.statusCd]);
+
+ return null; // 백그라운드 작업
+}
+```
+
+---
+
+## 🎯 7. 상태 수정 시나리오별 가이드
+
+### 시나리오 1: 학습 중단 후 재시작
+
+**현재 상태**:
+```json
+{
+ "statusCd": "STOPPED",
+ "step1Status": "STOPPED",
+ "lastError": "SERVER_RESTART_CONTAINER_MISSING_OUTPUT_INCOMPLETE"
+}
+```
+
+**프론트 표시**:
+- ⚠️ 중단됨 - 산출물 부족으로 중단됨
+- 버튼: [재실행] [이어하기]
+
+**액션**:
+
+**옵션 A) 재실행** (`POST /api/train/restart/{uuid}`):
+```javascript
+// 처음부터 다시 시작
+await axios.post(`/api/train/restart/${uuid}`);
+
+// 결과 상태
+{
+ "statusCd": "IN_PROGRESS",
+ "step1Status": "IN_PROGRESS",
+ "currentAttemptId": 새로운JobId
+}
+```
+
+**옵션 B) 이어하기** (`POST /api/train/resume/{uuid}`):
+```javascript
+// 중단된 지점부터 계속
+await axios.post(`/api/train/resume/${uuid}`);
+
+// 결과 상태
+{
+ "statusCd": "IN_PROGRESS",
+ "step1Status": "IN_PROGRESS",
+ "currentAttemptId": 새로운JobId,
+ // paramsJson에 resumeFrom 설정됨
+}
+```
+
+---
+
+### 시나리오 2: 학습 완료 후 테스트 실행
+
+**현재 상태**:
+```json
+{
+ "statusCd": "COMPLETED",
+ "step1Status": "COMPLETED",
+ "step2Status": "READY",
+ "bestEpoch": 45
+}
+```
+
+**프론트 표시**:
+- ✅ 완료 - 학습 완료 (테스트 대기)
+- 버튼: [테스트 실행]
+
+**액션**:
+```javascript
+// 테스트 실행 (bestEpoch 사용)
+await axios.post(`/api/train/test/run/45/${uuid}`);
+
+// 결과 상태
+{
+ "statusCd": "IN_PROGRESS",
+ "step1Status": "COMPLETED",
+ "step2Status": "IN_PROGRESS",
+ "step2StrtDttm": "2026-04-06 14:30:00"
+}
+```
+
+**프론트 표시 변경**:
+- 🔄 진행중 - 테스트 진행 중...
+- 버튼: [테스트 취소]
+
+---
+
+### 시나리오 3: 실행 중인 학습 취소
+
+**현재 상태**:
+```json
+{
+ "statusCd": "IN_PROGRESS",
+ "step1Status": "IN_PROGRESS",
+ "currentAttemptId": 123
+}
+```
+
+**프론트 표시**:
+- 🔄 진행중 - 학습 진행 중...
+- 버튼: [학습 취소]
+
+**액션**:
+```javascript
+// 학습 취소
+await axios.post(`/api/train/cancel/${uuid}`);
+
+// 결과 상태
+{
+ "statusCd": "STOPPED",
+ "step1Status": "STOPPED",
+ "currentAttemptId": 123
+}
+```
+
+**프론트 표시 변경**:
+- ⚠️ 중단됨 - 사용자가 학습을 취소함
+- 버튼: [재실행] [이어하기]
+
+---
+
+### 시나리오 4: 서버 재시작 후 자동 상태 복구
+
+**서버 재시작 전**:
+```json
+{
+ "statusCd": "IN_PROGRESS",
+ "step1Status": "IN_PROGRESS"
+}
+```
+
+**서버 재시작 후 API 호출**:
+```javascript
+// 주기적 폴링 또는 수동 호출
+await axios.post(`/api/train/status/${uuid}`);
+```
+
+**케이스 A) 학습 완료된 경우**:
+```json
+{
+ "statusCd": "COMPLETED",
+ "step1Status": "COMPLETED",
+ "step1EndDttm": "2026-04-06 15:00:00",
+ "step1MetricSaveYn": true
+}
+```
+- ✅ 완료 - 학습 완료
+- 버튼: [테스트 실행] [결과 보기]
+
+**케이스 B) 산출물 부족한 경우**:
+```json
+{
+ "statusCd": "STOPPED",
+ "step1Status": "STOPPED",
+ "lastError": "SERVER_RESTART_CONTAINER_MISSING_OUTPUT_INCOMPLETE: val.csv-lines-mismatch"
+}
+```
+- ⚠️ 중단됨 - 산출물 부족으로 중단됨
+- 버튼: [재실행] [이어하기]
+
+**케이스 C) 여전히 실행 중인 경우**:
+```json
+{
+ "statusCd": "IN_PROGRESS",
+ "step1Status": "IN_PROGRESS"
+}
+```
+- 🔄 진행중 - 학습 진행 중...
+- 버튼: [학습 취소]
+
+---
+
+## 📊 8. 에러 메시지 처리
+
+### 8.1 `last_error` 필드 해석
+
+| 에러 메시지 | 의미 | 프론트 표시 | 권장 액션 |
+|------------|------|-----------|----------|
+| `SERVER_RESTART_CONTAINER_MISSING_OUTPUT_INCOMPLETE` | 서버 재시작 후 컨테이너 없음 + 산출물 부족 | "서버 재시작으로 인한 중단 - 산출물 확인 필요" | [재실행] |
+| `val.csv-lines-mismatch` | val.csv 라인 수 부족 | "검증 데이터 부족 - 학습이 완료되지 않음" | [재실행] [이어하기] |
+| `val.csv-missing` | val.csv 파일 없음 | "검증 파일 없음 - 학습 실패" | [재실행] |
+| `total-epoch-missing` | paramsJson에 total_epoch 없음 | "설정 오류 - 에폭 정보 없음" | [재실행] |
+| `output-dir-missing` | 산출물 디렉토리 없음 | "산출물 디렉토리 없음 - 학습 실패" | [재실행] |
+
+### 8.2 에러 표시 컴포넌트
+
+```javascript
+function ErrorMessage({ lastError }) {
+ if (!lastError) return null;
+
+ const errorMessages = {
+ 'SERVER_RESTART_CONTAINER_MISSING_OUTPUT_INCOMPLETE': {
+ icon: '⚠️',
+ title: '서버 재시작으로 인한 중단',
+ message: '서버가 재시작되면서 학습이 중단되었습니다. 산출물을 확인하여 학습 상태를 복구합니다.',
+ severity: 'warning'
+ },
+ 'val.csv-lines-mismatch': {
+ icon: '📊',
+ title: '검증 데이터 부족',
+ message: '검증 데이터 라인 수가 예상보다 적습니다. 학습이 완료되지 않았을 가능성이 있습니다.',
+ severity: 'warning'
+ },
+ 'val.csv-missing': {
+ icon: '❌',
+ title: '검증 파일 없음',
+ message: 'val.csv 파일을 찾을 수 없습니다. 학습이 실패했을 가능성이 높습니다.',
+ severity: 'error'
+ }
+ };
+
+ // 에러 메시지 파싱
+ const errorKey = Object.keys(errorMessages).find(key => lastError.includes(key));
+ const errorInfo = errorMessages[errorKey] || {
+ icon: '⚠️',
+ title: '오류 발생',
+ message: lastError,
+ severity: 'error'
+ };
+
+ return (
+
+
+ {errorInfo.icon}
+ {errorInfo.title}
+
+
{errorInfo.message}
+