harness/plugins/zio-harness/knowledge/guardia/lessons-learned.md

GUARDiA 개발 교훈 (Lessons Learned)

GUARDiA 전 하네스 변경 이력(★교훈·근본원인·함정)과 kintex 트랙 소유자 피드백 로그에서 추출한 지식 문서. 각 항목은 [증상 → 근본원인 → 해결 패턴] 구조. 신규 개발·배포·디버깅 시 먼저 이 문서를 대조하라. 출처: C:\GUARDiA\CLAUDE.md(하네스 변경 이력), workspace\kintex\CLAUDE.md, workspace\kintex\docs\OWNER_FEEDBACK.md 갱신: 2026-07-12

---

1. DB / 스키마

1.1 sql.init mode=never + schema.sql 후행 확장 함정 (최다 재발 패턴)

• 증상: 운영 중 특정 API만 500, 로그에 relation "xxx" does not exist (OCR ocr_ai_task에서 최초 규명, bi 4테이블·erp 6+테이블 등 전 솔루션 확산).
• 근본원인: 초기 배포 후 schema.sql에 테이블을 추가해도 spring.sql.init.mode: never면 재적용되지 않음. 스키마 파일과 실제 DB가 조용히 갈라진다.
• 해결 패턴 (검증됨, 2026-06-18 OCR·BI):
  1. 시드에 유니크 인덱스를 걸어 멱등화 (재실행해도 중복 삽입 없음)
  2. mode: always + continue-on-error: true 로 전환
  3. DataAccessException 전역 핸들러로 SQL 오류 누출 차단 (스택트레이스 미노출)
  4. 전 솔루션 grep 감사: mode: never 패턴 발견 시 동일 수복 (bi·pms·rpa·cms·mes가 동일 위험군이었음)

1.2 매퍼가 참조하나 schema에 정의 없는 테이블 (2레이어 누락)

• 증상: ERP에서 mode=always로 바꿔도 여전히 relation does not exist 잔존.
• 근본원인: 애초에 schema.sql에 정의 자체가 없는 테이블 11종. 직접 분석으로 잡히는 레이어(6)와 조인으로만 드러나는 레이어(5, erp_bom·employee 등)가 따로 존재.
• 해결 패턴: 매퍼 XML을 역설계해 schema-missing-tables.sql 별도 파일로 정의 → 해당 파일만 mode=always 적용(기존 시드 무영향). 누락 컬럼은 멱등 ALTER TABLE ... ADD COLUMN IF NOT EXISTS.

1.3 PostgreSQL 방언 함정 2종

• ROUND(double, int) 불가: MES productionKpi 500. PG는 round(double precision, int) 시그니처가 없음 → 전체 식을 ::numeric 캐스팅 후 ROUND.
• ORDER BY/함수에서 SELECT 별칭 참조 불가: ERP finance costVariance 500. PG는 별칭을 함수 인자·ORDER BY 식 내부에서 참조 못 함 → 별칭 대신 전체 식을 반복 기술.

1.4 "테이블 누락"과 "파라미터 이슈"를 구분하라

• 증상: 스키마 수복 후에도 일부 엔드포인트 500/4xx 잔존.
• 근본원인: ERP procurement 2개는 필수 파라미터(vendorId/expiryDate) 미전달이 원인 — 테이블 문제가 아니라 정상 동작이었음.
• 해결 패턴: 오류 분류를 먼저: relation 누락 / 컬럼 누락 / 방언 / 파라미터·계약 문제를 각각 다른 티켓으로. 일괄 "스키마 문제"로 뭉뚱그리면 헛수고.

1.5 시드는 반드시 멱등 + 데모 스코프 정렬 (kintex)

