docs: workspace_config 경로 SSOT 트러블슈팅 문서 추가

Made-with: Cursor

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

@@ -4,6 +4,10 @@ tags: [research, llm, ssot, workspace-config, hardcoding, robeing]
 
 # 260315 모델 SSOT 하드코딩 분산과 workspace-config 로컬 이식 통합 리서치
 
+## 이 리서치가 받는 문제 문서
+
+- 현재 문제 정의와 영향 범위는 [workspace-config 루트기준 SSOT와 하드코딩 분산 문제 오픈](../troubleshooting/260316_workspace_config_루트기준_SSOT와_하드코딩_분산_문제오픈.md)에서 엽니다.
+
 ## 문제 정의
 
 - 로빙은 `DEFAULT_LLM_MODEL` 같은 SSOT 선언이 이미 존재하지만, 실제 호출부는 `GeminiHandler`, `google.generativeai`, `gemini-*` 문자열 하드코딩에 분산되어 있습니다.

journey/troubleshooting/260316_workspace_config_루트기준_SSOT와_하드코딩_분산_문제오픈.md

@@ -0,0 +1,72 @@
+tags: [troubleshooting, workspace-config, ssot, hardcoding, runtime]
+
+# workspace-config 루트기준 SSOT와 하드코딩 분산 문제 오픈
+
+## 문제 정의
+
+- `workspace-config`와 모델/런타임 설정은 SSOT라고 선언돼 있지만, 실제 코드·compose·문서에는 절대경로와 하드코딩, 분산 참조가 함께 남아 있습니다.
+- 그 결과 값 변경이 `WORKSPACE_ROOT + workspace-config/runtime.env|secrets.env` 한 곳에서 닫히지 않고, 프로젝트별 수정과 해석 혼선이 반복됩니다.
+
+## 관련 문서
+
+- [모델 SSOT 하드코딩 분산과 workspace-config 로컬이식 통합 리서치](../research/260315_모델SSOT_하드코딩_분산과_workspace_config_로컬이식_통합리서치.md)
+- [0_VALUE Infrastructure SSOT Principle](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/infrastructure-ssot-principle.md)
+- [0_VALUE Workspace Config](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/workspace-config/README.md)
+
+## 이 문서가 여는 리서치
+
+- 이 문제의 원인 수집과 구조 해석은 [모델 SSOT 하드코딩 분산과 workspace-config 로컬이식 통합 리서치](../research/260315_모델SSOT_하드코딩_분산과_workspace_config_로컬이식_통합리서치.md)로 이어집니다.
+
+## 재현 조건
+
+- 로컬 워크스페이스에서 `workspace-config/runtime.env`, `workspace-config/secrets.env`를 기준으로 설정을 맞추려 할 때
+- 하위 프로젝트의 compose, 코드, 문서가 여전히 절대경로 `/home/admin/...` 또는 서비스별 개별 설정을 전제할 때
+- 모델·엔드포인트·모니터·DB 설정 변경을 한 곳에서 끝내려 할 때
+
+## 확인된 사실
+
+### 1. 상위 SSOT는 절대경로가 아니라 루트 기준값 + 상대 구조를 요구한다
+
+- `0_VALUE/02_Governance/infrastructure-ssot-principle.md`는 환경마다 절대경로가 달라도, 루트 기준값 하나만 바꾸면 같은 디렉터리 구조와 같은 설정 해석 규칙을 따라가게 유지하라고 명시합니다.
+- `0_VALUE/02_Governance/workspace-config/README.md`는 `workspace-config`의 SSOT가 특정 절대경로가 아니라, 워크스페이스 루트 기준값 아래에서 같은 상대 구조를 해석하는 방식이라고 명시합니다.
+
+### 2. 현재 로컬에는 공용 런타임 파일 두 개가 존재한다
+
+- 로컬 경로 `/home/happybell/projects/workspace-config/runtime.env`가 존재합니다.
+- 로컬 경로 `/home/happybell/projects/workspace-config/secrets.env`가 존재합니다.
+- 현재 로컬 기준값은 `WORKSPACE_ROOT=/home/happybell/projects`입니다.
+
+### 3. runtime.env와 secrets.env의 역할 경계는 이미 분리됐다
+
+- `runtime.env`는 루트, 호스트, 포트, 공용 URL, NAS 경로, 모니터 URL, Redis, 로빙/스킬 URL 묶음 같은 비민감 운영값을 담습니다.
+- `secrets.env`는 NAS 계정, 외부 NAS 계정, Gitea 계정/토큰, DB URL, JWT 같은 민감값을 담습니다.
+
+### 4. 그런데 하위 프로젝트 적용 경계는 아직 닫히지 않았다
+
+- `robeing` 하위 서비스들의 compose와 코드 일부는 여전히 `/home/admin/workspace-config/...` 같은 서버 기준 절대경로를 전제합니다.
+- 일부 서비스는 여전히 서비스별 `.env`, 코드 기본값, 하드코딩 fallback을 같이 들고 있습니다.
+- 따라서 현재는 상위 원칙과 로컬 실행 구조가 완전히 일치한다고 볼 수 없습니다.
+
+## 영향 범위
+
+- 로컬 개발자가 `WORKSPACE_ROOT`와 `workspace-config` 두 파일만 바꾸면 된다고 믿고 작업해도, 실제 하위 프로젝트에서는 추가 수정이 발생할 수 있습니다.
+- 모델, 모니터, DB, URL, 포트 같은 공용 운영값이 여러 군데에서 따로 관리되면 회귀와 오판 위험이 커집니다.
+- 문제를 `troubleshooting -> research -> plans -> worklog` 흐름으로 닫아야 하는데, 시작점이 불명확해져 같은 논쟁이 반복됩니다.
+
+## 기대하는 상태
+
+- `WORKSPACE_ROOT`만 다르면 서버와 로컬이 같은 상대 구조 `workspace-config/runtime.env`, `workspace-config/secrets.env`를 동일하게 해석합니다.
+- 공용 운영값 변경 시 수정 지점은 `runtime.env`, `secrets.env` 두 파일로 닫힙니다.
+- 하위 프로젝트는 서비스별 `.env`나 코드 하드코딩이 아니라, 공용 런타임 파일만 기준으로 읽습니다.
+
+## 미확정 항목
+
+- 각 하위 프로젝트 compose가 로컬에서 어떤 방식으로 루트 기준값을 해석하게 맞출지
+- 서비스별 `.env`와 코드 fallback 중 무엇이 아직 실제 런타임 경로에 남아 있는지 전체 인벤토리
+- 로컬 기준 공용 파일만 읽도록 바꿀 때, 프로젝트별 예외가 필요한 서비스가 있는지 여부
+
+## 다음 단계
+
+- 원인과 잔존 경로 수집은 `research`에서 더 좁힙니다.
+- 어떤 저장소를 어떤 순서로 고칠지는 `plans`에서 고정합니다.
+- 닫힘 선언은 `worklog`에서만 합니다.