fix: 맵핑 관련 오류 로그 셋팅

docs/sso_guides/directory-api.md

@@ -0,0 +1,54 @@
+# Directory API Guide
+
+정책 정본은 [Integration Credential 및 Directory API 정책](https://gitea.hmac.kr/baron/baron-sso/wiki/Integration-Credential-%EB%B0%8F-Directory-API-%EC%A0%95%EC%B1%85)이다. 정확한 schema는 Backend OpenAPI를 따른다.
+
+## Credential 준비
+
+1. AdminFront의 API Key 관리에서 Directory 연동 credential을 발급한다.
+2. exact OperationID와 concrete Tenant subtree scope를 선택한다.
+3. 만료일과 발급 사유를 기록한다.
+4. secret은 발급 시 한 번만 안전하게 전달하고 log나 issue에 남기지 않는다.
+5. 교체 후 이전 secret이 무효인지 확인한다.
+
+`/admin/*`에 integration credential을 사용하지 않는다. interactive cookie/token과 한 요청에 혼합하지 않는다.
+
+## 사용자 생성
+
+요청 필드, credential 발급, idempotency, 오류 처리와 검증 절차는 [외부 사용자 계정 생성 상세 가이드](integration-directory-user-create-api-guide.md)를 따른다.
+
+- Endpoint: `POST /api/v1/integrations/directory/users`
+- OperationID: `directory.user.create`
+- credential scope 안의 concrete Tenant를 지정한다.
+- identity, status, 허용 profile field만 보낸다.
+- System Role, raw Keto relation, protected subtree를 payload로 주입하지 않는다.
+- `Idempotency-Key`를 logical create 요청에 결속한다.
+
+timeout 뒤 같은 payload와 idempotency key로 재시도한다. 다른 payload를 같은 key로 보내지 않는다.
+
+## Membership 변경
+
+- Endpoint: `PATCH /api/v1/integrations/directory/users/{userId}/memberships`
+- source와 destination이 credential scope에 포함되는지 확인한다.
+- add와 remove 대상을 exact UUID로 전달한다.
+- representative Tenant 변경이나 계정 삭제를 Membership 변경에 섞지 않는다.
+
+## 오류 처리
+
+- `401`: secret, 만료, revoke 상태 확인
+- `403`: OperationID, exposure, Tenant scope 확인
+- `409`: idempotency fingerprint 또는 Membership invariant 확인
+- `422`: field와 business validation 확인
+- `503`: 원장/readiness 장애이므로 사용자를 없다고 처리하지 않음
+
+오류 뒤 새 사용자를 임의 생성하기 전에 기존 idempotency 결과와 대상 identity를 조회한다.
+
+## 운영 종료
+
+1. acceptance용 임시 사용자와 Membership을 명시적으로 정리한다.
+2. 임시 credential을 revoke한다.
+3. revoked secret으로 호출이 거부되는지 확인한다.
+4. audit에서 OperationID, actor, Tenant, 결과가 기록되고 secret이 없는지 확인한다.
+
+조직 조회 연동은 [Org Context API Guide](org-context-api.md)를 따른다.
+
+한맥가족의 기존 사용자 사번·이름·전화번호 수정은 별도 [내부 인사 사용자 정보 수정 가이드](hr-profile-api.md)를 따릅니다. 일반 Directory 키의 접근 범위는 바뀌지 않습니다.