[feedback/feature] Tenant 문서 수집과 Template Registry 구축

[hywznn]

선행 계약

• [feedback/spec] 범용 사업장 문서·Excel 처리 계약 정의 knowledge#55
• [feedback/feature] 범용 문서·Excel 분석과 필드 정규화 ai#55

현재 한계

stored_file은 원본 저장 메타데이터를 보유하지만 문서 역할·분류·추출 상태·Template 버전·필드 근거를 표현하기 어렵고 scan_status도 현재 제한적입니다. 범용 입력을 위해서는 업로드와 AI 분석을 분리한 비동기 수집 수명주기가 필요합니다.

목표

원본 파일을 Tenant 단위로 안전하게 저장하고, 분석 Job·문서 분류·추출 후보·HR 검수·회사 전용 Template을 관리하는 Server 계약을 구현합니다.

작업 범위

• 업로드 시 확장자와 실제 MIME 불일치 검증
• 원본 checksum 기반 멱등 업로드와 중복 처리 방지
• document_role, document_type, processing_status, parser_version 저장
• 비동기 분석 Job 생성·재시도·실패 사유 관리
• 원본값·정규화값·근거 위치·신뢰도·검수 상태 저장
• Tenant 전용 Template과 Field Mapping 버전 관리
• AI 결과는 Candidate로 저장하고 HR 승인 후에만 Company·Worker 값 갱신
• DOCUMENT_VERIFIED Outbox Event로 관련 Workflow Step 재평가
• 파일 크기·Sheet 수·페이지 수·처리시간 제한
• Tenant 격리·권한·감사 이벤트 테스트

API 후보

POST /api/v1/documents
GET  /api/v1/documents/{id}/processing
POST /api/v1/documents/{id}/classification
PATCH /api/v1/documents/{id}/field-candidates
POST /api/v1/documents/{id}/verify
POST /api/v1/company-templates

완료 기준

• 같은 파일·Idempotency Key 재요청 시 중복 Job·문서 0건
• HR 승인 전 Canonical Company·Worker 값 변경 0건
• 실패·재시도·수동 전환 상태를 API에서 식별 가능
• 다른 Tenant의 파일·Template 접근 차단 테스트 통과
• AI 미응답 시에도 원본 파일과 Job 상태 보존

비범위

• OCR·LLM·문서 Parser 구현
• PDF/HWP 미리보기 품질 개선: [Document][P1] 합성 문서 품질 보완과 PDF·HWP 미리보기 지원 #186

우선순위

후순위 고도화 과제입니다.