Update README.md: refine user retention classification, enhance OpenSearch data collection details, and improve output file naming conventions

README.md

@@ -12,21 +12,27 @@
 - 예시: `python ds_new_user_analy.py --start-time "2025-08-22T12:00:00+09:00" --end-time "2025-08-25T12:00:00+09:00"`
 
 ### 1.3 그룹 분류
-- 리텐션 유저 (Retained_d1): 첫 접속 후 24시간 ~ 48시간 사이에 접속 기록이 있는 유저
-- 이탈 유저 (Retained_d0): 첫 접속 후 24시간 ~ 48시간 사이에 접속 기록이 없는 유저
+- Retained_d0: 첫 접속 후 24시간 이내에만 접속한 유저 (D+0 이탈)
+- Retained_d1: 마지막 접속이 D+1인 유저
+- Retained_d2: 마지막 접속이 D+2인 유저
+- Retained_d3: 마지막 접속이 D+3인 유저
+- Retained_d4: 마지막 접속이 D+4인 유저
+- Retained_d5: 마지막 접속이 D+5인 유저
+- Retained_d6: 마지막 접속이 D+6인 유저
+- Retained_d7+: D+7 이후에도 접속한 유저
 
 ### 1.4 OpenSearch 연결 정보
-opensearch:
-  host: "ds-opensearch.oneunivrs.com"
-  port: 9200
-  auth:
-    username: "admin"
-    password: "DHp5#r#GYQ9d"
-  use_ssl: true
-  verify_certs: false
-  timeout: 60
-  max_retries: 3
-  headers={"Connection": "close"}
+- opensearch:
+  - host: "ds-opensearch.oneunivrs.com"
+  - port: 9200
+- auth:
+  - username: "admin"
+  - password: "DHp5#r#GYQ9d"
+- use_ssl: true
+- verify_certs: false
+- timeout: 60
+- max_retries: 3
+- headers={"Connection": "close"}
 
 ## 2. OpenSearch 인덱스별 수집 데이터
 
@@ -34,7 +40,7 @@ opensearch:
 | 인덱스 | 수집 항목 | 분석 용도 |
 |--------|----------|----------|
 | `ds-logs-live-create_uid` | `uid`, `auth.id`, `@timestamp` | 신규 유저 식별 |
-| `ds-logs-live-login_comp` | `uid`, `auth.id`, `@timestamp`, `body.nickname`, `body.language` | 첫 로그인 시간, D+1 리텐션 판정, 닉네임, 사용 언어 |
+| `ds-logs-live-login_comp` | `uid`, `auth.id`, `@timestamp`, `body.nickname`, `body.language`, `country` | 첫 로그인 시간, 리텐션 판정, 닉네임, 사용 언어, 국가 |
 | `ds-logs-live-logout` | `uid`, `@timestamp` | 세션 종료 시간, 비정상 종료 여부 |
 | `ds-logs-live-heartbeat` | `uid`, `@timestamp` | 실제 활동 시간 추적 |
 
@@ -101,38 +107,46 @@ opensearch:
 - `uid`: 유저 ID
 - `auth_id`: 스팀 ID (auth.id)
 - `nickname`: 유저 닉네임 (body.nickname from login_comp)
-- `first_login_time`: 최초 로그인 시간 (KST)
-- `retention_status`: 리텐션 상태 (Retained_d0/Retained_d1)
+- `create_time`: 계정 생성 시간 (KST) - create_uid 기반
+- `retention_status`: 리텐션 상태 (Retained_d0/d1/d2/d3/d4/d5/d6/d7+)
 - `language`: 사용 언어 (body.language from login_comp 최신 기록)
+- `country`: 국가 정보 (country from login_comp)
 - `device`: 디바이스 정보 (body.device_mod)
 
 ### 3.2 플레이 시간 및 세션
-- `active_seconds`: D+0 실제 활동 시간 (초) - heartbeat 기반 계산
-- `total_playtime_minutes`: D+0 총 플레이 시간 (분)
 - `session_count`: D+0 접속 횟수 (login_comp 카운트)
-- `avg_session_length`: 평균 세션 길이 (분)
-- `logout_abnormal`: 비정상 종료 여부 (0/1) - last_logout < last_login 체크
+- `active_seconds`: D+0 실제 활동 시간 (초) - heartbeat 기반 계산 (--full 옵션 사용 시)
+- `total_playtime_minutes`: D+0 총 플레이 시간 (분) (--full 옵션 사용 시)
+- `avg_session_length`: 평균 세션 길이 (분) (--full 옵션 사용 시)
+- `logout_abnormal`: 비정상 종료 여부 (0/1) - last_logout < last_login 체크 (--full 옵션 사용 시)
 
 ### 3.3 던전 플레이 성과
