L2 참조정보 공급 규약 (REFERENCE DATA SUPPLY)

항목	내용
상태	규약(신규) — 첫 준수 도메인은 프로세스(ProcessCenter)
범위	도메인이 소유한 2차 기준정보(L2 참조정보) 를 다른 시스템이 참조할 수 있게 공급하는 공통 규칙
전제	L1 최상단 기준정보(조직도·임직원·부서코드)의 정본은 PortalConsole 디렉터리다. L2 는 그 위에 얹힌다
관련	`ADMIN_MENU_CONVENTION.md`(중앙 공급 규약의 선례), `MODULAR_PORTAL_INSTALLATION.md`(pull-and-cache), `ProcessCenter/docs/PROCESS_REFERENCE_CONTRACT.md`(첫 준수 도메인)

1. 왜 규약인가

"이런 류의 운영 기준정보가 더 생긴다"는 전제가 이미 사실로 확인된다. 같은 성격의 데이터가 플랫폼 안에 여럿 흩어져 있다.

데이터	현재 위치	계층
조직도 · 임직원 · 부서코드	PortalConsole 디렉터리	L1 최상단
프로세스(노드 · RACI · 시스템 매핑)	ProcessCenter	L2 — L1 을 인용
용어사전(glossary)	PortalConsole	L2
온톨로지 관계	PortalConsole	L2
애플리케이션 유형	PortalConsole	L2
부서장 역할 코드	PortalConsole(`shared/departmentHeadRole.ts`)	L2

도메인마다 제각각 공급하면 소비자는 도메인 수만큼 다른 계약을 배우게 된다. 그래서 한 번 정한 규칙을 모든 L2 도메인이 따른다. 반대로 "L2 는 모두 한 곳에 모은다"도 아니다 — 소유는 도메인에 두고, 공급 방식만 통일한다.

2. 기준정보 계층과 인용 규칙

계층	정의	정본
L1 최상단 기준정보	조직도 · 임직원 · 부서코드	PortalConsole 디렉터리
L2 2차 기준정보(참조정보)	L1 을 활용해 도메인이 만든 운영 기준정보. 도메인 안에서는 운영기준이고, 밖에서는 참조 기준	각 도메인 서비스(예: 프로세스 = ProcessCenter)

인용 규칙 (필수)

L2 는 L1 식별자를 인용한다 — 재정의하지 않는다(부서는 부서코드, 사람은 디렉터리 사용자 식별자).
L2 끼리 참조할 때도 상대의 표준 식별자를 인용한다(예: 프로세스 노드 → 시스템 코드).
값(이름·라벨)을 복사해 보관하지 않는다. 표시가 필요하면 조회 시점에 해석한다 — 이름이 바뀌면 복사본이 어긋난다.
L1 이 없는 상태에서 L2 를 만들지 않는다. L1 이 바뀌면 L2 의 참조가 먼저 정합해져야 한다.

3. 공급 규약 — L2 도메인이 지켜야 하는 5요소

3.1 안정 표준 식별자

식별자는 업무 코드 기반이다. 내부 대리 키(auto increment id)를 외부에 내보내지 않는다.
식별자는 유일성이 DB 제약으로 보장되어야 한다(코드에 unique 제약이 없으면 "표준 식별자"가 아니다).
계층 구조는 부모의 표준 식별자로 표현한다(대리 키 경로 배열 금지).

3.2 읽기 전용 서버 간 계약

공급은 읽기 전용 REST 다. 참조 대상 도메인이 자기 데이터를 남이 만들게 하지 않는다.
퍼블릭 API 가 아니다. 소비자는 발급받은 자격증명(서비스 키)으로 서버 간 호출만 한다. 키는 브라우저에 내려가지 않는다.
소비자별 자격증명 + 스코프로 권한을 좁힌다(예: read 만).
공급 도메인은 호출자의 사용자 컨텍스트(디렉터리 사용자 식별자)를 받아 원본 접근정책을 최종 적용한다 — 화면 숨김을 권한으로 대신하지 않는다.

3.3 버전 · 변경 피드

응답에 스냅샷 식별자와 버전을 담는다(소비자가 캐시 신선도를 판단할 수 있어야 한다).
변경 피드를 제공한다(changedSince 같은 증분 조회). 전체 재수신만 있으면 소비자는 매번 전량을 받아야 한다.
게시/승인 거버넌스가 있는 도메인은 게시본 기준으로 공급한다(작성 중·검토 중 값은 내보내지 않는다).

3.4 수명주기와 승계

