docs: align doc principle names and record nas lfs recovery

book/300_architecture/300_README.md

@@ -11,7 +11,7 @@ Part 2에서 우리는 게임 메커니즘을 활용한 설계를 소개했습
 ## 목차
 - 310_전체_시스템_구조_컨테이너와_마이크로서비스.md
 - 311_FastAPI_구조_원칙.md
-- 312_문서_작성_원칙.md
+- 312_writing-principles.md
 - 313_React_구조_원칙.md
 - 315_테스트_원칙.md
 - 320_Slack_기반_인터페이스_설계.md

book/300_architecture/311_백엔드_구조_원칙.md

@@ -241,7 +241,7 @@ utils
 - [ ] LLM 호출 횟수 계산 및 최적화 검토
 - [ ] 애매한 케이스는 LLM 우선 접근 원칙 적용 확인
 - [ ] 복잡한 워크플로우는 LangGraph 활용 검토
-- [ ] 원칙 문서 확인 완료 (`311_FastAPI_구조_원칙.md`, `312_문서_작성_원칙.md`)
+- [ ] 원칙 문서 확인 완료 (`311_FastAPI_구조_원칙.md`, `312_writing-principles.md`)
 - [ ] 웹훅 프록시 경로에서 원문 body 전달(`content=raw_body`) 여부 확인
 - [ ] 인증 실패 상태코드(403/401)가 500으로 재매핑되지 않는지 확인
 - [ ] 증상 완화용 폴백 대신 근본 원인 수정이 반영되었는지 확인

book/300_architecture/312_writing-principles.md

@@ -3,12 +3,16 @@
 **작성일**: 2025-10-13
 **수정일**: 2026-03-05 (SSOT 관리 기준 명시)
 **참고**: AGENTS.md, 311_백엔드_구조_원칙.md
+**상위 원칙**: [0_VALUE Writing Principles](../../../../0_VALUE/02_Governance/writing-principles.md)
 
 ---
 
 ## 0. SSOT 관리 기준
 
-- 문서 작성 상세 원칙의 SSOT는 본 문서(`312_문서_작성_원칙.md`)다.
+- 문서 작성 상세 원칙의 SSOT는 본 문서(`312_writing-principles.md`)다.
+- 상위 공통 원칙의 SSOT는 `0_VALUE/02_Governance/writing-principles.md`다.
+- 본 문서는 robeing 프로젝트에 필요한 구체화 문서다.
+- 원칙 충돌 시 상위 원칙을 먼저 검토하고, 예외가 필요하면 사용자에게 먼저 보고한 뒤 본 문서에 예외를 기록한다.
 - 하위 폴더 `README.md`와 개별 문서는 원칙 본문을 반복하지 않고 SSOT 링크만 둔다.
 - 동일 원칙을 여러 문서에 복제하지 않는다. 필요 시 본 문서를 수정하고 참조 링크만 갱신한다.
 - 실행/코드 정책(예: 폴백·예외 처리 최소화, 원인 경로 직접 수정)은 `AGENTS.md`를 SSOT로 본다.
@@ -157,6 +161,11 @@
   - 예: `https://github.com/<org>/<repo>/blob/<branch>/...`
 - 로컬 절대경로(`/home/...`, `C:\\...`)와 위키링크(`[[...]]`)는 GitHub 렌더링 호환성 이슈가 있어 기본 문서 본문에서 사용하지 않습니다.
 - 문서 추가/수정 시 링크 클릭 동작을 반드시 확인한 뒤 커밋합니다.
+- 트러블슈팅/실행 기록 문서는 필요 시 문서 상단에 `tags: [tag1, tag2, ...]` 형식의 태그를 둡니다.
+- 같은 계열 사건이 이어질 때는 기존 문서를 덮어쓰지 말고 새 문서로 분리한 뒤, 문서 하단에 `전후 관계 문서` 또는 `관련 문서` 링크를 둡니다.
+- 원칙은 `기존 문서 보존 + 새 사건은 새 문서 + 관련 문서끼리 링크`입니다.
+- 같은 목적의 상위 문서가 있으면 문서 상단에 `상위 원칙` 링크를 둡니다.
+- 동일 목적 문서는 파일명을 상위 SSOT basename에 맞춥니다.
 
 ### 구조화된 정보 형식 (AI/사람 모두 읽기 좋게)
 
@@ -288,7 +297,7 @@
 ### 필수 항목
 1. **원인**: 왜 문제가 발생했는가
 2. **교훈**: 다음에 어떻게 방지할 것인가
