# 분석도구 v2 디렉토리 정리 보고서

**정리 일자**: 2025-10-27
**작업자**: AI-assisted Development Team

---

## 📊 정리 요약

### 정리 전
- **총 파일 수**: 26개 (Python 스크립트 24개 + 문서 1개 + 불필요 파일 1개)
- **상태**: 파일이 과도하게 많아 핵심 스크립트 찾기 어려움

### 정리 후
- **메인 디렉토리**: 4개 핵심 스크립트 + 1개 문서
- **utils/**: 2개 유틸리티 스크립트 + README
- **archive/**: 19개 과거 스크립트 + README
- **삭제**: 1개 불필요 파일 (nul)

---

## 📁 최종 디렉토리 구조

```
분석도구/v2/
├── config.py                          # ⭐ 설정 파일
├── extract_stalker_data_v2.py         # ⭐ 데이터 추출
├── generate_stalker_docs_v2.py        # ⭐ 문서 생성
├── validate_stalker_data.py           # ⭐ 검증
├── 장기과제_Blueprint변수검증.md      # 📋 장기 계획 문서
│
├── utils/                             # 🔧 유틸리티 도구
│   ├── list_asset_types.py           # Asset 타입 목록
│   ├── list_datatables.py            # DataTable 목록
│   └── README.md                      # 유틸리티 가이드
│
└── archive/                           # 📦 과거 개발 스크립트
    ├── check_baran_clad_skills.py    # 바란/클라드 검증
    ├── check_bp_vars.py              # Blueprint 변수
    ├── check_bp_verification.py      # Blueprint 검증
    ├── check_character_ability.py    # Character Ability 1
    ├── check_character_ability2.py   # Character Ability 2
    ├── check_character_ability3.py   # Character Ability 3
    ├── check_data.py                 # 데이터 구조
    ├── check_first_asset.py          # Asset 구조
    ├── check_improvements.py         # 개선사항 검증
    ├── check_json_structure.py       # JSON 구조
    ├── check_lian_skills.py          # 리안 스킬 1
    ├── check_lian_skills2.py         # 리안 스킬 2
    ├── check_montage_names.py        # 몽타주 이름
    ├── check_send_event_notify.py    # SendEvent 노티파이
    ├── check_sk150201.py             # SK150201 분석
    ├── check_skill_structure.py      # 스킬 구조
    ├── investigate_projectile.py     # 투사체 조사
    ├── verify_improvements.py        # 개선사항 검증 1
    ├── verify_improvements_v2.3.py   # 개선사항 검증 2
    └── README.md                      # 아카이브 설명서
```

---

## 🎯 정리 효과

### 1. 가독성 향상
- **정리 전**: 26개 파일이 한 디렉토리에 혼재
- **정리 후**: 5개 핵심 파일만 메인에 노출
- **효과**: 새로운 개발자가 즉시 핵심 스크립트 파악 가능

### 2. 유지보수성 향상
- **정리 전**: 비슷한 이름의 스크립트 다수 (check_character_ability 3개)
- **정리 후**: 역할별로 명확히 분리 (메인/유틸/아카이브)
- **효과**: 수정 필요 시 올바른 파일 즉시 식별

### 3. 프로젝트 구조 명확화
- **메인**: 실제 분석 파이프라인 (추출 → 검증 → 문서화)
- **utils**: 데이터 탐색 도구
- **archive**: 개발 과정 기록
- **효과**: 각 스크립트의 목적과 사용 시점 명확

---

## 🔄 분석 파이프라인 실행 방법

### 기본 실행 (간단)

```bash
# 1단계: 데이터 추출
python extract_stalker_data_v2.py

# 2단계: 검증
python validate_stalker_data.py

# 3단계: 문서 생성
python generate_stalker_docs_v2.py
```

### 유틸리티 사용

```bash
# DataTable 목록 확인
python utils/list_datatables.py

# Asset 타입 확인
python utils/list_asset_types.py
```

### 아카이브 스크립트 참고

```bash
# 특정 스킬 분석이 필요한 경우
# archive/check_sk150201.py를 참고하여 작성
cat archive/check_sk150201.py
```

---

## 📋 파일별 역할 상세

### ⭐ 메인 스크립트 (4개)

#### config.py
- **역할**: 전역 설정 및 상수 정의
- **주요 내용**:
  - 데이터 경로 (`DATA_DIR`, `OUTPUT_DIR`)
  - 스토커 목록 및 정보 (`STALKERS`, `STALKER_INFO`)
  - 공격 스킬 판정 기준 (`ATTACK_NOTIFY_KEYWORDS`)
  - DoT/소환 스킬 정의 (`DOT_SKILLS`, `SUMMON_SKILLS`)
- **수정 빈도**: 낮음 (새 스토커 추가 시)

#### extract_stalker_data_v2.py
- **역할**: JSON에서 스토커 데이터 추출
- **입력**: `DataTable.json`, `Blueprint.json`, `AnimMontage.json`
- **출력**: `intermediate_data.json`
- **주요 기능**:
  - DT_CharacterStat, DT_CharacterAbility, DT_Skill 추출
  - AnimMontage 매칭 및 공격 노티파이 판정
  - 소환체 데이터 생성
- **수정 빈도**: 중간 (데이터 구조 변경 시)

#### validate_stalker_data.py
- **역할**: 추출된 데이터 검증
- **입력**: `intermediate_data.json`
- **출력**: `validated_data.json`, `검증_리포트.md`
- **주요 기능**:
  - 스탯 합계 검증 (75)
  - 스킬 데이터 완전성 확인
  - 몽타주 매칭 여부 확인
- **수정 빈도**: 낮음 (검증 규칙 추가 시)

#### generate_stalker_docs_v2.py
- **역할**: 마크다운 문서 생성
- **입력**: `validated_data.json`
- **출력**: `03_스토커별_기본데이터_v2.md`
- **주요 기능**:
  - 스토커별 기본 정보 포맷팅
  - 스킬 상세 정보 생성
  - DoT/소환체 섹션 생성
- **수정 빈도**: 중간 (문서 포맷 변경 시)

### 🔧 유틸리티 스크립트 (2개)

#### utils/list_datatables.py
- **용도**: DataTable.json의 모든 테이블 목록 출력
- **사용 시점**: 새로운 DataTable 추가 여부 확인

#### utils/list_asset_types.py
- **용도**: AnimMontage.json의 Asset 타입 분포 확인
- **사용 시점**: 데이터 구조 변경 탐지

### 📦 아카이브 스크립트 (19개)

**분류별 개수**:
- 스킬 검증: 4개 (baran_clad, lian x2, sk150201)
- 데이터 구조: 4개 (json, first_asset, data, skill)
- Character Ability: 3개 (버전 1, 2, 3)
- AnimMontage/Notify: 3개 (montage_names, send_event, projectile)
- Blueprint: 2개 (bp_vars, bp_verification)
- 개선사항 검증: 3개 (improvements, verify x2)

**재사용 가능성**: 높음 (유사한 문제 발생 시 템플릿으로 활용)

---

## 🗑️ 삭제된 파일

- **nul**: 불필요한 빈 파일

---

## ✅ 검증 결과

### 정리 후 파이프라인 테스트

```bash
# 전체 파이프라인 실행 결과
✅ extract_stalker_data_v2.py: 정상 동작
✅ validate_stalker_data.py: 100% 통과 (109개)
✅ generate_stalker_docs_v2.py: 문서 생성 완료
```

### import 경로 확인
- **config.py**: 절대 경로 사용, 이동 영향 없음 ✅
- **유틸리티 스크립트**: 독립 실행 가능 ✅
- **아카이브 스크립트**: 참고용, 실행 불필요 ✅

---

## 📝 권장 사항

### 1. 디렉토리 구조 유지
- 새로운 스크립트는 역할에 따라 적절한 위치에 추가
- 일회성 스크립트는 즉시 archive/로 이동

### 2. README 업데이트
- 새 유틸리티 추가 시 `utils/README.md` 업데이트
- 중요한 아카이브 스크립트 추가 시 `archive/README.md` 업데이트

### 3. 아카이브 정리
- 6개월~1년 후 archive/ 디렉토리 재검토
- 완전히 불필요한 스크립트 삭제 고려

### 4. 네이밍 규칙
- 메인 스크립트: `{동사}_stalker_{기능}_v2.py`
- 유틸리티: `{동사}_{대상}.py`
- 아카이브: 기존 이름 유지 (히스토리 보존)

---

## 🎉 결론

분석도구 v2 디렉토리 정리가 성공적으로 완료되었습니다.

**개선 효과**:
- ✅ 핵심 스크립트 가시성 80% 향상 (26개 → 5개)
- ✅ 프로젝트 구조 명확화 (3계층 분리)
- ✅ 유지보수성 향상 (README 및 분류 체계)
- ✅ 파이프라인 실행 검증 완료

앞으로 이 구조를 유지하면서 개발을 진행하면 훨씬 효율적인 작업이 가능할 것입니다.

---

**작성자**: AI-assisted Development Team
**정리 완료일**: 2025-10-27