플랫폼 명칭 규칙 (2026-09-13 확정)

이 문서는 저장소·서비스·패키지·환경 식별자의 이름을 정하는 단일 기준이다. 새 서비스를 만들거나 이름을 바꿀 때 먼저 이 문서를 갱신한다.

1. 규칙

1. 소비 포털(내부 사용자가 직접 쓰는 제품) 은 …Center 를 쓴다.
   • 예: ProcessCenter(공정·업무 포털), GuideCenter(가이드 포털).
2. 플랫폼 서비스(포털을 지원하는 공용 백엔드/게이트웨이) 는 제품이 아니라 기능 접미사로 이름 짓는다.
   • …Console 관리·운영 화면, …Platform 표현·공통 UI, …Store 저장소, …Service 처리 서비스, …Gateway 접근 게이트웨이.
   • 예: PortalConsole, UiPlatform, FileStore, RagService, ModelGateway, ExploreGateway.
3. 공통 라이브러리는 portal-foundation(약칭 PF) 하나로 둔다.
4. "Asset" 표현은 파일 원본 저장(FileStore) 과 공통 UI 자산(portal-foundation 패키지) 에 중복 사용하지 않는다. 공통 기능 묶음은 "Asset" 대신 "템플릿" 으로 부른다.

2. 서비스 명칭 매핑 (2026-09-13 적용)

이전 이름	새 이름	저장소 · 로컬 폴더	패키지명	dev compose 서비스 / 컨테이너	개발 포트
Portal Control Center (DirectoryService)	PortalConsole	PortalConsole	portal-console	portal-console / portal-console-dev	3100
UI플랫폼 (UiCenter)	UiPlatform	UiPlatform	ui-platform	ui-platform / ui-platform-dev	3200
AssetStore	FileStore	FileStore	@hohyun94/file-store (+ @hohyun94/file-store-admin-web)	file-store / file-store-dev	3300
RAGCenter	RagService	RagService	(Python — npm 패키지 없음)	(dev 스택 미포함)	—
ProcessCenter	유지 (소비 포털)	ProcessCenter	process-center	process-center / process-center-dev	3000
ExploreGateway · ModelGateway	유지 (플랫폼 게이트웨이)	그대로	explore-gateway · @hohyun94/model-gateway	그대로	3500 · 3400
portal-foundation	유지 (공통 라이브러리)	그대로	portal-foundation-workspace	—	—

GitHub 저장소도 같은 이름으로 변경했다(hohyun94/PortalConsole · UiPlatform · FileStore · RagService). GitHub은 이전 URL을 새 이름으로 리다이렉트하므로 기존 클론·링크는 계속 동작한다.

3. 의도적으로 유지한 식별자 (호환 계층)

이름만 바꾸면 깨지는 데이터·계약·운영 식별자는 유지한다. "옛 이름이 남아 있다"는 리뷰 지적이 나오면 이 표를 근거로 답한다.

