docs: SSOT·workspace_config 리서치 문서 추가

Made-with: Cursor

journey/README.md

@@ -67,6 +67,7 @@
 ### LLM 출력 계약 / 안정화
 
 - Pydantic AI 도입 기반 LLM 출력 안정화 방향확정 리서치 – `research/260313_pydantic_ai_도입_기반_llm_출력_안정화_방향확정_리서치.md`
+- 모델 SSOT 하드코딩 분산과 workspace-config 로컬 이식 통합 리서치 – `research/260315_모델SSOT_하드코딩_분산과_workspace_config_로컬이식_통합리서치.md`
 
 ### HITL / 리뷰 큐
 

journey/research/260315_모델SSOT_하드코딩_분산과_workspace_config_로컬이식_통합리서치.md

@@ -0,0 +1,125 @@
+---
+tags: [research, llm, ssot, workspace-config, hardcoding, robeing]
+---
+
+# 260315 모델 SSOT 하드코딩 분산과 workspace-config 로컬 이식 통합 리서치
+
+## 문제 정의
+
+- 로빙은 `DEFAULT_LLM_MODEL` 같은 SSOT 선언이 이미 존재하지만, 실제 호출부는 `GeminiHandler`, `google.generativeai`, `gemini-*` 문자열 하드코딩에 분산되어 있습니다.
+- 그 결과 모델명만 바꿔도 전체가 따라 바뀌지 않고, 서비스별 fallback과 직접 SDK 호출이 다시 살아나는 구조입니다.
+- 같은 유형의 문제가 인프라 문서에서는 주소, 포트, 경로, secret의 하드코딩과 runtime SSOT 불일치 문제로 반복 기록돼 있습니다.
+- 따라서 이번 이슈는 단순 모델 선택 문제가 아니라, `운영값을 한 곳에서 선언하고 실제 런타임이 그 계약만 따르게 만드는 구조`를 아직 닫지 못한 문제입니다.
+
+## 직접 연결되는 로빙 문서
+
+### 모델 SSOT와 모델 선택
+
+- [LLM 모델 비교 분석](./LLM_모델_비교_분석.md)
+- [로빙 LLM API, Agent API, 모델 선정, 비용 비교 리서치](./orchestration_tools/260312_로빙_LLM_API_Agent_API_모델선정_비용비교_리서치.md)
+
+### Gemini 단일 모델 고정과 fallback 기록
+
+- [Gemini 모델 최적화: gemini-2.5-flash-lite 전환](../troubleshooting/250906_gemini_model_optimization.md)
+- [admin gemini single model and ethics visibility](../troubleshooting/251021_admin_gemini_single_model_and_ethics_visibility.md)
+- [IR deck Gemini fallback 빈응답 처리](../troubleshooting/251202_ir_deck_gemini_fallback_빈응답_처리.md)
+
+### SSOT 분산과 하드코딩 잔존
+
+- [아침 뉴스 슬랙 포맷 SSOT 분산 및 표시 혼선](../troubleshooting/260310_아침뉴스슬랙포맷_SSOT_분산_및_표시혼선.md)
+- [프롬프트 DB 부분 도입 상태와 하드코딩 프롬프트 잔존](../troubleshooting/260311_prompt_db_partial_adoption_and_hardcoded_prompts.md)
+- [하드코딩 URL 제거 작업](../troubleshooting/250915_hardcoded_url_removal.md)
+- [로빙 인프라 설정 SSOT 원칙](../../book/300_architecture/314_infrastructure-ssot-principle.md)
+
+## 상위 SSOT와 workspace-config 기준 문서
+
+- [0_VALUE Infrastructure SSOT Principle](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/infrastructure-ssot-principle.md)
+- [0_VALUE workspace-config README](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/workspace-config/README.md)
+- [Infrastructure Project Structure](https://git.ro-being.com/ivada-infra/DOCS/src/branch/main/02_Architecture/Infrastructure_Project_Structure.md)
+- [51123 GitHub Org Repo Bootstrap Runbook](https://git.ro-being.com/ivada-infra/DOCS/src/branch/main/02_Architecture/51123_github_org_repo_bootstrap_runbook.md)
+- [23서버 워크스페이스 SSOT 구조전환 리서치](https://git.ro-being.com/ivada-infra/DOCS/src/branch/main/journey/research/260309_23서버_워크스페이스_SSOT_구조전환_리서치.md)
+- [23제어면 gateway workspace-config 단일화](https://git.ro-being.com/ivada-infra/DOCS/src/branch/main/journey/worklog/260309_23제어면_gateway_workspace_config_단일화.md)
+- [24서버 robeing runtime workspace-config 단일화](https://git.ro-being.com/ivada-infra/DOCS/src/branch/main/journey/worklog/260310_24서버_robeing_runtime_workspace_config_단일화.md)
+
+## 통합 해석
+
+### 1. workspace-config는 값 저장 폴더가 아니라 런타임 계약입니다
+
+- `workspace-config`는 단순 폴더가 아니라 공용 런타임 값의 계약과 실제 주입 지점으로 쓰입니다.
+- 상위 SSOT 문서와 인프라 구조 문서를 함께 보면, 핵심은 `값을 어딘가에 모아두는 것`이 아니라 `모든 서비스가 같은 파일 구조와 같은 키 이름을 공통 계약으로 해석하게 만드는 것`입니다.
+- 인프라 문서가 반복해서 닫는 결론도 같습니다. 코드 기본값, compose fallback, 수동 명령 예시, 프로젝트별 `.env`가 각자 값을 들고 있으면 SSOT는 선언만 있고 런타임 강제력이 없습니다.
+
+### 2. 로빙의 현재 모델 구조 문제도 같은 유형입니다
+
+- `DEFAULT_LLM_MODEL`은 선언돼 있지만, 실제 경로는 `GeminiHandler` 직접 생성, Gemini SDK 직접 호출, `gemini-*` fallback 리스트, 서비스별 개별 모델 하드코딩이 섞여 있습니다.
+- 그래서 `주 모델 변경`이 `SSOT 1개 값 변경`으로 닫히지 않고, 여러 서비스의 코드 경로를 다시 건드려야 하는 구조가 됩니다.
+- 즉 지금의 직접 원인은 `gpt-5-mini` 전환 작업이고, 근본 원인은 `모델 호출 계약의 SSOT`와 `실제 호출 구현`이 분리되지 않은 점입니다.
+
+### 3. 구조적으로 닫아야 할 기준
+
+- 모델명, 제공자, SDK 선택은 서비스 코드 곳곳이 아니라 공용 LLM 유틸리티 또는 팩토리에서만 결정돼야 합니다.
+- 서비스는 `어떤 모델을 쓸지`가 아니라 `어떤 작업을 요청할지`만 말해야 합니다.
+- fallback도 각 서비스가 개별 문자열 배열을 들고 있지 말고, 공용 정책 계층에서만 관리돼야 합니다.
+- 이 기준이 닫혀야 `DEFAULT_LLM_MODEL` 같은 값이 실제 SSOT가 됩니다.
+
+## workspace-config 로컬 이식 기준
+
+### 1. 기준 문서
+
+- 상위부터 확인할 문서는 다음 순서입니다.
+- [0_VALUE Infrastructure SSOT Principle](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/infrastructure-ssot-principle.md)
+- [0_VALUE workspace-config README](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/workspace-config/README.md)
+- [Infrastructure Project Structure](https://git.ro-being.com/ivada-infra/DOCS/src/branch/main/02_Architecture/Infrastructure_Project_Structure.md)
+- [51123 GitHub Org Repo Bootstrap Runbook](https://git.ro-being.com/ivada-infra/DOCS/src/branch/main/02_Architecture/51123_github_org_repo_bootstrap_runbook.md)
+- [23서버 워크스페이스 SSOT 구조전환 리서치](https://git.ro-being.com/ivada-infra/DOCS/src/branch/main/journey/research/260309_23서버_워크스페이스_SSOT_구조전환_리서치.md)
+- [23제어면 gateway workspace-config 단일화](https://git.ro-being.com/ivada-infra/DOCS/src/branch/main/journey/worklog/260309_23제어면_gateway_workspace_config_단일화.md)
+- [24서버 robeing runtime workspace-config 단일화](https://git.ro-being.com/ivada-infra/DOCS/src/branch/main/journey/worklog/260310_24서버_robeing_runtime_workspace_config_단일화.md)
+
+핵심은 `workspace-config`가 값 저장소가 아니라 `공용 런타임 설정의 구조와 계약 SSOT`라는 점입니다. 비민감값은 `runtime.env`, 민감값은 `secrets.env`, 서비스별 `.env`는 임시 오버라이드만 허용합니다.
+
+### 2. 로컬 이식 원칙
+
+- 로컬 이식은 서버 값을 그대로 복사하는 게 아니라 구조를 복제하면 됩니다.
+- 예를 들어 로컬 워크스페이스 루트에 `~/workspace-config/runtime.env`와 `~/workspace-config/secrets.env`를 만들면 됩니다.
+- `runtime.env`에는 비민감 운영값만 둡니다.
+- 예시 키:
+  - `WORKSPACE_ROOT`
+  - `HOST_51123`
+  - `HOST_51124`
+  - `NAS_HOST`
+  - `NAS_SHARE`
+  - `NAS_MOUNT_PATH`
+  - `GITEA_BASE_URL`
+  - `ROBEING_DEFAULT_HOST`
+  - `MONITOR_URL`
+  - `REDIS_HOST`
+  - `ROBEING_URLS`
+  - `SKILL_URLS`
+- `secrets.env`에는 인증정보와 DB 연결값만 둡니다.
+- 예시 키:
+  - `DATABASE_URL`
+  - `JWT_SECRET_KEY`
+  - `GITEA_PAT`
+  - `NAS_USERNAME`
+  - `NAS_PASSWORD`
+  - `ROBEING_MONITOR_DATABASE_URL`
+- 중요한 점은 서버 값을 로컬에 복제하는 것이 아니라, 키 이름과 역할만 동일하게 유지하고 값은 로컬 환경에 맞게 새로 만드는 것입니다.
+
+### 3. 따라야 하는 운영 방식
+
+- 각 프로젝트 `docker-compose.yml`이나 실행 스크립트는 공통 `env_file`로 이 두 파일만 읽어야 합니다.
+- 코드 기본값이나 compose `environment:`에 운영값을 하드코딩하지 않아야 합니다.
+- 서비스별 `.env`는 정말 필요한 로컬 실험 오버라이드에만 써야 합니다.
+- 주소, 포트, 시크릿이 바뀌면 `workspace-config`의 두 파일만 수정한 뒤 재기동해서 반영 여부를 검증해야 합니다.
+
+로컬 SSOT의 닫힘 조건은 아래 3가지입니다.
+
+1. 값을 바꿀 때 수정 지점이 `workspace-config` 2개 파일로 끝나는가
+2. 모든 서비스가 그 파일만 바라보는가
+3. 실제 실행 결과가 그 값으로 해석되는가
+
+## 이번 문서의 결론
+
+- 로빙의 현재 LLM 주모델 교체 난이도는 `모델 선정` 자체보다 `모델 호출 구조가 SSOT를 강제하지 못하는 설계`에서 발생합니다.
+- 인프라 쪽 `workspace-config`가 해결한 방식은 값 자체가 아니라 `계약과 주입 지점`을 단일화한 것입니다.
+- 로빙도 같은 방식으로 `모델명`, `제공자`, `fallback`, `SDK 선택`을 공용 유틸리티 또는 팩토리 한 곳으로 승격해야, 이후 모델 교체가 SSOT 변경 1회로 닫힙니다.