• 증상: 시드를 넣었는데도 정산·결제 등 행사스코프 화면이 텅 빔.
• 근본원인: 화면이 비는 진짜 원인은 데이터 부재가 아니라 시드가 데모 해소행사(workspaces[0]=start_date 최소, e-2026-live)에 안 묶임. 화면은 현재 선택된 행사 스코프로 조회한다.
• 해결 패턴: 데모 시드는 항상 "데모 계정이 실제로 진입하는 스코프(행사/테넌트/멤버십)"에 폐루프로 정렬. 403(행사 미가입)로 도면이 안 열리던 사고도 동일 계열 — 데모 계정 멤버십부터 확인.
• 연관 표준(kintex): FK 최소화+공통코드 소프트참조, tenant_id는 복합 PK 선두, 핫패스 인덱스·view/mview·배치 카탈로그를 데이터 표준 문서로 관리.

---

2. 배포 / CI-CD

2.1 웹훅 "완료" 로그인데 실제로는 no-op (1ms 진단법)

• 증상: push 해도 서버 반영 안 됨. 배포 로그는 "완료"로 찍힘.
• 근본원인 (guardia-rag에서 2중 결함): ① Gitea에 웹훅 자체가 없었음 ② 서버의 deploy_server.py가 구버전이라 해당 repo 처리 블록이 없어 웹훅을 받아도 1ms 만에 no-op 종료.
• 해결 패턴: 배포 로그가 '완료'여도 처리 시간이 1ms면 블록 부재를 의심하라. 점검 순서: Gitea 웹훅 존재/브랜치/시크릿 → 서버 deploy_server에 repo 블록 존재 → hook test로 E2E(pull→빌드→restart→health) 확인.

2.2 deploy_server.py는 서버 사본이 정본처럼 행동한다

• 증상: 로컬 저장소의 deploy_server.py를 고쳐도 배포 동작이 안 바뀜.
• 근본원인: 실제 실행되는 것은 서버 /opt/.../deploy_server.py 사본. 로컬만 고치면 무의미.
• 해결 패턴: deploy_server.py 수정 시 서버 사본 반영 + 서비스 재시작까지가 한 세트. 교체 전 .bak 백업.

2.3 Gitea 웹훅 3대 고전 이슈

• 증상: 웹훅 미발화 또는 403.
• 근본원인/해결: ① 웹훅 URL이 외부 도메인이면 NAT 헤어핀으로 실패 → localhost로 ② secret 불일치 → 403, 배포 서버 설정과 일치시킴 ③ Gitea app.ini ALLOWED_HOST_LIST에 loopback 미허용 → 추가.

2.4 배포 대상 경로가 git 체크아웃이 아니면 pull이 영원히 no-op

• 증상: guardia-rag — 웹훅·배포 스크립트 정상인데 서버 코드가 안 바뀜.
• 근본원인: /opt/guardia-rag가 git 저장소가 아니었음(수동 복사본) → git pull no-op.
• 해결 패턴: 배포 대상 디렉터리는 반드시 git 체크아웃으로 전환(데이터 디렉터리 보존) 후 자동배포 연결. 서버 HEAD 해시로 반영 검증.

2.5 배포 블록이 프론트만 배포하는 부분 결함

• 증상: manager — 프론트 변경은 반영되는데 백엔드 변경이 라이브에 안 나타남.
• 근본원인: deploy_server의 해당 블록에 백엔드 rsync/재시작 단계가 없었음.
• 해결 패턴: 배포 블록 신설·검증 시 프론트/백엔드/마이그레이션/재시작 4단계를 체크리스트로 확인. "일부만 배포되는" 블록은 정상처럼 보여 오래 숨는다.

2.6 Flyway 마이그레이션은 라이브 dry-run 후 배포 (kintex 표준)

• 증상: 마이그레이션 실패로 배포 롤백 반복.
• 해결 패턴: 배포 전 운영 DB에 BEGIN … ROLLBACK dry-run으로 신규 V 스크립트를 검증. 추가로 시크릿 fail-fast 프로파일 확인 + 배포 후 health 게이트 통과까지가 완료 조건.

