Newsletter Signup

docs/hcs-asset/newsletter-signup.md

id: 'newsletter-signup' status: ready

Newsletter Signup

Reference

URL: https://biodance.com/
위치: 페이지 하단 footer 내 우측 영역
구조: 제품 이미지 + 이메일 구독 폼 (밑줄 스타일 input + 화살표 submit 버튼)
배경: #f7f7f7, 텍스트: #2f3032, accent: #f8a48a

React Component

Path: apps/makitt-standard-commerce/src/components/assets/newsletter-signup/
Status: implemented
반응형: 데스크톱 (좌우 분할) / 모바일 (이미지 위 + 폼 아래 수직 스택)
i18n: ko, en, ja 지원
API: shopApi.subscribeNewsletter() 연동 완료

Prerequisites

makitt-server (shop-api)

고객 대면 API. shop storefront에서 호출.

API	Method	Endpoint	Status
뉴스레터 구독	POST	`/shop/{shopId}/newsletter/subscribe`	available
구독 해제	POST	`/shop/{shopId}/newsletter/unsubscribe`	available

Request: { email: string, name?: string }
Response: { success: boolean, message: string }
중복 구독 시 idempotent (성공 반환)
Controller: NewsletterController.java

makitt-server (admin-api)

셀러 어드민에서 구독자를 관리하기 위한 API.

API	Method	Endpoint	Status
구독자 목록 조회	GET	`/api/v1/shops/{shopId}/newsletter/subscribers`	available
구독자 삭제	DELETE	`/api/v1/shops/{shopId}/newsletter/subscribers/{email}`	available
뉴스레터 설정 조회	GET	`/api/v1/shops/{shopId}/newsletter/settings`	available
뉴스레터 설정 수정	PUT	`/api/v1/shops/{shopId}/newsletter/settings`	available
구독자 CSV 내보내기	GET	`/api/v1/shops/{shopId}/newsletter/subscribers/export`	not available

Controller: NewsletterAdminController.java
설정 영속화는 TODO (현재 enabled=true 하드코딩, subscriberCount만 동적)

makitt-server (도메인/모델링)

항목	내용	Status
DynamoDB Entity	`NewsletterSubscriber` — PK: `SHOP#{shopId}`, SK: `NEWSLETTER#{email}`	available
OpenSearch Index	`newsletter-subscribers` — keyword 매핑 (shop_id, email, status, source)	available
OpenSearch Document	`NewsletterSubscriberDocument` — `@JsonIgnoreProperties(ignoreUnknown = true)`	available
Domain Service	`NewsletterService` — CRUD + `EntityChangedEvent` 발행	available
Search Service	`NewsletterSearchService` — OpenSearch 연동 (검색, 카운트)	available
Application	`NewsletterApplication` — subscribe, unsubscribe, list, count, delete	available

makitt-web (셀러 어드민 UI)

기능	설명	Status
구독자 관리 탭	Customers → Messages → Newsletter 탭	available
구독자 목록	이메일, 이름, 상태, 소스, 구독일 테이블	available
검색/필터	이메일/이름 검색, 상태/소스 드롭다운 필터	available
구독자 삭제	확인 대화상자 + 삭제	available
페이지네이션	0-indexed, 20개 단위	available
설정 토글	뉴스레터 활성화/비활성화 스위치	available
CSV 내보내기	구독자 이메일 목록 다운로드	not available

makitt-shop (HCS 렌더링)

항목	설명	Status
`form` renderer	FormRenderer	available
`input` renderer	InputFieldRenderer	available
`button` renderer	ButtonRenderer	available
`newsletter.subscribe` action	`@makitt/api` action-registry.ts에 등록	available
`newsletter.unsubscribe` action	`@makitt/api` action-registry.ts에 등록	available

HCS JSON Asset

Path: apps/builder/data/hcs-asset/newsletter-signup.json
Status: created
Builder LocalAssetsPanel에서 조회/편집 가능

HCS Conversion Notes

section = section (flex row, 2컬럼 → 모바일 column)
좌측 = container > image (object-fit: cover)
우측 = container > heading + text + form > input + button
submit 버튼은 ArrowRight icon 사용 → icon renderer 활용
성공/에러 메시지는 conditional visibility (visible binding)
이메일 validation 에러는 form.errors.email 바인딩
form submit action = newsletter.subscribe

Remaining Work (Optional)

HCS action executor: newsletter.subscribe action을 @makitt/api action registry에 등록 ✓ 완료
HCS JSON: Builder data/hcs-asset/ 에 TreeNode JSON 생성 ✓ 완료
Settings 영속화: NewsletterSettings DynamoDB entity 추가 (현재 enabled=true 하드코딩)
CSV export: admin-api에 CSV 다운로드 엔드포인트 추가