상태 머신 | Notion

사규 상태 머신.drawio.png

1. 상태 다이어그램용 상세 설명 표

(UPLOADED → PREPROCESSED → REVIEWED_OK/FAIL → PUBLISHED + 실패 상태까지)

1-1. 상태별 의미·전이 조건 정리

상태 코드	상태 의미	진입 조건	다음 상태로 넘어가는 조건	챗봇/RAG에서의 취급	비고/주의점
`UPLOADED`	원본 사규/정책 문서만 올라온 초기 상태	시스템 관리자가 관리자 UI에서 사규/정책 파일(PDF/HWP 등)을 업로드 했을 때	전처리 워커가 잡을 가져가서 전처리를 시작하면 `PREPROCESSED` 또는 `PREPROCESS_FAILED`로 전이	이 상태의 문서는 검색 완전 제외, 챗봇/RAG에서 절대 사용 안 함	파일 메타데이터(제목, 도메인, 버전, 업로더, 업로드 시간)까지만 저장된 상태
`PREPROCESSED`	1차 PII 마스킹 + 텍스트 추출 + 청킹까지 끝난 전처리 완료 상태	전처리 엔진이 파일을 성공적으로 처리했을 때	콘텐츠 검토자가 전처리 결과 화면에서 검토 후OK → `REVIEWED_OK` / 문제 있음 → `REVIEWED_FAIL`	여전히 검색에서 제외, 단지 “전처리 결과를 검토할 수 있는 상태”일 뿐	자동 QA(구조 체크, 대표 질문 QA 등) 결과도 이 상태에서 함께 저장/표시
`PREPROCESS_FAILED`	전처리 엔진에서 텍스트 추출·마스킹·청킹 중 오류가 발생한 실패 상태	전처리 도중 포맷 오류, 인코딩 문제, 텍스트 0건 추출 등 오류 발생	관리자가 원본 문서를 수정하거나 포맷을 바꿔서 다시 올리면 새로운 `UPLOADED` 상태 레코드가 생성	검색 대상에서 완전히 제외.챗봇은 이 문서를 존재하지 않는 것처럼 취급	실패 사유(에러 코드·메시지)를 반드시 로그/DB에 남겨서 재현 및 전처리 로직 개선에 활용
`REVIEWED_OK`	전처리 결과를 사람이 확인했고 내용·구조에 문제가 없다고 승인한 상태	콘텐츠 검토자가 관리자/검토자 화면에서 전처리 결과를 확인 후 “전처리 이상 없음” 클릭	관리자가 게시 버튼을 눌러 `PUBLISHED`로 변경할 때	기본적으로 아직 검색 제외.PUBLISHED로 넘어가야 RAG에 포함	대표 질문 QA 점수는 낮지만 사람이 보기에도 문제 없다면 OK 가능(사람 검토가 최종 권한)
`REVIEWED_FAIL`	전처리 결과에 문제(누락, 깨짐, 구조 붕괴 등)가 있어 반려된 상태	콘텐츠 검토자가 전처리 결과를 본 뒤 “문제 있음” 선택 + 코멘트 입력	원본 수정/전처리 로직 수정 후, 관리자가 문서를 새로 올리면 새 레코드가 `UPLOADED`로 생성됨	검색에서 완전 제외.이 상태 문서는 RAG 인덱싱에서 반드시 제거	“어떤 문제가 있었는지”에 대한 검토자 코멘트를 남겨서 전처리 로직 개선에 피드백으로 활용
`PUBLISHED`	사규가 검토를 통과했고, 챗봇/RAG에서 실제로 사용하는 게시 상태	`REVIEWED_OK` 상태 문서에 대해 관리자가 “게시” 처리	새 버전이 올라와 PUBLISHED가 교체될 때(이전 버전은 DEPRECATED 또는 is_active=false로 전환하는 식으로 처리)	RAG 검색 대상.챗봇은 항상 이 상태의 문서(도메인별 최신 버전)만 근거로 사용	PUBLISHED 여부 + 버전/시행일 기준으로 “현재 유효한 사규”만 노출하도록 필터링

“사규 문서는 이렇게 다섯 가지 상태를 거쳐서야 챗봇에 들어가게 설계했습니다. 그냥 올리면 바로 쓰는 게 아니라, UPLOADED, PREPROCESSED, REVIEWED_OK, PUBLISHED처럼 단계별로 어디까지 진행됐는지 관리합니다.”
“중요한 규칙은 간단합니다. PUBLISHED 상태가 아니면 어떤 경우에도 RAG 검색 대상이 되지 않고, 직원에게 답변할 때는 항상 PUBLISHED이면서 최신 버전인 문서만 근거로 사용하도록 했습니다.”
“전처리 실패나 검토 반려처럼 문제가 생긴 문서는 PREPROCESS_FAILED나 REVIEWED_FAIL 상태에 남기고, 로그는 남기되 검색에서는 완전히 제외합니다.”