2.7 공유 트리에서는 파일단위 커밋

• 증상: 여러 트랙이 같은 워킹트리에서 작업하다 서로의 미완성 변경이 교차 커밋됨.
• 해결 패턴: git add . 금지 — 자기 작업 파일만 명시적으로 스테이징(파일단위 커밋). kintex 다수 배포 사고 후 표준화.

2.8 자격증명 회전 시 배포 인프라 전체 동기화

• 증상: 일부 repo만 자동배포 죽어 있음(itsm/web/manager/docs).
• 근본원인: Gitea 비밀번호 회전 후 deploy_server와 서버 원격 사본에 구버전 자격증명이 잔존.
• 해결 패턴: 자격증명 회전은 "사용처 인벤토리 → 전 지점 일괄 갱신 → repo별 push/pull 검증"까지. 범용 push 스크립트로 지점 통일.

2.9 서버 빌드 산출 경로 함정

• 증상: 홈페이지 — 빌드 성공인데 라이브 미반영.
• 근본원인: 빌드는 /opt/.../src에서 하고 서빙은 별도 웹루트 — 산출물 복사 단계 누락.
• 해결 패턴: "빌드 위치 ≠ 서빙 위치"를 배포 스크립트에 명시. push 스크립트의 bundle 단계가 일시 실패하면 수동 bundle→SFTP→push 동일 경로로 복구 가능함을 기록해 둠.

---

3. AI / LLM

3.1 대형 모델 500 에러의 진범은 코드가 아니라 서버 RAM

• 증상: Ollama generate 500. 타임아웃을 늘려도(30→120s) 재발.
• 근본원인: 서버 가용 RAM ~1.5~2.6GiB인데 7B/8B 모델은 4.3~4.6GiB 필요 → model requires X GiB > available 500. swap은 무효 — Ollama는 물리 RAM만 검사한다.
• 해결 패턴: 소형 모델 채택이 정답: 비전=moondream, 텍스트=llama3.2:1b→qwen3:1.7b(+deepseek-r1:1.5b). 코드 수정(타임아웃)만으로 해결 안 되는 인프라 문제임을 먼저 판별하라(에러 메시지에 RAM 수치가 있음).

3.2 Ollama 타임아웃 표준 = 120s (전 시스템 통일)

• 증상: CPU 추론 콜드스타트에서 30s/45s 타임아웃으로 AI 기능 산발 실패.
• 해결 패턴: 전 솔루션 OllamaClient/HTTP 타임아웃을 generate·vision 모두 120s로 통일(10여 개 시스템 전수 수정 이력). 신규 클라이언트도 120s가 기본.

3.3 모델 태그 정확성 — :latest가 항상 있는 게 아니다

• 증상: /api/generate 404.
• 근본원인: 서버에 llava:7b로 pull된 모델을 코드가 llava( = :latest)로 호출.
• 해결 패턴: 서버 /api/tags 실측 태그를 그대로 사용 + model-status 진단 엔드포인트로 상시 확인 가능하게.

3.4 콜드로드 위험 관리

• 증상: 임베딩/검색은 가벼운데 생성·비전 호출 순간 서버 전체가 흔들림.
• 근본원인: 생성/비전 모델 콜드로드가 RAM을 순간 점유.
• 해결 패턴: 소형 모델 기본 + 비전 자동로드 금지 + 동시성 제한 + 실패 시 "검색만 degraded:true" 폴백(전체 다운 대신 부분 기능 유지).

3.5 폴백 체인과 프로바이더 아키텍처

• 패턴: 3계층 추론 폴백 Claude(외부 승인 단일 경로) → Qwen3(온프레미스 소형) → 기존 소형 모델. AiTextRouter+AiConfig 설정형 전환(UIWS 패턴). API 키는 서버 env에서만 로드 — DB·코드·커밋·로그·응답 기재 금지, 실패 시 자동 폴백.
• 경계 규칙: 솔루션은 중앙 guardia-rag 경유만 — 개별 솔루션에서 LLM 직접호출 신설 금지. 계약 URL 정합 주의(manager·mro에서 /feedback→/rag/feedback 오배선 실사례).

