권한과 복구 안내

새 담당자가 안전하게 이어받도록 씁니다

운영 인계서는 코드를 만든 사람이 옆에 없어도 실패 상태를 구분하고 다음 행동을 결정할 수 있게 하는 문서입니다. 성공 명령만 적으면 데이터가 잘못되었을 때 같은 작업을 반복할 수밖에 없습니다. 이번 레슨에서는 새 담당자가 원본을 확인할 권한, 공개 파일을 배포할 권한, 기준을 변경할 승인 경로를 구분합니다. 보고서 정정의 영향과 마지막 정상 결과의 상태까지 함께 설명하는 것이 목표입니다.

인계 대상은 이번 모듈의 quality.run 경로입니다. 예전 run.sh가 남아 있으므로 파일 이름만 보고 아무 경로를 실행하지 않도록 공개 명령을 명시합니다. 절대 개인 경로나 컴퓨터 사용자 이름을 문서에 적는 대신 ZIP 루트에서 실행하는 상대 경로를 안내합니다. 명령, 입력 파일, 정상 결과, 실패 코드와 판단 기준이 한 흐름으로 연결되어야 합니다. 실행 기록을 읽는 담당자와 공개 결과를 소비하는 사람의 필요 정보는 다릅니다.

공개 필드를 허용 목록으로 고릅니다

입력에 이메일이나 인증 토큰이 추가되었다고 가정합니다. 원본 전체를 로그에 출력한 뒤 나중에 지우는 방식은 복사본의 범위를 알기 어렵게 만듭니다. 먼저 공개에 필요한 필드를 고릅니다. 지역·날짜별 비교 보고서는 단위, 유효 행 수, 날짜와 집계값이면 수치를 설명할 수 있습니다. 오류 조사에는 실행 ID, 입력 해시, 단계별 건수와 코드가 필요하지만 개인별 상세 행을 통째로 적을 필요는 없습니다.

필드를 제외하는 denylist는 새 민감 필드가 생길 때 놓칠 수 있습니다. 이번 안내는 필요한 키만 선택하는 allowlist를 사용하여 모르는 새 열이 자동 공개되지 않게 합니다. 다만 필드 이름을 제한했다고 결과가 익명이라는 결론은 낼 수 없습니다. 지역과 날짜가 지나치게 세밀하면 다른 자료와 연결될 가능성을 검토해야 합니다. 현재 학습 자료는 개인별 기록이 없는 합성 표본이며 실제 공개 시에는 집계 단위와 이용 목적을 별도로 판단합니다.

입력 해시는 원본 식별에 유용하지만 비밀값을 가리는 기능은 아닙니다. 추측 가능한 값은 같은 방식으로 해시하여 대조할 수 있습니다. 로그에 토큰을 해시해 남기면 안전하다는 가정도 하지 않습니다. 조사에 필요하지 않은 비밀은 기록하지 않습니다. 공개 보고서의 입력 해시를 노출할 필요도 소비 목적에 따라 결정하고 진단용 기록을 통째로 외부 링크에 올리지 않습니다. 편리한 추적과 접근 범위를 함께 설계합니다.

권한을 행동 단위로 나눕니다

원본 보존 폴더와 품질 감사 파일은 진단 담당자가 읽습니다. report.json은 공개 담당자가 검토하고 배포할 수 있습니다. 정책 한계값을 바꾸는 권한은 분석 책임자의 승인과 연결합니다. 파일을 읽을 수 있다는 사실이 결측 기준을 바꿀 권한까지 뜻하지 않도록 인계서에 역할을 적습니다. 이 실습은 OS 계정이나 실제 파일 권한을 설정하지 않으므로 문서에 적은 권한을 이미 시스템이 강제한다고 주장하지 않습니다.

진단 자료 보존 기간은 재현 필요성과 조직의 삭제 기준을 함께 검토하여 정합니다. 이번 실습에서 임의의 법정 보존 기간을 정하지 않습니다. 대신 보존 목적, 접근 담당, 삭제 승인 담당, 확인 날짜를 인계서 제출 항목으로 둡니다. 실패 원본을 조사 종료 전에 지우면 재현 근거가 없어질 수 있고 필요가 끝난 원본을 계속 복제하면 접근 관리가 어려워집니다. 보존과 삭제도 운영 작업으로 담당자를 지정합니다.

오류 코드별 첫 행동을 정합니다

TRAFFIC_MISSING과 RAIN_MISSING은 입력의 관측 누락이 기준을 넘었다는 뜻입니다. 먼저 해당 입력 해시의 원본과 누락 지역·날짜를 확인하고 공급자의 정정 여부를 검토합니다. 같은 파일을 여러 번 재시도하는 것은 품질을 회복하지 않습니다. 승인된 새 입력을 받은 뒤 다시 실행합니다. 한계값을 낮추거나 높이는 결정은 공개 목적의 근거와 함께 검토하며 단지 작업을 성공 상태로 만들기 위해 바꾸지 않습니다.

DUPLICATE_KEY는 같은 지역·날짜가 반복되었다는 뜻입니다. 반복 값이 같더라도 이번 경로는 배치를 거절하므로 원본의 재전송 문제를 확인합니다. 다른 값이 반복되면 최신 개정본을 확인하고 승인된 한 행을 공급받습니다. NEGATIVE_TRAFFIC은 절대 합계 계약과 어긋납니다. 임의 절대값 변환으로 문제를 숨기지 않습니다. 각 오류는 코드 수정이 필요한지 원본 정정이 필요한지 나누어 판단하고 처리 근거를 남깁니다.

