RealLux V3 — 관리자 마케팅 고도화 + 네이버쇼핑 EP 연계 실구현

날짜 2026-07-21 · 서비스 reallux.crowny.org:9985 (crowny-reallux) · 스펙 SSOT /Users/ef/crowny-reallux/SPEC-V3.md

개요

사용자 지시: "reallux 쇼핑몰 관리자페이지 마케팅기능 고도화. 네이버쇼핑에 연계하는 방법, 연계할 때 상품마다 연계되는 상품/연계 안되는 상품 구분하는 방법 실제 구현." + 참고 대상으로 식스샵·아임웹·카페24 관리자페이지 지정.

0. 착수 시점에 발견한 사고 — 서비스가 죽어 있었음

https://reallux.crowny.org → 503. 원인은 게이트웨이가 아니라 데몬 자체가 없었음(LaunchAgent 미등록, 수동 node server.js로만 떠 있던 서비스가 종료된 상태). → ~/Library/LaunchAgents/org.crowny.reallux.plist 신규 등록(KeepAlive, REALLUX_PORT=9985, REALLUX_BASE_URL). 이후 상시 구동.

1. 조사 (울트라 6에이전트, 530k 토큰)

네이버 EP3.0 규격 — 공식 PDF 2본 확보 + 적대 교차검증(확실/추정/불확실 등급화)
연계불가 조건 30항 체크리스트 → 자동판정 가능/수동확인 분류
식스샵/아임웹/카페24 마케팅 메뉴 전수조사 — 각 30~35개 기능 표

핵심 확정 사실:

EP = TSV(탭구분), UTF-8 BOM 금지, 첫 행 헤더 필수, .txt
필수 필드: id, title, price_pc, link, image_link, category_name1, shipping
shipping: 0=무료배송, -1=착불
image_link: 300×300px 이상(500×500 권장), 4000×4000 이하, 4MB 미만
price_mobile은 2024-06-28부로 수신 중단 → 생성하지 않음
검수 1~2 영업일, 미노출 상품은 파트너센터 > 상품관리 > 상품현황 및 관리 > 미서비스 상품
⚠ 상품명 허용 특수문자 화이트리스트는 출처마다 상충 → 자동차단 규칙화 보류(경고만)

2. 구현 산출물

한선씨 엔진 (판정 SSOT)

파일	내용
`한선씨/네이버연계.한선` (21KB)	R01~R18 판정, 4상(티/옴/타/음), EP 값 정제, 요약EP I/U/D
`한선씨/마케팅.한선` (9KB)	기간할인·쿠폰유효·쿠폰할인액·최종결제금액·배송비판정

STRICT 컴파일 경고 0, crownyc run 자체검증 각 20 assert 전항목 PASS(2회 재호출 오염 검증 포함).

server.js (962 → 1890줄, 제로 의존성 유지)

GET /ep/reallux.txt (전체 EP, 25컬럼) · GET /ep/reallux-brief.txt (요약 EP, class+update_time 선두)
네이버 관리자 API 5종: naver/audit, naver/settings GET·PUT, naver/override/:code, naver/preview
마케팅 API: 쿠폰 CRUD·검증·사용내역, 기간할인 CRUD, 재입고 알림, 팝업·배너, marketing/stats
GET /api/marketing/public (배너·팝업 공개 노출)
GET /sitemap.xml, GET /robots.txt
주문 확장: 기간할인·쿠폰 서버 재계산(클라 조작 무시)
index.html </head> 주입: SEO 메타·OG·소유확인(네이버/구글)·GA4·GTM·네이버애널리틱스·메타픽셀·카카오픽셀·customHead. admin.html에는 미주입
R06 이미지 규격은 PNG/JPEG/WebP/GIF 매직바이트 직접 파싱(외부 라이브러리 없음)

관리자 UI (admin.html/admin.js, 967 → 1566줄)

사이드바 신규 3섹션 + 대시보드 카드 3개