3.6 목표 스택 vs 개발서버 어댑터 분리

• 증상: 고객 목표 스택(Qwen3-32B·vLLM·Milvus·GPU)을 개발서버에 그대로 올리려다 실행 불가.
• 해결 패턴: 목표 스택은 어댑터/설정으로 정렬하되 개발서버(~2GB·GPU 없음)에서는 경량 폴백(소형모델·Chroma·Ollama) 강제, 대형 스택 실행 금지. 기본 env는 현행과 동일하게 유지해 회귀 0.

3.7 AI 답변은 근거 기반 + 데이터는 사전 적재 (kintex)

• 패턴: AI가 답하는 정보는 크롤링해서 DB에 먼저 적재(실시간 외부호출 금지), grounding+인용으로 환각 차단(abstain UX). 토큰 최소화: 결정론 라우팅·소형모델 우선·RAG 축소·캐싱·집계는 SQL로(LLM에 집계시키지 않는다).

---

4. 프론트 / UI

4.1 rollup win32 크래시 — 서버 빌드를 신뢰하라

• 증상: 로컬 Windows에서 Vite/rollup 빌드가 렌더 단계 크래시.
• 근본원인: rollup win32 네이티브 이슈(로컬 환경 한정).
• 해결 패턴: 로컬은 esbuild 등으로 문법 검증만 하고 실빌드는 서버(Linux) 빌드를 신뢰 → 배포 청크 검증으로 확인. 로컬 크래시 때문에 코드를 의심하지 말 것.

4.2 다크모드에서 컬러 버튼 글자가 어두워지는 버그

• 증상: 파란/컬러 배경 버튼·배지의 흰 글자가 다크모드에서 어두운 색으로 뒤집힘 (kintex 77곳+2곳).
• 근본원인: 텍스트 색이 테마 변수(전경색)에 묶여 다크 전환 시 함께 반전.
• 해결 패턴: 컬러 배경 위 텍스트는 --color-on-accent 전용 토큰(라이트/다크 모두 흰색)으로 분리. 신규 컴포넌트도 accent 배경이면 무조건 on-accent 사용.

4.3 병렬 로케일 편집 = 키 유실

• 증상: 다국어 작업 후 일부 i18n 키가 사라져 화면에 키 이름이 노출.
• 근본원인: 여러 에이전트/트랙이 공유 i18n JSON을 동시 편집 → 마지막 쓰기가 다른 쪽 키를 덮어씀.
• 해결 패턴: 로케일 파일 편집은 직렬화 + 편집 후 로케일 간 키 대조 게이트(ko/en/zh/ja 키셋 diff)를 통과해야 완료.

4.4 화면이 비는 원인은 UI 버그가 아닐 수 있다 (행사스코프)

• §1.5와 동일 사건의 프론트 측 교훈: "데이터 없음" 신고를 받으면 API 빈 응답인지, 스코프(선택 행사·권한) 문제인지, 시드 문제인지를 먼저 갈라라. 프론트 수정으로 덤비면 헛수고.

4.5 UI 레퍼런스는 문자 그대로 — 자체 재해석 금지

• 증상: "전부 WISE대로 안 되어 있다" 강한 소유자 피드백(셸·아코디언 메뉴·캘린더·대시보드·로고).
• 해결 패턴: 정본(UIWS frontend / Nifty ui-elements)을 구조 그대로 이식하고 토큰만 번역(kx). 디자인 기준은 학습 md(DESIGN_SYSTEM_NIFTY.md 등)로 문서화해 재해석 여지를 제거. 아이콘은 이모지 금지·선(stroke) SVG 직접 제작.

4.6 홈/진입 IA를 기획 1순위로

