# 내부 인사 사용자 정보 수정

이 가이드는 외부 인사 도구에서 기존 SSO 사용자의 사번·이름·전화번호를 수정하는 절차입니다. 사용자 연결에는 SSO의 `userId`를 사용합니다. 사번이나 이메일을 고유 사용자 키로 사용하지 않습니다.

정확한 요청·응답은 [OpenAPI](../../backend/docs/openapi.yaml)를 따릅니다. 구현과 검증 기록은 [#2506](https://gitea.hmac.kr/baron/baron-sso/issues/2506)에 있습니다. 기존 [Directory API](directory-api.md)의 외부 사용자 생성·소속 변경과 별도 경로입니다.

## 연결 준비

1. AdminFront의 `API 키 관리`에서 `내부 인사 연동`을 선택합니다.
2. 한맥가족의 대상 조직을 선택합니다.
3. `내부 인사 사용자 조회` 키와 `내부 인사 사용자 수정` 키를 각각 발급합니다.
4. 도구에 키를 별도로 보관하고 브라우저 코드·로그·CSV에 넣지 않습니다.
5. 외부 인사 사용자와 SSO `userId`의 연결을 확인합니다.

조회 키는 `hr.user.profile.read`, 수정 키는 `hr.user.profile.update`를 사용합니다. 현재 대표 소속이 키의 조직 범위 안에 있어야 합니다. Stealth와 시스템 관리자 계정은 이 경로에서 처리하지 않습니다. 기존 일반 Directory 키를 대신 사용할 수 없습니다.

전체 대상의 `userId`가 필요하면 기존 [조직 조회 API](org-context-api.md)의 `members[].id`를 사용합니다. 이 조회에는 별도의 `baron.org-context.read` 키와 허용된 조직 범위가 필요합니다. 외부 인사 자료와 연결할 때 여러 사용자가 같은 이름을 쓰거나 사번이 비어 있으면 자동으로 일치시킨 것으로 처리하지 않습니다.

## 조회와 수정

아래 요청의 호스트는 사용 중인 SSO 주소로 지정합니다. `userId`에는 SSO 사용자 UUID를 넣습니다. 먼저 조회 키로 현재 정보를 읽습니다.

```http
GET /api/v1/integrations/hr/users/{userId}/profile
X-Baron-Key-ID: <read-client-id>
X-Baron-Key-Secret: <read-secret>
```

응답의 `revision`은 조회한 사용자 정보의 버전입니다. 이 값을 `expectedRevision`에 넣고 수정 키로 변경을 요청합니다. 사번 앞자리의 0을 보존하려면 JSON 문자열로 전달합니다.

```http
PATCH /api/v1/integrations/hr/users/{userId}/profile
X-Baron-Key-ID: <update-client-id>
X-Baron-Key-Secret: <update-secret>
Idempotency-Key: <unique-source-event-id>
Content-Type: application/json

{
  "expectedRevision": "<revision-from-get>",
  "employeeNumber": "001234"
}
```

필드를 생략하면 기존 값은 유지됩니다. 사번에 `null` 또는 빈 문자열을 보내면 사번을 삭제합니다. 이름은 비어 있지 않은 문자열이며, 전화번호는 `+821012345678`처럼 국가번호를 포함한 E.164 문자열입니다. 이름·전화번호의 `null`과 빈 문자열은 거절됩니다.

이 경로는 `employeeNumber`, `name`, `phone`만 수정합니다. 부서·직급·직책·입퇴사 상태·비밀번호·권한 변경을 같은 요청에 넣지 않습니다. 기존 사번 호환 키는 서버가 함께 맞춥니다.

## 결과 확인과 재시도

수정 응답의 `operationId`와 `statusUrl`을 저장합니다. `200`은 SSO 저장 결과이며 WORKS 반영 완료를 뜻하지 않습니다. `202`이면 저장 결과 확인이 필요하므로 조회 키로 `statusUrl`을 조회합니다.

```http
GET /api/v1/integrations/hr/users/{userId}/operations/{operationId}
X-Baron-Key-ID: <read-client-id>
X-Baron-Key-Secret: <read-secret>
```

응답은 SSO 저장 상태, 저장 후 처리 상태, WORKS 작업 상태를 구분합니다. `worksmobileStatus=verified`는 해당 작업의 원격 검증 완료를 뜻합니다. `pending`과 `processing`은 대기 상태입니다. `failed`와 `not_enqueued`는 원격 반영 완료가 아니므로 원인을 확인합니다. `superseded`는 더 최신 변경으로 교체된 작업이므로 이전 작업의 반복 조회를 끝내고 최신 작업을 확인합니다. 자세한 WORKS 작업 처리는 [WORKS 연동 Runbook](../runbooks/worksmobile.md)을 따릅니다.

| 상태 필드 | 값과 처리 |
| --- | --- |
| `storageStatus` | `committed`는 SSO 저장 확정입니다. `unknown`은 결과 미확정이며 새 작업으로 중복 요청하지 않습니다. `not_committed`는 저장 확정 전 상태입니다. |
| `projectionStatus` | `pending`은 조회용 사본 반영 대기, `applied`는 반영 완료, `failed`는 반영 실패입니다. |
| `postCommitStatus` | `pending`은 후속 처리 대기, `applied`는 처리 완료, `failed`는 재처리 대상, `blocked`는 운영 확인이 필요한 중단 상태입니다. |

도구는 대기 중인 작업의 ID를 보존하고 제한된 간격으로 상태를 조회합니다. 대기 시간이 도구의 제한을 넘으면 작업을 대기 목록에 남깁니다. `unknown`을 실패로 단정하거나 새 키로 같은 변경을 다시 보내지 않습니다.

| 결과 | 도구의 처리 |
| --- | --- |
| 응답을 받지 못함 | 같은 본문과 같은 `Idempotency-Key`로 재시도합니다. |
| `409` revision 충돌 | 현재 정보를 다시 조회하고 변경 내용을 비교한 뒤 새 작업으로 요청합니다. |
| `409` 재시도 내용 충돌 | 기존 작업 키에 다른 본문을 사용했는지 확인합니다. |
| `409` 식별자 충돌 | 다른 계정이 해당 로그인 식별자를 사용하는지 확인합니다. |
| `401` 또는 `403` | 키의 상태·Operation·현재 조직 범위를 확인합니다. |
| `503` | 조회 또는 저장소 장애를 확인하고 기존 작업 결과부터 확인합니다. |

전체 사번 갱신 도구도 사용자마다 조회·수정·결과 확인을 수행합니다. 각 사용자 변경에 별도 작업 키를 사용하고 성공·실패·대기 결과를 따로 남깁니다. 이 API에는 일괄 수정 endpoint가 없습니다.

## 사용자 편집 화면에서 비교

사용자 정보 편집 화면에서 `WORKS 정보 비교`를 선택합니다. 저장된 SSO 정보와 현재 WORKS 값을 비교하며, 다른 항목 아래에 `WORKS: 값`을 표시합니다. 이 버튼은 값을 수정하지 않습니다.

비교 대상은 이름·이메일·전화번호·사번·보조 이메일·대표 소속의 부서·직급·직책·직무입니다. 원격 API가 반환하지 않은 필드는 조회 불가로 표시합니다. 미연결 계정·연동 비대상·조회 실패는 값 불일치와 구분합니다. SSO 보조 전화번호와 계정 상태는 이 필드 비교 대상이 아닙니다.

화면을 수정하면 이전 비교 결과를 숨깁니다. 변경을 저장한 뒤 다시 비교합니다. WORKS 반영은 비동기 처리이므로 저장 직후에는 이전 WORKS 값이 표시될 수 있습니다.