베스킨 라빈스 FAQ 프로젝트

main 반영 커밋: https://ap-northeast-2.console.aws.amazon.com/codesuite/codecommit/repositories/br_faq_chat/commit/a7bd953d1ce13296a739e540c50b6e686428ad6f?region=ap-northeast-2

마감 메모 - #564 br-item 가격 section 전처리/배치 프로세스

1. 최종 방향

• br-homepageinfo-01 원본을 직접 덮어쓰지 않고 신규 br-item-01에 발행하는 방식으로 확정했다.
• 이유: 홈페이지 원본 설명, 영양정보, 알레르기 정보는 절대 훼손되면 안 되며, 가격은 매월/수시 변경될 수 있는 운영성 데이터이므로 원본과 분리하는 편이 안전하다.
• 처리 방법: br-item-01 문서는 br-homepageinfo-01 문서 JSON을 그대로 복사한 뒤, 가격 매칭이 검증된 상품에만 마지막 section으로 가격 정보를 추가한다.

2. 데이터 기준

• 기준 원본은 br-homepageinfo-01 전체 문서다. 이번 기준으로 156건 전체가 br-item-01로 복사되어야 한다.
• 가격 매칭 기준은 br-promotion-01의 26년 6월 고정 라인업 문서다.
  • 케이크 라인업 Document ID: 20260607164348056551
  • 커피+음료 라인업 Document ID: 20260607164350563222
• 이유: 검색어 기반 라인업 검색은 월/키워드/유사문서 영향으로 흔들릴 수 있으므로, 운영 대상 라인업 문서를 고정 ID로 조회해야 재실행 결과가 안정적이다.

3. 전처리 단계

• 1단계: DDB PRODUCT_CATALOG_STATE에서 홈페이지 상품 master를 만든다.
  • 이유: AI가 임의 productId를 만들지 못하게 하고, 실제 홈페이지 상품명/카테고리 기준으로만 매칭하기 위함이다.
• 2단계: br-promotion-01 고정 라인업 문서를 가져온다.
  • cake 문서는 케이크 후보, BEV 문서는 음료/커피 후보로 나누어 사용한다.
• 3단계: AI backend의 ai_product_lineup_sheet_structuring으로 라인업 원문을 CAKE/BEV products JSON으로 구조화한다.
  • 이유: 라인업 원문은 사람이 읽는 텍스트라 줄바꿈, 복수 가격, 비고, 판매기간이 섞여 있어 규칙만으로 안정 추출하기 어렵다.
  • 처리 원칙: AI가 제품명/가격을 확실히 못 읽으면 빈값 또는 invalid로 보내고, 뒤 단계에서 저장 차단/검토 대상으로 남긴다.
• 4단계: ai_product_lineup_item_structuring으로 구조화된 라인업 상품을 홈페이지 master 후보와 매칭한다.
  • 이유: AI가 이름 유사도를 보되 productId는 반드시 masterCandidates에 있는 값만 쓰게 제한하기 위함이다.
• 5단계: Lambda에서 deterministic validation을 다시 수행한다.
  • 검증 항목: sourceRowId 존재 여부, productId master 존재 여부, 카테고리 일치, 가격 파싱 가능 여부, 중복 sourceRowId, 미매칭/모호/가격오류 여부.
  • 이유: AI 결과를 그대로 저장하지 않고 저장 가능 상태를 코드로 재검증해야 운영 데이터 오염을 막을 수 있다.

4. 예외/그룹 처리

• 판매 종료로 확인된 케이크는 가격 매칭 실패가 아니라 IGNORED로 처리한다.
• 수동 영양소 문서로 관리되는 티 상품은 가격 전처리 대상에서 제외한다.
• 아메리카노처럼 홈페이지 문서 하나에 여러 세부 라인업 가격이 묶이는 상품은 그룹 가격으로 병합해 하나의 가격 section에 모두 넣는다.
• 이유: 홈페이지 기준 문서 구조가 상품 단위이고, 라인업은 옵션/세부 판매명 단위일 수 있어 1:1 매칭만 강제하면 정상 상품이 미매칭으로 남는다.

5. 저장 gate

• dryRun=true이면 PRODUCT_ITEM_PREPROCESS_RUN 저장/발행 없이 결과만 확인한다.
• dryRun=false이면 PRODUCT_ITEM_PREPROCESS_RUN summary/detail을 DDB에 저장한다.
• publishBrItem=true이고 gateStatus=READY일 때만 br-item-01 발행을 수행한다.
• gateStatus가 READY가 아니면 br-item-01 저장은 차단한다.
• 이유: 운영 배치에서 라인업 추출/매칭 실패가 있어도 원본 인덱스나 br-item-01을 잘못 덮어쓰지 않도록 하기 위함이다.

