Update Company X realtime sync docs

journey/README.md

@@ -54,6 +54,7 @@
 - [컴퍼니엑스 직원용 모바일 파일 포털 아이디어](./ideas/260307_companyx_mobile_file_portal_아이디어.md)
 - [23장애시 24서버 임시진입면승격 아이디어](./ideas/260309_23장애시_24서버_임시진입면승격_아이디어.md)
 - [외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 리서치](./research/260307_external_nas_companyx_sync_research.md)
+- [외부 NAS -> 내부 NAS 컴퍼니엑스 실시간동기화 리서치](./research/260312_external_nas_companyx_실시간동기화_리서치.md)
 - [External NAS -> Internal NAS Sync Probe](./research/260307_external_nas_to_internal_nas_sync_probe.md)
 - [컴퍼니엑스 직원용 모바일 파일 포털 리서치](./research/260307_companyx_mobile_file_portal_research.md)
 - [51123 구 IP 하드코딩 실행 경로와 런타임 SSOT 불일치 리서치](./research/260309_51123_구IP하드코딩_실행경로_SSOT불일치_리서치.md)
@@ -68,6 +69,7 @@
 - [24 자동배포 0초 종료 runtime SSOT 복구 계획](./plans/260311_24자동배포_0초종료_runtime_ssot복구_계획.md)
 - [23서버 워크스페이스 SSOT 구조전환 계획](./plans/260309_23서버_워크스페이스_SSOT_구조전환_계획.md)
 - [외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 운영계획](./plans/260311_external_nas_companyx_sync_운영계획.md)
+- [외부 NAS -> 내부 NAS 컴퍼니엑스 실시간동기화 계획](./plans/260312_external_nas_companyx_실시간동기화_계획.md)
 - [rb8001 24 자동배포 SSOT 복구 및 SSH 인증 수정 완료](./worklog/260311_rb8001_24자동배포_ssot복구_및_ssh인증수정_완료.md)
 - [goosefarminvesting 도메인 인증서 및 nginx 정합화 계획](./plans/260311_goosefarminvesting_도메인_인증서_및_nginx_정합화_계획.md)
 - [goosefarminvesting 도메인 vhost 인증서 적용 및 실도메인 검증](./worklog/260311_goosefarminvesting_도메인_vhost_인증서_적용_및_실도메인_검증.md)
@@ -79,3 +81,4 @@
 - [24전환 배포대상과 ingress 24IP 교정 1차](./worklog/260309_24전환_배포대상과_ingress_24IP_교정_1차.md)
 - [24서버 NAS 마운트 복원 및 ONNX 백업 실행](./worklog/260309_24서버_nas마운트복원_onnx백업실행.md)
 - [Company X 외부 NAS 동기화 스크립트 구현 및 대표 검증](./worklog/260311_companyx_external_nas_sync_스크립트구현_및_대표검증.md)
+- [Company X 30분주기 cron 적용 및 예측 검증](./worklog/260312_companyx_sync_30분주기_cron적용_및_예측검증.md)

journey/plans/260312_external_nas_companyx_실시간동기화_계획.md

