179 lines
16 KiB
Markdown
179 lines
16 KiB
Markdown
# 프로젝트 시나리오 MD ➔ JSON 변환 계획서 (Plan)
|
|
|
|
## 1. 개요 및 목적
|
|
|
|
본 계획은 [`scenario_md`](file:///d:/edunlab/milicontent2/scenario_md) 디렉토리에 정리된 60개 군 특화 PBL 프로젝트 시나리오 마크다운(`.md`) 파일들과 [`data`](file:///d:/edunlab/milicontent2/data) 디렉토리의 메타데이터를 결합하여, [`data/A13.json`](file:///d:/edunlab/milicontent2/data/A13.json) 표준 스키마를 100% 준수하는 프로젝트 JSON 파일들을 [`scenario_json`](file:///d:/edunlab/milicontent2/scenario_json) 디렉토리에 일괄 생성하는 것을 목표로 합니다.
|
|
|
|
---
|
|
|
|
## 2. 데이터 소스 및 구조 분석
|
|
|
|
### 2.1 소스 데이터 자산
|
|
|
|
| 데이터 자산 | 위치 / 경로 | 주요 내용 및 역할 |
|
|
| :--------------------------- | :------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- |
|
|
| **시나리오 MD 문서** | [`scenario_md/{Project_Dir}/*.md`](file:///d:/edunlab/milicontent2/scenario_md) | 프로젝트 메인 시나리오, 실습가이드, 실습자료 및 정답코드 원문 |
|
|
| **프로젝트 목록 메타데이터** | [`data/projectlist02.md`](file:///d:/edunlab/milicontent2/data/projectlist02.md) | 60개 프로젝트의 분야, 난이도, 학습유형, 전쟁사례, 학습초점, 추천사유 |
|
|
| **미션 상세 메타데이터** | [`data/missions02.md`](file:///d:/edunlab/milicontent2/data/missions02.md) | 600개 미션(60개 과제 x 10개 미션)의 설명, 산출물, 정량/정성 평가, 검증방법, 피드백 방안 |
|
|
| **표준 스키마 템플릿** | [`data/A13.json`](file:///d:/edunlab/milicontent2/data/A13.json) | 최종 산출될 프로젝트 JSON의 표준 구조 및 필드 규격 |
|
|
|
|
---
|
|
|
|
## 3. JSON 스키마 필드 매핑 정의 (A13.json 준수)
|
|
|
|
### 3.1 프로젝트 레벨 필드 (Project Metadata)
|
|
|
|
```json
|
|
{
|
|
"version": "1.0.0",
|
|
"exportedAt": "2026-10-08T00:00:00.000Z",
|
|
"id": "ADM01",
|
|
"title": "결원·근무부하 추세 대시보드와 보충 필요량 예측",
|
|
"category": "행정·인사",
|
|
"level": 3,
|
|
"durationDays": 5,
|
|
"requiredHours": 27.5,
|
|
"status": "COMPLETED",
|
|
"isRecommended": false,
|
|
"summary": "",
|
|
"objectives": "<p>러시아-우크라이나 전쟁에서는 소형 드론이 정찰과 공격에 대량으로 쓰이면서... (시나리오 MD의 '프로젝트 목표' 매핑)</p>",
|
|
"deliverables": ["...", "..."],
|
|
"constraints": "<h4>...</h4><ul>...</ul>",
|
|
"evalSummary": "<h4>공통 PASS/FAIL 판정 원칙</h4><ul>...</ul>",
|
|
"prerequisites": "파이썬 기초 및 데이터 분석 라이브러리 활용 역량",
|
|
"refFiles": [],
|
|
"refText": "",
|
|
"projectSkills": [
|
|
{
|
|
"skillId": "competency_...",
|
|
"level": 2,
|
|
"category": "...",
|
|
"subCategory": "..."
|
|
}
|
|
],
|
|
"prerequisiteVods": [],
|
|
"missions": [
|
|
/* 10개 미션 객체 */
|
|
]
|
|
}
|
|
```
|
|
|
|
> **📌 `objectives` 필드 매핑 원칙**:
|
|
>
|
|
> - `scenario_md` 프로젝트 파일의 **'프로젝트 목표'** (`| **프로젝트 목표** | ... |`) 내용이 결과물 JSON의 최상위 `objectives` 필드에 매핑됩니다.
|
|
|
|
### 3.2 미션 레벨 필드 (Mission Object: M01 ~ M10)
|
|
|
|
| JSON 필드명 | 데이터 타입 | 데이터 출처 및 생성 규칙 |
|
|
| :---------------- | :-----------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| `id` | String | `{ProjectID}_M{01~10}` 형식 (예: `OPS01_M01`) |
|
|
| `sequence` | Number | 미션 순번 (`1` ~ `10`) |
|
|
| `title` | String | 미션명 (`missions02.md` 및 실습가이드 미션 제목) |
|
|
| `durationHours` | Number | 소요시간 (예: `1.5`, `2.0`, `2.5`, `3.0`, `3.5`) |
|
|
| `overview` | HTML String | **미션 목표 매핑**: `scenario_md`의 미션 테이블 내 **'목표'** (`\| **목표** \| ... \|`) ➔ `<p>{목표 내용}</p>` |
|
|
| `objectives` | HTML String | **미션 수행 매핑**: `scenario_md`의 미션 테이블 내 **'수행'** (`\| **수행** \| ... \|`) ➔ `<p>{수행 내용}</p>` |
|
|
| `scenario` | HTML String | **미션 배경 및 수행 당위성 스토리**: `overview`(목표)와 `objectives`(수행)를 왜 해야 하는지 설명하는 스토리, 실습 흐름 및 최종 결과물 정의 |
|
|
| `attachments` | Array | 첨부파일 목록 |
|
|
| `materials` | Array | 미션 관련 가상 데이터 및 참조자료 경로 목록 |
|
|
| `materialText` | HTML String | 참조 사이트, 수업용 가상 데이터 샘플, 주의사항 (`<p>`, `<ul>`, `<a>`) |
|
|
| `techStack` | Array[String] | 미션에 사용되는 기술/도메인 키워드 태그 목록 |
|
|
| `deliverables` | Array[String] | 미션 산출물 목록 (필수/선택 표기 포함) |
|
|
| `evaluationKeys` | Array[HTML] | 평가 질문(PASS/FAIL), PASS 증거, 보완이 필요한 상태, 보완 방법 |
|
|
| `evaluationTypes` | Array[String] | 평가 구분 (`["REQUIRED", ...]` 또는 `["OPTIONAL", ...]`) |
|
|
| `evaluationText` | HTML String | 미션 판정 구분, 핵심 평가영역, PASS 조건, 채점자 판정 메모 |
|
|
| `aiGuidelines` | Object | `allow` (허용), `rules` (준수사항), `forbid` (금지사항) |
|
|
| `guideSteps` | Array[Object] | **학습활동 (`_실습가이드.md` 참고)**: 1~5단계 세부 가이드 (`step`, `problem`, `activity`, `evalText`, `attachments`) — `_실습가이드.md`의 진행 순서, 확인할 결과, 도전 과제를 기반으로 작성 |
|
|
|
|
> **📌 `scenario` (미션 시나리오) 작성 원칙**:
|
|
>
|
|
> - **미션 수행 당위성 스토리텔링 (Why 스토리)**:
|
|
> - 각 미션의 `overview`(목표)와 `objectives`(수행)를 단순 요약하거나 복사하지 않고, **"이 목표와 수행을 왜 해야 하는가?"**(현장 전술적 문제의식, 분석/구현이 시급한 이유, 해결해야 할 핵심 과제 등)를 설명하는 생생한 배경 스토리를 **2~3문장**으로 작성하여 학습자의 몰입도를 극대화합니다.
|
|
> - **수행 내용의 자연스러운 문장 연결 (Copy&Paste 금지)**:
|
|
> - `objectives`(미션 수행 내용)의 원문 문장들을 그대로 복사·나열하지 않고, **"이 문제를 해결하기 위해 본 미션에서는 [핵심 수행 과제 및 분석·구현 활동]을(를) 체계적으로 수행합니다."** 와 같이 앞선 배경 스토리와 맥락이 매끄럽게 이어지는 **간결하고 완성도 높은 1문장**으로 정제하여 작성합니다.
|
|
> - **실습 흐름 및 안내**: 실습가이드에 따른 N단계 세부 활동(기본 기능 구현 ➔ 결과 지표 검증 ➔ 파라미터 튜닝 및 도전과제)의 전체적인 진행 흐름을 명확히 안내합니다.
|
|
> - **최종 결과물**: 미션 수행을 통해 완성해야 할 산출물(`<code>{산출물}</code>`) 명세를 명시합니다.
|
|
|
|
> **📌 `guideSteps` (학습활동) 작성 원칙**:
|
|
>
|
|
> - 각 미션의 학습활동(`guideSteps`)은 프로젝트 디렉토리 내 **`_실습가이드.md`** (예: `OPS01_실습가이드.md`)의 내용을 적극 참고하여 작성합니다.
|
|
> - `_실습가이드.md`의 미션별 **'진행 순서'** 항목을 1~4단계 세부 활동으로 분할하여 `problem`, `activity`, `evalText`를 구조화합니다.
|
|
> - `_실습가이드.md`의 **'확인할 결과'**는 각 단계의 핵심 확인 지표(PASS 기준)로 반영합니다.
|
|
> - `_실습가이드.md`의 **'도전 과제'**는 마지막 심화 튜닝 단계(Step 5 또는 추가 단계)로 매핑합니다.
|
|
|
|
---
|
|
|
|
## 4. 단계별 변환 구현 계획 (Implementation Phases)
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A[Step 1: 메타데이터 파싱<br>projectlist02.md & missions02.md] --> B[Step 2: 시나리오 및 실습가이드 MD 파싱<br>메인 시나리오 / _실습가이드.md / 정답코드]
|
|
B --> C[Step 3: 데이터 결합 & 필드 매핑<br>프로젝트 목표➔objectives / 미션 목표➔overview / 미션 수행➔objectives / 'Why' 스토리 및 _실습가이드.md➔guideSteps]
|
|
D --> E[Step 5: 스키마 검증 & 무결성 테스트<br>60개 JSON 필드 누락 및 타입 검증]
|
|
C --> D[Step 4: JSON 직렬화 & 파일 생성<br>scenario_json/ 하위에 저장]
|
|
```
|
|
|
|
### [단계 1] 메타데이터 로더 구현
|
|
|
|
- `data/projectlist02.md`를 파싱하여 60개 프로젝트의 기본 속성(분야, 난이도, 유형, 전쟁사례, 추천사유 등)을 딕셔너리로 인덱싱
|
|
- `data/missions02.md`를 파싱하여 600개 미션의 속성(소요시간, 복잡도, 설명, 산출물, 평가방안, 검증기준 등)을 `(프로젝트ID, 미션번호)` 키로 인덱싱
|
|
|
|
### [단계 2] 시나리오 및 실습가이드 MD 파서 구현
|
|
|
|
- `scenario_md` 하위의 각 프로젝트 폴더 순회:
|
|
1. **메인 시나리오 MD**:
|
|
- **'프로젝트 목표'** 파싱 ➔ 최상위 `objectives`에 매핑
|
|
- **미션별 '목표'** 파싱 ➔ 미션 `overview`에 매핑
|
|
- **미션별 '수행'** 파싱 ➔ 미션 `objectives`에 매핑
|
|
- 제약사항, 유의사항, 최종 판정 기준 파싱
|
|
2. **`_실습가이드.md`**:
|
|
- 미션별 **'진행 순서'**, **'확인할 결과'**, **'도전 과제'**, **'제출물'** 파싱 ➔ `guideSteps` (학습활동) 생성 시 사용
|
|
3. **코드/실습자료 MD**: 실습 코드 블록, 테스트 케이스, 평가 데이터 파싱
|
|
|
|
### [단계 3] HTML 텍스트 변환 및 스키마 빌더 개발
|
|
|
|
- `A13.json` 규격에 맞는 HTML 태그(`<p>`, `<h4>`, `<ul>`, `<li>` 등) 서식화 모듈 적용
|
|
- **필드 매핑 적용**:
|
|
- 최상위 `objectives`: `scenario_md` 프로젝트 파일의 '프로젝트 목표' 매핑
|
|
- 각 미션 `overview`: `scenario_md` 미션 테이블의 '목표' 매핑
|
|
- 각 미션 `objectives`: `scenario_md` 미션 테이블의 '수행' 매핑
|
|
- 각 미션 `scenario`: `overview`(목표)와 `objectives`(수행)를 **왜 해야 하는지(필요성, 전술적 문제의식, 당위성)**를 풀어낸 2~3문장의 스토리텔링과, 문제 해결을 위한 핵심 과제를 매끄럽게 연결한 1문장, N단계 실습 흐름, 최종 산출물 명세 결합
|
|
- 각 미션 `guideSteps` (학습활동): **`_실습가이드.md`**를 참고하여 단계별 문제(`problem`), 활동(`activity`), 평가기준(`evalText`) 자동 생성
|
|
- 미션별 평가 루브릭(`evaluationKeys`, `evaluationTypes`, `evaluationText`) 및 AI 가이드라인(`aiGuidelines`) 구성
|
|
|
|
### [단계 4] JSON 생성 및 저장 파이프라인
|
|
|
|
- 스크립트: [`scripts/convert_md_to_json.py`](file:///d:/edunlab/milicontent2/scripts/convert_md_to_json.py)
|
|
- 출력 경로: [`scenario_json/{ProjectID}.json`](file:///d:/edunlab/milicontent2/scenario_json) (총 60개 파일)
|
|
- UTF-8 인코딩 및 들여쓰기 2칸(`indent=2`, `ensure_ascii=False`) 적용
|
|
|
|
### [단계 5] 검증 및 품질 보증 (QA)
|
|
|
|
1. **스키마 정합성 검증**: `A13.json`의 모든 키와 타입이 60개 생성 파일에 빠짐없이 존재하는지 검증
|
|
2. **미션 완결성 검증**: 각 프로젝트별 10개 미션(총 600개)이 누락 없이 정상 매핑되었는지 확인
|
|
3. **텍스트 무결성 검증**: 깨진 문자, 미변환 마크다운 문법, 빈 필드 존재 여부 자동 점검
|
|
|
|
---
|
|
|
|
## 5. 산출물 및 관리 계획
|
|
|
|
| 산출물 | 저장 경로 | 설명 |
|
|
| :----------------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------------------- |
|
|
| **변환 실행 스크립트** | [`scripts/convert_md_to_json.py`](file:///d:/edunlab/milicontent2/scripts/convert_md_to_json.py) | MD ➔ JSON 일괄 변환 파이프라인 스크립트 |
|
|
| **스키마 검증 스크립트** | [`scripts/validate_scenario_json.py`](file:///d:/edunlab/milicontent2/scripts/validate_scenario_json.py) | A13.json 대비 60개 JSON 스키마 유효성 검사기 |
|
|
| **프로젝트 JSON 파일** | [`scenario_json/*.json`](file:///d:/edunlab/milicontent2/scenario_json) | 60개 완성된 프로젝트 JSON 파일 |
|
|
| **작업 진행 보고서** | [`ai_prompt/03-2_md_to_json.md`](file:///d:/edunlab/milicontent2/ai_prompt/03-2_md_to_json.md) | 계획 및 최종 변환 결과 요약 문서 |
|
|
|
|
---
|
|
|
|
## 6. 변환 실행 및 검증 결과 (Execution Results)
|
|
|
|
- **변환 실행 일시**: 2026-10-08
|
|
- **생성된 프로젝트 JSON 수**: **60개** ([`scenario_json`](file:///d:/edunlab/milicontent2/scenario_json) 디렉토리)
|
|
- **생성된 하위 미션 수**: **600개** (프로젝트당 10개 미션)
|
|
- **스키마 검증 결과**: **100% 통과 (오류 0건)**
|
|
- [`data/A13.json`](file:///d:/edunlab/milicontent2/data/A13.json)의 21개 최상위 키, 17개 미션 키, 5개 가이드스텝 키 100% 일치
|
|
- 최상위 `objectives`: `scenario_md`의 **'프로젝트 목표'** 매핑 완료
|
|
- 각 미션 `overview`: `scenario_md` 미션 테이블의 **'목표'** 매핑 완료
|
|
- 각 미션 `objectives`: `scenario_md` 미션 테이블의 **'수행'** 매핑 완료
|
|
- 각 미션별 `scenario`, `deliverables`, `evaluationKeys`, `evaluationTypes`, `evaluationText`, `aiGuidelines`, `guideSteps` 정상 구성 완료
|