-- `dungeon_entry_count`: 던전 진입 횟수 (survival_sta 카운트)
-- `dungeon_first_mode`: 처음 플레이한 던전 모드 (body.dungeon_mode)
-- `dungeon_first_stalker`: 처음 선택한 스토커 (body.stalker_name)
-- `dungeon_first_result`: 첫 던전 결과 (0: 사망, 1: 탈출, 2: 미플레이)
-- `dungeon_escape_count`: 던전 탈출 성공 횟수 (body.result = 1)
-- `dungeon_escape_rate`: 던전 탈출률 (%)
-- `avg_survival_time`: 평균 생존 시간 (body.play_stats.playtime)
-- `max_survival_time`: 최대 생존 시간
-- `total_armor_break`: 총 갑옷 파괴 횟수 (body.play_stats.armor_break_cnt)
-- `raid_play_count`: 레이드 플레이 횟수 (body.play_stats.raid_play)
-- `escape_count`: 던전 포기(탈주) 횟수 (dead with body.inter_type = 0)
+- **공통 지표**
+  - `dungeon_first_mode`: 처음 플레이한 던전 모드
+  - `dungeon_first_stalker`: 처음 선택한 스토커
+  - `dungeon_first_result`: 첫 던전 결과 (0: 사망, 1: 탈출, null: 미플레이)
+  
+- **모드별 지표** (COOP, Solo, Survival, Survival_BOT, Survival_Unprotected)
+  - `{mode}_entry_count`: 모드별 던전 진입 횟수
+  - `{mode}_first_result`: 모드별 첫 플레이 결과
+  - `{mode}_escape_count`: 모드별 탈출 성공 횟수
+  - `{mode}_avg_survival_time`: 모드별 평균 생존 시간
+  - `{mode}_max_survival_time`: 모드별 최대 생존 시간
+  - `{mode}_armor_break_count`: 모드별 갑옷 파괴 횟수
+  - `{mode}_raid_play_count`: 모드별 레이드 횟수
 
 ### 3.4 전투 성과
-- `monster_kill_count`: 몬스터 처치 수 (body.play_stats.monster_kill_cnt 합계)
-- `player_kill_count`: 플레이어 킬 수 (body.instigator_uid = uid)
-- `player_killed_count`: 플레이어에게 사망 수 (body.target_uid = uid)
-- `death_count`: PK 이외 사망 횟수 (dead 인덱스 카운트, inter_type != 0)
-- `avg_damage_per_game_monster`: 게임당 평균 몬스터 피해량 (총 피해량 ÷ 던전 입장 횟수)
-- `avg_damage_per_game_player`: 게임당 평균 플레이어 피해량 (총 피해량 ÷ 던전 입장 횟수)
+- **모드별 킬 수**
+  - `{mode}_monster_kill_count`: 모드별 몬스터 처치 수
+  - `{mode}_player_kill_count`: 모드별 플레이어 킬 수
+  
+- **사망 원인 분석**
+  - `death_PK`: PK로 인한 사망
+  - `death_GiveUp`: 포기로 인한 사망 (inter_type = 0)
+  - `death_Mob`: 몬스터에게 사망 (inter_type = 1)
+  - `death_Trap`: 함정에 의한 사망 (inter_type = 10)
+  - `death_Red`: 레드존 사망 (inter_type = 11)
+  - `death_Others`: 기타 원인 사망
 
 ### 3.5 진행도 및 성장
 - `level_max`: 도달한 최고 레벨 (body.level from level_up 최댓값)
@@ -143,8 +157,7 @@ opensearch:
 - `skill_points_earned`: 획득한 스킬 포인트 수 (skill_point_get 카운트)
 
 ### 3.6 아이템 및 경제
-- `items_obtained_count`: 획득한 아이템 수 (item_get 카운트)
-- `highest_item_grade`: 획득한 최고 등급 아이템 (body.item_grade)
+- `highest_item_grade`: 획득한 최고 등급 장비 아이템 (body.item_grade, base_type = 2)
 - `blueprint_use_count`: 블루프린트 사용 횟수 (craft_from_blueprint 카운트)
 - `shop_buy_count`: 상점 구매 횟수 (shop_buy 카운트)
 - `shop_sell_count`: 상점 판매 횟수 (shop_sell 카운트)
@@ -216,7 +229,8 @@ ds_new_user_analy.py
    - `--end-time`: 분석 종료 시간 (KST)
    - `--output-dir`: 결과 파일 저장 경로 (기본값: 현재 폴더)
    - `--batch-size`: 배치 처리 크기 (기본값: 1000)
-   - `--max-workers`: 병렬 처리 스레드 수 (기본값: 6)
+   - `--max-workers`: 병렬 처리 스레드 수 (기본값: 16)
+   - `--full`: 세션 관련 상세 지표 포함 (기본값: False)
    - `--sample-size`: 샘플 분석 크기 (None이면 전체 분석)
 
 2. 데이터 처리
@@ -478,11 +492,11 @@ with ThreadPoolExecutor(max_workers=max_workers) as executor:
 4. **FALSE POSITIVE 체크**: 0값이 의심될 때 OpenSearch에서 직접 데이터 확인
 
 ### 4.6 출력 파일 및 로깅
-- **결과 파일명**: `ds-new-user-fixed_YYYYMMDD_HHMMSS.csv`
-- **로그 파일명**: `ds-new-user-fixed-analysis_YYYYMMDD_HHMMSS.log`
+- **결과 파일명**: `ds-new_user_analy-YYYYMMDD_HHMMSS.csv`
+- **로그 파일명**: `ds-new_user_analy-YYYYMMDD_HHMMSS.log`
 - **인코딩**: UTF-8 with BOM (Excel 호환)
-- **형식**: CSV (66개 분석 지표)
-- **저장 위치**: `E:\DS_Git\DS_data_center\DS Log 분석\analysis_results\`
+- **형식**: CSV (기본 약 80개 지표, --full 옵션 시 세션 지표 추가)
+- **저장 위치**: 스크립트 실행 디렉토리 내 `analysis_results/` 폴더
 - **시간 형식**: 모든 시간 필드는 KST 기준 `YYYY-MM-DDTHH:mm:ss+09:00` 형식
 - **로깅**: hack-detector 수준의 상세 로깅 (파일 + 콘솔 동시 출력)