DOCS/journey/plans/260312_companyx_sync_상태기록강화_및_재개실행_계획.md

tags

tags
infra nas companyx sync plans

260312 Company X 상태 기록 강화 및 재개 실행 계획

상태: 완료 (2026-03-12 상태 기록 강화 구현, tmp 인벤토리 생성, 전체 재개 실행 완주)

상위 원칙

• Infra Project Identity
• Core Infrastructure Principles
• Operational Guardrails
• 공통 작성 원칙: 0_VALUE Writing Principles

관련 문서

• Company X 장시간 동기화 상태 미기록 종료 이슈
• Company X 장시간 동기화 상태 미기록 종료 리서치
• 외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 운영계획

문제 정의

• 현재 스크립트는 장시간 실행 중단 시 상태 파일과 실패 로그를 남기지 못해 전체 동기화 완료 여부를 닫지 못한다.
• 목표는 전체 동기화를 다시 시작하는 것이 아니라, 중간 상태가 남는 재개 가능 실행으로 바꿔서 이 아이디어를 운영 기준으로 닫는 것이다.

구조 결정 고정

• 상태 파일은 마지막에만 쓰지 않고, 파일 다운로드 성공 시마다 갱신한다.
• 실패 로그도 예외 발생 시 즉시 append 한다.
• 임시 파일은 자동 삭제하지 않고, 재개 전 별도 목록으로 기록한다.
• 전체 재개 실행 전 기존 tmp* 파일 목록을 먼저 남긴다.
• 상태 파일 경로는 /mnt/nas/workspace/.sync-logs/companyx_sync_state.json로 고정한다.
• 실패 로그 경로는 /mnt/nas/workspace/.sync-logs/companyx_sync_failures_YYYYMMDD.jsonl로 고정한다.
• 임시 파일 진단 로그 경로는 /mnt/nas/workspace/.sync-logs/companyx_tmp_inventory_YYYYMMDD.jsonl로 고정한다.
• 실행 요약 파일 경로는 /mnt/nas/workspace/.sync-logs/companyx_sync_summary_YYYYMMDD_HHMMSS.json로 고정한다.

실행 순서

1. 스크립트 상태 기록을 강화한다

• last_scanned_path, last_downloaded_path, updated_at, downloaded, skipped, failed 누적치를 중간에도 기록하게 바꾼다.
• 종료 시점이 아니라 실행 중에도 상태 파일이 남게 만든다.
• 최소 기록 주기는 파일 다운로드 성공 시마다 1회로 둔다.
• 디렉터리 스캔만 진행되고 다운로드가 없을 때도 last_scanned_path, updated_at은 주기적으로 갱신하게 한다.

2. 임시 파일 진단 목록을 남긴다

• /mnt/nas/workspace/6.Company X 아래 tmp* 파일 경로, 크기, 수정시각을 별도 진단 로그로 기록한다.
• 이 단계에서는 삭제하지 않는다.
• 필드는 path, size, mtime, captured_at, run_id로 고정한다.

3. 전체 동기화를 다시 재개한다

• 같은 대상 /6.Company X -> /mnt/nas/workspace/6.Company X로 실행한다.
• 이미 받은 파일은 수정시각 + 파일 크기 기준으로 건너뛴다.
• 재개 실행 명령 기준:
  • /home/admin/infra/scripts/bin/companyx_external_nas_sync.py

4. 종료 상태를 검증한다

• 완료 시 상태 파일, 실패 로그, 삭제 후보 로그, 최종 요약이 모두 남는지 확인한다.
• 재실행 시 skipped 증가와 불필요한 재다운로드 부재를 다시 확인한다.
• 완료 후 기본 검증 명령 기준:
  • pgrep -af 'companyx_external_nas_sync.py$'
  • find '/mnt/nas/workspace/.sync-logs' -maxdepth 1 -type f | sort
  • sed -n '1,120p' /mnt/nas/workspace/.sync-logs/companyx_sync_state.json

체크리스트

• 상태 파일이 실행 중에도 갱신된다. 완료
• 실패 로그가 예외 시 즉시 append 된다.
• 재개 전 기존 tmp* 목록이 기록된다. 완료
• 재개 실행 후 최종 요약이 남는다. 완료
• 대표 경로와 전체 경로 모두에서 재실행 가능성이 확인된다. 완료
• 상태 파일, 실패 로그, 임시파일 진단 로그, 요약 파일의 경로와 필드가 고정값대로 생성된다. 완료

검증 기준

• /mnt/nas/workspace/.sync-logs/companyx_sync_state.json이 실행 중에도 최신 시각으로 갱신된다.
• 실패가 있으면 companyx_sync_failures_YYYYMMDD.jsonl에 즉시 남는다.
• 재개 실행 후 전체 요약에서 downloaded/skipped/failed/delete_candidates가 구분된다.
• 완료 후 임시 파일 잔존 여부와 최종 파일 상태를 비교 설명할 수 있다.
• 임시 파일 진단 로그와 최종 요약 파일이 실제로 생성된다.

완료 조건

• 전체 동기화가 중단돼도 현재 위치를 설명할 수 있는 상태 기록이 남는다.
• 재개 실행으로 /6.Company X -> /mnt/nas/workspace/6.Company X를 운영 기준으로 닫을 수 있다.
• 이 주제는 더 이상 원인 불명 종료 문제가 아니라 완주 기록이 남는 운영 절차로 전환된다.

2026-03-12 실행 결과

• /home/admin/infra/scripts/bin/companyx_external_nas_sync.py에 상태 파일 중간 기록, tmp 인벤토리, 요약 파일, 종료 신호 처리 로직을 반영했다.
• 대표 경로 재실행에서 companyx_sync_state.json, companyx_sync_summary_20260312_121529.json, companyx_tmp_inventory_20260312.jsonl 생성을 확인했다.
• 전체 경로 재개 실행은 2026-03-12 13:59:01 KST에 종료됐고 companyx_sync_summary_20260312_121619.json이 생성됐다.
• 최종 수치는 downloaded=18481, skipped=34352, failed=0, delete_candidates=16, files_seen=52833이다.
• 따라서 이 계획의 핵심이었던 상태 미기록 복구와 재개 가능 실행 검증은 완료됐다.