ChannelTalk Clone — Session F: Backend Mapping Inspector (완료)

Date: 2026-07-06 KST · Baseline: 91899d8 (A/B/C/D 통합) · E(비주얼) 완료 위에서 작업

BLUF

docs/mapping/p0-guide-backend-map.json(2.6MB, 24 가이드)을 로컬 SQLite로 임포트하고, guide→surface→services→endpoints→DB tables/fields 전체 체인을 관측/추론 신뢰도와 증거 경로와 함께 탐색하는 인스펙터를 클론 내부에 구축. 기존 /api/mappings 계약과 ALF BackendMapStrip은 무손상 재사용.

핵심 설계

기존 surface_mappings(평탄 요약)는 field별 신뢰도·증거 손실 → ARCHITECTURE.md가 명시한 guide_records 테이블 신설(SCHEMA_VERSION 0003_guide_records)로 전체 충실도 저장.
임포터가 snake_case 원본 → camelCase 리치 DTO 정규화 후 upsert(canonical_key 멱등, 재임포트 안전).
관측(observed)=실제 네트워크 캡처, DB 테이블/필드=대부분 clone_inferred → UI에서 명시적으로 대비/경고.

변경 파일

신규:

src/server/db/import-mappings.ts (임포터 + CLI)
src/app/api/mappings/guides/route.ts (리치 목록 API)
src/app/mappings/{layout,page}.tsx, src/app/mappings/[key]/page.tsx
src/components/mappings/{types.ts, ui.tsx, MappingChrome, MappingInspector, GuideDetail}.tsx 수정(F 소유):
src/server/db/schema.ts (guide_records + index, 버전업)
src/server/dto/mapping.ts (GuideRecord 리치 DTO)
src/server/repositories/mapping-repository.ts (guide record CRUD)
src/server/services/mapping-service.ts (listGuides/getGuide, surface 폴백)
src/app/api/mappings/guides/[key]/route.ts (리치 상세로 확장, 하위호환 폴백)
src/server/db/seed.ts (demo seed에 guide import 통합, 파일 없으면 경고만)
package.json (db:import:mappings 스크립트)
src/components/inbox/InboxWorkspace.tsx, src/components/alf/AlfChrome.tsx (레일 "Backend" 스텁 → /mappings 링크 배선; 최소 편집)

명령/검증 (모두 통과)

npm run db:seed → guide_records=24 임포트, surface_mappings=5 무손상
npm run lint → pass (0 error/warning)
npm run build → pass, 신규 라우트 /mappings, /mappings/[key], /api/mappings/guides 등록
curl /api/mappings → 기존 5 surface 정상(회귀 없음)
curl /api/mappings/guides → 24 리치 레코드 + 18 surface facet + 필터 동작
curl /api/mappings/guides/help:c2d439c6 → 52 observed 엔드포인트, clone_inferred 필드, open_questions·증거경로(docs/runtime/local) 보존, 관측 응답 키
스크린샷: 데스크톱 인덱스/상세, 모바일 인덱스 (가로 스크롤 없음)

규칙 준수

증거 경로 보존 ✓ (docs/runtime_capture/local_text/static_chunk 카테고리별 표시)
추론 DB 이름을 실제 ChannelTalk 내부로 단정하지 않음 ✓ (clone_inferred 라벨 + 경고 배너 + open_questions)
불확실성 가시화 ✓ (엔드포인트별 관측/추론 배지, 필드별 신뢰도 색상)
Inbox/ALF 광범위 리스타일 없음 ✓ (E 소유 프리미티브는 import 재사용만)

블로커

없음. (기존 Turbopack NFT 경고는 A/B/C/D부터 존재, 비차단)

다음 액션(권장)

Session G(Mattermost POC) 또는 P1(Analytics/Workflow) 진행 가능
커밋 미실행(사용자 요청 대기): F 변경 + E 미커밋 비주얼 작업이 워킹트리에 공존
향후: observed_response_fields의 전체 스키마(현재 top-level 키만 저장)를 별도 뷰로 확장 여지