@@ -0,0 +1,111 @@
+---
+tags: [infra, nas, companyx, sync, realtime, plans]
+---
+
+# 260312 외부 NAS -> 내부 NAS 컴퍼니엑스 실시간동기화 계획
+
+**상태**: 완료 (2026-03-12 cron 적용, 중복 실행 방지 검증, 1분 제한 실측 기반 주기 30분으로 보정)
+
+## 상위 원칙
+- [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)
+
+## 관련 문서
+- [Infra Journey](../README.md)
+- [외부 NAS -> 내부 NAS 컴퍼니엑스 실시간 동기화 아이디어](../ideas/260312_external_nas_companyx_실시간동기화_아이디어.md)
+- [외부 NAS -> 내부 NAS 컴퍼니엑스 실시간동기화 리서치](../research/260312_external_nas_companyx_실시간동기화_리서치.md)
+- [외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 운영계획](./260311_external_nas_companyx_sync_운영계획.md)
+- [Company X 상태기록 강화 및 재개 실행](../worklog/260312_companyx_sync_상태기록강화_및_재개실행.md)
+
+## 문제 정의
+
+- 전체 트리 기준 재귀 조회는 이미 동작하지만, 현재 구조 그대로는 `거의 즉시` 반영을 말하기 어렵다.
+- 2026-03-12 실측에서 전체 트리 `--dry-run`은 `3분 45초`가 지나도 종료되지 않았고, 작은 폴더 Search API는 빠르지만 루트 전체 재귀 Search는 신뢰 가능한 결과를 주지 못했다.
+- 따라서 이번 계획의 목표는 `실시간처럼 보이는 과장`이 아니라, 현재 근거로 재현 가능한 `짧은 지연 동기화 운영안`을 고정하는 것이다.
+
+## 구조 결정 고정
+
+- 허용 지연은 `30분 이내`로 고정한다.
+- 기본 실행 방식은 `cron 기반 30분 주기 증분 pull`로 고정한다.
+- 전체 루트 `/6.Company X`는 기존 `List` 기반 재귀 scan/pull을 유지한다.
+- Search API는 전체 루트 대체재로 쓰지 않는다.
+- Search API는 변화가 잦고 범위가 좁은 일부 상위 폴더에서만 보조 후보로 제한 검토한다.
+- 증분 기준은 기존과 동일하게 `수정시각 + 파일 크기`를 유지한다.
+- 해시는 기본 증분 판정 기준으로 올리지 않는다.
+- 내부 NAS DSM webhook/API 제어를 기본 전제로 두지 않는다.
+- 외부 삭제는 내부 NAS에 자동 전파하지 않고, 삭제 후보 로그만 남긴다.
+- 같은 주기의 중복 실행은 허용하지 않는다.
+- 하루 1회는 전체 루트 기준 검증 스캔을 수행해 Search API 누락 가능성과 누적 불일치를 점검한다.
+- SHA256은 표본 무결성 검증과 의심 파일 확인에만 제한적으로 사용한다.
+
+## 실행 순서
+
+### 1. 30분 주기 실행 엔트리를 고정한다
+
+- `companyx_external_nas_sync.py`를 30분마다 실행하는 cron 엔트리를 기준안으로 둔다.
+- 실행 겹침 방지를 위해 lock 파일 또는 `flock` 기반 단일 실행 제어를 같이 둔다.
+- 로그는 기존 `.sync-logs` 경로를 재사용한다.
+
+### 2. 전체 루트 30분 주기 증분 실행을 먼저 기준안으로 채택한다
+
+- 최초 기준안은 `/6.Company X -> /mnt/nas/workspace/6.Company X` 전체 루트 재귀 조회다.
+- 이유는 현재 직접 검증된 방식 중 전체 범위를 안정적으로 설명 가능한 경로가 이것뿐이기 때문이다.
+- Search API를 먼저 중심 구조로 승격하지 않는다.
+- 내부 NAS나 외부 NAS의 파일 변경 webhook이 있다는 가정을 실행 기준에 넣지 않는다.
+
+### 3. Search API는 일부 상위 폴더 후보에서만 별도 검증한다
+
+- `/6.Company X/7. 사진`처럼 범위가 제한된 상위 폴더를 후보로 둔다.
+- 작은 범위에서 `pattern`, `mtime_from`, `mtime_to` 기반 검색이 계속 일관되게 맞는지 확인한다.
+- 이 검증이 반복 통과되기 전까지 Search API는 보조 최적화 후보로만 취급한다.
+
+### 4. 하루 1회 전체 검증 스캔을 추가한다
+
+- 10분 주기 실행과 별도로 하루 1회 전체 루트 기준 재귀 스캔을 수행한다.
+- 목적은 Search API 보조 최적화가 일부 폴더에서 쓰이더라도 누락 파일, 이동 파일, 시간 오차를 다시 맞추기 위함이다.
+- 이 검증 스캔도 같은 상태 파일과 요약 파일 체계를 사용한다.
+
+### 5. 운영 임계치를 수치로 확인한다
+
+- 30분 주기 실행의 평균 소요 시간, 최장 소요 시간, 겹침 발생 여부를 기록한다.
+- `1회 실행 시간이 30분을 반복 초과`하면 주기를 더 늘리거나 상위 폴더 분할로 전환한다.
+- `Search API 후보 폴더`는 동일 시점 `List` 결과와 표본 비교해 누락이 없을 때만 다음 단계로 올린다.
+- `해시 재계산`은 2026-03-12 실측에서 같은 표본 기준 `stat 0.927ms` 대비 `sha256 617.713ms`, 약 `666.4배` 느렸으므로 운영 기본 루프에 넣지 않는다.
+- 전체 루트 `1분 제한` 실측에서는 `directories_seen=436`, `files_seen=2276`이었고, 기존 완주 총량 대비 단순 비례 예상 시간은 약 `23.4분`이었다.
+- 따라서 현재 기본안은 `10분`이 아니라 `30분`이 안전한 보수 주기다.
+
+## 체크리스트
+
+- 허용 지연 `30분`이 문서와 실행 설정에서 일치한다.
+- cron 기준 실행이 중복 없이 유지된다.
+- 전체 루트 기준 30분 주기 실행에서 상태 파일과 요약 파일이 남는다.
+- 1회 실행 시간이 주기를 반복 초과하지 않는다.
+- Search API는 전체 루트 대체재가 아니라 일부 상위 폴더 후보로만 사용된다.
+- 해시는 기본 증분 판정이 아니라 표본 검증에만 남는다.
+- 하루 1회 전체 검증 스캔이 별도로 남는다.
+- 삭제 전파 없이 삭제 후보 로그만 남는다.
+
+## 검증 기준
+
+- 30분 주기 실행 3회 이상에서 `failed=0` 또는 원인 설명 가능한 실패 로그가 남는다.
+- 각 실행 요약에서 `started_at`, `finished_at`, `downloaded`, `skipped`, `failed`를 확인할 수 있다.
+- 같은 시간대 중복 프로세스가 생기지 않는다.
+- 하루 1회 전체 검증 스캔 결과와 30분 주기 실행 결과 사이에 설명되지 않는 누락이 없다.
+- Search API 후보 폴더는 같은 표본에 대해 `List`와 결과가 일치한다.
+
+## 완료 조건
+
+- `실시간` 대신 `30분 이내 반영`이라는 운영 표현이 문서와 실행 결과에서 일치한다.
+- 30분 주기 증분 pull이 재현 가능하고, 중복 실행 없이 안정적으로 돈다.
+- Search API는 과장 없이 `일부 상위 폴더 보조 최적화 후보`로만 정리된다.
+- 이 주제는 더 이상 막연한 실시간 아이디어가 아니라, 측정값에 근거한 운영 기준으로 전환된다.
+
+## 현재 추천 결론
+
+- 현재 근거 기준 1순위는 `cron 30분 주기 + 전체 루트 증분 pull + 하루 1회 전체 검증 스캔`이다.
+- Search API는 작은 폴더에서 빠르게 동작했지만 루트 전체에서는 신뢰 가능한 결과를 주지 못했으므로, 일부 상위 폴더에서만 제한 검토한다.
+- 해시는 직접 실측에서 `수정시각 + 파일 크기`보다 현저히 느렸으므로, 운영 루프가 아니라 표본 검증에만 남긴다.
+- 내부 NAS 관리자 계정으로 DSM API 로그인 자체는 가능했지만, 현재 확인된 API 목록에는 알림/webhook 제어 항목이 없었으므로 webhook 기반 설계는 채택하지 않는다.
+- 전체 루트 1분 제한 실측 기반 예상 시간이 약 `23.4분`이므로, 현재 추천 점수는 `92%`다.

