[AI Integration][P0] 근로자 이름 정규화 후보 검색·다중 후보 선택 계약

[hywznn]

배경

2026-08-13 E2E QA에서 DB 표시명 응웬반A는 조회됐지만 발화 응우옌 반 A는 TARGET_NOT_FOUND가 발생했습니다.

현재 Server AiSlotResolutionTransaction은 AI의 targetDisplayName을 같은 회사 안에서 findByDisplayName()으로 조회하고 0건이면 실패, 2건 이상이면 TARGET_AMBIGUOUS로 중단합니다. 안전한 중단은 되어 있지만 공백·대소문자·alias·한글 음차 변형 후보 검색과 HR 선택 응답이 없습니다.

AI는 회사별 Worker DB를 모르므로 후보 반환과 자동 확정 여부는 Server가 소유해야 합니다.

목표 흐름

AI PLAN
→ 원문 대상 문자열 + 보수적 정규화 문자열
→ Server 회사 범위 후보 검색
   ├─ 0건: TARGET_NOT_FOUND
   ├─ 1건: ANALYZE 계속
   └─ 2건 이상 또는 음차 alias 후보: 선택 후보 반환, 자동 실행 금지
→ Client에서 HR이 Worker 선택
→ 선택한 workerRef로 ANALYZE 재개

Server 작업

• Worker 검색용 canonical key 정의: Unicode NFC, 공백·구분자·영문 대소문자 정규화
• 표시명 exact match를 최우선으로 유지
• normalized match와 승인된 alias match를 후순위 후보로 추가
• 한글 음차 변형은 임의 fuzzy distance로 자동 확정하지 않고 Knowledge alias/검수 데이터 기반 후보로만 사용
• 모든 검색은 현재 company 범위로 제한
• 후보별 workerRef, 사용자 표시명, match type, 안전한 설명 반환
• 다중 후보·저신뢰 후보에서 Case/Task 자동 생성 차단
• HR 선택 후 선택한 workerRef를 보존해 ANALYZE 재개
• 감사 로그에 입력 문자열·정규화 버전·선택 결과를 저장하되 불필요한 개인정보 원문 로그는 금지
• exact/공백/대소문자/alias/음차/동명이인/타 사업장 격리 계약 테스트

AI·Knowledge·Client 경계

• AI [Auth] 사업장 회원가입·초기 ADMIN 계정 생성 API 구현 #43: 대상 원문/보수적 정규화 및 Intent 설명 가능성 계약
• Knowledge [Docs] OpenAPI 공유용 Swagger HTML 자동 배포 #51: 이름 변형 Gold 후보와 승인 alias 규칙
• Client: 후보 선택 UI와 자동 실행 차단 안내

완료 조건

• 응웬반A, 응웬 반 A가 같은 Worker 후보를 반환
• 승인 데이터가 있다면 응우옌 반 A도 같은 후보군에 포함
• 같은 정규화 키를 가진 Worker가 2명 이상이면 자동 확정하지 않음
• 다른 사업장의 Worker는 후보에 포함되지 않음
• HR 선택 전 Case·Task 생성 및 Workflow 실행이 발생하지 않음

Refs fowoco/ai#43
Refs fowoco/knowledge#51