---
tags: [infra, nas, companyx, sync, plans]
---

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

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

## 상위 원칙
- [Infra Project Identity](../../00_Philosophy/00_IDENTITY/Infra_Project_Identity.md)
- [Core Infrastructure Principles](../../00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md)
- [Operational Guardrails](../../00_Philosophy/02_GUARDRAILS/Operational_Guardrails.md)
- 공통 작성 원칙: [0_VALUE Writing Principles](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/writing-principles.md)

## 관련 문서
- [Company X 장시간 동기화 상태 미기록 종료 이슈](../troubleshooting/260312_companyx_sync_장시간동기화_상태미기록종료_이슈.md)
- [Company X 장시간 동기화 상태 미기록 종료 리서치](../research/260312_companyx_sync_장시간동기화_상태미기록종료_리서치.md)
- [외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 운영계획](./260311_external_nas_companyx_sync_운영계획.md)

## 문제 정의

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

## 구조 결정 고정

- 상태 파일은 마지막에만 쓰지 않고, 파일 다운로드 성공 시마다 갱신한다.
- 실패 로그도 예외 발생 시 즉시 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`이다.
- 따라서 이 계획의 핵심이었던 `상태 미기록` 복구와 `재개 가능 실행` 검증은 완료됐다.