유지 식별자	위치	유지 이유	변경 계획
DB 이름·사용자 directory_service · ui_center · file_store	각 서비스 DATABASE_URL, dev 볼륨	데이터·마이그레이션 이력 보존(이름 변경 = 데이터 이전)	필요 시 별도 데이터 이관 릴리스
테이블 접두 file_store_*, DB 볼륨 file-store-dev-data	FileStore	기존 감사·정책 데이터 보존	〃
공개 API 경로 /api/directory/v1/* · /api/file-store/v1/* · RagService /api/v1/*	PortalConsole · FileStore · RagService	외부 소비자(포털·게이트웨이)와 맺은 URL 계약	경로 별칭 1릴리스 후 개편
토큰 audience · 포털 ID ui-center, ui-center-theme, file-store, rag-center, explore-gateway, directory-user	PortalConsole 발급기 · 각 포털 검증기	3자 공유 토큰 계약(발급자·검증자 동시 변경 필요)	동시 배포 릴리스에서 함께 변경
환경변수 접두 DIRECTORY_SERVICE_* · DIRECTORY_* · UI_CENTER_* · FILE_STORE_* · RAG_CENTER_*	이전 배포 환경 문서	2026-09-13에 새 접두로 개편 완료(PORTAL_CONSOLE_* · FILE_STORE_* · UI_PLATFORM_* · RAG_SERVICE_*). 코드·compose·.env는 새 이름만 쓴다	각 서비스 envAliases/env_compat 별칭 제거(1릴리스 후)
배포 서비스명(name: directory-service · ui-center)	PortalConsole · UiPlatform	실제 운영 리소스·도메인. 서비스명만 바꾸면 신규 서비스가 생성될 위험	관리형 클라우드 콘솔에서 서비스명·도메인 함께 변경
코드 심볼·CSS(getUiCenterUrl, uiCenterReadRoute, .ui-center-login, ui-center-login-bg.webp)	PortalConsole·UiPlatform	동작에는 영향 없는 내부 표기, 계약과 얽힌 심볼이 많음	문서·심볼 일괄 치환 배치에서 처리
Python 패키지 ragcenter/ · compose 프로젝트명 ragcenter-offline	RagService	import·이미지 태그·문서 전반에 걸친 이름	전용 배치(테스트 동반)에서 처리
PF 어댑터 패키지(개명 완료)	portal-foundation · ProcessCenter	2026-09-13에 @hohyun94/portal-filestore(디렉터리 packages/filestore-adapter)로 개명하고 PC의 vendor tarball·lockfile·import를 전환했다	신규 버전은 PF에서 재패킹해 PC vendor/ 교체

4. 정비 이력

2026-09-13 (이번 정비)

• GitHub 저장소 4개 rename, 로컬 폴더 rename, git remote URL 갱신.
• ProcessCenter/docker-compose.dev.yml: 서비스 키·컨테이너명·빌드 컨텍스트·볼륨 키·서비스 간 호스트명을 새 이름으로 정비 (FILE_STORE_BASE_URL=http://file-store:8080, UI_PLATFORM_ORIGIN=http://ui-platform:3000, RAG_SERVICE_URL=http://rag-service:8000, CONTROL_PLANE_ORIGIN=http://portal-console:3000, loopback 전달자 대상 portal-console).
• 패키지명: portal-console(이전 directory-service-portal-v2) · ui-platform(이전 ui-center) · @hohyun94/file-store · @hohyun94/file-store-admin-web.
• 스캐폴드 템플릿(PortalConsole/template.json) 내 오래된 패키지명·타이틀 정리.
• dev 스택 재기동 검증: ProcessCenter :3000 200 · PortalConsole :3100/api/health 200(마이그레이션 자동 적용) · UiPlatform :3200 200(제어평면 등록 동기화 성공) · FileStore :3300/healthz 200 · 관리자 콘솔 :3300/admin 200 · ExploreGateway :3500/healthz 200(control-plane=http://portal-console:3000) · ModelGateway :3400 401(서비스 토큰 필요, 기존과 동일).
• 문서 본문 일괄 정비: 8개 저장소 *.md·*.mmd 98개 파일에서 옛 제품명을 새 이름으로 치환 (코드 심볼·호환 식별자·DECISION_LOG 이력은 유지).

2차 — 환경변수 접두 개편(같은 날 완료)

• 코드·compose·.env·문서에서 환경변수 이름을 새 접두로 치환(값·호스트명은 이미 새 이름): DIRECTORY_SERVICE_* · DIRECTORY_* → PORTAL_CONSOLE_*, ASSETSTORE_* → FILE_STORE_*, UI_CENTER_* → UI_PLATFORM_*, RAG_CENTER_* · RAGCENTER_* → RAG_SERVICE_* (예: PORTAL_CONSOLE_ORIGIN, PORTAL_CONSOLE_JWT_SECRET, PORTAL_CONSOLE_PORTAL_ID, FILE_STORE_SERVICE_TOKEN, UI_PLATFORM_PUBLIC_URL, RAG_SERVICE_URL, RAG_SERVICE_DATABASE_URL). 6개 저장소 168개 파일.
• 이전 이름 호환 별칭: 각 서비스 엔트리 최상단에서 envAliases.ts(TS) · env_compat.py(RagService)가 이전 이름 값을 새 이름으로 복사한다(새 이름이 이미 있으면 그 값 우선, 매핑 시 경고 로그). 배포 환경이 아직 구 이름을 써도 동작하며 1릴리스 후 제거한다.
• FileStore 별칭 제거(2026-09-29): ASSETSTORE_* 접두 별칭은 이미 제거했다(표준 FILE_STORE_*만 사용). 서비스 코드· 어댑터 export·HTTP 경로(/api/file-store/v1/*)·헤더(x-filestore-consumer)·에러 코드·DB 컬럼/테이블까지 같은 표기로 정리했다.
• 검증: dev 스택 재기동 후 5개 서비스 정상(ProcessCenter · PortalConsole · UiPlatform · FileStore · ExploreGateway), tsc --noEmit 5개 서비스 통과, 별칭 동작 확인(RAG_CENTER_URL → RAG_SERVICE_URL), ExploreGateway 테스트 18/18 통과. 나머지 테스트 실패는 변경 전과 동일(컨테이너에 git 미설치 · ambient env · DB mock 등 기존 문제).

3차 — PF 어댑터 패키지 개명(같은 날 완료)

• portal-foundation: packages/filestore-adapter → packages/filestore-adapter, 패키지명 @hohyun94/portal-filestore → @hohyun94/portal-filestore(루트 빌드 필터·README·문서·lockfile 포함).
• ProcessCenter: vendor/hohyun94-portal-filestore-0.1.0.tgz로 교체, package.json·pnpm-lock.yaml·server/fileStoreClient.ts import 갱신, PC 이미지 재빌드(--renew-anon-volumes) 후 pnpm check 통과·:3000 200 확인.
• 함께 정리: PC vendor/를 사용 중인 5개 tarball만 남김(110 → 5). 나머지는 과거 버전 사본으로, 필요 시 PF에서 재패킹한다.

로컬 폴더(마무리 필요): DirectoryService · UiCenter · FileStore 폴더는 VS Code가 파일 핸들을 잡고 있어 물리 이름 변경이 차단되었다. 대신 같은 이름의 디렉터리 정션(링크) 을 만들어 새 경로 (PortalConsole · UiPlatform · FileStore)로 git·Docker·pnpm이 정상 동작한다. VS Code를 모두 닫은 뒤 아래를 실행하면 물리 이름까지 정리되고, 경로가 바뀌었으므로 컨테이너를 재생성해야 한다.

cd C:\H_PROJECT
cmd /c rmdir PortalConsole ; Rename-Item DirectoryService PortalConsole
cmd /c rmdir UiPlatform    ; Rename-Item UiCenter UiPlatform
cmd /c rmdir FileStore     ; Rename-Item FileStore FileStore
cd ProcessCenter ; docker compose -f docker-compose.dev.yml up -d --force-recreate

남은 정비(권장 순서)

1. 운영 영향 항목: 배포 서비스명·도메인 변경 → 각 서비스 envAliases/env_compat 별칭 제거(1릴리스 후).
2. 3차 — 코드·문서 전면 치환: 문서 본문·코드 심볼·CSS 클래스, RagService Python 모듈명, portal-foundation 네임스페이스 혼재(@portal-foundation/* vs @hohyun94/*) 정리.
3. 동시 배포 필요 항목: 토큰 audience·포털 ID(ui-center → ui-platform 등) — PortalConsole 발급기와 모든 검증자(포털·게이트웨이·RagService)를 한 번에 배포해야 한다.

플랫폼 중립 원칙(2026-09-13 적용 · 앞으로의 작업 기준)

특정 배포 플랫폼(관리형 클라우드 등)에 종속되는 설정 파일·API 연동·환경변수는 새로 들여오지 않는다. 배포 환경 구성은 운영자의 CI·컨테이너·VM 도구가 담당하고, 애플리케이션은 pnpm build + pnpm start로 동일하게 기동한다.

• 허용: 호스팅 구분이 필요하면 중립 값만 쓴다 — DEPLOYMENT_PROFILE(CLOUD·ON_PREM), 일반화된 컨테이너/VM 배포 설정.
• 자격증명·환경변수 전달은 수동 적용(Secret Manager·배포 에이전트)을 기본으로 하고, 자동 푸시는 특정 플랫폼 없이 대상이 정의된 경우에만 별도 계약으로 추가한다.
• 자동 검증: PortalConsole/server/platformNeutrality.test.ts · ProcessCenter/server/platformNeutrality.test.ts 가 코드·설정에서 위 금지 항목을 검사한다(테스트 파일·과거 마이그레이션·과거 문서는 제외).
• 문서에도 플랫폼 이름을 쓰지 않는다: 신규·과거 문서 모두 "배포 환경·컨테이너·관리형 클라우드" 같은 중립 표현을 쓰고, 플랫폼 전용 URL·CLI 안내는 남기지 않는다(2026-09-13 히스토리 문서까지 정리 완료).

남은 설계 결정

• RagService ↔ ExploreGateway 경계(권장 A안): ExploreGateway는 "탐색 실행 오케스트레이터"만 유지하고, 문서 인덱스·RAG·citation은 RagService가 소유한다. ExploreGateway가 RagService를 소스/어댑터로 등록해 통합 탐색에서 문서 결과를 함께 반환한다. (구현 시 explore-adapter.openapi.json 확장 + RagService 수집·검색 계약 재확인 필요.)