• 증상: 84화면을 설계하고도 로그인 후 홈이 누락되는 사고.
• 해결 패턴: 기획 단계에서 역할별 랜딩(디폴트 visitor, 로그인 후 role→홈 라우팅)과 메뉴 게이트를 최우선 정의. 미인증 루트는 로그인 폼이 아니라 제품 소개 히어로 랜딩.

4.7 이미지 프레임과 실측 비율 정합

• 증상: 세로 포스터가 16:11 가로 카드에 늘어남/잘림.
• 해결 패턴: 에셋 실측 비율(0.67~0.8)에 맞춘 프레임(3:4) + object-fit: cover. 외부 이미지는 다운로드해 빌드 내장(핫링크 금지)이 기본.

4.8 Stitch(외부 디자인 도구) 불안정 시 문서화 폴백

• 증상: Stitch 생성 2회 연속 실패로 화면 작업 블로킹.
• 해결 패턴: design.md에 스펙이 이미 있으므로 스펙 직접 구현으로 폴백하고 폴백 사실을 문서화. 외부 도구는 경유 원칙이되 단일 실패점이 되게 두지 않는다.

4.9 기타 잔사고

• favicon: repo의 favicon.ico가 톰캣 기본 아이콘인 채 배포 — 브랜드 에셋도 검증 대상.
• CSS 변경 미반영 신고: 실제로는 브라우저 캐시 — 배포 검증은 번들 해시/청크 내용으로.
• 반응형: 전 화면 풀블리드·전 브레이크포인트·빈 여백 금지를 전역 NFR로 못 박아야 화면별 재작업이 줄어든다.

---

5. 프로세스 / 하네스 운영

5.1 하네스 workspace-루트 등록 누락 (반복 사고)

• 증상: 스킬/에이전트를 만들었는데 루트 세션에서 트리거되지 않음.
• 근본원인: 하네스가 workspace/<sol>/.claude/에만 존재 — 루트 .claude/에 미등록 (ITSM·Manager·UIWS·ESN·OCR 등 다수 사후 등록 이력).
• 해결 패턴: 하네스 생성 시 사용 위치(루트 vs 솔루션) 기준으로 등록 위치를 확정하고, 주기적 "하네스 감사"로 ①루트 미등록 스킬 ②오케스트레이터가 참조하나 어디에도 존재하지 않는 에이전트(crm-* 4종, solution-devops-dev 실사례)를 검출·보수.

5.2 MyBatis @MapperScan은 annotationClass를 지정하라

• 증상: OCR 기동 크래시 — TemplateMapper 빈 누락.
• 근본원인: 광범위 @MapperScan이 인터페이스 스캔을 오동작.
• 해결 패턴: @MapperScan(annotationClass = Mapper.class) 표준 — @Mapper 붙은 인터페이스만 빈 등록. 표준 프레임워크 명세에 편입됨.

5.3 Spring bean 이름 충돌

• 증상: 신규 모듈 추가 후 기동 실패(bean-name collision).
• 근본원인: system/message와 기존 work/message처럼 다른 패키지의 동일 클래스명이 같은 빈 이름 생성.
• 해결 패턴: 공통 명사(message·notice 등) 모듈 신설 시 기존 패키지와 클래스명 충돌 여부 grep 후 명명(접두사) — 컴파일은 통과하고 기동에서 터지므로 배포 전 기동 테스트 필수.

5.4 공유 파일 단일 소유 규칙

• 증상: 여러 에이전트가 App.jsx(라우팅)·네비게이션·i18n 등 공유 파일을 동시 수정 → 충돌·회귀.
• 해결 패턴: 오케스트레이션 시 공유 파일은 단일 에이전트가 소유(예: 라우팅·네비 = renewal-dev 단독)하고 나머지는 요청만 한다. 데이터 목록(solutions.js 등)은 스프레드 병합 대신 단일 출처 유지.