-3. **원칙**: 위반한 원칙이 있는가 (원칙 문서 참조: `311_백엔드_구조_원칙.md`, `312_문서_작성_원칙.md`)
+3. **원칙**: 위반한 원칙이 있는가 (원칙 문서 참조: `311_백엔드_구조_원칙.md`, `312_writing-principles.md`)
 
 ### 올바른 예시
 ```markdown

book/300_architecture/313_프론트_구조_원칙.md

@@ -2,7 +2,7 @@
 
 **작성일**: 2025-11-29
 **수정일**: 2026-01-21 (컴포넌트 분리 기준 300줄 → 500줄 완화)
-**참고**: 311_FastAPI_구조_원칙.md, 312_문서_작성_원칙.md
+**참고**: 311_FastAPI_구조_원칙.md, 312_writing-principles.md
 
 ## 1. 컴포넌트 설계 원칙
 
@@ -264,5 +264,5 @@ src/
 - 상위 원칙: 이 문서는 일반적인 React 프로젝트 원칙을 다룹니다.
 - 프로젝트별 특화 규칙: 각 프로젝트의 README나 문서에 추가 규칙 명시
 - 백엔드 원칙: `311_FastAPI_구조_원칙.md` 참고
-- 문서 작성 원칙: `312_문서_작성_원칙.md` 참고
+- 문서 작성 원칙: `312_writing-principles.md` 참고
 

book/300_architecture/314_infrastructure-ssot-principle.md

@@ -1,9 +1,16 @@
 # 314 인프라 설정 SSOT 원칙
 
+**상위 원칙**: [0_VALUE Infrastructure SSOT Principle](../../../../0_VALUE/02_Governance/infrastructure-ssot-principle.md)
+
 ## 1. 목적
 - 인프라 핵심 설정(IP, 포트, 업스트림, 공통 URL, 환경별 엔드포인트)을 단일 출처(Single Source of Truth)로 관리한다.
 - 값 변경 1건이 다수 코드/설정/문서 수정을 유발하는 구조를 제거한다.
 
+## 1.1 상위 원칙 관계
+- 상위 공통 원칙의 SSOT는 `0_VALUE/02_Governance/infrastructure-ssot-principle.md`다.
+- 본 문서는 robeing 운영 구조에 맞춘 구체화 문서다.
+- 원칙 충돌 시 상위 원칙을 먼저 검토하고, 예외가 필요하면 사용자에게 먼저 보고한 뒤 본 문서에 예외를 남긴다.
+
 ## 2. 원칙
 ### 2.1 단일 출처
 - 런타임 설정의 기준 파일은 `/home/admin/infra-config/runtime.env` 단일 파일로 한다.

book/300_architecture/315_테스트_원칙.md

@@ -2,7 +2,7 @@
 
 **작성일**: 2025-01-03
 **수정일**: 2026-02-04 (UX 검증 원칙 추가)
-**참고**: 311_백엔드_구조_원칙.md, 312_문서_작성_원칙.md
+**참고**: 311_백엔드_구조_원칙.md, 312_writing-principles.md
 
 ---
 
@@ -229,5 +229,5 @@ docker compose down && docker compose up -d --build
 ## 10. 참고
 
 - FastAPI 구조 원칙: `311_백엔드_구조_원칙.md` 섹션 18 (테스트 원칙)
-- 문서 작성 원칙: `312_문서_작성_원칙.md` (troubleshooting 기록 방법)
+- 문서 작성 원칙: `312_writing-principles.md` (troubleshooting 기록 방법)
 - 트러블슈팅: `journey/troubleshooting/251110_레거시_테스트_폴더_정리.md`

journey/plans/251225_프롬프트_동적관리_계획.md

@@ -7,7 +7,7 @@
 
 **원칙 참조**:
 - `book/300_architecture/311_백엔드_구조_원칙.md` (계층 분리, DB state 경유)
-- `book/300_architecture/312_문서_작성_원칙.md`
+- `book/300_architecture/312_writing-principles.md`
 - `book/300_architecture/315_테스트_원칙.md` (TDD)
 - `book/300_architecture/313_Gemini_프롬프트_설계_원칙.md`
 
@@ -531,7 +531,7 @@ post_check_result:
 
 ## 참고 문서
 - `book/300_architecture/311_백엔드_구조_원칙.md`
-- `book/300_architecture/312_문서_작성_원칙.md`
+- `book/300_architecture/312_writing-principles.md`
 - `book/300_architecture/315_테스트_원칙.md`
 - `book/300_architecture/313_Gemini_프롬프트_설계_원칙.md`
 - `journey/troubleshooting/250806_happybell80_동적프롬프트구현.md`

journey/plans/260307_24서버_정상복구_초기서버_기준_계획.md

@@ -0,0 +1,173 @@
+# 260307 24서버 정상복구 초기서버 기준 계획
+
+**작성일**: 2026-03-07  
+**상태**: draft  
+**전제**: 51124는 현재 빈 초기 서버에 가깝고, 51123이 `테스트 + 임시 운영` 역할을 겸하고 있다.
+
+---
+
+## 1. 목표
+- 51124를 다시 robeing 프로덕션 실행 서버로 복구한다.
+- 51123의 임시 수용 상태를 종료하고, 원래 역할인 `테스트 + 보조 + 인프라`로 되돌린다.
+- 복구 후에도 IP/경로/시크릿 변경이 대량 수정으로 번지지 않도록 SSOT 구조를 함께 정착시킨다.
+
+## 2. 복구 원칙
+1. 24는 처음부터 다시 쌓는다고 가정한다.
+- 과거 상태를 추측 복원하지 않는다.
+- 필요한 구성요소를 체크리스트로 다시 올린다.
+
+2. 서비스보다 기반을 먼저 복구한다.
+- OS/계정/권한/디렉터리/SSOT/네트워크가 먼저다.
+- 이 기반 없이 컨테이너만 올리면 재장애 가능성이 높다.
+
+3. 프로덕션 판정은 24에서만 확정한다.
+- 23에서 정상인 것은 사전 검증 근거일 뿐이다.
+- 최종 정상 판정은 24의 실제 헬스체크와 실경로 검증으로만 내린다.
+
+## 3. 24 서버에 먼저 갖춰야 할 것
+### 3.1 운영 기본 계층
+- 배포 사용자 계정 및 SSH 접근
+- Docker / Docker Compose
+- 기본 로그 경로
+- 시스템 시간대, 방화벽, 필수 패키지
+- 재부팅 후 자동 기동 정책(systemd 또는 compose 운영 규칙)
+
+### 3.2 프로젝트 루트 구조
+- `/home/admin/robeing`
+- `/home/admin/infra-config`
+- 서비스별 배포 루트 경로
+- 로그/데이터/마운트 경로
+
+### 3.3 설정 SSOT 계층
+- `/home/admin/infra-config/runtime.env`
+- `/home/admin/infra-config/secrets.env`
+- 서비스별 `.env`는 비워 두거나 로컬 오버라이드 전용으로 유지
+- IP/포트/내부 호스트/외부 연계 주소는 runtime.env 기준으로만 관리
+
+### 3.4 네트워크/연계
+- 24 -> 23 DB 접근 확인
+- 24 -> NAS 또는 대체 스토리지 접근 확인
+- 23 gateway가 24 upstream으로 다시 붙을 수 있는지 확인
+- 헬스체크/내부 포트/UFW 정책 선반영
+
+## 4. 복구 대상 서비스
+### 4.1 우선 복구
+- `rb8001`
+- `skill-email`
+- `skill-calendar`
+- `skill-news`
+- `skill-slack`
+- `skill-rag-file`
+- `skill-embedding`
+- `ChromaDB`
+
+### 4.2 조건부 복구
+- `robeing-monitor`
+- 기타 실험/보조 컨테이너
+
+원칙:
+- 프로덕션 핵심 경로를 먼저 복구한다.
+- 모니터링/실험 서비스는 핵심 경로 안정화 후 붙인다.
+
+## 5. 단계별 실행 계획
+### 5.1 Phase 1: 바닥 공사
+- 24 서버 기본 패키지, Docker, 사용자 권한, SSH 키, 방화벽 구성
+- 프로젝트 루트 디렉터리 생성
+- `infra-config` 배치 및 권한 적용
+- Gitea Actions가 접근할 배포 경로 생성
+
+완료 기준:
+- SSH 접속 가능
+- Docker 실행 가능
+- 배포 경로/권한 오류 없음
+
+### 5.2 Phase 2: 설정 이식
+- 23 기준 운영값 중 24에 필요한 항목만 선별
+- `runtime.env`와 `secrets.env`에 반영
+- 하드코딩 IP/경로가 남아 있는 서비스는 이 단계에서 제거
+
+완료 기준:
+- 각 서비스 compose가 24에서 동일한 SSOT 파일을 읽음
+- 서비스 내부 코드에 23 전용 하드코딩이 남아 있지 않음
+
+### 5.3 Phase 3: 데이터/스토리지 연계
+- PostgreSQL 연결 확인
+- ChromaDB 볼륨 및 데이터 경로 확인
+- NAS 또는 공유 스토리지 마운트 확인
+- 로그 저장 경로 확인
+
+완료 기준:
+- DB read/write 정상
+- 필요한 파일 마운트가 실제 경로에서 읽힘
+- 로그가 지정 경로에 기록됨
+
+### 5.4 Phase 4: 서비스 기동
+- 핵심 서비스부터 `docker compose down && docker compose up -d --build`
+- 각 서비스별 헬스체크 확인
+- 컨테이너 포트/네트워크 실제 바인딩 확인
+
+완료 기준:
+- `docker ps` 기준 핵심 컨테이너 running/healthy
+- 서비스별 health endpoint 응답 정상
+
+### 5.5 Phase 5: 23과 연결 복구
+- 23 gateway upstream을 24 기준으로 재설정
+- auth / gateway / upstream 로그를 같은 요청 기준으로 대조
+- 실제 도메인 기준 요청 흐름 검증
+
+완료 기준:
+- `ro-being.com` 실제 경로에서 핵심 API 응답 정상
+- gateway/nginx/upstream 로그가 한 요청 기준으로 이어짐
+
+### 5.6 Phase 6: 역할 정상화
+- 24를 프로덕션으로 확정
+- 23의 임시 실행 컨테이너 정리
+- 23을 다시 `테스트 + 보조 + 인프라` 역할로 축소
+- 임시 예외 설정 제거 여부 확인
+
+완료 기준:
+- 프로덕션 트래픽 기준 서버가 24로 고정됨
+- 23은 테스트/보험 역할만 수행
+
+## 6. 검증 체크리스트
+1. 인프라
+- SSH, Docker, disk, memory, UFW 정상
+
+2. 데이터
+- 24에서 PostgreSQL 연결 정상
+- ChromaDB 경로/볼륨 정상
+- 공유 스토리지 접근 정상
+
+3. 서비스
+- `rb8001` health 정상
+- 핵심 스킬 health 정상
+- monitor 필요 시 health 정상
+
+4. 요청 흐름
+- 실제 도메인에서 gateway -> upstream 응답 정상
+- 인증 경로 정상
+- 로그가 요청 단위로 추적 가능
+
+5. 운영
+- Actions 배포 성공
+- 재기동 후 자동 복구 가능
+- 23/24 역할 문서와 실제 구성이 일치
+
+## 7. 실패 패턴 경계
+- 23의 임시값을 24 복구값으로 착각하는 것
+- `.env`, compose, 코드, 문서가 각각 다른 값을 갖는 것
+- 컨테이너만 살아 있고 실제 도메인 요청은 실패하는 상태를 정상으로 오판하는 것
+- 24 복구 전에 23 임시 설정을 정리해 버리는 것
+
+## 8. 복구 완료 선언 조건
+- 24에서 핵심 서비스가 healthy
+- 실제 도메인 기준 핵심 경로 응답 정상
+- 23 gateway와 24 upstream 연결 정상
+- 문서, runtime.env/secrets.env, 배포 경로가 서로 일치
+- 23 임시운영 예외 항목이 후속 문서에 정리됨
+
+## 9. 후속 문서 연결
+- [260303_23테스트보조_24프로덕션_운영전환_계획](./260303_23테스트보조_24프로덕션_운영전환_계획.md)
+- [260304_24장애시_23자동임시프로덕션전환_계획](./260304_24장애시_23자동임시프로덕션전환_계획.md)
+- [260304_51123_임시복구_서비스연속성_조치내역](../troubleshooting/260304_51123_임시복구_서비스연속성_조치내역.md)
+- [260307_gateway_SSOT_runtime_secrets_분리_적용_및_검증](../troubleshooting/260307_gateway_SSOT_runtime_secrets_분리_적용_및_검증.md)

journey/plans/archive/250808_감정시스템_현실적용_5단계_로드맵.md

@@ -40,6 +40,6 @@
 
 - `book/200_core_design/225_온톨로지_기반_지식_표현.md`
 - `book/300_architecture/311_백엔드_구조_원칙.md`
-- `book/300_architecture/312_문서_작성_원칙.md`
+- `book/300_architecture/312_writing-principles.md`
 - `book/300_architecture/315_테스트_원칙.md`
 - `troubleshooting/251002_emotion_top-p_improvement.md` (감정 직접 노출 금지)

journey/plans/archive/250906_news_system_integration.md

@@ -62,5 +62,5 @@ SKILL_PUBLISH_URL=http://localhost:8511
 
 ### 원칙 문서
 - `book/300_architecture/311_백엔드_구조_원칙.md` - 계층 분리, Repository 패턴, 테스트 원칙
-- `book/300_architecture/312_문서_작성_원칙.md` - 문서 작성 규칙
+- `book/300_architecture/312_writing-principles.md` - 문서 작성 규칙
 - `book/300_architecture/database/tables.md` - rb_news 테이블 스키마 참고

journey/plans/archive/251016_ontology_coldmail_implementation.md

@@ -6,7 +6,7 @@
 
 **원칙 참조** (구현 전 필수 확인):
 - `311_백엔드_구조_원칙.md`: 계층 분리, DB는 state 경유
-- `312_문서_작성_원칙.md`: 핵심만 간결, 파일명:줄번호
+- `312_writing-principles.md`: 핵심만 간결, 파일명:줄번호
 - `315_테스트_원칙.md`: 테스트는 TDD로 진행 (Red → Green → Refactor)
 
 ---

journey/plans/archive/251206_skill_calendar_자동배포_구성.md

@@ -30,5 +30,5 @@ skill-calendar 서비스를 Gitea Actions를 통해 51124 서버에 자동 배
 
 - `troubleshooting/251225_skill_calendar_자동배포_구성.md`: 구현 완료 기록
 - `troubleshooting/250728_happybell80_nginx프록시및CI배포문제해결.md`: SSH 인증 실패 해결
-- `book/300_architecture/312_문서_작성_원칙.md`: 문서 작성 원칙
+- `book/300_architecture/312_writing-principles.md`: 문서 작성 원칙
 

journey/plans/archive/260202_뉴스브리핑_LangGraph_전환.md

@@ -5,7 +5,7 @@
 **관련 파일**: `rb8001/app/services/skills/startup_news_skill.py`, `rb8001/app/services/workflows/headlines_workflow.py`, `rb8001/tests/test_headlines_workflow.py`  
 **원칙 참조** (구현 전 필수 확인):
 - `311_백엔드_구조_원칙.md`: LangGraph 워크플로우 (섹션 5), 계층 분리
-- `312_문서_작성_원칙.md`: 핵심만 간결, 파일명:줄번호
+- `312_writing-principles.md`: 핵심만 간결, 파일명:줄번호
 - `315_테스트_원칙.md`: 테스트는 TDD로 진행 (Red → Green → Refactor)
 
 ---
@@ -109,5 +109,5 @@ START → fetch_naver → fetch_sea → extract_terms → format → send → EN
 ## 참고
 
 - `book/300_architecture/311_백엔드_구조_원칙.md`
-- `book/300_architecture/312_문서_작성_원칙.md`
+- `book/300_architecture/312_writing-principles.md`
 - `book/300_architecture/315_테스트_원칙.md`

journey/plans/archive/260304_51124_먹통_근본원인_해결계획.md

@@ -10,7 +10,7 @@
 - [51124 먹통 원인 확정 리서치](../research/260304_51124_먹통_48시간_코드차분_원인확정_리서치.md)
 - [51124 먹통 사용자 시나리오](../scenarios/260304_아침브리핑_지연_먹통_복구_사용자시나리오.md)
 - [51123 임시복구 조치내역](../troubleshooting/260304_51123_임시복구_서비스연속성_조치내역.md)
-- [문서 작성 원칙](../../book/300_architecture/312_문서_작성_원칙.md)
+- [문서 작성 원칙](../../book/300_architecture/312_writing-principles.md)
 
 ## 2. 근본 원인(확정)
 - `INTENT_ENGINE=graph` + `INTENT_USE_LANGGRAPH=true`에서

journey/research/README.md

@@ -3,7 +3,7 @@
 ## 개요
 로빙 프로젝트의 학술적 기반과 참고한 연구들을 정리한 섹션입니다.
 
-리서치 문서 작성 원칙(SSOT): [`../../book/300_architecture/312_문서_작성_원칙.md`의 "리서치 문서" 섹션](../../book/300_architecture/312_%EB%AC%B8%EC%84%9C_%EC%9E%91%EC%84%B1_%EC%9B%90%EC%B9%99.md)
+리서치 문서 작성 원칙(SSOT): [`../../book/300_architecture/312_writing-principles.md`의 "리서치 문서" 섹션](../../book/300_architecture/312_writing-principles.md)
 
 ## 연구 분야
 

journey/research/orchestration_tools/260205_openclaw_로빙_적용_리서치.md

@@ -1,7 +1,7 @@
 # OpenClaw 아키텍처 분석 및 로빙 적용 리서치
 
 **작성일**: 2026-02-05 (260226 보완)
-**참고**: 312_문서_작성_원칙.md, 311_백엔드_구조_원칙.md
+**참고**: 312_writing-principles.md, 311_백엔드_구조_원칙.md
 **원본**: https://github.com/openclaw/openclaw
 **로컬 클론**: `ivada/openclaw` (260226 클론)
 
@@ -124,7 +124,7 @@ OpenClaw(구 Moltbot/Clawdbot)는 WhatsApp·Slack·Telegram 등 메신저로 대
 ## 6. 참고 문서
 
 - 311_백엔드_구조_원칙.md: 계층 분리, LangGraph 워크플로우
-- 312_문서_작성_원칙.md: 핵심만 간결, 파일명:줄번호
+- 312_writing-principles.md: 핵심만 간결, 파일명:줄번호
 - 360_로빙_컨테이너_경량화_전략.md: Stateless Router + Microservices
 - orchestration_tools/250925_langgraph_vs_n8n_comparison.md: LangGraph vs n8n
 - orchestration_tools/260205_openclaw_official_docs_summary.md: OpenClaw 공식 문서 요약 (docs.openclaw.ai)

journey/troubleshooting/250103_감정_기반_응답_길이_제어_구현.md

@@ -77,6 +77,6 @@ emotion_length_map = {
 ## 참고
 
 - `plans/archive/251016_emotion_integration_plan.md`: 원본 계획 문서
-- `312_문서_작성_원칙.md`: 문서 작성 원칙
+- `312_writing-principles.md`: 문서 작성 원칙
 - `315_테스트_작성_원칙.md`: 테스트 작성 원칙
 

journey/troubleshooting/251019_claude_rb8001_미해결_이슈_정리.md

@@ -2,7 +2,7 @@
 
 **날짜**: 2025-10-19  
 **작성자**: Claude (51124)  
-**작성 원칙**: `DOCS/300_architecture/312_문서_작성_원칙.md` 준수  
+**작성 원칙**: `DOCS/300_architecture/312_writing-principles.md` 준수  
 **참고**: `CLAUDE.md`의 트러블슈팅 작성 규칙 및 범위
 
 ---

journey/troubleshooting/251021_admin_gemini_single_model_and_ethics_visibility.md

@@ -83,4 +83,4 @@ Ethics violation detected: **윤리적 제약 위반**: 공정성 원칙
 - `rb8001@daad1bd` rb8001: use only gemini-2.5-flash-lite; hide ethics text from user; dedup Gemini init; clarify ethics priority
 
 ---
-문서 규칙: `DOCS/300_architecture/312_문서_작성_원칙.md` 준수
+문서 규칙: `DOCS/300_architecture/312_writing-principles.md` 준수

journey/troubleshooting/251021_admin_slack_doc_analysis_pipeline_langgraph.md

@@ -90,4 +90,4 @@ Non-text message subtype ignored: message_changed
 - `rb8001@daad1bd` single gemini + hide ethics text
 
 ---
-문서 규칙: `DOCS/300_architecture/312_문서_작성_원칙.md` 준수
+문서 규칙: `DOCS/300_architecture/312_writing-principles.md` 준수

journey/troubleshooting/251022_claude_OCR_파이프라인_개선_테스트.md

@@ -110,4 +110,4 @@
 상세 내역: `251023_claude_skill-rag-file_OCR_품질_개선_배포.md`
 
 ---
-문서 규칙: `DOCS/300_architecture/312_문서_작성_원칙.md` 준수
+문서 규칙: `DOCS/300_architecture/312_writing-principles.md` 준수

journey/troubleshooting/251022_claude_rb8001_web_search_미수행.md

@@ -98,4 +98,4 @@
 - CQR/엔티티링크·rerank 추가: resolve→link→cqr→search→rerank→summarize→format 파이프 및 AsyncSqliteSaver 도입 (커밋: `8cdb444`)
 
 ---
-문서 규칙: `DOCS/300_architecture/312_문서_작성_원칙.md` 준수
+문서 규칙: `DOCS/300_architecture/312_writing-principles.md` 준수

journey/troubleshooting/251023_claude_skill-rag-file_OCR_품질_개선_배포.md

@@ -160,4 +160,4 @@ curl -X POST http://localhost:8508/api/reindex \
 - 재색인 API는 점진적 품질 개선과 A/B 테스트에 유용. force_ocr 플래그로 안전하게 제어 가능.
 
 ---
-문서 규칙: `DOCS/300_architecture/312_문서_작성_원칙.md` 준수
+문서 규칙: `DOCS/300_architecture/312_writing-principles.md` 준수

journey/troubleshooting/251128_ir_deck_valuation_backend_architecture.md

@@ -184,4 +184,4 @@ CREATE TABLE ir_deck_feedback (
 ## 관련 문서
 
 - [IR Deck 배치 테스트 문제점 분석](./251128_ir_deck_batch_test_issues.md) - 배치 테스트 결과 및 해결 사항
-- `DOCS/book/300_architecture/312_문서_작성_원칙.md` - 문서 작성 규칙
+- `DOCS/book/300_architecture/312_writing-principles.md` - 문서 작성 규칙

journey/troubleshooting/251216_bayesian_presentation_ballquiz_redesign.md

@@ -113,7 +113,7 @@
   - 포트 사용 전 `netstat` 또는 `ss` 명령어로 사용 중인 포트 확인
   - nginx 설정 파일에서 프록시 포트 확인 (`/etc/nginx/sites-enabled/default`)
   - 다른 서비스와 충돌하지 않는 포트 사용
-- **원칙**: `312_문서_작성_원칙.md` - 확인된 사실만 기록
+- **원칙**: `312_writing-principles.md` - 확인된 사실만 기록
 
 ### 프론트엔드/백엔드 기본값 일치 확인
 - **원인**: Section 1 제거 후 프론트엔드만 section 2로 변경, 백엔드는 section 1 유지

journey/troubleshooting/260226_NAS_192_168_219_51_접속불가_임시백업복구.md

@@ -35,3 +35,6 @@
 
 ## 참고
 - 기존 NAS 백업 체계 문서: `./250729_서버백업및로그관리체계구축.md`
+
+## 후속 문서
+- 다음 단계: [260307_NAS_192_168_0_101_SSOT_전환_및_CIFS_실마운트_복구](./260307_NAS_192_168_0_101_SSOT_전환_및_CIFS_실마운트_복구.md)

journey/troubleshooting/260306_51123_gitea_lfs_permission_denied_502_복구.md

@@ -1,5 +1,7 @@
 # 51123 Gitea LFS 권한 오류로 인한 git.ro-being.com 502 복구
 
+tags: [gitea, lfs, nas, recovery]
+
 **날짜**: 2026-03-06  
 **작성자**: admin  
 **관련 파일**: `/etc/gitea/app.ini`, `/etc/nginx/sites-enabled/default`
@@ -37,3 +39,6 @@
 - Gitea LFS가 NAS 경로를 사용하면, 서비스 기동 전 `마운트 상태 + 대상 디렉터리 소유권`이 동시에 만족되어야 함.
 - `502`만 보고 nginx 문제로 단정하면 오판 가능성이 높고, 반드시 `nginx(upstream) + systemd(gitea) + journal`을 같은 시각대로 교차 확인해야 함.
 - 스토리지 경로가 마운트 의존일 때는 마운트 해제/권한 변동 감시를 운영 체크리스트에 포함해야 함.
+
+## 후속 문서
+- 다음 단계: [260307_Gitea_LFS_NAS_권한정렬_및_실업로드_검증](./260307_Gitea_LFS_NAS_권한정렬_및_실업로드_검증.md)

journey/troubleshooting/260307_Gitea_LFS_NAS_권한정렬_및_실업로드_검증.md

@@ -0,0 +1,73 @@
+# 260307 Gitea LFS NAS 권한정렬 및 실업로드 검증
+
+tags: [gitea, lfs, nas, cifs, ssot]
+
+**날짜**: 2026-03-07  
+**작성자**: admin  
+**관련 파일**: `/etc/gitea/app.ini`, `/usr/local/bin/mount-nas-ssot.sh`, `/etc/systemd/system/mount-nas-ssot.service`, `/home/admin/infra-config/runtime.env`, `/home/admin/infra-config/secrets.env`
+
+---
+
+## 문제 상황
+- Gitea는 기동 중이었고 `git.ro-being.com` 일반 Git push/pull도 정상 동작했다.
+- 하지만 실제 `git lfs push` 검증에서는 `500 Internal Server Error`로 실패했다.
+- 즉 "LFS 경로가 설정돼 있다"와 "실제 대용량 파일 업로드가 된다"가 분리된 상태였다.
+
+## 검증으로 확인한 사실
+1. 일반 Git 경로는 정상
+- `git push`, `git pull`은 정상
+
+2. LFS 경로는 비정상
+- 실제 `git lfs` 업로드 테스트에서 반복적으로 `500` 발생
+- `journalctl -u gitea` 기준 실패 시각(2026-03-07 09:35 KST) 로그:
+  - `mkdir /mnt/nas/gitea-lfs/18: permission denied`
+
+3. 근본 원인
+- `gitea.service`는 `git:git (uid=131 gid=138)`로 실행
+- NAS CIFS 마운트는 `uid=1001,gid=1000,file_mode=0755,dir_mode=0755` 기준
+- 결과적으로 `/mnt/nas/gitea-lfs`는 `admin:xusers` 소유처럼 보였고, `git` 사용자는 쓰기 불가
+
+## 실제 조치
+### 1. 마운트 권한 정렬
+- `/usr/local/bin/mount-nas-ssot.sh`의 CIFS 옵션을 아래 기준으로 조정
+  - `uid=1001`
+  - `gid=1000`
+  - `forceuid,forcegid`
+  - `file_mode=0664`
+  - `dir_mode=0775`
+
+### 2. Gitea 실행 사용자 그룹 정렬
+- `git` 사용자를 `xusers` 그룹에 추가
+- 결과: `git` 사용자가 `/mnt/nas/gitea-lfs`에 그룹 쓰기 가능
+
+### 3. 서비스 반영
+- NAS 재마운트 실행
+- `gitea.service` 재시작
+- `sudo -u git` 기준 직접 쓰기 테스트 성공
+
+## 재검증 결과
+1. 권한
+- `id git` -> `groups=138(git),1000(xusers)`
+- `/mnt/nas/gitea-lfs` -> `drwxrwxr-x`
+
+2. 실업로드 검증
+- `test-meta-skill` 저장소에 임시 브랜치 생성 후 1MB 바이너리 파일을 `git lfs`로 push
+- 재클론 후 `git lfs pull` 수행
+- 원본과 재다운로드 파일 SHA256 일치
+
+3. NAS 저장 확인
+- 실제 생성 경로:
+  - `/mnt/nas/gitea-lfs/4a/22/ae83cbb68dcdcddb9e053fdce9466e63463881c981597bb6c797ca4a0f7b`
+- 검증 시점 기준 LFS 파일 수:
+  - before=0
+  - after_push=1
+  - after_pull=1
+
+## 결론
+- 현재 Gitea LFS는 설정상 연결된 수준이 아니라, 실제로 NAS에 대용량 파일을 저장하는 상태까지 검증 완료됐다.
+- 이번 조치로 `git lfs push -> Gitea -> /mnt/nas/gitea-lfs` 경로가 실동작함을 확인했다.
+- 이후 동일 계열 문제 재발 시, `Gitea 상태`보다 먼저 `gitea 실행 사용자`와 `NAS 마운트 권한`을 함께 봐야 한다.
+
+## 전후 관계 문서
+- 이전: [260306_51123_gitea_lfs_permission_denied_502_복구](./260306_51123_gitea_lfs_permission_denied_502_복구.md)
+- 관련: [260307_NAS_192_168_0_101_SSOT_전환_및_CIFS_실마운트_복구](./260307_NAS_192_168_0_101_SSOT_전환_및_CIFS_실마운트_복구.md)

journey/troubleshooting/260307_NAS_192_168_0_101_SSOT_전환_및_CIFS_실마운트_복구.md

@@ -0,0 +1,74 @@
+# 260307 NAS(192.168.0.101) SSOT 전환 및 CIFS 실마운트 복구
+
+## 시간
+- 기준일: 2026-03-07
+- 작업 시각: 2026-03-07 오전
+
+## 배경
+- 서버 이전 후 NAS 내부 사설 IP가 `192.168.219.51`에서 `192.168.0.101`로 변경되었다.
+- 51123은 임시운영 상태에서 `/mnt/nas`를 다시 실NAS로 연결해야 했고, 동시에 SSOT 원칙에 맞게 NAS 설정을 정리할 필요가 있었다.
+- 기존 `/mnt/nas`는 실제 마운트가 아니라 로컬 디렉터리처럼 남아 있었고, `weekly-backup.sh`가 기대하는 `/mnt/nas/backup/weekly`도 실NAS 기준으로는 정합성이 깨져 있었다.
+
+## 확인된 사실
+1. `192.168.0.101`은 실제 응답하는 NAS였다.
+- `ping` 정상 응답
+- `22/80/443/139/445/5000/5001` 포트 오픈 확인
+- `5000/5001` 응답 기준 Synology DSM 장비 확인
+
+2. NAS 내부에는 기존 백업 구조가 남아 있었다.
+- `home` 공유 접근 가능
+- `backup/current/{robing,gitea,config}` 존재
+- `gitea-lfs` 디렉터리 존재
+
+3. 서버 쪽 마운트 설정은 구식 값이 남아 있었다.
+- `/etc/fstab`에 `//192.168.219.51/home /mnt/nas cifs username=admin,password=...` 형태의 평문 설정 존재
+- 이는 이전 IP 기준이며, SSOT 원칙에도 맞지 않았다.
+
+## 실제 조치
+### 1. NAS 접근 확인
+- `smbclient -L //192.168.0.101 -U admin%...` 로 `home`, `homes` 공유 확인
+- `smbclient //192.168.0.101/home ...` 로 `backup`, `gitea-lfs` 실제 존재 확인
+
+### 2. SSOT 반영
+- `/home/admin/infra-config/runtime.env`
+  - `NAS_HOST=192.168.0.101`
+  - `NAS_SMB_PORT=445`
+  - `NAS_SHARE=home`
+  - `NAS_MOUNT_PATH=/mnt/nas`
+- `/home/admin/infra-config/secrets.env`
+  - `NAS_USERNAME=admin`
+  - `NAS_PASSWORD=...`
+
+### 3. 마운트 방식 교체
+- `/etc/fstab`의 평문 CIFS 항목은 주석 처리
+- `/usr/local/bin/mount-nas-ssot.sh` 생성
+  - `runtime.env`, `secrets.env`를 읽어 CIFS 마운트 수행
+- `/etc/systemd/system/mount-nas-ssot.service` 생성 및 enable
+  - 부팅 후 SSOT 기준으로 NAS 마운트 복구 가능하도록 구성
+
+### 4. 권한 정합화
+- 초기 마운트는 `uid=1000` 기준이라 현재 사용자 `admin(uid=1001)`가 쓰기 불가
+- 마운트 옵션을 `uid=1001,gid=1000`으로 교정
+- 이후 `/mnt/nas/backup/weekly` 생성 및 쓰기 가능 확인
+
+## 검증 결과
+1. 마운트 상태
+- `//192.168.0.101/home on /mnt/nas type cifs` 확인
+- `df -h /mnt/nas` 기준 5.3T 마운트 정상
+
+2. 구조 확인
+- `/mnt/nas/backup/current`
+- `/mnt/nas/backup/archives`
+- `/mnt/nas/gitea-lfs`
+
+3. 쓰기 확인
+- `/mnt/nas/backup/weekly/latest.txt` 생성 및 기록 성공
+
+## 결론
+- 51123의 `/mnt/nas`는 다시 실NAS(`192.168.0.101`)를 바라보도록 복구되었다.
+- NAS 접속 정보는 `infra-config/runtime.env` + `secrets.env` 기준으로 SSOT화되었다.
+- 기존 `nas-fallback` 임시 우회 상태에서 한 단계 진전했지만, fallback 데이터 동기화 여부는 별도 점검이 필요하다.
+
+## 전후 관계 문서
+- 이전: [260226_NAS_192_168_219_51_접속불가_임시백업복구](./260226_NAS_192_168_219_51_접속불가_임시백업복구.md)
+- 관련: [260307_51123_성수이전_네트워크변경_운영기록](./260307_51123_성수이전_네트워크변경_운영기록.md)