# 시나리오 코드(MD) ➔ Jupyter/Colab Notebook(.ipynb) 일괄 변환 및 Colab 배포 계획서

## 1. 개요 및 목적

본 계획은 [`scenario_md`](file:///d:/edunlab/milicontent2/scenario_md) 하위 60개 프로젝트 디렉토리에 수록된 `*_정답코드.md` 파일과 [`scenario_json`](file:///d:/edunlab/milicontent2/scenario_json)의 미션 메타데이터를 결합하여, **Google Colab(구글 코랩)** 및 로컬 Jupyter 환경에서 즉시 실행 가능한 **Jupyter Notebook (`.ipynb`)** 파일들을 일괄 생성하고 원클릭 실습 환경을 구축하는 것을 목표로 합니다.

---

## 2. 데이터 소스 및 산출물 구조

### 2.1 소스 데이터 자산

| 데이터 자산          | 위치 / 경로                                                                                    | 주요 내용 및 역할                                                                   |
| :------------------- | :--------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------- |
| **정답 코드 MD**     | [`scenario_md/{Project_Dir}/*_정답코드.md`](file:///d:/edunlab/milicontent2/scenario_md)       | 60개 프로젝트(총 600개 미션)의 미션별 독립 실행 파이썬 코드 및 설명                 |
| **프로젝트 JSON**    | [`scenario_json/{ID}.json`](file:///d:/edunlab/milicontent2/scenario_json)                     | 프로젝트 및 10개 미션별 상세 메타데이터 (목표, 시나리오, 실습가이드, 평가기준)      |
| **학생 코드 생성기** | [`scripts/student_generator.py`](file:///d:/edunlab/milicontent2/scripts/student_generator.py) | 정답 코드에서 핵심 로직을 추출하여 학생용 실습 스켈레톤(TODO 빈칸/힌트) 자동 생성기 |

### 2.2 최종 산출물 체계

생성되는 노트북은 프로젝트별 독립 디렉토리(`uploads/{ProjectID}/`) 하위에 분류하여 강사용/참고용 **정답 노트북**, 학습자용 **학생 실습 노트북**, 그리고 SOP/모의훈련형 **실습 워크북 노트북**으로 체계적으로 관리합니다.

```text
uploads/
├── ADM01/
│   ├── ADM01_solution.ipynb   # 정답 및 완전 실행 노트북
│   └── ADM01_student.ipynb    # 학생 실습용 빈칸/힌트 노트북
├── C207/
│   └── C207_workbook.ipynb   # 작전절차(SOP) 및 모의훈련 워크북 노트북
├── OPS01/
│   ├── OPS01_solution.ipynb
│   └── OPS01_student.ipynb
└── ... (총 60개 프로젝트 디렉토리)
```

---

## 3. Jupyter / Colab 노트북 셀 구조 설계

각 `.ipynb` 파일은 Colab 환경에서 가장 쾌적하게 실행될 수 있도록 아래와 같은 표준 셀 시퀀스로 구성됩니다.

```mermaid
flowchart TD
    Cell1[셀 1: 프로젝트 타이틀 & Colab 뱃지<br>Markdown 셀] --> Cell2[셀 2: Colab 환경 설정 & 패키지 설치<br>Code 셀]
    Cell2 --> M01[미션 1: 설명 및 가이드 MD ➔ 코드 셀]
    M01 --> M02[미션 2: 설명 및 가이드 MD ➔ 코드 셀]
    M02 --> MDot[...]
    MDot --> M10[미션 10: AAR 종합 분석 MD ➔ 코드 셀]
```

### 3.1 셀별 상세 구성

1. **Cell 1 (Header & Colab Badge) [Markdown]**:
   - 프로젝트 ID, 제목, 도메인 분야, 학습 목표 요약
   - **`Open In Colab` 뱃지**: 클릭 시 본 노트북이 Colab에서 즉시 열리는 원클릭 링크 제공

   ```markdown
   # [ADM01] 결원·근무부하 추세 대시보드와 보충 필요량 예측

   [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/edunlab/milicontent2/blob/main/uploads/ADM01/ADM01_solution.ipynb)

   > **[안내]** 본 실습의 모든 데이터는 코드 내부에서 난수로 자동 생성되는 교육용 가상 데이터입니다.
   ```

2. **Cell 2 (Environment Setup) [Code]**:
   - 코랩 환경 필수 패키지 자동 설치 및 폰트/경고 설정

   ```python
   # Colab 환경 설정 및 필수 라이브러리 확인
   !pip install -q numpy pandas matplotlib scipy scikit-learn

   import sys
   import numpy as np
   import pandas as pd
   import matplotlib.pyplot as plt
   import warnings
   warnings.filterwarnings('ignore')

   print("실행 환경 준비 완료: Python", sys.version.split()[0])
   ```

3. **Mission Cells (M01 ~ M10 반복 구성)**:
   - **Mission Intro [Markdown]**: 미션 순번, 제목, 난이도, 소요시간, 문제 배경 및 수행 지침, 검증 기준
   - **Mission Code [Code]**:
     - **정답 노트북 (`solution`)**: 완성된 파이썬 실행 코드 및 시각화/검증 로직
     - **학생 실습 노트북 (`student`)**: 핵심 알고리즘 및 데이터 가공 부위에 `### TODO: 코드 작성 ###` 및 힌트 주석 적용
   - **Mission Output/Check [Markdown]**: 예상 실행 콘솔 출력 및 PASS/FAIL 확인 지침

---

## 4. 학생 실습용 코드(Student Code) 자동화 규칙

[`scripts/student_generator.py`](file:///d:/edunlab/milicontent2/scripts/student_generator.py)의 지능형 변환 규칙을 적용하여 실습 몰입도를 높입니다:

1. **데이터 생성 및 유틸리티 함수**: 기초 가상 데이터 생성 로직은 그대로 유지하여 즉시 실습 착수 가능하도록 구성
2. **핵심 분석 / 모델링 / 계산 로직**:
   - 주요 수식, Scikit-learn 모델 훈련/예측, 판정 로직을 `### TODO: [미션 지침에 맞게 구현] ###`으로 블록 처리
   - 주석으로 파라미터 힌트 및 반환값 규격 명시
3. **평가 및 검증 Assert 로직**: 실습자가 작성한 코드가 올바른지 스스로 검증할 수 있도록 테스트 코드는 활성화 상태로 유지

---

## 5. 단계별 실행 계획 (Implementation Phases)

```mermaid
flowchart TD
    P1[Phase 1: 통합 빌더 스크립트 개발<br>scripts/build_all_notebooks.py] --> P2[Phase 2: 60개 시나리오 일괄 빌드<br>uploads/{ProjectID}/ 에 생성]
    P2 --> P3[Phase 3: 무결성 및 구문 검증<br>nbformat 스키마 & AST 문법 검사]
    P3 --> P4[Phase 4: Colab 배포 URL 매핑 & 문서화]
```

### [단계 1] 통합 빌더 스크립트 개발 (`scripts/build_all_notebooks.py`)

- `scenario_md` 내 `*_정답코드.md` 및 `*_실습자료*.md` 파싱 모듈
- `scenario_json/*.json` 메타데이터 연동 모듈 (미션 설명 및 가이드 삽입)
- `student_generator.py`를 활용한 학생용 코드 변환 모듈 결합
- 표준 `.ipynb` (v4 format) JSON 구조 생성 및 파일 저장

### [단계 2] 60개 시나리오 일괄 빌드 실행

- 총 60개 프로젝트 폴더 생성 (`uploads/{ProjectID}/`)
- 코드형 35개 과제: `solution.ipynb` + `student.ipynb` (70개 파일)
- 워크북형 25개 과제: `workbook.ipynb` (25개 파일)
- **총 95개 `.ipynb` 노트북 생성 완료**

### [단계 3] 노트북 스키마 및 문법 검증 (QA)

- `nbformat`을 통한 Jupyter Notebook 표준 포맷 검증
- 파이썬 `ast.parse()`를 통한 정답 코드 구문 오류 0건 검증

### [단계 4] Google Colab 배포 및 활용 가이드

- GitHub 저장소 배포 시 일괄 동작하는 Colab 링크 생성
- `scenario_json`에 노트북 경로 또는 Colab URL 메타데이터 연계 지원

---

## 6. 변환 실행 및 검증 결과 (Execution Results)

- **변환 실행 일시**: 2026-10-08
- **빌드 실행 스크립트**: [`scripts/build_all_notebooks.py`](file:///d:/edunlab/milicontent2/scripts/build_all_notebooks.py)
- **산출물 저장 위치**: [`uploads/{ProjectID}/`](file:///d:/edunlab/milicontent2/uploads) (총 60개 폴더)

### 6.1 산출물 생성 통계

| 실습 유형             | 프로젝트 수 | 생성 파일 유형                                | 생성 파일 수 | 대표 프로젝트                        |
| :-------------------- | :---------: | :-------------------------------------------- | :----------: | :----------------------------------- |
| **코드 기반 실습**    |    35개     | `{ID}_solution.ipynb`<br>`{ID}_student.ipynb` |     70개     | ADM01, OPS01, ISR01, DAT06, MNT02 등 |
| **SOP/모의훈련 실습** |    25개     | `{ID}_workbook.ipynb`                         |     25개     | C207, C210, ISR05, LOG04, TRN04 등   |
| **합계**              |  **60개**   | -                                             |   **95개**   | 전 분야 60개 프로젝트 100% 완료      |

### 6.2 품질 검증 (QA) 결과

| 검증 항목              | 검증 대상           | 검증 기준                                     |      결과       |
| :--------------------- | :------------------ | :-------------------------------------------- | :-------------: |
| **JSON/스키마 규격**   | 95개 노트북 전체    | `nbformat` (v4) 표준 JSON 포맷 준수 여부      | **PASS (100%)** |
| **파이썬 문법성 검증** | 35개 솔루션 코드 셀 | `ast.parse()` 구문 분석 시 SyntaxError 여부   | **PASS (0건)**  |
| **Colab 호환성**       | 95개 노트북 전체    | `Open In Colab` 뱃지 및 환경설정 셀 포함 여부 | **PASS (100%)** |
| **미션 완결성**        | 600개 미션 전체     | 미션 1~10 메타데이터 및 지침 바인딩 여부      | **PASS (100%)** |

### 6.3 Colab 원클릭 실행 URL 형식

```text
# 정답 노트북 (Solution)
https://colab.research.google.com/github/edunlab/milicontent2/blob/main/uploads/{ProjectID}/{ProjectID}_solution.ipynb

# 학생 실습용 노트북 (Student)
https://colab.research.google.com/github/edunlab/milicontent2/blob/main/uploads/{ProjectID}/{ProjectID}_student.ipynb

# 작전절차/모의훈련 워크북 (Workbook)
https://colab.research.google.com/github/edunlab/milicontent2/blob/main/uploads/{ProjectID}/{ProjectID}_workbook.ipynb
```