상태를 계약에 명시한다(예: ACTIVE/INACTIVE/RETIRED).
폐기·병합 시 승계(successor) 를 계약으로 표현한다 — 참조가 끊기면 소비자 매핑이 고아가 된다.
소비자가 "없어진 참조"를 만났을 때의 규칙(승계로 이어받기 / 참조 무효화)을 문서에 적는다.

3.5 발견 · 온보딩 (제어평면)

새 소비자는 PortalConsole 카탈로그에서 능력(capability)을 발견하고, 키 발급·스코프 승인을 받아 붙는다.
즉 온보딩 비용은 "계약 학습 + 키 발급"이어야 하며, 소비자별 코드 수정이나 공급 도메인 배포를 요구하지 않는다.
소비자 목록과 참조 관계(어느 시스템이 어느 대상을 참조하는가)는 추적 가능해야 한다 — 보존기간은 사내 정책을 따른다.

4. 소비자 규칙

참조는 인용만 한다. L2 값을 자기 DB에 복제해 정본처럼 쓰지 않는다(캐시는 캐시일 뿐이다).
L1 과의 교차 조회는 안정 식별자로 조인한다(예: 프로세스의 담당자 식별자 ↔ 디렉터리 사용자).
공급 도메인 장애 시 마지막 정상 캐시 → 로컬 시드 순으로 내려간다. 참조 실패로 자기 화면이 죽지 않게 한다(ADMIN_MENU_CONVENTION.md §4 의 폴백 규칙과 같다).
캐시 TTL·갱신 시점을 문서에 남긴다(소비자마다 다르면 장애 때 원인이 흩어진다).
게시본만 참조한다. 드래프트 상태 값을 기준으로 업무 판단(승인·매핑 확정)을 하지 않는다.

5. 적합성 체크리스트 (새 L2 도메인 온보딩)

#	확인
1	L1 식별자를 인용하는가(재정의·복사 없음)
2	표준 식별자가 업무 코드 기반이고 유일성 제약이 있는가
3	읽기 전용 + 서버 간 자격증명(퍼블릭 아님)인가
4	스코프로 권한이 좁혀지는가
5	스냅샷/버전 + 변경 피드가 있는가
6	게시본 기준으로만 내보내는가
7	수명주기·승계 규칙이 계약에 있는가
8	PortalConsole 카탈로그로 온보딩되는가
9	사용자 단위 접근정책을 공급 도메인이 최종 적용하는가
10	소비자 캐시·폴백 규칙이 문서화되어 있는가

6. 적용

도메인	상태
프로세스(ProcessCenter)	첫 준수 도메인 — 계약 v2 설계·확정(2026-09-20): `ProcessCenter/docs/PROCESS_REFERENCE_CONTRACT.md`
용어사전 · 온톨로지 · 애플리케이션 유형 · 부서장 역할	기존 L2 후보 — 규약 적합성 점검은 후속(이관 여부는 각 소유 판단)

7. 확정된 결정 (2026-09-20)

#	항목	확정
1	자격증명 발급 주체	목표는 제어평면(PortalControlCenter) 카탈로그 연계. 첫 준수 도메인은 공급 도메인이 소비자별 키를 자체 관리로 시작하고, 카탈로그 연계는 후속(키 목록·스코프는 옮길 수 있게 데이터로 관리)
2	표준 식별자 유일성	전역 유일을 기본으로 한다. DB unique 제약으로 보장하며, 이미 제약이 있는 도메인은 재작업하지 않는다(제약 유무는 선언·마이그레이션·적용 DB 세 곳을 모두 확인해 판단한다). 분류 축(taxonomy)은 속성이지 식별의 필수 요소가 아니다
3	코드 변경	게시·확정 거버넌스가 있는 도메인은 확정 후 표준 식별자 변경을 서버가 거부한다. 불가피하면 새 식별자 + 승계 연결
4	승계	승계 필드는 먼저 계약에 두고, 값은 병합·폐기 기능을 만들 때 채운다. 소비자는 승계 추종/무효 표시 규칙을 따른다
5	참조 추적	구조화 요약만 기록(원문·비밀 없음). 보존 기간은 사내 정책 대기 — 임의 값을 코드에 넣지 않는다
6	부속 목록 공급	노드가 코드로 참조하는 부속 기준정보(예: 시스템 목록) 도 같은 규약으로 함께 공급한다 — 코드만 주고 이름을 못 찾게 두지 않는다

남은 외부 의존은 두 가지다.

감사·추적 보존 기간 — 사내 정책 확정 전 값 없음.
L1 표준 표기 확정 — 부서코드·임직원 식별자의 표준 표기는 디렉터리 담당과 협의. 그 전까지 L2 는 기존 L1 키를 그대로 인용만 한다(새 표기를 만들어 쓰지 않는다).