INJECTED는 테스트에서 DB 쓰기 중 실패를 재현한 코드입니다. 실제 배포 자료가 아니라 연습용 장애 주입이라는 사실을 안내합니다. PUBLISH는 저장 커밋 뒤 공개 파일 교체 직전 실패한 연습 경로입니다. 후자는 db_committed가 true일 수 있으므로 이전 보고서가 유지되어도 DB까지 옛 상태라고 말할 수 없습니다. 실패 시점이 다른 두 사례를 함께 설명하면 새 담당자가 모든 실패를 롤백으로 오해하지 않습니다.

재처리와 정정을 구분해서 안내합니다

복구 순서는 마지막 성공 보고서 확보, 실패 시도 확인, 보존 원본 확인, 승인된 입력 제공, 새 경로 실행, 결과 대조입니다. 보고서 파일이 이미 정상이라고 해서 새 배치가 처리되었다고 생각하지 않도록 생성 계보와 실행 상태를 확인합니다. 동일 입력을 재처리하면 실행 ID는 달라지고 원본 해시는 같을 수 있습니다. 실행 횟수와 자료 버전을 혼동하지 말고 수정본 여부는 승인 기록 및 입력 해시로 설명합니다.

정정 입력을 처리한 뒤에는 저장 전체 행과 공개 비교 행을 구분해 확인합니다. 한 지역의 통행량이 100에서 105로 정정되면 전체 저장 합계는 395, 유효 비교 합계는 305가 됩니다. 보고서 숫자 하나를 수동 변경하지 않고 파이프라인에서 다시 만듭니다. 정정 전후 값, 영향 지역·기간, 원인, 새 입력의 해시와 검증 결과를 묶어 전달합니다. 수치를 이미 사용한 사람에게도 수정 범위가 보이도록 안내문을 작성합니다.

보고서 안의 lineage는 그 보고서의 성공 시도에 속합니다. 별도 lineage.json은 가장 최근 실패일 수 있으므로 보고서와 날짜가 다르다고 즉시 파일이 손상되었다고 판단하지 않습니다. 감사 JSON 기록에 실패가 없을 때도 저장 공간 부족으로 감사 쓰기 자체가 실패했을 가능성을 조사합니다. 현재 코드는 DB와 외부 파일을 동시에 원자적으로 갱신하지 않습니다. 인계서에는 이 한계와 DB 확인 후 재처리 경로를 함께 씁니다.

실행 가능 여부와 판단 가능 여부를 검토합니다

제출 문서는 성공 절차뿐 아니라 품질 실패, 적재 롤백, 커밋 후 공개 실패를 각각 다룹니다. 담당자가 확인할 파일과 다음 명령을 단계마다 적고 기대값을 검사 실행으로 확인합니다. 승인 없이 오래된 정정본을 재생하지 않으며 동시 실행을 지원하지 않는 한계를 적습니다. 기능이 없다는 사실을 숨기지 않는 것이 사고 후 임의 대응을 줄입니다. 같은 결과를 얻는 방법과 결과가 맞는지 판단하는 방법을 함께 제공합니다.

체크리스트는 yes 표시만 요구하지 않습니다. 공개 JSON에 허용 목록 밖 필드가 없는지 확인한 근거, 원본 접근 역할, 실패 시 report 해시 유지 검사의 이름, 재실행 성공 기록을 적습니다. 실제 계정을 만들거나 권한을 바꾸지 않은 상태는 미적용으로 표시합니다. 문서 실습의 완료는 위험을 없앴다는 선언이 아니라 담당자가 경계와 근거를 이해할 수 있게 작성하는 것입니다. 운영 적용 여부는 실제 설정 검토와 분리하여 남깁니다.

마지막으로 새 담당자의 입장에서 문서를 읽고 질문 세 가지에 답합니다. 지금 공개된 결과는 어느 입력으로 만들었는가, 새 시도는 어디서 실패했는가, 재시도 전에 누가 무엇을 확인해야 하는가입니다. 답이 실행 파일 이름이나 담당자의 기억에만 있으면 필요한 내용을 보완합니다. 더 읽기의 로깅 장은 구조화된 진단 구현을 확장하는 자료입니다. 여기서는 정보 최소화와 실패 복구 판단을 전달하는 인계 문서를 완성합니다.

payload={'run_id':'demo','status':'failed','error_code':'TRAFFIC_MISSING','email':'learner@example.invalid','token':'sample-only'}
allowed=('run_id','status','error_code')
print({k:payload[k] for k in allowed})

{'run_id': 'demo', 'status': 'failed', 'error_code': 'TRAFFIC_MISSING'}

for committed in [False,True]:
    action='verify DB, retry approved input' if committed else 'verify rollback, correct input'
    print('db_committed='+str(committed),action)

db_committed=False verify rollback, correct input
db_committed=True verify DB, retry approved input

old={'stored':390,'paired':300}
new={'stored':395,'paired':305}
for key in ['stored','paired']:
    print(key,old[key],new[key],'delta',new[key]-old[key])

stored 390 395 delta 5
paired 300 305 delta 5