# 상품 상세 본문 렌더 가이드 — 블록 본문·중간 이미지·공유 CSS

저장된 상품 상세를 **쇼핑몰 화면에 그리는 쪽**의 계약이다. 블록을 작성·저장하는 법은 `get_doc('product/content-blocks')` 를 본다.
같은 내용이 MCP 내장 문서 `get_doc('product/block-rendering')` 과 skill `references/product-block-rendering.md` 에 있다.

## 1. 상세 응답 필드의 역할 (GET /v1/products/:id)

| 필드 | 역할 | 렌더에서 |
|---|---|---|
| `content` | 렌더용 본문 HTML. 블록 상품이면 서버가 `content_blocks` 를 컴파일해 함께 저장한 결과다 | 1순위 |
| `content_type` | 편집 방식 표시(블록·이미지·HTML 등). `image` 인데 compiled `content` 가 있는 실상품이 있다 | 원천 판정에 쓰지 않는다 |
| `content_images` | 이미지형 상세의 별도 이미지 목록 | `content` 가 비었거나 정제 후 남는 것이 없을 때만, 원래 순서로 |
| `content_blocks` | 편집 원본(JSON). 공개 응답에 항상 온다고 가정하지 않는다 | 쓰지 않는다(다시 컴파일하지 않는다) |
| `images` | 대표 갤러리 | 상세 본문과 섞지 않는다 |

`generate_commerce_code(framework: "nextjs")` 생성물의 `Product` 는 이 값을 이렇게 옮긴다:
`detailHtml` = `content`(trim) · `detailText` = `content` 의 평문 · `detailImages` = `content_images`(https URL 만, 순서 유지) · `contentType` = `content_type` 문자열(없으면 `''`).
빈 `content` 는 정상 상태이고 조회 실패(HTTP 오류)와 다르다 — 조회 실패는 상세 화면의 오류 상태로 따로 처리한다.

## 2. 렌더 원천 우선순위

1. **비어 있지 않은 `content`** — 정제 후 글자나 이미지가 남으면 이것만 그린다. `content_type=image` 여도 버리지 않는다.
   중간 이미지를 뽑아 별도 갤러리로 옮기거나 `content_images` 를 뒤에 덧붙이지 않는다(중복·재배열이 된다).
2. `content` 에 태그가 없으면 평문이다 — escape 된 글자로 그린다(줄바꿈 유지).
3. `content` 가 비었거나 정제 후 남는 것이 없으면 **`content_images` 를 원래 순서로** 그린다.
4. 그것도 없으면 서버가 만든 평문(`detailText`), 그것도 없으면 **명시적 빈 상태**("상세 설명이 아직 등록되지 않았어요.").

## 3. 정제 계약 — 원문을 그대로 주입하지 않는다

- 원문은 실행되지 않는 `<template>` 에 파싱만 하고, 허용 태그·속성만 React 요소로 다시 만든다.
  `dangerouslySetInnerHTML`·`v-html`·`{@html}` 로 원문을 넣지 않는다. 정규식만으로 HTML 을 정제하지 않는다.
- 허용 태그: `p div section span br b strong i em u s a ul ol li h2~h6 table caption thead tbody tfoot tr th td figure figcaption img blockquote hr details summary`.
- 통째로 버리는 요소(안의 글자까지): `script style template noscript iframe object embed form input button select textarea svg math video audio link meta` 등.
  그 밖의 모르는 서식 태그(`font`·`center` 등)는 벗기고 안의 글자와 순서는 남긴다.
- 속성: `class`(계약 JSON 의 `classes`+`legacyAliases` 만, 게이지 칸의 `is-on` 예외), `title`, `aria-hidden="true"`, `aria-label`, `role="img"`,
  `a[href]`(새 탭 + `rel="noopener noreferrer"`), `img[src|alt]`, `th/td[colspan|rowspan|scope]`, `details[open]`. `on*`·`style`·`id`·`srcset`·`target` 은 버린다.
- URL: 자격증명 없는 `https://` 절대 URL, 또는 루트 기준 상대 경로(`/uploads/a.jpg`)만. `javascript:`·`data:`·`http:`·`//host`·역슬래시·`/api/`(BFF) 경로는 버린다.
- 인라인 style 은 옮기지 않는다. 컴파일러가 붙이는 유일한 값(`max-width:100%;height:auto`)은 CSS 가 같은 제한을 건다.
- 너무 큰 본문(1,000,000자 초과)·깊은 중첩(64단계)·노드 12,000개 초과는 그리지 않고 다음 원천으로 넘어간다.

## 4. 이미지

- 본문 이미지의 `src`·`alt`·순서를 그대로 둔다. `alt` 가 비면 "상품명 상세 이미지".
- `loading="lazy"`·`decoding="async"`·`max-width:100%; height:auto`. 커버·비율 사진의 높이는 공유 CSS 가 정한다.
- 깨진 이미지는 **그 자리에** "…— 이미지를 불러오지 못했어요." 대체 문구를 남긴다. 뒤 문단은 그대로 이어진다.

## 5. 공유 CSS·클래스 계약

- 파일: `product-detail.css` + `product-detail.contract.json` — bootservice/vendor(commerce-front `src/vendor` 서브모듈),
  vendor commit `62b4f8ec23f3e97a9335f363b994691ecd453a81`.
