[Document] Agent 요청 canonical field allowlist Resolver 구현

[hywznn]

한 줄 목표

Agent가 문서 자동화에 필요한 field key를 요청하면 Server가 임의 SQL 없이 Worker·Company·Task의 허용된 업무값만 찾아 구조화해 반환합니다.

이번 결정

• 실제 PII를 ***, OOO로 치환하거나 복원하지 않습니다.
• 법적 실명·표시 이름·여권번호·외국인등록번호·전화번호·이메일·주소·계좌번호는 현재 Resolver에서 반환하지 않습니다.
• Agent/LLM은 DB에 직접 접근하지 않고 canonical field key만 요청합니다.
• Server가 tenant/company 범위와 고정 allowlist를 검증한 뒤 resolved, source, sensitivity, value를 구성합니다.
• 값이 없는 허용 field는 MISSING, 인식된 PII field는 값 없이 FORBIDDEN, 알 수 없는 field는 요청 오류로 처리합니다.

MVP 허용 field

• Worker: nationality_code, preferred_language, work_status, stay_expiry_date, contract_start_date, contract_end_date
• Company: name
• Task: task_type, workflow_id, workflow_catalog_version, due_date, status

구현 범위

• canonical tag → 고정 Resolver key 매핑
• Worker·Company·Task repository 기반 조회
• task-worker-company 관계 검증
• 해석 결과에 source, resolved, sensitivity, status 포함
• 실제 값은 로그·해석 이력 테이블에 저장하지 않고 field key와 결과 상태만 저장
• V9 migration으로 Agent field 해석 메타데이터 구조 추가
• PII field 차단, 알 수 없는 field 거부, 타 사업장 접근 차단 테스트
• AI 팀이 사용할 요청/응답 예시 문서화

실행 흐름

Server → Agent 문서 분석 요청(PII 없음)
Agent → requiredFieldKeys 반환
Server → allowlist Resolver 실행
Server → 허용된 resolved values만 Agent 문서 실행 요청에 포함

완료 조건

• Agent가 요청한 허용 field가 현재 DB 값으로 해석됩니다.
• 실제 PII는 응답·DB 메타데이터·일반 로그에 남지 않습니다.
• Agent가 SQL·DB column명을 임의로 지정할 수 없습니다.
• 같은 requestId+field key는 중복 이력으로 쌓이지 않습니다.
• 전체 테스트와 Flyway validate가 통과합니다.

병합 순서와 관계

• Refs [AI Integration] 데모 Agent 요청에 원본 업무데이터 전달 #61: 실제 PII를 Agent·LLM 요청에서 제외
• Refs [AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현 #8: Server ↔ AI Runtime 계약
• Follow-up [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24: AiRun orchestration에서 이 Resolver를 호출
• V9 사용. V8을 소유한 #57이 먼저 병합된 뒤 이 작업을 병합합니다.
• #57의 document·file 패키지는 수정하지 않습니다.

[hywznn]

범위를 다시 확인한 결과, 별도 canonical Resolver·V9 메타데이터 테이블까지 만드는 것은 현재 MVP에 과한 구현입니다. 이번 단계는 #61에서 Agent/LLM 요청의 실제 PII 필드를 제외하고 *** 치환도 사용하지 않는 계약 검증만 수행합니다. DB schema 변경이 없으므로 V9도 이 작업에서 사용하지 않습니다.