5.5 소유자 피드백은 권위 로그 파일로 전수 기록

• 패턴: 세션 중 지시를 docs/OWNER_FEEDBACK.md 같은 단일 권위 파일에 상태(완료/배포중/대기)와 함께 전수 기록 — 누락 방지와 "다시 실행" 요청의 기준점이 된다. 처리 로그(커밋 해시·마이그레이션 번호)도 함께.

5.6 산출물(문서) 갱신 정책

• 패턴: 개발계획서·설계서는 개발 전/중 1회, 사용자·운영자 지침서는 완성+QA 후 최종 메뉴 기준 1회. UI가 요동치는 중에 지침서를 만들면 전량 재작업(비용) — "최초 1회 + 최종 1회, 중간 갱신 금지".

5.7 하네스 간 경계(중복 회피) 명시

• 패턴: 신규 하네스는 반드시 인접 하네스와의 경계를 선언(예: 검색 인프라=rag, 환각방지=ai-trust, 이 하네스는 그 위 레이어만). 경계 없는 하네스는 서로 같은 파일을 재구현하며 §5.4 사고를 낳는다.

5.8 오류 응답·보안 불변

• 패턴: 스택트레이스는 절대 노출하지 않고 ID+요약만 반환(§1.1의 누출 차단 핸들러와 세트). 자격증명·IP·키는 코드/커밋/로그/문서 어디에도 기재 금지 — 지식 문서(본 문서 포함)도 동일.

5.9 "동작 안 함" 신고는 실경로부터 확인

• 증상: fa 솔루션 미인증 POST가 405 — 라우트 고장으로 오인.
• 근본원인: 라우트는 정상, 실제 경로가 다름(/api/fa/auth) — 기존 특성.
• 해결 패턴: 고장 신고를 받으면 수정 전에 정상 계약(실경로·필수 파라미터·인증 요구)을 먼저 실측해 "고장"인지 "오사용"인지 판별.

---

6. 인프라 / 보안 운영

6.1 Java 서비스 env 주입은 systemd drop-in으로

• 증상: 전 서비스에 공통 환경변수(AI 키·admin 비번 참조)를 배포해야 하는데, 대부분의 Java 서비스가 EnvironmentFile 없이 명령줄 인자로 기동됨.
• 해결 패턴: 기존 유닛 파일과 ExecStart를 건드리지 않고 systemd drop-in(ai-env.conf)으로 EnvironmentFile만 추가 + daemon-reload. 17개 서비스에 무중단 일괄 적용된 검증 패턴.

6.2 시크릿은 서버 내부에서 생성·암호화하고 값은 어디에도 남기지 않는다

• 패턴: admin 비밀번호는 서버에서 랜덤 생성 → AES-256-GCM 암호화 파일(600) + 별도 키파일(root 600) + root 전용 복호 헬퍼로 관리. 전 과정이 서버 내부 crypto로 이뤄져 세션 로그·커밋·문서에 값이 노출될 여지 자체를 제거. admin123 류 시드 하드코딩은 표준 위반.

6.3 인증 표준: JWT+RBAC 위에 2FA를 "레이어로만" 추가

• 증상: 인증 이식 시 기존 auth를 통째로 교체하면 전 사용자 로그인 장애.
• 해결 패턴: 기존 auth가 있으면 교체 금지 — 2FA(TOTP RFC6238)만 레이어 추가, 없으면 전체 이식. 로그인 실패 잠금 포함. 토큰 키는 앱별 분리(예: uiws_*)로 세션 간섭 방지.

6.4 읽기전용/시간 가드는 백엔드+UI 이중 방어

• 증상: "금일 이전 업무일지 조회 전용" 같은 정책을 UI에서만 막으면 API 직접 호출로 우회됨.
• 해결 패턴: 백엔드 403(저장된 데이터 기준 판정, 파라미터 조작 우회 차단) + UI 차단의 이중 방어. 판정 기준은 요청값이 아니라 저장된 값(workDate)이어야 우회가 안 된다.

