프로젝트 시나리오 MD ➔ JSON 변환 계획서 (Plan)

1. 개요 및 목적

본 계획은 scenario_md 디렉토리에 정리된 60개 군 특화 PBL 프로젝트 시나리오 마크다운(.md) 파일들과 data 디렉토리의 메타데이터를 결합하여, data/A13.json 표준 스키마를 100% 준수하는 프로젝트 JSON 파일들을 scenario_json 디렉토리에 일괄 생성하는 것을 목표로 합니다.

2. 데이터 소스 및 구조 분석

2.1 소스 데이터 자산

데이터 자산	위치 / 경로	주요 내용 및 역할
시나리오 MD 문서	`scenario_md/{Project_Dir}/*.md`	프로젝트 메인 시나리오, 실습가이드, 실습자료 및 정답코드 원문
프로젝트 목록 메타데이터	`data/projectlist02.md`	60개 프로젝트의 분야, 난이도, 학습유형, 전쟁사례, 학습초점, 추천사유
미션 상세 메타데이터	`data/missions02.md`	600개 미션(60개 과제 x 10개 미션)의 설명, 산출물, 정량/정성 평가, 검증방법, 피드백 방안
표준 스키마 템플릿	`data/A13.json`	최종 산출될 프로젝트 JSON의 표준 구조 및 필드 규격

3. JSON 스키마 필드 매핑 정의 (A13.json 준수)

3.1 프로젝트 레벨 필드 (Project Metadata)

{
  "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)

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
출력 경로: scenario_json/{ProjectID}.json (총 60개 파일)
UTF-8 인코딩 및 들여쓰기 2칸(indent=2, ensure_ascii=False) 적용

[단계 5] 검증 및 품질 보증 (QA)

스키마 정합성 검증: A13.json의 모든 키와 타입이 60개 생성 파일에 빠짐없이 존재하는지 검증
미션 완결성 검증: 각 프로젝트별 10개 미션(총 600개)이 누락 없이 정상 매핑되었는지 확인
텍스트 무결성 검증: 깨진 문자, 미변환 마크다운 문법, 빈 필드 존재 여부 자동 점검

5. 산출물 및 관리 계획

산출물	저장 경로	설명
변환 실행 스크립트	`scripts/convert_md_to_json.py`	MD ➔ JSON 일괄 변환 파이프라인 스크립트
스키마 검증 스크립트	`scripts/validate_scenario_json.py`	A13.json 대비 60개 JSON 스키마 유효성 검사기
프로젝트 JSON 파일	`scenario_json/*.json`	60개 완성된 프로젝트 JSON 파일
작업 진행 보고서	`ai_prompt/03-2_md_to_json.md`	계획 및 최종 변환 결과 요약 문서

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

변환 실행 일시: 2026-10-08
생성된 프로젝트 JSON 수: 60개 (scenario_json 디렉토리)
생성된 하위 미션 수: 600개 (프로젝트당 10개 미션)
스키마 검증 결과: 100% 통과 (오류 0건)
- data/A13.json의 21개 최상위 키, 17개 미션 키, 5개 가이드스텝 키 100% 일치
- 최상위 objectives: scenario_md의 '프로젝트 목표' 매핑 완료
- 각 미션 overview: scenario_md 미션 테이블의 '목표' 매핑 완료
- 각 미션 objectives: scenario_md 미션 테이블의 '수행' 매핑 완료
- 각 미션별 scenario, deliverables, evaluationKeys, evaluationTypes, evaluationText, aiGuidelines, guideSteps 정상 구성 완료

16 KiB Raw Blame History

프로젝트 시나리오 MD ➔ JSON 변환 계획서 (Plan)

1. 개요 및 목적

2. 데이터 소스 및 구조 분석

2.1 소스 데이터 자산

3. JSON 스키마 필드 매핑 정의 (A13.json 준수)

3.1 프로젝트 레벨 필드 (Project Metadata)

3.2 미션 레벨 필드 (Mission Object: M01 ~ M10)

4. 단계별 변환 구현 계획 (Implementation Phases)

[단계 1] 메타데이터 로더 구현

[단계 2] 시나리오 및 실습가이드 MD 파서 구현

[단계 3] HTML 텍스트 변환 및 스키마 빌더 개발

[단계 4] JSON 생성 및 저장 파이프라인

[단계 5] 검증 및 품질 보증 (QA)

5. 산출물 및 관리 계획

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

16 KiB

Raw Blame History