# WORKS 인사 연동 가이드

## 적용 범위

특수 인사 lifecycle과 WORKS 계정 자동화는 정책에 허용된 `hanmac-family` subtree에 적용된다. 인사 상태의 기준은 Baron이며 WORKS는 예약과 상태에 따라 생성·갱신·정지·삭제되는 외부 계정이다.

## 상태

| 상태 | WORKS 처리 | Baron 처리 |
| --- | --- | --- |
| `active` | 유지·갱신 | 활성 |
| `temporary_leave` | 유지·갱신 | 단기휴무 |
| `suspended` | 정지 | 정지 |
| `preboarding` | 입사 예약 시각부터 생성 | 먼저 생성, 처리 후 활성 |
| `baron_guest` | 삭제 | 유지 |
| `offboarding` | 퇴사 예약 시각부터 삭제 | 처리 후 보관 |
| `extended_leave` | 삭제, 복귀 예약 시 재생성 | 복귀 후 활성 |
| `worksmobile_disabled` | 삭제 | 유지 |
| `archived` | 삭제 | 보관 |

정확한 허용 상태와 예약 시각은 원격 Wiki 정책을 따른다.

`active` 사용자의 WORKS 계정이 현재 없더라도 화면 조회만으로 상태를 바꾸지 않는다. 관리자가 생성 이력, 전체 Directory 조회 결과와 진행 중 작업을 확인한 뒤 `Baron WORKS 미사용으로 교정`을 실행한다. 생성 이력 확인 불가와 현재 Directory 조회 불가는 서로 다른 결과이며, 후자는 보정을 막는다. 상세 기준은 [WORKS 계정 이력·현재 부재 보정 정책](https://gitea.hmac.kr/baron/baron-sso/wiki/WORKS-Account-Status-Reconciliation.-)을 따른다.

## 사용자 추가와 상태 변경

1. AdminFront 사용자 화면에서 대상 Tenant를 선택한다.
2. 즉시 사용자는 활성, 예약 입사자는 입사대기와 입사일을 지정한다.
3. 상태 변경에 필요한 날짜를 입력한다.
4. 저장 후 Baron 상태와 예약 작업이 표시되는지 확인한다.
5. WORKS 처리 실패 시 같은 작업을 반복 생성하지 않고 Queue/operation 상태를 확인한다.

## WORKS에서 정보 가져오기

1. Worksmobile 비교 화면을 연다.
2. 대상 사용자의 `Works정보 가져오기`를 선택한다.
3. 차이가 있는 허용 field만 선택한다.
4. stale comparison이 거부되면 새로고침 후 다시 비교한다.
5. WORKS 값이 비어 있다는 이유로 Baron 값을 자동 삭제하지 않는다.

수동 Works→Baron과 자동 Baron→Works 방향을 구분한다. 양방향 field는 충돌 정책을 확인한다.

## 식별자와 값 변환

- 사용자 연결은 canonical UUID와 검증된 WORKS external key를 사용한다.
- email local-part uniqueness는 적용 Tenant subtree 정책을 따른다.
- phone은 WORKS outbound 형식으로 정규화하되 Baron 원본을 임의 변경하지 않는다.
- organization, grade, position, employee number의 source 방향을 field별로 유지한다.

## 권한과 환경

- 메뉴 조회, WORKS 관리, 대상 Tenant 사용자 편집 권한을 각각 검사한다.
- staging에서는 조회·비교를 검증할 수 있어도 실제 WORKS write가 차단될 수 있다.
- production relay는 idempotency, retry, 예약 기록을 사용한다.
- rate limit은 bounded retry와 backoff를 사용하며 무제한 병렬 호출하지 않는다.

테넌트 변경 후 반영 확인과 Directory·SCIM 연결 점검은 [WORKS 연동 Runbook](../runbooks/worksmobile.md)을 따른다. orphan 등 공통 복구는 [Data Integrity Runbook](../runbooks/data-integrity.md)을 따른다. 정책 정본은 [Gitea Wiki](https://gitea.hmac.kr/baron/baron-sso/wiki)다.