6. DDB 기록

• summary PK: PRODUCT_ITEM_PREPROCESS_RUN, SK: RUN#{runId}
• detail PK: PRODUCT_ITEM_PREPROCESS_RUN#{runId}, SK: ROW#{sourceRowId}
• summary/detail에는 TTL을 넣어 장기 누적을 방지한다.
• 이유: 매일 도는 배치의 검수 이력은 필요하지만, 상세 row가 무한히 쌓이면 운영 테이블 관리 부담이 커진다.

7. br-item-01 발행 방식

• Vectocore list_all_extreme_data로 br-homepageinfo-01 전체 문서를 조회한다.
• 전체 원본 문서를 br-item-01에 복사한다.
• 가격 매칭된 상품에는 가격 section을 추가한다.
• 가격 매칭되지 않은 상품도 br-item-01에 원본 그대로 복사한다.
• 이유: 사용자가 요구한 핵심 조건이 “br-homepageinfo-01 100% 복사 후, 매칭된 건만 가격 추가”였기 때문이다.

8. 관리자 확인

• web-admin 시스템 메뉴에 제품 전처리 상태를 메인 메뉴로 추가했다.
• get_batch_monitoring_status에서는 상품 품목 전처리 배치 행을 볼 수 있다.
• get_product_item_preprocess_run에서는 최신 전처리 run의 row 상세를 확인한다.
• 관리자가 확인할 주요 값:
  • gateStatus
  • matchedCount / readyToSaveCount
  • blockedCount
  • unmatchedCount
  • invalidPriceCount
  • brItemPublish.successCount
  • brItemPublish.pricePublishedCount
  • brItemPublish.copiedWithoutPriceCount

9. 자동 배치

• ProductHomepageCrawlerBatchStack에 EventBridge Rule을 추가했다.
• 스케줄: cron(40 20 * * ? *) = 한국시간 매일 05:40
• payload:
  • command: product.preprocess_br_item
  • dryRun: false
  • useAi: true
  • lineupSourceMode: vectocore
  • publishBrItem: true
  • vectocoreTimeoutSeconds: 120
• 이유: 가격이 변경될 수 있으므로 매일 새벽 원본 복사와 가격 section 갱신을 자동으로 반복해야 한다.

10. 수동 실행/검증 방법

• dry run 예시:
  {"command":"product.preprocess_br_item","runId":"manual-br-item-preprocess-YYYYMMDD-dryrun","dryRun":true,"useAi":true,"lineupSourceMode":"vectocore","lineupMonth":"26년 6월"}
• 실제 발행 예시:
  {"command":"product.preprocess_br_item","runId":"manual-br-item-preprocess-YYYYMMDD-save","dryRun":false,"useAi":true,"lineupSourceMode":"vectocore","lineupMonth":"26년 6월","publishBrItem":true,"vectocoreTimeoutSeconds":120}
• 결과 확인:
  • Lambda 응답 summary에서 gateStatus와 brItemPublish 확인
  • 관리자 제품 전처리 상태 화면에서 상세 row 확인
  • br-item-01 문서 수가 br-homepageinfo-01 원본 수와 같은지 확인
  • pricePublishedCount가 매칭 가격 반영 건수와 일치하는지 확인

11. release 검증

• product-homepage-crawler-batch-lambda tests: 73 passed
• admin-backend-lambda tests: 156 passed
• ai-backend-lambda npm test: 219 passed
• web-admin lint: error 없음, 기존 warning만 존재
• web-admin test: 61 files / 492 tests passed
• web-admin build: 통과
• root npm run build: 통과
• CDK synth: 통과

12. 반영 커밋

• main 반영 커밋: https://ap-northeast-2.console.aws.amazon.com/codesuite/codecommit/repositories/br_faq_chat/commit/a7bd953d1ce13296a739e540c50b6e686428ad6f?region=ap-northeast-2

13. 후속 운영 시 주의사항

• 라인업 월이 바뀌면 고정 Document ID도 새 월 라인업 문서로 교체해야 한다.
• gateStatus가 REVIEW_REQUIRED이면 br-item-01 발행이 차단되므로 관리자 상세에서 blockReason을 먼저 확인한다.
• 가격이 없는 원본 상품은 오류가 아니라 copiedWithoutPriceCount로 남을 수 있다.
• br-homepageinfo-01 원본 구조는 계속 보존 대상이며, 가격 section 추가는 br-item-01에서만 수행하는 것이 현재 결정된 운영 방식이다.