- SHA-256: css `a6fa3af410e4cfc05dc35e4deeef536ba81079639cb45c8c24840ae756891cbd` · contract `ccd24537d60db695c6f6d8beaecd9d3a97b9c189534c68307a918d0ced844b44`.
  contractVersion(`1.0.0`) 문자열만으로 최신 여부를 판정하지 않는다.
- 블록 18종(heading · text · image · imageText · features · specs · notice · html · subscriptionPlan · cover · steps · stats · faq · compare · policyBadges · sizeGuide · meterGroup · fitFor)과
  섹션 틴트·cover·imageText·FAQ·표·인라인 아이콘·반응형 규칙이 이 CSS 한 벌에 들어 있다.
- 루트 래퍼는 `bp-detail-view`. 실제 몰은 `bp-detail-view is-responsive` 로 감싸 768px 이상에서 PC 모양이 된다.
  몰 톤은 `--bp-detail-link`·`--bp-detail-radius-scale`·`--bp-detail-scale` 변수로만 조정한다.
- 형제 저장소의 product-detail-css 1.0.0(dist)은 cover 등 확장 블록 규칙이 없는 이전 판이다. 최신이라 부르거나 대체하지 않는다.
- **확보 경로**: `generate_commerce_code(framework: "nextjs", step: "detail" 또는 "all")` 생성물의 `vendor/product-detail/` 에
  CSS·contract·`manifest.json`(commit·SHA-256·바이트)·README 가 바이트 그대로 들어 있다. 공개 CDN·npm 단독 패키지는 없다 — URL 을 지어내지 않는다.
- 검증: `shasum -a 256 vendor/product-detail/product-detail.css vendor/product-detail/product-detail.contract.json` 결과를 manifest 와 비교한다.

## 6. Next.js 생성 파일 (framework: "nextjs")

| 파일 | 내용 |
|---|---|
| `components/product-detail-body.tsx` | `ProductDetailBody({ product })` — 루트 `bp-detail-view`, 자기 CSS import |
| `components/product-detail-body.css` | 래퍼 최소 규칙(이미지 폭 제한·상태 문구·깨진 이미지). 공유 CSS 를 덮지 않는다 |
| `lib/product-detail-content.ts` | DOM 없는 순수 규칙 — 허용 목록·URL 검사·원천 판정(`selectDetailView`) |
| `vendor/product-detail/product-detail.css` | 공유 CSS 원본 |
| `vendor/product-detail/product-detail.contract.json` | 클래스 계약 원본 |
| `vendor/product-detail/manifest.json` | 출처·commit·SHA-256 |
| `vendor/product-detail/README.md` | 검증 명령·갱신 규칙 |

`ProductDetailBody` 의 입력은 `Pick<Product, 'name' | 'detailHtml' | 'detailText' | 'detailImages' | 'contentType'>` 이다.
루트에 `data-detail-source`(html·text·images·empty)가 붙어 어떤 원천으로 그렸는지 확인할 수 있다.

## 7. 확인용 예제 (Next.js)

생성 후 아래 페이지를 추가하고 `next dev` 로 `/detail-fixture` 를 열면 렌더 계약을 네트워크 없이 확인할 수 있다.
중간 이미지는 예시 도메인이라 불러오지 못하고, 그 자리에 대체 문구가 남은 채 뒤 문단이 이어져야 한다.

```tsx
// app/detail-fixture/page.tsx
import { ProductDetailBody } from '@/components/product-detail-body';

const product = {
  name: '예시 상품',
  contentType: 'block',
  detailHtml:
    '<div class="bp-detail"><div class="bp-text description-text">앞 문단</div>' +
    '<div class="bp-images bp-ratio-origin bp-images-stack"><figure class="bp-image">' +
    '<img src="https://images.example.test/middle.jpg" alt="중간 사진" loading="lazy"></figure></div>' +
    '<div class="bp-text description-text">뒤 문단</div>' +
    '<div class="bp-faq"><details class="bp-faq__item"><summary class="bp-faq__q">세척 방법은?</summary>' +
    '<div class="bp-faq__a">마른 천으로 닦아 주세요.</div></details></div></div>',
  detailText: '',
  detailImages: [],
};

export default function DetailFixturePage() {
  return (
    <main style={{ maxWidth: 860, margin: '0 auto', padding: 16 }}>
      <ProductDetailBody product={product} />
    </main>
  );
}
```

## 8. 검증 체크리스트

- 390px·768px·1440px 에서 문서 전체 가로 넘침이 없다(`document.documentElement.scrollWidth <= innerWidth`). 실측표는 자기 칸 안에서만 가로 스크롤된다.
- 블록 상품(`content_images=[]`)의 인라인 이미지 수·`src` 순서·문단 사이 위치가 원문과 같다.
- 중간 이미지 하나가 실패해도 그 자리에 대체 문구가 있고 뒤 문단이 보인다.
- imageText 는 넓은 화면에서 사진 옆·좁은 화면에서 계약 CSS 대로 접히고, FAQ 는 JS 없이 열리고 닫힌다. 표의 `scope`·`colspan` 이 남는다.
- `script`·`on*`·`javascript:`·`data:` 이미지·`iframe`·`form` 이 화면에 남지 않는다.
- 운영 상품 수정·이미지 업로드·실결제로 확인하지 않는다. 운영 GET 결과와 fixture·mock 브라우저 결과를 구분해 기록한다.
