HCS Fragment Server Overlay — E2E Handoff

Spec: README.md (같은 폴더)

서버 (makitt-server)

• KeyPrefix — HCS_FRAGMENT, HCS_FRAGMENT_LIST_GLOBAL, ENTITY_HCS_FRAGMENT 추가
• HcsFragmentKey, HcsFragment (entity), HcsFragmentRepository, HcsFragmentService 신설
• HcsFragmentApplication (순수 persistence — validation 책임 X)
• HcsFragmentController — PUT/GET-list/GET-one/DELETE /api/v1/hcs/fragments[/{id}]
• SecurityConfig — /api/v1/hcs/** permitAll (개발 단계)

Compiler (apps/compiler)

• services/fragment-overlay.service.ts — makitt-api 호출 (list/put/delete)
• services/fragment-library.service.ts — bundle cache + fresh server overlay merge (server 우선)
• routes/fragments.ts — POST /fragments/{id} (synthetic shop 으로 wrap → runValidationPipeline 3단 검증 → 200/422 분기 → 200 시 makitt-api PUT) + DELETE /fragments/{id} (pass-through)
• app.ts — CORS PUT/DELETE 추가, fragmentsRouter 등록

Builder (apps/builder)

• lib/fragment-library-loader.ts — bundle sync 유지 + module load 시 server overlay fire-and-forget fetch + refreshServerFragmentOverlay() export

Compiler 는 tsx watch 모드라 hot-reload 자동 반영. 다음을 라이브로 확인:

#	호출	결과
C1	POST /fragments/test-probe (정상 fragment)	200 validation 통과 → persist 단계로 진입 (현재 makitt-api 미재기동이라 phase:persist 에서 fail — 정상)
C2	POST /fragments/totally-broken (badtype 포함)	422 + 3 errors (STRUCTURE_INVALID_TYPE / HIERARCHY_INVALID_CHILD / HIERARCHY_INVALID_PARENT) — gate 동작

→ Validation pipeline 통째로 라이브 동작 확인. synthetic shop wrap 패턴 (state[], content[], i18n, imports[모든 라이브러리], shop.fragments) 으로 확정.

#	시나리오	기대 결과	상태
1	bundle 에 있는 order-cancel-form-default 동일 id 로 server PUT (label 변경)	200 + clean 진단	C1 부분 통과 (validate OK, persist 단계는 server 재기동 필요)
2	makitt-api GET /api/v1/hcs/fragments 에서 등록 확인	total ≥ 1, fragmentId 존재	server 재기동 후
3	builder 새로고침 (재기동 X)	FragmentsPanel 에 신규 label 노출	server 재기동 후
4	헨리엣 compiler /save 호출	compiled-shop 에 신규 label 반영 → shop URL 에 변경	server 재기동 후
5	깨진 fragment (badtype 등) PUT	422 + validations.errors ≥ 1, DB 무손상	C2 통과 ✅
6	server entry DELETE	builder/compiler 가 bundle 본 fallback	server 재기동 후

• 검증 통과 후 본 spec 폴더를 docs/spec/finished/hcs-fragment-server-overlay/ 로 이동

• MEMORY.md 의 "📌 다음 세션 진입점" 갱신 — 다음 작업 = "Henriette PDP 리뷰 영역 작업 (snapshot-node 으로 노드 합의 → review fragment 작업)"

• Promotion skill — server 안정화된 fragment → bundle library.json 으로 흡수 + server 삭제. /promote-fragment <id> 단발 호출.

• Per-shop scope — global 외에 shop-scoped fragment overlay (헨리엣 전용 fragment 등 등장 시).

• Contract 서버화 검토 — fragment server 화로 충분한지 6개월 운영 후 재평가.