refactor: 문서 개선 중

docs/TechLog/final/document.md

@@ -108,9 +108,11 @@ PostgreSQL 테이블
 ```
 
 레지스트리가 없습니다. 공개 Hub 는 소스가 들어간 이미지라 쓸 수 없고, k3s 의 containerd 소켓은
-root 전용이라 사용자 셸에서 닿지 않습니다. 그래서 클러스터 안에 일회성 Job 을 띄워 tar 를
-import 합니다. 배포 단위는 `hyeonworks.com`(prod) 하나이고 서브도메인은 쓰지 않습니다 —
-공개는 `/`, API 는 `/api` 입니다.
+root 전용이라 사용자 셸에서 닿지 않습니다. 그래서 클러스터 안의 일회성 Job 으로 tar 를
+import 하는 경로를 씁니다. 이 경로가 성립하려면 Job 이 host 의 containerd 소켓을 명시적으로
+mount 하고 그 소켓을 열 수 있는 권한으로 실행되어야 합니다. `kube-system` namespace 나
+클러스터 RBAC 권한만으로 host 소켓에 접근되는 것은 아닙니다. 배포 단위는
+`hyeonworks.com`(prod) 하나이고 서브도메인은 쓰지 않습니다 — 공개는 `/`, API 는 `/api` 입니다.
 
 ---
 
@@ -1185,11 +1187,33 @@ nginx 도 서빙했지만 **브라우저는 `/favicon.ico` 를 물었고** 404
 ### 12.8 npm 환경 변수 누출 (운영 아님, 검증 절차)
 
 vitest 를 `npm`/`npx` 로 돌리면 `npm_config_*` 환경 변수가 설정되고
-`ci-workflow-generation.test.ts` 가 실패합니다. 이 저장소에서 테스트를 돌릴 때는:
+`ci-workflow-generation.test.ts` 가 실패합니다. `tech-log-frontend` 저장소 루트에서 먼저
+남아 있는 변수를 확인합니다.
 
+<!-- command-mode: operator -->
 ```bash
-env $(env | grep -i "^npm_config" | cut -d= -f1 | sed 's/^/-u /' | tr '\n' ' ') \
-  ./node_modules/.bin/vitest run …
+env | grep -i '^npm_config'
+```
+
+출력이 있으면 같은 셸에서 그 변수만 `unset` 한 뒤 다시 확인합니다. 아래 loop 는 현재 환경의
+`npm_config_*` 이름만 골라 지웁니다.
+
+<!-- command-mode: operator -->
+```bash
+while IFS='=' read -r name _; do
+  if [[ ${name,,} == npm_config_* ]]; then
+    unset "$name"
+  fi
+done < <(env)
+
+env | grep -i '^npm_config'
+```
+
+두 번째 확인에서 아무것도 나오지 않으면 npm/npx 래퍼를 거치지 않고 실행기를 직접 부릅니다.
+
+<!-- command-mode: operator -->
+```bash
+./node_modules/.bin/vitest run …
 ```
 
 ---
@@ -1504,19 +1528,39 @@ jpa-feed-query-performance  축 이름 「조회 전략」  축 3개
 `check:types` 는 tsconfig 여섯 개를 차례로 돌립니다 — app · node · test · recipes ·
 web-worker · service-worker. 루트 tsconfig 를 직접 부르는 명령은 그중 어느 것도 지나지 않습니다.
 
+프론트 검증은 `tech-log-frontend` 저장소 루트에서 실행합니다. §12.8의 환경 변수 정리를
+먼저 끝낸 뒤 아래 세 줄을 실행합니다. 마지막 vitest 호출이 unit · component · tech-log 기능
+테스트를 함께 돕니다.
+
+<!-- command-mode: operator -->
 ```bash
-# 프론트 — 다섯 개를 다 돌린다. npx tsc --noEmit 은 아무것도 검사하지 않는다
 npm run check:types
 npm run lint
-env $(env | grep -i "^npm_config" | cut -d= -f1 | sed 's/^/-u /' | tr '\n' ' ') \
-  ./node_modules/.bin/vitest run tests/unit tests/component tests/features/tech-log
+./node_modules/.bin/vitest run tests/unit tests/component tests/features/tech-log
+```
 
-# 백엔드 — 커밋한 뒤에 돌린다(산출물 이름에 커밋 해시가 들어간다)
-cd src && ./gradlew cleanStaleTraceableJars build
+세 명령이 모두 0으로 끝나야 프론트 검증이 끝난 것입니다. `npx tsc --noEmit` 성공은 이 저장소의
+타입 검증을 대신하지 않습니다.
 
-# 설계 패키지
-python3 scripts/check-openapi.py && python3 scripts/check-consistency.py \
-  && python3 scripts/check-contract-parity.py
+백엔드는 `tech-log-backend` 저장소 루트에서 먼저 작업 트리를 확인합니다. 빌드 산출물 이름에
+커밋 해시가 들어가므로 `git status --short` 출력이 남아 있다면 먼저 그 변경이 의도한 것인지
+확인하고 커밋 상태를 정리합니다.
+
+<!-- command-mode: operator -->
+```bash
+git status --short
+cd src
+./gradlew cleanStaleTraceableJars build
+```
+
+`src` 로 이동한 같은 위치에서 설계 패키지의 세 검사를 각각 실행합니다. 한 줄로 묶지 않아 어느
+검사가 실패했는지 그대로 남깁니다.
+
+<!-- command-mode: operator -->
+```bash
+python3 scripts/check-openapi.py
+python3 scripts/check-consistency.py
+python3 scripts/check-contract-parity.py
 ```
 
 ---