feat: integrate orgfront and expose internal ids

docs/trouble-shooting/issue-663-hanmac-family-orgfront-sync.md

@@ -0,0 +1,43 @@
+# Issue #663: 한맥가족 사용자 테넌트 동기화 및 직무/직급 표시 정리
+
+## 개요
+
+adminfront 사용자 관리 화면과 orgfront 조직도/조직 선택기 사이의 한맥가족 사용자 표시 기준을 정리했다.
+
+기존에는 사용자 상세 화면에서 `metadata.hanmacFamily` 값에 의존해 한맥가족 탭을 결정했다. 이 방식은 기존 사용자가 이미 한맥가족 테넌트 트리에 소속되어 있어도 metadata 플래그가 없으면 외부 기업 회원으로 분류될 수 있었다.
+
+## 정책 기준
+
+- `docs/organization-chart-policy.md`에 따라 한맥가족 조직은 `COMPANY_GROUP` 아래의 `COMPANY`/`USER_GROUP` 테넌트 계층으로 판단한다.
+- 한맥가족 사용자의 직무/직급은 단일 사용자 필드보다 소속별 `additionalAppointments`를 우선한다.
+- orgfront 표시명은 직무가 있으면 `이름(직무) 직급` 형태를 사용한다.
+
+## 구현 요약
+
+- adminfront
+  - 한맥가족 root tenant 및 subtree 판정 유틸을 추가했다.
+  - 기존 사용자의 `tenant`, `joinedTenants`, `companyCode`, `tenantSlug`를 기준으로 한맥가족 여부를 계산한다.
+  - 사용자 상세 초기화 시 한맥가족 subtree 소속이면 `metadata.hanmacFamily`가 없어도 한맥가족 탭을 표시한다.
+  - 한맥가족 저장 시 기존 단일 `position`/`jobTitle` payload를 비우고 `additionalAppointments`를 사용한다.
+- orgfront
+  - 사용자 표시명 공통 유틸을 추가했다.
+  - 조직도와 조직 선택기 모두 동일한 표시명 로직을 사용한다.
+  - `metadata.additionalAppointments`에 현재 테넌트와 매칭되는 직무/직급이 있으면 이를 우선 사용한다.
+
+## 검증
+
+- RED 확인
+  - `adminfront`: 한맥가족 subtree 사용자 판정 유틸 부재로 unit test 실패 확인.
+  - `orgfront`: 조직도/조직 선택기에서 `이름(직무) 직급` 표시가 없어 Playwright test 실패 확인.
+- GREEN 확인
+  - `adminfront`: `npm run test:unit -- src/features/users/orgChartPicker.test.ts`
+  - `adminfront`: `npm run test:unit`
+  - `adminfront`: `npm run build`
+  - `orgfront`: `npm run lint`
+  - `orgfront`: `npm run build`
+  - `orgfront`: `npx playwright test tests/orgchart-picker.spec.ts tests/orgchart-vector-render.spec.ts --project=chromium`
+
+## 남은 정책/운영 메모
+
+- 이슈는 `한맥가족사 조직도 반영` 마일스톤에 연결했다.
+- 해당 마일스톤은 Due Date가 비어 있다. 목표 Due Date를 정해 마일스톤에 반영하는 것이 좋다.