마케팅: 쿠폰 / 기간할인 / 팝업·배너 / 재입고 알림 (4탭 + 모달 CRUD)
네이버쇼핑: EP 토글·URL 복사·파트너센터 등록절차 안내 · 4상 현황카드(클릭 필터) · 카테고리 매핑표 · 상품별 판정 테이블(배지+사유+오버라이드) · EP 미리보기 · 수동확인 안내
SEO·추적: SEO 메타 / 소유확인 2종 / 추적ID 5종 + customHead

스토어프론트 (app.js/style.css)

최상단 배너 · 팝업(N일 숨김) · 기간할인 실판매가 반영 · 쿠폰 입력·적용 · 품절 사이즈 재입고 알림 폼 · 상품 상세 JSON-LD Product 스키마

3. "연계되는 상품 / 안 되는 상품" 구분 방식

4상균형3진 판정 — 우선순위 차단(타) > 수동확인(음) > 경고(옴) > 통과(티)

상	판정	EP 포함
티	연계가능	✅
옴	보완필요(경고)	✅
타	연계불가(차단)	❌
음	수동확인(사람 판단 필요/강제제외)	❌

차단(타): R01 필수필드 누락 · R02 판매가 0 이하 · R03 상품명 100자 초과 · R04 제어문자 · R05 이미지 없음 · R06 이미지 규격 미달 · R07 배송비 범위 위반 · R08 재고 0 경고(옴): R09 네이버 카테고리 미매핑 · R10 가격비교ID 없음 · R11 홍보문구 · R12 반복 특수문자 · R13 그림문자 · R14 정가<판매가 · R15 권장필드 길이초과 · R17 브랜드/원산지 미입력 수동확인(음): R16 판매금지·제한 품목 의심(주류·담배·의약품 등) · R18 관리자 강제제외

4. 검증 실측 (게이트 9/9 PASS)

node --check 3파일 PASS · 한선씨 2본 STRICT 0경고 + assert 전항목 일치
EP 무결성: 헤더 25컬럼, 전행 컬럼수 일치, BOM 없음(69 64 09 = id\t), price_mobile 없음, \r 없음
위반 상품 6종 인위 생성 → R02/R05/R03/R08/R06/R16 정확 판정 + EP 제외 실증 → 정리
서버 재계산 검증: 클라가 price=1, couponDiscount=999999 전송해도 서버가 무시하고 자체 계산값 사용
기존 API 전수 회귀 0
공개 HTTPS 6경로 200: /api/health /admin /ep/reallux.txt /ep/reallux-brief.txt /sitemap.xml /robots.txt

종단 실증: RL-101에 600×600 이미지 부여 → 연계불가 → 보완필요(R09,R10)로 전환 + EP 본문에 실제 출현 → 원복 후 다시 연계불가. 판정↔EP 연동이 실제로 작동함을 확인.

5. 메인 세션이 직접 수리한 결함 2건

등급	내용	수리
P1	`/api/marketing/public` 부재 → 배너·팝업이 영영 안 뜸(스토어프론트 에이전트가 소비자만 구현)	공개 라우트 추가
P2	SEO description/keywords 주입 시 index.html 정적 태그와 중복	주입값 있으면 정적 태그 선제거

6. 잔여 이슈 (사용자 조치 필요)

★ 현재 상품 16개 전부 연계불가 — 사유: images: [](상품 이미지 미등록). 네이버 EP는 image_link 필수 + 300×300px 이상이라 이미지 없이는 구조적으로 연계 불가. 관리자 > 상품관리에서 상품 사진을 올려야 연계 시작됨.
네이버 카테고리 ID 미매핑(R09 경고) — 파트너센터 카테고리 코드를 관리자 > 네이버쇼핑 > 카테고리 매핑표에 입력해야 매칭 품질 상승.
파트너센터 등록은 사람이 해야 함 — 관리자 화면의 EP URL을 복사해 네이버 쇼핑파트너센터 > 상품관리 > 상품정보 수신 현황 > 등록요청에 붙여넣기(검수 1~2 영업일).
condition/import_flag/goods_type/product_flag 코드값은 EP3.0 원문 기준이나 원본 PDF 재접속 실패(503)로 독립 재대조 미완 — 실운영 전 파트너센터 최신 가이드로 1회 대조 권장.