journey/research/260312_external_nas_companyx_실시간동기화_리서치.md

@@ -0,0 +1,211 @@
+---
+tags: [infra, nas, companyx, sync, realtime, research]
+---
+
+# 260312 외부 NAS -> 내부 NAS 컴퍼니엑스 실시간동기화 리서치
+
+## 상위 원칙
+- [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)
+
+## 관련 문서
+- [외부 NAS -> 내부 NAS 컴퍼니엑스 실시간 동기화 아이디어](../ideas/260312_external_nas_companyx_실시간동기화_아이디어.md)
+- [외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 리서치](./260307_external_nas_companyx_sync_research.md)
+- [외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 운영계획](../plans/260311_external_nas_companyx_sync_운영계획.md)
+- [Company X 상태기록 강화 및 재개 실행](../worklog/260312_companyx_sync_상태기록강화_및_재개실행.md)
+
+## 목적
+
+- `실시간에 가까운 동기화`가 현재 구조에서 왜 필요한지, 그리고 지금 근거로 어디까지 말할 수 있는지 좁힌다.
+- 이 문서는 실시간 동기화 방식을 확정하는 문서가 아니라, `why`를 분리해 다음 `plans`가 무엇을 고정해야 하는지 정리하는 것을 목표로 한다.
+
+## 리서치 질문
+
+1. 이미 검증된 배치/재개 동기화 구조만으로도 운영 기준을 만족하는가
+2. 실시간 또는 짧은 주기 동기화가 필요한 이유는 무엇인가
+3. 현재 근거만으로 이벤트 기반 실시간 동기화를 말할 수 있는가
+4. 지금 시점에서 닫을 수 있는 질문과 아직 닫을 수 없는 질문은 무엇인가
+
+## Facts
+
+### 1. 외부 NAS -> 내부 NAS 기본 동기화 구조는 이미 운영 가능 수준까지 검증됐다
+
+- 외부 NAS `/6.Company X`를 내부 NAS `/mnt/nas/workspace/6.Company X`로 동기화하는 구조 자체는 이미 검증됐다.
+- 2026-03-12 최종 실행 기준 `downloaded=18481`, `skipped=34352`, `failed=0`, `files_seen=52833`, `downloaded_bytes=83980539725`가 기록됐다.
+- 즉 `실시간` 여부와 별개로, `외부 원본 -> 내부 기준 저장소 -> 서버는 내부 NAS만 사용` 구조는 이미 성립한다.
+
+근거:
+- [260307_external_nas_companyx_sync_research.md](./260307_external_nas_companyx_sync_research.md)
+- [260311_external_nas_companyx_sync_운영계획.md](../plans/260311_external_nas_companyx_sync_운영계획.md)
+- [260312_companyx_sync_상태기록강화_및_재개실행.md](../worklog/260312_companyx_sync_상태기록강화_및_재개실행.md)
+
+### 2. 현재 검증된 접근 경로는 DSM API 기반 조회/다운로드다
+
+- 외부 NAS 직접 SMB(Server Message Block) `139/445` 접근은 현재 직접 사용 경로가 아니다.
+- 현재 검증된 외부 접근은 Synology DSM(DiskStation Manager) File Station API다.
+- 따라서 지금 사실 기준에서 검증된 방식은 `외부 이벤트 push`가 아니라 `원격 조회 후 필요한 파일을 가져오는 pull` 구조다.
+
+2026-03-12 21:01 KST 실측값:
+- DSM 로그인: `4.124초`
+- 루트 목록 조회 `/6.Company X`: `0.059초`, 응답 크기 `3401B`, 항목 `16개`
+- 대표 사진 폴더 목록 조회 `/6.Company X/7. 사진/220308_X코스_5기 발표 사진`: `0.084초`, 응답 크기 `5559B`, 항목 `20개`
+- 샘플 파일 다운로드 `Thumbs.db` `12,288B`: `0.175초`
+- 샘플 파일 다운로드 엑셀 `151,832B`: `0.131초`
+- 샘플 파일 다운로드 JPG `457,889B`: `0.233초`
+- 샘플 파일 다운로드 PDF `20,147,273B`: `0.731초`, 약 `26.27 MiB/s`
+
+근거:
+- [260307_external_nas_to_internal_nas_sync_probe.md](./260307_external_nas_to_internal_nas_sync_probe.md)
+- [260307_external_nas_companyx_sync_research.md](./260307_external_nas_companyx_sync_research.md)
+
+### 3. 현재 구현 스크립트는 주기 실행/재개 실행에는 맞지만, 외부 변화 이벤트 수신 구조는 아니다
+
+- 현재 스크립트 `/home/admin/infra/scripts/bin/companyx_external_nas_sync.py`는 DSM API로 폴더를 재귀 조회하고 파일을 내려받는다.
+- 상태 파일, 실패 로그, 삭제 후보 로그, 요약 파일을 남기며 장시간 재개 실행도 가능하다.
+- 하지만 코드와 현재 문서 기준으로는 외부 NAS 변화 이벤트를 받아 즉시 실행하는 webhook, queue, daemon 구조는 확인되지 않았다.
+
+2026-03-12 21:01 KST 전체 트리 `--dry-run` 실측값:
+- 실행 시작: `2026-03-12 21:01:21 KST`
+- `3분 45초` 경과 시점에도 전체 스캔이 종료되지 않았다.
+- 중단 직전 상태 파일 기준 `directories_seen=2744`, `files_seen=12913`, `failed=1`, `termination_signal=SIGTERM`이었다.
+- 같은 시점 `downloaded=12912`, `downloaded_bytes=136,138,945,147`로 기록됐는데, 이는 `--dry-run`에서 실제 저장 대신 `내려받아야 할 파일`로 계산된 누적치다.
+- 즉 `전체 트리 재조회 자체`가 분 단위 작업이며, 최소한 현재 구조를 그대로 두고는 `거의 즉시 반영`을 가정하기 어렵다.
+
+근거:
+- [/home/admin/infra/scripts/bin/companyx_external_nas_sync.py](/home/admin/infra/scripts/bin/companyx_external_nas_sync.py)
+- [260311_companyx_external_nas_sync_스크립트구현_및_대표검증.md](../worklog/260311_companyx_external_nas_sync_스크립트구현_및_대표검증.md)
+- [260312_companyx_sync_상태기록강화_및_재개실행.md](../worklog/260312_companyx_sync_상태기록강화_및_재개실행.md)
+
+### 4. 실시간 동기화 필요성은 구조 성립 여부가 아니라 최신성 요구 수준에서 나온다
+
+- 기존 아이디어 문서에서도 핵심 문제는 `내부 NAS 최신 반영 시점이 아직 실행 주기에 의존한다`는 점이었다.
+- 즉 실시간 동기화의 질문은 `가능하냐`보다 `내부 NAS 반영 지연을 얼마나 줄여야 하느냐`에 가깝다.
+- 현재까지는 전체 동기화 성공과 재개 가능성은 검증됐지만, `몇 분 이내`, `거의 즉시`, `일 단위` 중 어떤 최신성 목표가 필요한지는 아직 확정되지 않았다.
+
+근거:
+- [260312_external_nas_companyx_실시간동기화_아이디어.md](../ideas/260312_external_nas_companyx_실시간동기화_아이디어.md)
+
+### 5. 현재 근거만으로는 이벤트 기반 실시간 동기화를 검증했다고 말할 수 없다
+
+- 실동작으로 검증된 것은 `대표 경로 동기화`, `전체 트리 완주`, `재실행 건너뛰기`, `상태 기록`이다.
+- 외부 NAS 변화 발생 직후 자동 감지, 즉시 실행, 중복 트리거 제어, 이동/삭제 이벤트 처리 같은 항목은 아직 직접 검증 기록이 없다.
+- 따라서 `실시간 동기화 가능`보다는 `실시간에 가까운 주기 동기화 후보를 검토할 근거가 생겼다`가 현재 사실 범위에 더 맞다.
+
+### 6. Search API는 부분적으로 동작하지만, 현재 NAS에서 전체 트리 증분 검색 대체재로 바로 쓰기는 어렵다
+
+- 2026-03-12 21:07 KST 실측에서 `SYNO.FileStation.Search` 자체 호출은 성공했다.
+- 작은 대표 폴더 `/6.Company X/7. 사진/220308_X코스_5기 발표 사진`에서는 정확 파일명 검색이 `start 0.060초 + list 0.078초`로 성공했고, `mtime_from/mtime_to` 조건도 정상 동작했다.
+- 같은 대표 폴더에서 `mtime_window_hit`은 `total=19`, `mtime_window_miss`는 `0건`으로 나와 시간 조건 필터도 확인됐다.
+- 하지만 루트 `/6.Company X` 전체 재귀 검색에서는 `Thumbs.db`, `창업기획자 등록절차 및 운영 안내(26.2월).hwp` 같은 실제 존재 파일명을 줘도 `finished=true`와 빈 결과만 반환됐다.
+- 즉 현재 NAS에서는 `Search API = 사용 불가`는 아니지만, `전체 루트 증분 검색을 신뢰할 수 있는 상태`도 아니다.
+
+2026-03-12 21:07~21:09 KST 실측값:
+- 작은 폴더 정확 파일 검색: `start 0.060초`, `list 0.078초`, `total=1`
+- 작은 폴더 `mtime` 적중 검색: `start 0.063초`, `list 0.072초`, `total=19`
+- 작은 폴더 `mtime` 비적중 검색: `start 0.060초`, `list 0.074초`, `0건`
+- 루트 전체 `Thumbs.db` 검색: `start 0.060초`, `list 0.073초`, `0건`
+- 루트 전체 특정 HWP 검색: `start 0.058초`, `list 0.079초`, `finished=true`, 결과 없음
+
+### 7. 해시 기반 판정은 `수정시각 + 파일 크기`보다 직접 측정 기준으로 훨씬 느리다
+
+- 2026-03-12 21:19 KST 기준 `/mnt/nas/workspace/6.Company X`에서 대표 파일 4개와 임의 표본 20개, 총 `24개` 파일 `48,437,603B`를 대상으로 비교했다.
+- 같은 파일 집합에서 `stat(파일 크기 + 수정시각)` 평균은 `0.927ms`였다.
+- 같은 파일 집합에서 `sha256` 평균은 `617.713ms`였다.
+- 즉 이 표본에서는 해시 계산이 `수정시각 + 파일 크기` 조회보다 약 `666.4배` 느렸다.
+- 대표 파일별로도 `Thumbs.db 75.6배`, 엑셀 `149.5배`, JPG `286.8배`, 20MB PDF `518.8배`로 모두 해시 쪽이 현저히 느렸다.
+- 따라서 현재 운영 질문이 `변경 여부 판정 속도`라면, 해시는 기본 증분 기준보다 표본 검증용으로 두는 것이 맞다.
+
+2026-03-12 21:19 KST 실측값:
+- 전체 표본 `24개`, `48,437,603B`
+- `stat` 평균: `0.927ms`
+- `sha256` 평균: `617.713ms`
+- 비율: `sha256 / stat = 666.4배`
+- `Thumbs.db` `12,288B`: `stat 0.015ms`, `sha256 1.137ms`, `75.6배`
+- 엑셀 `151,832B`: `stat 0.018ms`, `sha256 2.750ms`, `149.5배`
+- JPG `457,889B`: `stat 0.022ms`, `sha256 6.202ms`, `286.8배`
+- PDF `20,147,273B`: `stat 0.351ms`, `sha256 181.927ms`, `518.8배`
+
+### 8. 내부 NAS DSM API 로그인은 가능하지만, 알림/webhook 제어 API는 현재 노출되지 않았다
+
+- 2026-03-12 21:49 KST 기준 내부 NAS `192.168.0.101:5001`은 DSM HTTPS로 응답했다.
+- 같은 시각 내부 NAS 계정으로 DSM API 로그인도 성공했다.
+- 다만 API 목록 조회 기준 `SYNO.Core.Notification`, `SYNO.Core.Notification.Advanced`는 현재 NAS에서 노출되지 않았다.
+- 즉 `내부 NAS 관리자 계정으로 DSM API 로그인 가능`과 `파일 변경 webhook/API 제어 가능`은 같은 뜻이 아니다.
+- 현재 확인 범위에서는 내부 NAS도 파일 접근 API(`SYNO.FileStation.List`)는 가능하지만, 알림/webhook 설정을 API로 제어할 직접 경로는 확인되지 않았다.
+
+2026-03-12 21:49 KST 실측값:
+- API 정보 조회: `SYNO.API.Auth`, `SYNO.Core.Desktop.Initdata`, `SYNO.Core.User`, `SYNO.FileStation.List` 노출 확인
+- DSM API 로그인: `auth.cgi` 경유 `success=true`
+- 파일 공유 조회: `docker`, `home`, `homes` 확인
+- 알림 관련 API: `SYNO.Core.Notification*` 미노출
+
+### 9. 전체 루트 1분 제한 실측 기준 현재 전수 조회는 약 23분대로 추정된다
+
+- 2026-03-12 22:15 KST 기준 전체 루트 `/6.Company X`를 대상으로 `60초` 제한 실행을 했다.
+- 이 실행은 `SIGTERM`으로 종료됐고, 그 시점 summary 기준 `directories_seen=436`, `files_seen=2276`, `skipped=2275`, `failed=1`이었다.
+- 기존 전체 완주 기록의 총량 `directories_seen=10549`, `files_seen=52833`을 기준으로 단순 비례 추정하면 현재 전체 전수 조회 시간은 약 `23.4분`이다.
+- 이 값은 엄밀한 완료 실측이 아니라 `1분 표본 기반 예측`이지만, 현재 구조에서 `10분 이내 전체 전수 조회`를 기본 가정으로 두기 어렵다는 근거로는 충분하다.
+
+2026-03-12 22:15~22:16 KST 실측값:
+- 제한 시간: `60초`
+- `directories_seen=436`
+- `files_seen=2276`
+- `skipped=2275`
+- `downloaded=0`
+- `failed=1`
+- `termination_signal=SIGTERM`
+- 예상 전체 시간: `약 23.2~23.4분`
+
+## Interpretation
+
+### 1. 이 아이디어의 핵심 `why`는 구조 성립이 아니라 최신성 목표 정의다
+
+- 기본 동기화 구조는 이미 검증됐기 때문에, 실시간 아이디어의 초점은 `무엇을 만들 수 있나`가 아니라 `왜 더 빠른 반영이 필요한가`다.
+- 즉 다음 단계에서 먼저 닫아야 할 질문은 도구 선택보다 `허용 가능한 반영 지연`이다.
+
+### 2. 현재 근거로 가장 보수적인 해석은 `짧은 주기 pull`이 1차 후보라는 것이다
+
+- 현재 검증된 외부 접근이 DSM API pull 방식이고, 이벤트 수신 경로는 확인되지 않았다.
+- 따라서 지금 근거만 놓고 보면 `외부 변화 감지 -> 즉시 push`보다 `짧은 주기 재조회 -> 증분 동기화`가 더 직접적인 운영 후보다.
+- 이것은 권장안 확정이 아니라, 현재 검증 범위에 더 가까운 해석이다.
+- 다만 2026-03-12 실측 기준 전체 트리 `dry-run`이 `3분 45초`를 넘어도 끝나지 않았으므로, 현재 구조 그대로는 `1분 미만` 같은 촘촘한 polling은 비현실적일 가능성이 높다.
+- 반대로 단일 목록 조회가 `0.06~0.08초`, 20MB PDF 1건 다운로드가 `0.73초`였으므로, 범위를 더 좁히거나 상위 폴더를 분할하면 `짧은 주기 후보`를 다시 따져볼 여지는 있다.
+- Search API는 작은 폴더에서는 매우 빠르지만, 루트 전체 재귀 검색에서는 실제 존재 파일도 놓쳤으므로 현재 단계에서 전체 스캔 대체재로 가정하면 안 된다.
+- 따라서 지금 가장 보수적인 운영 해석은 `전체 루트는 기존 pull/scan`, `변화가 잦은 일부 상위 폴더만 Search API 추가 검토`다.
+- 같은 맥락에서 증분 기준도 해시보다 `수정시각 + 파일 크기`가 훨씬 빠르므로, 짧은 주기 운영에서는 해시를 기본 판정 기준으로 올리지 않는 것이 맞다.
+- 내부 NAS도 현재 확인 기준으로는 `파일 변경 webhook`을 API로 바로 붙일 근거가 없으므로, 실시간 문제를 webhook 전제로 풀면 안 된다.
+- 그리고 현재 1분 제한 실측 기준 전체 루트 전수 조회는 약 `23분대`로 추정되므로, 전체 루트 기준 `10분 주기`는 안전한 기본안이 아니다.
+
+### 3. 실시간성 수준을 정하지 않으면 `plans`가 과도하게 넓어진다
+
+- `1분 이내`, `10분 이내`, `업무시간대만 5분 주기`, `야간 1회`는 모두 다른 운영안이다.
+- 최신성 목표가 없으면 polling 주기, 실패 복구, 동시 실행 방지, 삭제 정책, 경보 기준이 함께 흔들린다.
+- 따라서 이 리서치의 결론은 `실시간 구현`이 아니라 `실시간 요구 수준을 먼저 고정해야 한다`는 데 있다.
+
+## Unresolved
+
+1. 최신성 목표
+- 내부 NAS 반영 지연을 몇 분 이내로 요구하는지 아직 미확정
+
+2. 외부 변화 감지 방식
+- DSM API 폴링 외에 webhook 또는 이벤트 기반 경로가 실제로 가능한지 미검증
+- DSM Search API를 루트 전체 증분 검색에 신뢰할 수 있는지 미확정
+- 내부 NAS DSM에서 알림/webhook API를 별도 활성화하거나 제어할 수 있는지 미확정
+
+3. 운영 비용
+- 짧은 주기 재조회 시 DSM 세션, API 호출량, 장시간 중복 스캔 비용이 어느 정도인지 미확정
+- 전체 해시 재계산 비용을 운영 주기에 포함할 수 있는지 미확정
+
+4. 변경 유형별 정책
+- 삭제, 이동, 부분 업로드, 파일 교체가 짧은 주기 동기화에서 어떻게 보일지 미확정
+
+5. 실행 방식
+- cron 기반 짧은 주기 실행, 상주 프로세스, 외부 이벤트 트리거 중 무엇이 맞는지 미확정
+
+## 현재 결론
+
+- `외부 NAS -> 내부 NAS` 동기화 자체는 이미 운영 가능 수준으로 검증됐으므로, 실시간 아이디어의 쟁점은 `가능성`이 아니라 `필요한 최신성 수준`이다.
+- 현재 직접 검증된 경로는 DSM API 기반 pull이므로, 지금 사실 범위에서 말할 수 있는 가장 강한 결론은 `짧은 주기 증분 동기화 후보를 검토할 수 있다`까지다.
+- 이벤트 기반 실시간 동기화는 아직 직접 검증되지 않았고, 전체 루트 전수 조회도 현재 예측상 `23분대`이므로, 다음 단계는 `10분`이 아니라 `30분급 보수 주기`를 기본안으로 두는 `plans` 문서가 맞다.