6.5 외부 클라우드·발송 채널은 소유자 승인 게이트

• 패턴: EAS 클라우드 빌드(G3), SMTP 발송, root SSH, 외부 API(Anthropic 단일 예외) 등 경계를 넘는 작업은 승인 게이트로 명시하고 승인 전엔 준비물(eas.json·에셋)까지만 진행. 승인 이력은 CLAUDE.md/메모리에 날짜와 함께 기록.

6.6 상시 회귀 테스트를 배포 완료 조건으로

• 패턴: 전 시스템 공용 회귀 스위트(예: 126/126)를 배포·수복 후 반드시 재실행 — "고친 것"과 "깨뜨린 것"을 같은 게이트로 검증. 테스트 스크립트의 인증도 하드코딩 대신 런타임 조달(암호화 저장소)로 유지.

6.7 API 응답 스키마에서 민감 컬럼은 구조적으로 제외

• 패턴: ip_addr·ssh_user·os_pw_enc 같은 컬럼은 마스킹이 아니라 응답 스키마(ServerOut)에서 아예 제외 — 실수로 새는 경로를 구조적으로 차단. 자격증명 컬럼은 AES-256-GCM 암호화 저장.

---

7. 검증(QA) 운영

7.1 경계면(shape) 교차 검증은 모듈 완성 "직후" 점진 수행

• 증상: 백엔드 봉투(PageResponse)를 프론트가 배열로 언랩하거나, audioId 타입 불일치 등 — 컴파일은 통과하고 런타임에서만 터짐(UIWS 모바일 실사례 2건).
• 해결 패턴: 백엔드 응답 shape과 프론트 호출부를 동시에 읽어 교차 비교하는 QA를 각 모듈 완성 직후 돌린다. 전부 만든 뒤 몰아서 하면 수정 범위가 폭발.

7.2 "적용 완료" 판정은 라이브 실측으로

• 패턴: 대규모 전파(WISE 18종 등) 후 완료 판정은 ①health 게이트 ②스팟체크(라우트+인증 가드) ③실 E2E(대표 시나리오 1건) ④전체 회귀의 4단계. 파일만 바뀐 것과 라이브에 반영된 것은 다르다(§2 전반의 이유로).

7.3 대량 전파는 감사 매트릭스 → 웨이브 병렬 → 직렬 배포

• 패턴: N개 솔루션 일괄 작업은 먼저 유형 매트릭스 감사(브랜딩만/승격/보강/신규)로 분류 → 유형별 웨이브 병렬 구현 → 배포는 직렬(health 게이트 하나씩). 병렬 배포는 장애 원인 격리를 불가능하게 한다.

---

부록: 배포 전 체크리스트 (교훈 요약)

1. 스키마: 신규 테이블/컬럼이 mode 정책상 실제 적용되는가? 시드 멱등? (§1.1~1.2)
2. Flyway: 라이브 BEGIN…ROLLBACK dry-run 통과? (§2.6)
3. 커밋: 파일단위 스테이징인가? 공유 파일 소유자 확인? (§2.7, §5.4)
4. 웹훅: 배포 로그 처리시간 1ms 아님? 서버 HEAD 갱신 확인? (§2.1, §2.4)
5. 배포 블록: 프론트+백엔드+마이그레이션+재시작 4단계 모두? (§2.5)
6. health 게이트 통과 + 번들/청크 실측 검증(캐시 아님 확인)? (§2.6, §4.9)
7. 기동 테스트: bean 충돌·매퍼 빈 누락 없음? (§5.2~5.3)
8. AI: 소형모델·120s·태그 실측·중앙 rag 경유? (§3.1~3.5)
9. 시드: 데모 계정이 진입하는 스코프에 묶였는가? (§1.5)
10. 보안: 스택트레이스·자격증명·키 미노출? (§5.8)