journey/worklog/260312_companyx_sync_30분주기_cron적용_및_예측검증.md

@@ -0,0 +1,37 @@
+---
+tags: [infra, nas, companyx, sync, realtime, worklog]
+---
+
+# 260312 Company X 30분주기 cron 적용 및 예측 검증
+
+## 관련 문서
+- [외부 NAS -> 내부 NAS 컴퍼니엑스 실시간동기화 리서치](../research/260312_external_nas_companyx_실시간동기화_리서치.md)
+- [외부 NAS -> 내부 NAS 컴퍼니엑스 실시간동기화 계획](../plans/260312_external_nas_companyx_실시간동기화_계획.md)
+- [외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 운영계획](../plans/260311_external_nas_companyx_sync_운영계획.md)
+
+## 작업
+
+- `/home/admin/infra/scripts/bin/companyx_external_nas_sync_cron.sh`를 추가해 `flock` 기반 중복 실행 방지와 실행 로그 기록을 묶은 cron 래퍼를 만들었다.
+- 사용자 crontab에 `*/30 * * * * /home/admin/infra/scripts/bin/companyx_external_nas_sync_cron.sh` 엔트리를 적용했다.
+- 대표 폴더 기준 수동 실행 검증과, 전체 루트 `60초` 제한 실행으로 현재 전수 조회 속도를 다시 측정했다.
+
+## 검증
+
+- 대표 폴더 수동 실행:
+  - 대상: `/6.Company X/7. 사진/220308_X코스_5기 발표 사진`
+  - 결과: `downloaded=20`, `failed=0`, `files_seen=20`
+  - 산출물:
+    - `/mnt/hdd/logs/companyx/companyx_external_nas_sync_cron.log`
+    - `/mnt/nas/workspace/.sync-logs-cron-test/companyx_sync_state.json`
+    - `/mnt/nas/workspace/.sync-logs-cron-test/companyx_sync_summary_20260312_221114.json`
+- 중복 실행 방지:
+  - 전체 루트 실행 중 같은 래퍼를 다시 호출했을 때 로그에 `skip: previous sync still running`이 남았다.
+- 전체 루트 `60초` 제한 실측:
+  - 시작: `2026-03-12 22:15:41 KST`
+  - 종료: `2026-03-12 22:16:41 KST`
+  - 결과: `directories_seen=436`, `files_seen=2276`, `skipped=2275`, `failed=1`, `termination_signal=SIGTERM`
+  - 기존 완주 총량(`directories_seen=10549`, `files_seen=52833`) 대비 단순 비례 예상 시간: 약 `23.4분`
+
+## 한 줄 결론
+
+- Company X 전체 루트 기준 기본 주기는 `10분`보다 `30분`이 안전하다는 근거가 확보됐고, cron 래퍼와 중복 실행 방지는 실제로 적용 및 검증됐다.