예약 광고 서비스 「어바웃픽」 상품·서비스 기획서 v1.8

• 작성일: 2026-10-02 · 작성: 서현일(CPO) · 대상: 기획·디자인·프론트엔드·백엔드·QA·영업·경영지원
• 범위: 선주 모바일(신규) · 고객웹(8월통합) · 예약 어드민
• 화면 ID는 「8월통합 완벽 기획서」 기준(CW-·SJ-·AD-) 그대로 사용, 신규 화면만 새 번호(SJ-90~, CW-58~61, AD-80~) 부여. 화면별 요소·문구·버튼 동작은 「화면 정의서」(screens)와 Figma 정책 카드에 정리.
• 표기: [확인됨] 실측·문서 근거 · [제안] 이번 기획 제안값 · [미확인] 근거 없음 · [확인 필요] 개발·세무 확인 대상 · [결정 필요] D-번호

0. 한 장 요약

선주가 월 정액으로 「어바웃픽」 등급(A·B·C) 구독 시 아래 세 가지를 한 번에 위탁 가능.

1. 지면 광고 — 고객웹 새소식 홈·출조 탭·검색·탐색 지도·선박 상세의 12개 지면에 AD 표시와 함께 노출. 고객이 이미 무언가를 정한 순간에 노출: 날씨 확인 시(이 바다로 나가는 배), 날짜 선택 시(이번 주 남은 자리), 마감 확인 시(같은 바다로 나가는 배), 검색 결과가 적은 경우(하루만 옮기면). 화면은 8월통합 디자이너가 제작해 둔 광고 컴포넌트(AD 표시 · 가로 배너 · 검색 추천리스트)와 선박 카드 그대로 사용. 등급 차이는 노출 지면 수와 묶음 내 노출 순서.
2. SNS 홍보·광고 대행 — 어바웃피싱 인스타그램 게시·릴스, 카카오 채널 출조 소식, 메타 광고 집행 대행, 네이버 키워드광고 운영 대행, 블로그·유튜브 체험 콘텐츠. 광고 대행 수수료와 체험 콘텐츠도 등급 혜택에 포함(광고비 자체는 선주 부담).
3. 운영 지원 — 선박 사진 촬영, 조황 업로드 대행, 선박 소개 정비, 상품·출조 일정 등록 대행.

12개월을 한 번에 결제하는 「연간 일시 계약」은 추가 할인 5%p · 노출 30일 연장 · 선박 사진 촬영 · 다음 해 자리 우선 확보 추가 제공(2.5).

광고비는 정산금 지급 시 차감이 디폴트(기본값), 정산 이력이 없거나 정산정보가 없는 선주는 계좌 선입금. 세금계산서는 회사가 청구 회차마다 별도 발행.

선주 측 화면은 최소화. 1단계 판매는 영업이 오프라인으로 설명·계약 후 어드민에서 대리 등록, 첫 회차(또는 총액)를 계약금으로 계좌 선수취. 선주 앱 신청 흐름은 2단계로 연기(D-26).

1단계 오픈 목표일은 2027-01-05(화). 개발은 11/2 착수, 광고 서비스 이용약관은 12차 개정에 포함해 11/14 공고·12/14 시행 후 판매 개시.

공수는 프론트엔드 41.0일(고객웹 18.5 · 선주 6.5 · 어드민 12.5 · QA 수정 3.5) · 백엔드 53.5일 · 디자인 6일 · QA 9.5일(맨데이). 선주 측에서 줄인 공수를 고객웹으로 이동 배분. 개발 기간(11/2~12/11, 영업일 30일) 내 완료를 위해 외부 백엔드 1명(D-19)과 외부 프론트 1명 14.0일(D-34) 필요. 외부 프론트 10/30까지 미확보 시 조황 카드(P8)·지도 사진 마커 등을 2/15로 연기하는 절단안(프론트 34.5일 · 백엔드 50.0일 · 지면 10개)으로 착수.

반드시 지키는 원칙 네 가지.

• 기본 노출은 무료. 광고 미구매 선박의 기존 노출 위치와 노출 순서 변경 없음.
• 고객웹 유료 노출에는 전부 AD 표시(8월통합 AD-mark) 부착, SNS에는 「광고」 표기. 모듈 이름은 「이 바다로 나가는 배」처럼 상황을 설명하는 이름 사용, 「스폰서」「인기」「추천」 단독 같은 표현으로 대체 불가. 광고는 일반 목록 사이에 삽입하지 않고 별도 묶음으로 노출, 일반 목록의 노출 순서와 개수 변경 없음.
• 광고 상품에 선주 비용으로 만드는 할인 쿠폰 포함 불가. 숙박 플랫폼 두 곳이 광고 상품에 쿠폰 비용을 결합하고 짧은 유효기간으로 소멸시킨 건으로 과징금(2025-08-12 공정위 발표, 야놀자 5억4천만원·여기어때 10억원) 부과 후 2026-05-20 기소된 사례 근거(여기어때 부당이득 359억원으로 기재).
• 정책·단가 변경 시 30일 전 고지, 기존 계약은 만료일까지 원래 조건 보장.

1. 왜 하는가

1.1 수익 구조

• 9월 예약 손익(원장 9/1~9/29): 순거래액 3.16억원, 우리 몫 매출 1,936만원(수수료 815만원 · 선매입 686만원 · 대회 436만원), 광고비 5,479만원, 순손실 약 6,300만원 [확인됨: 48_9월_예약손익].
• 수수료 3%로는 거래액이 늘어도 적자 폭 축소 효과 미미. 사업성 채점에서 중개 모델은 18점 [확인됨: 8/21 사업성 채점].
• 선주에게 직접 받는 정액 매출 필요. 3개월 뒤 계약 선박 30척(A 5 · B 10 · C 15) 기준 월 1,075만원(부가세 별도)으로 9월 수수료 수익(815만원) 초과 [가정].

1.2 공급 쪽 문제

• 등록 선박 943척 중 상품을 한 번이라도 등록한 선박은 436척(47.9%), 8월 실제 결제 발생 선박은 167척 [확인됨: 2026-08-31 공급 퍼널 실측].
• 선주에게 「어바웃피싱에 올리면 고객이 온다」는 경험을 주는 장치 부재. 광고·홍보 대행은 이 경험을 유료로 확실하게 제공하는 수단.
• 운영 지원(사진·조황·소개 정비)은 상세 페이지 품질을 높여 광고를 사지 않은 고객 경험 개선에도 기여.

1.3 선주가 낼 만한가

• 선주에게 빈 좌석은 그대로 버려지는 매출. 1인 결제액 9만원 기준 A등급(유어선 월 60만원)은 월 약 7석, B등급(40만원)은 약 5석, C등급(25만원)은 약 3석 추가 판매 시 손익분기 [가정: 1인 9만원은 고객웹 카드 표기 「90,000원~」 수준].
• 선주 인터뷰 5곳으로 지불 의사와 등급 단가를 10/9 전 확인(D-01 근거).

1.4 시장·경쟁에서 확인한 것

정리: 낚시 예약 분야에는 공개된 광고 상품 가격표 없음. 가격의 앱 내 공개 자체가 차별점.

1.5 법·정책에서 지켜야 할 것

2. 상품 구성

2.1 등급과 가격

업종은 선박 정보로 자동 구분. 유선 = 최대 탑승 22인 이상 대형 선박(전국 약 20척), 그 외는 유어선. 가격은 부가세 별도 [결정 필요 D-02].

유어선(월 금액, 원)

유선(월 금액, 원)

• 월 금액 = 1개월 단가 × (1 − 약정 할인율). 총 금액 = 월 금액 × 약정 개월 수. 원 단위 미만 버림.
• 부가세 = floor(공급가액 × 0.1). 청구 합계 = 공급가액 + 부가세.
• 프로모션 일수(무상 연장)는 운영자가 계약마다 0~60일 범위에서 부여 가능, 종료일에 추가. 프로모션 기간은 0원.
• 단가는 어드민 「단가·상품 관리」(AD-86)에서 변경, 변경 단가는 적용일 이후 신규 계약에만 적용. 적용일은 오늘로부터 30일 뒤부터 선택 가능.

2.2 등급별로 받는 것

• 「회차」는 계약 시작일부터 한 달 단위(5.3). 이용권은 회차 시작일에 생성. O1·O3은 계약 첫 회차에만 생성.
• 선주 자료 미제출로 사용하지 못한 이용권은 해당 회차 종료 시 소멸. 회사 사정으로 처리하지 못한 이용권은 다음 회차로 한 번만 이월(carried_in), 성과 화면에 「다음 달로 넘어간 작업」으로 노출.
• 광고 대행(S4·S7)의 등급 혜택은 대행 수수료에 한함. 메타·네이버에 실제 집행되는 광고비는 등급과 관계없이 선주가 계좌로 선입금(최소 광고비는 2.3과 동일).
• S4 「3회차마다 1건」 = 3·6·9·12회차 시작일에 이용권 1건 생성. S5·O1은 약정 조건 충족 시 계약 첫 회차에 1건 생성.
• 유튜브 체험 영상(S6)은 등급에 미포함, 상담으로만 접수.
• 연간 일시 계약은 이 표에 2.5의 혜택 추가.

2.3 단건 홍보 상품 (등급 없이도 구매 가능)

• S4·S7 과세 공급가액에 광고 예산 포함 여부(우리 계정에서 집행 후 재청구하는 구조) [세무 확인 필요 D-21]. 확인 전까지 예산 + 수수료 전체를 공급가액으로 간주.
• S7 운영 규칙: 키워드는 선박이 실제 출항하는 지역·항구·어종과 선박명만 사용. 타 업체 상호·타 플랫폼 이름은 키워드와 문구에 사용 불가. 광고 문구와 키워드 목록은 집행 전 선주 확인 필수. 해당 회차 미소진 광고비는 다음 회차로 이월, 해지 시 잔여 광고비 환불. 월말 결과 보고 = 노출 · 클릭 · 평균 클릭 비용 · 선박 상세 방문 · 광고로 들어온 예약(6.1 전환 기준).
• O4는 예약 어드민 상품관리에서 운영자가 대리 입력 [확인 필요: 어드민 상품 대리 등록 권한]. 선주는 등록 결과를 선주 모바일 상품관리에서 확인·수정.
• S6은 1단계에서 「상담 신청」만 접수(제휴 크리에이터 풀 확정 전) [결정 필요 D-13].
• 단건 상품도 정산 차감 또는 계좌 선입금으로 수납. 청구 시점은 5.4 기준(정산 차감 = 운영자 작업 시작 시, 계좌 입금 = 신청 즉시).

2.5 연간 일시 계약 [결정 필요 D-38]

12개월 약정 총액을 한 번에 계좌로 선입금하는 계약(billing_type = U, months = 12). 1단계는 영업이 AD-82에서 「연간 일시 계약」 선택 후 대리 등록.

유어선(월 금액 · 총액, 원, 부가세 별도)

유선(월 금액 · 총액, 원, 부가세 별도)

• 청구: 승인 시 총액 청구 1건(cycle_no = 0, kind UPF)을 계좌 결제로 생성. 예: 유어선 A = 5,040,000 + 부가세 504,000 = 5,544,000원. 세금계산서는 입금일에 총액 1장 [세무 확인 필요 D-21].
• 정산 차감 선택 불가(일시 결제는 계좌 선입금 전용, 5.4).
• 이용권(SNS·광고 대행·운영)은 일시 결제여도 회차 시작일마다 생성.
• 등급 변경 불가(연장·해지만 가능, 5.1).
• 다음 해 자리 우선 확보는 상한 판정 함수에서 「연간 일시 계약의 연장 계약」을 대기 계약보다 앞에 두는 방식으로만 처리. 상한 자체 초과 불가.
• 중도 해지(5.7): 받아야 할 금액 = min(사용 기간 정가, 연간 일시 총액) + 이미 받은 연간 전용 혜택의 단건 가격(촬영 1회 200,000원). 잔여 프로모션 일수 소멸.
• 연간 일시 단가는 AD-86 단가표에 「연간 일시 추가 할인율」(디폴트 5%p) 한 칸으로 관리.

2.4 1단계에서 빼는 것

3. 지면 노출 정책

이번 개정의 중심은 고객웹 노출임. 아이디어 215건(지면 53 · 카드 32 · 맥락 35 · 콘텐츠 29 · 해외 사례 28 · 기발한 것 30 · 법 검토 39) 수집 후 고객 가치 · 선주 가치 · 표시 의무 · 공수 기준으로 선별, 1단계 12개 지면, 2단계 7개, 3단계 6개로 구분함.

설계 원칙 다섯 가지.

1. 고객이 이미 무언가를 정한 순간에 노출. 날씨 조회 시, 날짜 선택 시, 마감 확인 시, 다음 출조 검토 시.
2. 광고는 「목록 사이에 끼우지 않고」 별도 묶음으로 구성. 일반 목록의 노출 순서와 개수는 유지.
3. 광고 화면은 새로 그리지 않음. 8월통합 디자이너가 만들어 둔 광고 컴포넌트와 카드를 그대로 사용(3.5). 등급 차이는 노출 지면 수와 묶음 내 노출 순서로 구분.
4. 모든 유료 노출에 광고 표시(고객웹 AD 표시, SNS 「광고」) 필수. 모듈 이름은 「~하는 배」처럼 상황을 설명하는 형태로 작성.
5. 맥락(바다·날짜·어종·위치)은 조건으로만 사용하고, 노출 순서는 광고비(등급)와 무작위로만 결정. 「맥락 점수 순」 같은 숨은 순위 생성 금지.

3.1 공통

• 노출 대상 = 계약 상태 「집행 중」 + 선박 「노출중」 + 지면별 조건 충족.
• 「예약 가능」 = 고객웹 선박 상세에서 [예약하기] 탭이 가능한 상품(노출·판매 중·잔여 1석 이상). 당일 예약 미운영으로 날짜 조건은 내일부터 산정 [확인됨].
• 예약 가능한 상품이 없는 날은 전 지면 미노출, 해당 기간만큼 연장하지 않음. 선주 광고 홈(SJ-90)에 경고 노출.
• 선택 순서(모든 지면 동일): ① 지면 조건 통과 ② 지면 참여 등급 ③ 등급 순(A → B → C) ④ 같은 등급 내 해시 오름차순. 해시 = sha256(session_id + ':' + 지면코드 + ':' + 선박번호)의 앞 8바이트를 부호 없는 정수로 읽은 값, 동일 시 선박번호 오름차순. 같은 방문 동안 동일 순서 유지.
• 표시 순서는 지면별로 다를 수 있음. 「내일 새벽 출항」(P3)은 선택된 선박을 출항 시각 순으로 노출. 그 외 지면은 선택 순서 그대로 노출.
• 같은 모듈 내 동일 선박은 한 번만 노출. 단, P2는 날짜 탭별 재노출 가능, 아래 2번 제한에서는 탭 전체를 1번으로 산정.
• 한 화면에서 동일 선박의 광고 노출은 최대 2번. 프론트는 한 화면의 지면을 표시 순서대로 일괄 요청(10장 POST /usr/ads/slots의 placements), 서버는 그 순서대로 선택하면서 이미 2번 노출된 선박을 후보에서 제외하고 다음 후보로 채움. 별도 요청(CW-59 바텀시트, P13, 지도 이동 후 P14)은 각각 별도 산정. 서버에 상태 저장하지 않음.
• 3.1의 「일반 목록에서 빼지 않는다」의 예외는 P8 단독. P8 일반 칸에서는 앞 3칸에 노출된 광고 선박 제외(같은 조황 카드 중복 노출 방지 목적).
• 광고 묶음은 일반 목록 사이에 삽입하지 않음. 광고 선박도 일반 목록에서 제외하지 않음(일반 목록의 개수·순서·「N건」 표기가 광고로 인해 변경되지 않음).
• 광고 노출 차단 스위치: 어드민 AD-86에서 전체(ad_setting.ADS_ENABLED) · 지면별(ad_module_rule.enabled)로 차단. 서버 여러 대는 60초 내 반영(3.6 캐시). 차단 기간 동안 계약 기간 연장 없음, 24시간 이상이면 프로모션 일수로 보상.
• 미납·일시정지·만료·해지 시 60초 내 전 지면에서 제외(3.6 캐시). 선박 숨김은 훅 기준 60초, 훅 누락 시 5분 대사 배치 기준으로 제외.
• 광고 미구매 선박의 기존 모듈(인기선박·실시간 조황·기획전·「이런 곳은 어때요?」 등)의 노출 순서와 노출 여부는 유지.
• 광고 배치 제외 화면: 예약 주문서·결제 진행 중 · 취소·환불 신청 · 탈퇴 · 약관·FAQ·고객센터 · 조과 등록 폼 · CCTV·물때·날씨 화면을 가리는 모달. 광고는 모달·플로팅 형태로 노출하지 않음.

3.2 지면별 (1단계, 2027-01-05 오픈)

• 전시관리 섹션 유형: 015 「광고-이번 주 함께하는 배」 · 016 「광고-이번 주 남은 자리」 · 017 「광고-내일 새벽 출항」 · 018 「광고-선장님 조황 소식」(전시 위치 새소식 홈). 광고 섹션은 같은 전시 위치에서 연달아 배치 불가(저장 시 얼럿 「광고 섹션은 연달아 둘 수 없습니다. 사이에 일반 섹션을 두세요.」).
• 모듈 제목·부제는 전시관리 입력값 사용, 디폴트는 위 표 「모듈 이름」. 섹션이 없는 지면(P4·P5·P6·P7·P12·P13·P14·P17)은 AD-86에서 이름 변경.
• 한 화면의 광고 모듈 수 상한: 출조 탭 3 · 새소식 홈 3 · 검색 결과 2 · 선박 상세 1(+바텀시트 1).

3.3 판매 상한 (재고)

• 지역(출조 탭 9지역)별 상한: A 6 · B 10 · C 15. 전국 상한(1단계 운영 여력): A 10 · B 20 · C 40 [결정 필요 D-08].
• 지면이 늘어도 상한은 유지. 지면 증가분만큼 한 척이 받는 노출이 늘어나는 구조임. 2단계 지면 오픈 시 상한 재검토.
• 상한 판정 = 신청 기간의 날짜별 「입금 대기·집행 예정·집행 중·일시정지」 계약 수를 집계해 그 최댓값이 상한보다 작은지 여부. 앞뒤로 이어지는 계약(한 계약 종료 다음 날 다른 계약 시작)은 같은 날 겹치지 않으므로 1로 산정. 같은 선박의 연장 계약은 기존 계약과 겹치지 않으므로 자기 슬롯을 막지 않음.
• 같은 함수로 승인·입금 확인·대기 승격·영업 상담용 남은 슬롯(AD-82) 계산.
• 승인 시 초과하면 AD4096 → 운영자는 대기로 선택 가능. 입금 확인 시 초과하면 입금은 기록하고 확인 팝업(컨펌)에서 「대기 1번으로 두기」 또는 「환급」 선택.
• 상한 판정에 사용하는 계약 기간 종료일 = effective_end(= coalesce(terminate_date, end_date)). 해지 예정·등급 변경 계약의 슬롯은 해지일 다음 날부터 비워짐.
• 상한 계산에 「대기에서 올라온 확인 중」 계약(promoted_at 있음)도 포함. 운영자 처리 전 같은 슬롯으로 다음 대기자가 중복 승격되지 않도록 하기 위한 목적.
• 등록 시점에 이미 상한에 도달했거나 같은 지역·등급에 기간이 겹치는 대기 계약이 있으면 새 계약도 「대기」로 접수(먼저 대기한 선박을 앞지르지 않음).
• 대기 승격: 등급별로 대기 계약을 등록 시각 순으로 하나씩 확인, 해당 계약 기간의 지역·전국 판정을 모두 통과한 계약만 「확인 중」으로 승격 후 AN16을 발송. 다른 지역에서 전국 상한이 풀린 경우도 매 실행마다 전체 대기 계약을 확인하므로 반영됨. 승인은 운영자가 처리.
• 대기 판정 기간 = [max(희망 시작일, 오늘 + 2영업일), 같은 약정 개월].
• 앞 순번 실패 시 해당 앞 순번의 판정 기간과 겹치는 뒤 순번은 건너뜀(앞지르지 않음), 겹치지 않는 뒤 순번은 판정 진행.
• 희망 시작일 + 30일 경과 후에도 대기 상태면 자동 취소(CXL, 사유 「대기 기간 경과」) 및 AN21을 발송.
• 대기 순번은 저장하지 않고 조회 시점에 계산(같은 지역·등급 대기 중 등록 시각 순위).
• 상한 판정 함수는 exclude_contract_idx를 입력값으로 받음(대기에서 승격된 확인 중 계약 승인 시 자기 자신을 두 번 세지 않기 위한 목적). 반려·취소·[대기로] 시 promoted_at 삭제.
• 선박 지역 → 9지역 대응: 시도 기준. 부산·울산은 경남, 서울은 경기, 충북·세종·대전은 충남, 대구는 경북, 광주는 전남으로 처리 [결정 필요 D-14].

3.4 광고 안내 시트(CW-58) 문구

제목: 광고 선박 안내 본문: - 「AD」 표시가 붙은 선박은 선주님이 비용을 내고 노출하는 광고입니다. - 광고 묶음 안의 순서는 광고 등급 순서이고, 같은 등급 안에서는 무작위로 정해집니다. 평점·조황·가격과는 관계가 없습니다. - 광고는 검색 결과와 목록의 순서·개수를 바꾸지 않습니다. 광고가 아닌 선박은 고객님이 고른 정렬 기준(거리순·인기순·가격순)을 따릅니다. - 일부 광고는 지금 보시는 바다·날짜·검색 조건에 맞춰 고릅니다. 예약 이력으로 고르는 광고는 맞춤 광고 설정에서 끌 수 있습니다. - 광고 선박도 예약·결제·취소·환불 기준은 다른 선박과 똑같습니다. 버튼: [확인] · 텍스트 버튼 [맞춤 광고 설정] → CW-61 진입: 현재 주소에 &sheet=ad-info 추가. 뒤로가기·[확인]·바깥 영역 탭 시 닫힘.

3.5 광고 화면 구성 — 8월통합 디자이너 컴포넌트 그대로

광고 화면은 새로 그리지 않음. 8월통합 파일에 디자이너가 이미 만들어 둔 광고 컴포넌트와 선박 카드를 그대로 사용. 등급에 따른 카드 모양 변경 없음. 등급 차이는 노출 지면 수(A 12 · B 11 · C 6, 2.2)와 묶음 내 노출 순서(A → B → C)로 구분.

• 상품 줄(Card/Ship/Common의 「생새우 외수질 + 잔여」 줄)은 P2·P3·지도 바텀시트·CW-59에 한해 노출. P1·P5는 「인기 선박 모음」 「찜한 선박」처럼 미노출.
• 배너 문구는 서버가 완성 문구(title1 · title2 · sub)로 전달. 프론트에서 문구 생성하지 않음.
• 선장 한마디·대표 사진(AD-81 카드 소재)은 1단계 고객웹 카드에 미사용. 2단계 P18(선장 소개 블록)과 SNS 소재에 사용.
• 금지 문구(모듈 이름·배너 문구): 인기 · 베스트 · TOP · 랭킹 · 1위 · 에디터 픽 · 프리미엄 · 인증 · 보증 · 「추천」 단독 · Sponsored · 파트너 · 제휴 · 협찬. 「AD」는 AD 표시 컴포넌트에 한해 사용. 디자이너 추천리스트 머리 줄의 예시 문구(「어피 추천 | 인기선박 | 조황 좋음」)는 금지 문구에 해당하므로 어종·항구·날짜 키워드로 변경해 사용.
• 새 색·새 모양 생성 금지. AD 표시 축소·삭제 금지.

3.6 맥락 데이터와 선택 엔진

모든 지면은 서빙 API 하나(10장 POST /usr/ads/slots)를 호출, 지면별 조건은 서버의 모듈 규칙 표(ad_module_rule)로 관리. 새 지면 오픈 시 프론트 모듈 + 규칙 1행 추가.

• 맥락은 「통과/탈락」 조건으로만 사용. 노출 순서는 3.1 선택 순서(등급 → 해시).
• 캐시: 노출 대상 목록(집행 중 계약 · 등급 · 지역 · 항구 좌표 · ad_module_rule · ad_creative)은 서버 인스턴스 메모리에 보관, 60초마다 ad_contract·ad_setting·ad_module_rule·ad_creative의 max(updated_at) 변경 시 재조회(서버 여러 대 사이 무효화는 이 방식으로 단일화). 맥락(ad_boat_context·ad_region_wave)은 10분마다 재조회.
• 서빙 중 DB를 조회하는 대상은 네 가지에 한함: P7 회원의 마지막 결제 예약 1건, P1 회원의 최근 1년 결제 예약 지역 목록(최근 결제 순, 회원별 1분 캐시), ad_user_pref(회원별 1분 캐시), P5·P17 기준 선박 1건.
• 「가까운 지역」(P1 탭 순서·P12) = ad_region의 지역 대표 좌표와 고객 위치의 직선거리 순.
• P8 일반 칸은 프론트가 기존 조황 피드 응답에서 P8 응답의 선박을 제외하고 렌더링(기존 피드 API는 변경 없음). P4·P13의 검색 조건 해석은 검색 API와 같은 함수를 사용하되 광고 후보(최대 약 100척) 내에서만 필터링.
• 서빙 API 응답의 각 칸에 reason(화면에 쓰는 완성 문구, 예 「1. 22(금) 파고 0.5m · 3석」) 함께 전달. 프론트는 상품 줄·배너 문구를 reason으로 렌더링, res_dt로 선박 상세 날짜 전달. 프론트에서 문구 생성하지 않음.

3.7 2단계·3단계 지면 (1단계 성과를 보고 연다)

3.8 표시 규칙 (모든 지면)

4. 홍보·운영 작업 정책

4.1 작업 흐름

상품별 단계(ad_service_item.needs_material · needs_review)

• 「자료 요청」이 없는 상품은 접수 → 제작 중, 「선주 확인」이 없는 상품은 제작 중 → 완료로 바로 전환.
• 카카오 출조 소식(S3)은 매주 목요일 10시 묶음 발송. 수요일 18시까지 「게시 준비」 상태가 된 작업에 한해 해당 주 발송에 포함. 수신 동의 고객 대상, 08:00~20:50에 한해 발송.
• SNS 게시물은 첫 줄에 「광고」(블로그는 「협찬」, 유튜브는 「유료 광고 포함」) 표기 필수. 운영자가 결과물 업로드 시 「표시 확인」 체크해야 「선주 확인」으로 전환 가능.
• 사진 촬영(O1)은 촬영 날짜를 운영자가 선주와 전화로 협의해 어드민에 입력(선주 화면에 날짜 노출). 결과 사진은 운영자가 어드민 선박 정보에 반영.
• 메타 광고 대행(S4)은 선주가 신청 시 예산·기간 입력, 입금 확인 후 운영자가 광고 문구·이미지를 「선주 확인」으로 전송해 승인되면 집행(게시 준비 = 집행 중). 종료 후 노출·클릭·랜딩 방문 수를 운영자가 메타 광고 관리자 수치로 입력해 결과 화면에 노출.
• 네이버 키워드광고 대행(S7)은 첫 회차에 키워드 목록과 광고 문구를 「선주 확인」으로 전송해 승인되면 집행(게시 준비 = 집행 중). 다음 회차부터는 같은 키워드로 유지, 변경 시에 한해 재확인. 회차 종료 시 운영자가 네이버 검색광고 관리자 수치(노출·클릭·평균 클릭 비용·광고비 소진)를 입력해 결과 화면에 노출.
• 블로그(S5)는 운영자가 블로거와 탑승 날짜를 협의해 어드민에 입력, 선주는 해당 날짜 1석 비워 둠(선주 모바일 「예약자 추가」로 직접 등록, 결제 0원).

4.2 처리 상한

• 월 처리 상한 [결정 필요 D-11]: 인스타그램 게시 45건 · 릴스 12건 · 카카오 소식 칸 주 15칸 · 조황 업로드 400건 · 사진 촬영 8회 · 블로그 10건 · 메타 대행 10건 · 네이버 키워드광고 대행 20건 · 상품·일정 등록 대행 60건.
• 이용권 이월 판정: 회차 종료 시 ops_shortfall(운영자가 처리 상한 초과로 접수를 받지 못했거나 운영 사정으로 미룬 수, 운영자가 작업 보드에서 기록)만 다음 회차 carried_in으로 이월. 선주 미사용 이용권은 소멸. 이월분은 다음 회차에서 우선 사용, 재이월 없음.
• 운영 사정 기록: AD-84 상세의 [운영 사정으로 다음 회차로] → 해당 회차 ops_shortfall + 1. 회차 종료 후 운영 사정으로 취소된 작업의 이용권은 다음 회차 carried_in으로 반환.
• 운영 사정으로 작업 취소 시 이용권 반환, 선주 사유(자료 미제출·선주 요청)로 취소 시 사용 처리.
• 조황 업로드(O2) 1건 = 업로드 1회(사진 최대 10장 + 조황 글 1건).
• 등급 이용권은 상한에서 우선 확보. 계약 승인 시 「이번 달 남은 처리량 ≥ 그 계약 이용권」 확인, 부족하면 승인 화면에 경고 노출(승인은 가능, 운영자 판단).
• 단건 신청 시 상한 도달 상태면 「이번 달 접수가 마감됐어요. 다음 달 1일부터 신청할 수 있어요.」 노출 후 신청 차단(AD4093).

5. 계약과 결제

5.1 계약 단위

• 계약 1건 = 선박 1척 × 등급 1개 × 약정 기간 1개. 동일 선박에 기간이 겹치는 계약은 하나만 허용(상태 확인 중·대기·입금 대기·집행 예정·집행 중·일시정지 기준).
• 1단계: 영업팀이 선주 대면 설명·계약 후 어드민(AD-82)에서 대리 등록. 선주 앱 SJ-90E에는 등급 소개와 [상담 요청]만 노출(ad_consult, item_code PLAN → OP01 → 영업 연락). 2단계: 선주 모바일 신청(SJ-91·92) 오픈(D-26).
• 신청·취소·요청·승인·수정 요청 가능한 계정: 업체 대표 계정(업체 로그인 계정). 직원 계정(partner_users)은 조회와 작업 자료 업로드만 가능 [확인 필요: 대표·직원 구분 컬럼]. 로그인 응답에 is_owner 전달.
• 모든 선주 API는 boat_idx의 로그인 업체 소속 여부 확인, 미소속 시 403 AD4031.
• 연장 = 새 계약. 시작일 = 기존 종료일 다음 날, 상태 확인 중 → 승인 시 집행 예정. 등급 변경 = 새 계약(다음 회차 시작일부터, 같은 트랜잭션에서 상한 검사, 초과 시 등급 변경 불가) + 기존 계약 terminate_date = 새 계약 시작일 전날(사유 등급 변경, 할인 반환 없음). 이 세 가지는 POST /adm/ads/contracts/{id}/change-grade 한 번에 한 트랜잭션으로 처리. 새 계약의 약정은 단가표 값(1·3·6·9·12) 중 운영자가 선택, 디폴트(기본값)는 원 계약 남은 개월 이하의 최댓값, 결제 방법은 원 계약 값(변경 가능), 청구 방식은 월 결제만 가능. 정산 차감이면 즉시 집행 예정, 계좌면 입금 대기 + 1회차 청구. 원 계약 마지막 회차의 ops_shortfall은 새 계약 1회차 carried_in으로 이관. 새 계약이 입금 기한 경과·반려로 취소되는 경우, 원 계약 해지일 미경과 시 같은 트랜잭션에서 원 계약의 terminate_date·terminate_reason 삭제(이력 change_grade_rollback) 후 OP01을 발송. 원 계약이 마지막 회차면 「다음 회차」가 없으므로 등급 변경은 AD4092로 차단, 다른 등급 연장(새 계약)으로 안내. 일시 결제 계약은 등급 변경 불가(연장·해지만 가능). 두 경우 모두 선주는 「요청」만 가능, 처리는 운영자 담당.
• 같은 선박 계약 기간 겹침은 DB에서 차단: btree_gist 확장 + EXCLUDE USING gist (boat_idx WITH =, daterange(start_date, effective_end, '[]') WITH &&) WHERE status IN (REQ,WAI,PAY,SCH,ACT,PAU). effective_end = coalesce(terminate_date, end_date) 생성 컬럼(STORED)으로, 겹침 제약·상한·대기 승격·노출 자격·회차 생성에 모두 이 값 사용. 프로모션 일수 증가 시 뒤 계약과의 겹침(AD4091)·상한 재검사.

5.2 계약 상태

상태 칩 색 토큰(글자/배경, 대비 4.5:1 이상): 초록 #00754A/#E6F7EF · 주황 #9A5200/#FFF4E5 · 빨강 #B3261E/#FDECEC · 파랑 #0041FF/#EBF0FF · 회색 #5F5F5F/#EFEFEF.

정지 원인 플래그(pause_flags): UNPAID(미납) · OPS(운영 정지, 사유 필수) · HIDDEN(선박 노출안함). 원인 전체 해소 시에만 집행 중으로 복귀. 정지 중에도 회차 청구 유지(회사 귀책 정지는 OPS 사유 「회사 사정」으로 기록, 프로모션 일수로 보상).

전이 규칙

5.3 기간과 회차

• 시작 희망일은 신청일 기준 2영업일 뒤부터 선택 가능(공휴일 제외, 기존 휴일 코드 사용). plans API에서 min_start_date 전달.
• 승인 시점이 시작 희망일 경과 후인 경우 승인일 다음 날로 자동 조정, AN02 문구에 변경된 날짜 표기.
• n회차 시작일 = 계약 시작일 + (n − 1)개월. 해당 월에 같은 날이 없으면 해당 월 말일. 앞 회차 날짜에서 누적 가산하지 않고 항상 계약 시작일 기준으로 계산.
• n회차 종료일 = (n+1)회차 시작일 − 1일. 마지막 회차 종료일 = 계약 시작일 + 약정 개월(같은 규칙) − 1일.
• 계약 종료일 = 마지막 회차 종료일 + 프로모션 일수.

• 서버 날짜 계산은 KST 날짜(시간 없음)로만 처리. 라이브러리 기본 월 더하기(넘침 이월) 사용 금지.

5.4 청구

• 월 청구(기본): 회차 시작일에 해당 회차 청구 생성(00:00 체인 배치). 회차는 effective_end 범위 안에서만 생성(해지일 이후 시작하는 회차는 미생성). 금액 = 월 금액 + 부가세.
• 계좌 선입금: 승인 시점에 1회차 청구(월 결제) 또는 총액 청구(일시 결제, cycle_no = 0) 생성. 2회차부터는 회차 시작일 배치에서 생성.
• 계약금 선수취(1단계 기본): 대리 등록 시 「첫 회차 계좌 선수취」 디폴트 켜짐. 켜짐 상태면 결제 방법이 정산 차감이어도 1회차 청구는 계좌 입금(ad_invoice.pay_method = T)으로 생성, 승인 → 입금 대기 → 입금 확인 → 집행 예정 순으로 진행. 2회차부터는 선택한 결제 방법(정산 차감 또는 계좌) 적용. 운영자가 끄는 경우(사유 필수) 기존 규칙대로 정산 차감 계약은 승인 즉시 집행 예정. 이 값은 정산 차감 계약에서만 유효(계좌 계약은 원래 선입금). 연장·등급 변경으로 생성한 새 계약은 false로 생성. 정산 차감 대상은 계약이 아니라 청구의 결제 방법(ad_invoice.pay_method = D) 기준으로 판단. 컬럼 ad_contract.first_cycle_upfront bool · upfront_off_reason text.
• 청구 기한(due_date): 계좌 = 청구일 + 7일, 정산 차감 = 청구일 + 14일(미납 안내 기준일과 동일).
• 일시 결제는 계좌 선입금인 경우에 한해 선택 가능. 12개월 일시 결제 시 연간 일시 계약 혜택(2.5) 적용.
• 단건 홍보 상품: 정산 차감은 운영자가 작업을 접수 상태에서 다음 상태(자료 요청·제작 중)로 변경 시 1회 청구. 계좌 입금은 신청 즉시 청구(기한 7일), 운영자는 입금 확인 후 작업 시작. 계좌 단건이 7일(168시간) 안에 미입금 시 작업과 청구 함께 취소, AN20을 발송(매시 배치). 메타 광고 대행(S4)·네이버 키워드광고 대행(S7)은 회사가 광고비를 선집행하는 구조이므로 계좌 선입금만 허용. 등급 혜택으로 대행 수수료가 무료여도 광고비는 동일 방식으로 수납.
• 청구 번호: ADI-YYYYMM-NNNNN. unique(contract_idx, cycle_no) WHERE kind IN (CYC, UPF), unique(service_order_idx) WHERE service_order_idx IS NOT NULL.

5.5 정산금 차감

현행 정산 구조 [확인됨]: 정산은 예약 1건당 1행(accounts), 어드민 정산관리에서 운영자가 행 선택 후 [선택지급요청] 클릭 시 지급 진행. 선주 정산관리는 동일 행들을 정산 예정일 단위로 묶어 노출.

• 차감 시점 = 운영자의 [선택지급요청] 클릭 시. 같은 트랜잭션에서 선박별 차감액 계산 후 지급 묶음(ad_payout) 생성.
• 차감 대상 = 해당 선박의 결제 방법이 정산 차감인 미수 청구, 청구일 오래된 순.
• 차감액 = min(미수 합계, 이번에 지급 요청한 그 선박 행들의 지급액 합). 최종 지급액 = 지급액 합 − 차감액(0원까지 가능).
• 지급 요청 전 확인 팝업에 선박별 「지급액 · 광고비 차감 · 최종 지급액」 노출, [지급 요청] 클릭 시 확정.
• 지급 묶음 ad_payout: 선박별 1행. gross_amount(선택 행 지급액 합) · deduction_amount · refund_amount(환급 중 「다음 지급 때 돌려줌」 분) · net_amount = gross − deduction + refund. 선택한 정산 행은 ad_payout_item(payout_idx, accounts_idx unique)에 추가, 동일 행의 중복 묶음 포함 방지.
• 미리보기 → 확정: 미리보기 응답에 preview_token(선택 행·금액 해시, 10분 유효) 전달, 확정 요청 시 토큰 전송. 그 사이 미수나 행 금액 변경 시 409 AD4097 「금액이 바뀌었습니다. 다시 확인해 주세요」.
• 실제 이체 금액 기준은 net_amount. 현행 지급 요청 후 이체가 경영지원 수동 이체(어드민 엑셀)인지 은행 연동인지 [현행 실측 필요 — 10/9까지 최상수 확인]. 수동 이체인 경우 AD-34 엑셀에 「광고비 차감」「광고비 환급」「최종 지급액」 열 추가, 경영지원은 최종 지급액으로 이체.
• 지급 요청 취소 기능은 현행 미제공 [확인됨: 어드민 정산 화면 버튼 실측]. 1단계 미추가. 잘못 요청한 묶음은 운영자가 AD-83에서 차감 1건 되돌리기로 정정.
• 지급 완료 후 발생한 고객 취소는 기존 정산 로직대로 다음 정산에서 처리, 광고비 차감은 변경하지 않음.
• 선주 정산관리(SJ-30)는 정산 예정일 카드마다 「광고비 차감(예정)」 노출. 예정액 배분 = 정산 예정일이 이른 카드부터, 청구일이 이른 미수부터 카드의 「지급 예정액」(정산 금액) 한도 안에서 배분. 지급 요청 후에는 해당 카드가 「광고비 차감」 확정값으로 변경. 어드민 정산 목록의 행별 「광고비 차감(예정)」도 동일 순서(정산 예정일 → 정산번호 순)로 행 단위 배분한 값임.
• 예: 왕감자호 미수 275,000원(단건 청구 2건: 인스타그램 릴스 1편 추가 · 블로그 체험 후기), 1. 24 카드 지급 예정액 485,550원·1. 31 카드 332,500원 → 1. 24 카드 차감(예정) 275,000원·최종 210,550원, 1. 31 카드 차감 0원.
• 정산 차감 계약이나 지급할 정산이 계속 없는 경우 5.6 미납 규칙에 따라 계좌 입금 요청.

5.6 미납

• 미납 판정 대상은 회차·일시·조정 청구(CYC·UPF·ADJ)에 한함. AN07·AN08 금액과 SJ-90·SJ-01 경고 금액도 이 범위의 미수만 사용(SJ-99 미수 합계는 단건 포함 전체). 단건 청구(SVC) 미수로는 계약 미정지. 정산 차감 단건은 다음 지급 시 계속 차감, +21일 경과 시 해당 작업만 「보류」 표시(운영자가 게시 보류).

5.7 중도 해지 [결정 필요 D-10]

• 해지일 = 운영자가 해지 처리 시 지정(오늘 또는 이후, 디폴트 오늘). 해당일 23:59까지 노출, 다음 날 00:00 배치에서 상태를 해지로 변경 및 정산 확정.
• 해지일 지정 시 effective_end = 해지일, 해지일 이후 시작하는 회차·청구는 미생성.
• 미리보기(어드민 해지 팝업)는 해지일 기준으로 계산, 「이미 회수」(collected_supply)와 「취소·감액될 미수 청구」, 해지일 전 시작할 회차 청구 예정분 함께 노출. 확정 시 같은 공식으로 재계산, 미리보기와 다르면 OP01 「해지 정산 금액이 바뀜」 발송.
• 선주 요청 해지: 받아야 할 금액 = min(사용 기간 정가, 원 계약 총액).
• 사용 기간 정가 = 1개월 단가 × 끝난 회차 수 + floor(1개월 단가 × 해지 회차 사용일 ÷ 해지 회차 실제 일수). 사용일 = 해지 회차 시작일부터 해지일까지(해지일 포함). 프로모션 기간은 0원.
• 수동 단가 계약은 할인 반환 없이 「수동 월 금액 × 사용 기간」(같은 일할 규칙)으로 계산.
• 정산 순서: ① 해당 계약의 미수 청구 정리: 전혀 회수되지 않은 청구(OPEN)는 취소(VOID). 일부 회수된 청구(PART)는 회수액으로 감액 후 완납(PAID, 감액 이력) 처리. 감액 청구의 부가세 = floor(회수액 ÷ 11), 공급가액 = 회수액 − 부가세. 수정세금계산서는 이 값으로 발행 ② 차액 = 받아야 할 금액 − 이미 회수한 공급가액 ③ 양수면 조정 청구(ADJ) 발행, 음수면 환급(ad_refund) 생성.
• 환급 방법: 정산 차감으로 회수한 분은 다음 지급 시 환급(NEXT_PAYOUT → 지급 묶음 refund_amount로 APPLIED). 30일 안에 해당 선박 지급이 없으면 계좌 환급(BANK)으로 변경, OP01을 발송. 계좌로 수납한 분은 계좌 환급, 경영지원 이체 후 어드민에서 환급 완료 클릭.
• 예: 유어선 A 12개월(월 450,000, 총 5,400,000), 시작일 2027-02-05. 4회차(5. 5~6. 4, 31일) 중 5. 19 해지(사용일 15일) → 정가 = 600,000×3 + floor(600,000×15÷31)=290,322 → 2,090,322. 원 총액 미만이므로 2,090,322. 4회차까지 모두 회수(450,000×4 = 1,800,000) → 조정 청구 290,322원(부가세 별도).
• 회사 귀책 해지: 할인 반환 없이, 이미 청구한 회차의 해지일 다음 날부터 해당 회차 종료일까지 일할 환급(일시 결제면 남은 전체 기간).
• 등급 변경 해지: 할인 반환 없음.
• 조정 청구·환급의 부가세는 단일 식으로 계산: floor(최종 공급가액 × 0.1) − 이미 받은 부가세(양수면 조정 청구 부가세, 음수면 환급 부가세). 1원 차이 방지 목적으로 청구별 개별 계산 금지. 예: 1회차 해지 예시의 환급 = 공급가액 140,323 + 부가세 14,033(45,000 − 30,967) = 154,356원(부가세 포함). 금액 조정은 수정세금계산서로 처리.
• 예(1회차 진행 중 해지): 유어선 A 12개월, 1회차(1. 5~2. 4, 31일) 1. 20 해지 → 사용일 16일 → 정가 floor(600,000 × 16 ÷ 31) = 309,677원 → 1회차 회수 450,000원(정산 차감) → 환급 140,323원(부가세 별도, 다음 지급 시).

5.8 세금계산서

• 청구 건별로 회사가 광고 용역 세금계산서 발행(공급받는 자 = 선박 정산정보의 사업자, 없으면 제휴업체 사업자).
• 1단계는 경영지원이 홈택스에서 발행 후 어드민 청구·납부 관리(AD-83)에 발행일·승인번호 입력 [결정 필요 D-18].
• 수신 이메일: 신청서에서 입력(디폴트 = 제휴업체 정보의 이메일).

6. 측정과 리포트

6.1 지표 정의

6.2 수집 방식

• 세션 ID: 고객웹 셸이 uuid v4로 생성해 sessionStorage af_ad_sid에 저장. 앱이 30분 넘게 백그라운드 상태였다가 복귀 시 재생성. 원격 앱(/booking, /map)은 셸이 주입한 값 사용.
• 기기 식별값 anon_id: localStorage af_anon_id(uuid v4, 영구). 셸이 로그인 직후, 그리고 회원 토큰이 있는 상태로 앱·웹 실행 시(같은 기기·회원 조합은 하루 1회) POST /usr/ads/identify {anon_id} 호출(회원 토큰 필수) → ad_identity에 연결 이력을 행 단위로 누적. 비로그인 클릭은 anon_id로 기록, 같은 기기에서 로그인 후 결제 시 연결.
• 노출 측정: IntersectionObserver(threshold 0.5). 1초 타이머는 다음 중 하나에 해당 시 정지 및 초기화 — 카드가 최상위 패널에 있지 않음(위에 다른 패널이 쌓임), 바텀시트 열림, document.hidden. root 미지정(기본 = 화면). 가로 캐러셀 안에서 가려진 부분은 브라우저가 조상 스크롤 영역 기준으로 잘라 계산하므로, 화면 밖 모듈의 카드는 노출로 미집계. 이미 집계한 (세션, 지면, 선박)은 sessionStorage af_ad_seen에 기록, 뒤로가기·새로고침 시에도 재집계하지 않음.
• 전송: 이벤트를 모아 5초마다 또는 20건 도달 시 POST /usr/ads/events로 전송. 본문은 JSON 문자열, Content-Type text/plain, 인증 헤더 미첨부(다른 도메인이어도 사전 요청 미발생). 회원 연결은 identify로만 처리. pagehide·visibilitychange(hidden) 시 fetch keepalive로 잔여 이벤트 전송. 재전송은 네트워크 오류와 5xx인 경우에 한해 최대 3회, 4xx는 폐기. events 응답에 Access-Control-Allow-Origin(고객웹 도메인 목록과 정확히 일치) 추가.
• 서버는 이벤트에 anon_id·session_id만 저장. 전환 귀속: 결제한 회원이 그 anon_id의 「클릭 시각 이전 마지막 연결 회원」이거나 「클릭과 결제 사이에 연결된 회원」이면 해당 클릭을 결제 회원의 클릭으로 간주(공유 기기에서 이전 회원이 연결돼 있어도 클릭 뒤 로그인한 결제 회원이 우선). contract_idx와 boat_idx 일치 여부, 지면 코드 일치 여부 검증. anon_id당 10분에 300건 초과 요청은 폐기.
• 중복 제거: Redis가 있으면 event_id를 24시간 보관, 없으면 ad_event_dedup(event_id PK) 테이블에 INSERT … ON CONFLICT DO NOTHING으로 필터링, 48시간 지난 행은 매일 삭제. 요청 수 제한은 Redis가 없는 경우 게이트웨이(nginx limit_req, IP당 초당 20건)에서 처리.
• GA4: 같은 시점에 af_ad_impression·af_ad_click(파라미터 placement, boat_idx, contract_idx, position, grade) 전송. GA4 권장 이벤트 이름(ad_impression)과의 중복 방지 목적으로 접두 추가. 원천은 자체 DB임.
• position: 모듈 안 순번(1부터). 이벤트에 module_ctx(지면별 맥락 요약: P2 날짜, P6 장소 코드, P13 옮긴 날짜, P17 날짜)와 card_tier(A/B/C/L 목록 줄/F 조황 카드/M 마커) 함께 전송. 선주 성과 화면(SJ-95)의 「지면별」 표는 12개 지면을 화면 묶음 5개(새소식 홈 · 출조 탭 · 검색 · 지도 · 선박 상세)로 묶어 노출.

6.3 집계

• 매일 00:30 배치: occurred_at(KST) 기준 전날과 그 전날 이틀치를 재집계해 ad_daily_stat(PK stat_date, contract_idx, placement) 덮어쓰기(늦게 도착한 이벤트 반영). 전환 귀속은 전날 결제 완료된 예약 대상으로 168시간 창 안의 마지막 클릭 탐색. 전날 06 취소완료로 변경된 예약(선주가 예약대기에서 거절한 건 포함)은 CANCELED로 변경, 원래 결제일 행에서 예약·결제액 제외 및 취소 수 추가. 부분취소는 전환 금액을 「결제액 − 부분취소액」으로 수정.
• 선주 화면에는 「1. 19(화)까지 집계」처럼 어제 날짜 표기. 성과 조회는 period=cycle(이번 회차)·prev_cycle(지난 회차)·all(전체 기간)·custom(from·to)과 group=day·placement·month 지원. 92일 제한은 group=day에만 적용. 전체 기간은 group=month로 조회.
• 월간 성과 알림(AN15): 매월 3일 10시, 지난달 1일~말일.

7. 화면 목록과 경로

7.1 선주 모바일 (선주 모바일 라우트)

1단계는 「보고 맡기는」 화면만 제작. 신청·요청은 2단계(D-26).

• 1단계 SJ-90E [상담 요청] → 확인 팝업 「영업 담당자가 1영업일 안에 전화드릴게요」 → POST /ptn-m/ads/consults {item_code:'PLAN'}. SJ-94 하단 [연장·변경 문의]는 1단계에서 고객센터 전화 연결(02-722-0365)로 처리. AN10·AN18·AN20·AN21 버튼 링크는 1단계에서 SJ-90으로 연결.

7.2 고객웹

7.3 어드민 (메뉴: 파트너스 > 광고 관리)

7.4 화면 이동

• SJ-01 → SJ-90 · SJ-60 → SJ-90 · SJ-30 → SJ-99
• SJ-90 → SJ-94 · SJ-95 · SJ-96 · SJ-99 · (계약 없음) 상담 요청 확인 팝업
• SJ-94 → SJ-95 · SJ-99
• SJ-96 → SJ-97 → SJ-97R
• (2단계) SJ-90E → SJ-91 → SJ-92 → SJ-92C → SJ-93 → SJ-90 · SJ-94 → SJ-94R · SJ-96 → SJ-98
• 모든 고객웹 광고 카드·배너 → CW-30(날짜가 있는 지면은 &resDt) · AD 표시 → CW-58 → [맞춤 광고 설정] → CW-61
• CW-01 P8 조황 카드 → CW-60 → [이 배 예약하기] → CW-30
• CW-30 예약 달력 마감일 → 「같은 바다로 나가는 배 보기」 → CW-59 → 카드 → CW-30(다른 배, &resDt) · [이날 출항하는 배 모두 보기] → CW-51(지역·날짜)
• CW-40 사진 마커 → 「선박 정보」 바텀시트 줄 → CW-30
• CW-27 P12 카드 → CW-30 · CW-51 P13 카드 → CW-30(&resDt=옮긴 날짜)
• AD-80 → AD-81 · AD-82 · AD-83 → AD-81 · AD-84 → AD-81 · AD-85 → AD-81 · AD-34 → AD-83
• 알림톡 버튼 → 선주 모바일 경로(12장 표의 「연결」 열)

8. 표기 규격

청구 상태 표(모든 화면 공통)

공통 상태(모든 신규 화면)

확인 팝업 공통: 가운데 모달(폭 293), 제목 좌측 정렬, 하단에 풀폭 주 버튼 + 그 아래 텍스트 버튼 취소. 문구에 조사가 붙는 변수(상품명 등) 뒤에는 조사를 쓰지 않도록 문장 구성(예: 「인스타그램 게시, 이대로 맡길까요?」).

9. 데이터 모델 (신규, 스키마 af_re)

기존 테이블·API 변경 - displays.section_code: 015 「광고-이번 주 함께하는 배」 · 016 「광고-이번 주 남은 자리」 · 017 「광고-내일 새벽 출항」 · 018 「광고-선장님 조황 소식」(새소식 홈) 추가(common_code SECTION). 버전은 신버전에 한함. - ad_contract에 first_cycle_upfront bool default true 추가(5.4 계약금 선수취). - partner_users.menu_permit: PTN_MENU에 「AD 광고·홍보」 추가(직원 조회 권한). - 기존 선박 검색 API는 변경 없음. 검색 결과 화면은 검색 API와 서빙 API(P4·P13)를 각각 호출. 서버는 검색 조건 해석 함수 공유. - 선박 노출 여부를 바꾸는 기존 API(어드민 선박정보수정·선주 노출 토글)에서 광고 계약 정지 원인 HIDDEN을 추가·제외하는 훅 호출. 5분 대사 배치로 누락 보정. - 정산 목록 API(선주 /ptn/boats/{id}/settlements, 어드민 정산 목록)에 ad_deduction(예정 또는 확정), final_payout 필드 추가. accounts 값은 변경 없음. - 어드민 [선택지급요청]에 미리보기(preview) 단계 추가: 선박별 gross·deduction·refund·net + preview_token 반환 → 토큰과 함께 확정 요청. - 어드민 정산 목록 엑셀에 「광고비 차감」「광고비 환급」「최종 지급액」 열 추가.

10. API

공통 - 형식: 기존 booking-api 응답 형식. 목록 = {list, total_count, page, limit}. 금액 = 원 정수. 날짜 = YYYY-MM-DD, 일시 = ISO 8601(+09:00). - 오류 코드: AD4097 미리보기 후 금액 변경 · AD4001 필수값 누락·형식 오류 · AD4031 권한 없음(직원·다른 업체 선박) · AD4091 기간 겹침 · AD4092 상태 불일치 · AD4098 이미 처리된 청구 · AD4099 같은 유형 요청 진행 중 · AD4093 월 처리 마감 · AD4094 이용권 없음 · AD4095 수정 횟수 초과 · AD4096 판매 상한 초과 · AD4221 날짜 오류 · AD5001 일시 오류. 응답 {code, message}. message는 화면에 그대로 노출 가능한 문장. 화면 정의서에 문구가 정해진 코드는 화면 정의서 문구 우선.

선주 모바일 | 메서드·경로 | 요청 | 응답 핵심 필드 | |---|---|---| | GET /ptn-m/ads/summary?boat_idx= | — | price_from{A,B,C}(업종별 1개월 단가), max_discount_rate, consult_open(boolean), boat{boat_idx,name,boat_class,region_code}, current_contract{contract_idx,contract_no,grade,status,pause_flags,start_date,end_date,cycle_no,cycle_start,cycle_end,next_bill_date,monthly_price}, other_contracts[{contract_idx,status,grade,start_date}], stats_cycle{impressions,clicks,ctr,bookings,booking_amount,roas,until_date}, quotas[{item_code,name,granted,used}], orders_open[{order_idx,item_code,status,due_date}], current_contract에 wait_order(조회 시 계산), pay_due_at, terminate_date, pay_method, billing_type 포함, warnings[{code:'NO_PRODUCT'|'UNPAID'|'HIDDEN'|'OPS',message}], unpaid_amount, open_orders_count, has_invoices, quotas[{item_code,name,granted,carried_in,used}], is_owner · unpaid_amount = 미납 판정 대상(CYC·UPF·ADJ) 미수(정지 경고 문구용), unpaid_total = 단건 포함 전체 미수(「광고비 내역 · 미수 N원」 줄용) | | GET /ptn-m/ads/plans?boat_idx=&start_date=&months=&grade=&billing_type= | start_date·months 미전달 시 min_start_date·3개월 기준 | boat_class, max_discount_by_grade, region_code, region_name, grades[{grade,monthly_by_months{1,3,6,9,12},discount_by_months,benefits[{item_code,label,qty}],placements[], remaining_slots, is_full}], min_start_date, has_settlement_info, tax_email_default, boat_visible, min_product_price(본전 계산 줄), terms_version, quote{grade, months, start_date, end_date, monthly_price, vat, bill_amount, total_price, saved_amount}(grade 전달 시 해당 등급, 미전달 시 B) · SJ-92에서 등급·약정·시작일·청구 방식 변경 시마다 재호출 | | POST /ptn-m/ads/contracts (헤더 Idempotency-Key) | {boat_idx, grade, months, start_date, pay_method:'D'|'T', billing_type:'M'|'U', tax_email, terms_version} | 201 {contract_idx, contract_no, status:'REQ'|'WAI', wait_order, start_date, end_date, monthly_price, vat, bill_amount, total_price} · AD4001 · AD4031 · AD4091 · AD4221(시작일 < min_start_date) · AD4001(pay_method D 선택 시 정산정보 없음 → message 「정산정보가 없어 계좌 입금만 고를 수 있어요」) | | GET /ptn-m/ads/contracts?boat_idx= | — | list[{contract_idx,contract_no,grade,months,status,start_date,end_date}] | | GET /ptn-m/ads/contracts/{id} | — | 계약 전체 + cycles[{cycle_no,start,end}] + invoices[] + history[{to_status,reason,created_at}] + requests[] + quotas_by_cycle | | POST /ptn-m/ads/contracts/{id}/cancel | — | 200 · AD4092(확인 중·대기 상태 아님) | | POST /ptn-m/ads/contracts/{id}/requests | {type:'EXT'|'CHG'|'TRM', target_grade?, memo(0~300자)} | 201 {request_idx} · AD4099(동일 유형 OPEN 요청 존재) · 일시 결제 계약의 CHG는 AD4092 | | GET /ptn-m/ads/contracts/{id}/stats?period=cycle|prev_cycle|all|custom&from=&to=&group=day|placement|month | group=day인 경우에 한해 최대 92일 | rows[], totals{impressions,clicks,ctr,bookings,booking_amount,canceled,ad_cost_supply,roas}, until_date | | GET /ptn-m/ads/contracts/{id}/conversions?page=&limit=20 | — | list[{paid_at,masked_name,people,amount,placement,status}] | | GET /ptn-m/ads/invoices?boat_idx=&status=&page= | — | list[{invoice_idx,invoice_no,kind,title,bill_date,due_date,supply,vat,total,paid,status,pay_method,deductions[{payout_date,amount}],deposits[{date,amount}],tax_issued_at}], refunds[{refund_idx, contract_no, invoice_idx, supply, vat, total, method:'NEXT_PAYOUT'|'BANK', status, created_at, payout_date, done_at}], unpaid_total, bank{name,account,holder,depositor_rule} | | GET /ptn-m/ads/service-items?boat_idx= | — | list[{item_code,name,price,unit,lead_days,desc,is_closed_this_month,quota_left}] | | POST /ptn-m/ads/service-orders (헤더 Idempotency-Key) | {boat_idx, item_code, source:'Q'|'B', memo(0~500), pay_method?, meta{budget,start,end}?} | 201 {order_idx, status, invoice?} · AD4093 · AD4094 · AD4001(S4 예산 300,000 미만·S4 정산 차감 선택) | | POST /ptn-m/ads/consults | {boat_idx, item_code:'PLAN'|'S6', contact_time(S6 필수 2~50자, PLAN 선택), memo(0~500)} | 201 · OP01 발송 · 동일 선박·item_code의 OPEN 상담 존재 시 AD4099 | | GET /ptn-m/ads/service-orders?boat_idx=&tab=open|done | — | list[{order_idx,order_no,item_code,name,status,source,due_date,scheduled_at,updated_at}] | | GET /ptn-m/ads/service-orders/{id} | — | 작업 전체 + files[{kind,url,thumb,mime}] + timeline[] + review_due_at | | POST /ptn-m/ads/service-orders/{id}/upload-urls | {files:[{name,size,mime}]} (최대 20개) | [{file_key, upload_url(서명 URL, 15분)}] · 크기·형식 초과 AD4001 | | POST /ptn-m/ads/service-orders/{id}/materials | {file_keys[], memo(0~500)} | 200, 상태 MAT → WIP | | POST /ptn-m/ads/service-orders/{id}/approve | — | 200 · AD4092 | | POST /ptn-m/ads/service-orders/{id}/revision | {memo 10~500자} | 200 · AD4095 |

• 1단계 미개발 선주 API(2단계): GET /ptn-m/ads/plans · POST /ptn-m/ads/contracts · POST …/cancel · POST …/requests · GET /ptn-m/ads/service-items · POST /ptn-m/ads/service-orders의 source B(단건 앱 구매). 1단계 consults는 item_code 'PLAN'(등급 상담)과 'S6' 수신.
• 업로드 제한: 사진 jpg·png·heic(서버에서 jpg 변환) 장당 20MB, 최대 20장 / 영상 mp4·mov 1개 300MB. 파일별 서명 URL로 직접 업로드(저장소·common_file 연결 방식은 [확인 필요 — 기존 조황 이미지 업로드 경로 재사용]).

고객웹 | 메서드·경로 | 요청 | 응답 | |---|---|---| | POST /usr/ads/slots | JSON 본문 {session_id, page_key(화면 1회 진입마다 uuid), placements:[표시 순서대로 예 'P1','P2','P3'], lat?, lng?, ctx:{P4·P13: 검색 파라미터 원본 · P5: boat_idx · P17: boat_idx, date · P6: place_code · P14: bbox 'sw_lat,sw_lng,ne_lat,ne_lng' · P7·P8·P12·P1~P3: 없음}}, 회원 토큰(있는 경우). Content-Type application/json | {slots:{지면코드:{title, items[{card, tier:'A'|'B'|'C'|'T'|'R'|'S'|'M', reason, res_dt?, ad{contract_idx, grade, label:'광고'}}], groups?(P1 지역 탭 · P2 날짜 탭 {key, label, tide?, items[]}), search_query?(P17: {area, reservation_dt}, items가 비어도 항상 반환)}}} · 해당 없는 지면은 items [] (프론트는 모듈 미노출) | | POST /usr/ads/identify | {anon_id} (회원 토큰 필수) | 204 | | POST /usr/ads/events | 인증 헤더 없음, 응답에 Access-Control-Allow-Origin, text/plain JSON {session_id, anon_id, events:[{event_id,type,placement,contract_idx,boat_idx,position,card_tier,module_ctx,page_key,occurred_at,query}]} 최대 50건 | 202 | | GET·PUT /usr/ads/pref | 회원 토큰 필수 · PUT {personalized:boolean} | {personalized} |

• card = 기존 선박 카드 필드(boat_idx, name, port_name, region_text, distance_km, min_price, fish_tags[최대 3], image) + near_seat{date, seats} · 상품 줄(P2·P3·P14·P17) {date, product_name, seats, product_idx, tide} · 목록 줄(P3) {depart_time, seats, wave} · 조황 카드(P8) {catch_idx, catch_photo, fish, catch_text, posted_at} · 마커(P14) {lat, lng, thumb} · 배너(P6·P7·P12·P17) banner{title1, title2, sub, image} · 추천리스트(P4·P13) {reason_keys[3], product_count}. 등급별 필드 차이 없음.
• 한 요청의 placements 내에서 서버가 노출 순서대로 선정, 동일 선박의 3번째 노출 차단(3.1). 서버는 page_key 미저장, 이벤트 묶음 키로만 사용.
• 제목: 섹션 지면(P1·P2·P3·P8)은 전시관리(display-v2) 타이틀 사용, 그 외 지면은 응답 title(ad_module_rule 이름) 사용.
• events.query는 P4·P13에 한해 검색 파라미터 원본 포함, 그 외 지면은 null.
• 지면 응답은 3.6의 캐시와 세션 해시로 생성(서빙 중 DB 조회는 3.6에 명시한 네 가지에 한함). 300ms 내 생성 실패한 지면은 items []로 응답.
• 맞춤 광고 해제 회원(또는 비회원)은 uses_personal 지면(P7)에서 items [], P1 탭 노출 순서에 예약 이력 미반영.

어드민 | 메서드·경로 | 설명 | |---|---| | GET /adm/ads/contracts?keyword=&status=&grade=&region=&pay_method=&boat_class=&date_type=REQ|START|END&start=&end=&page=&limit= | 계약 목록 {list[{contract_idx, contract_no, boat_name, company_name, region_name, grade, months, status, pause_flags, start_date, effective_end, pay_method, monthly_price, requested_at, wait_order}], total_count, counts{REQ, WAI, PAY, SCH, ACT, PAU, UNPAID}} | | GET /adm/ads/boats?keyword= | AD-82 선박 검색 [{boat_idx, name, company_name, region_name, boat_class, max_people, visible, products_30d, has_settlement_info, has_open_contract}] | | POST /adm/ads/contracts | 대리 등록 {…신청 필드, status:'DRF'|'REQ', is_manual_price, monthly_price, manual_reason, promo_days, annual_lump(true 시 months 12 · billing_type U · pay_method T 고정, 프로모션 30일 자동)} | | GET /adm/ads/contracts/{id} · PATCH /adm/ads/contracts/{id} | 상세·수정(DRF·REQ·WAI에 한해 조건 변경 가능, PAY·SCH·ACT에서는 promo_days·tax_email·memo만 변경 가능) | | POST /adm/ads/contracts/{id}/approve {start_date?, dry_run?} · /waitlist · /cancel {memo} · /reject {reject_code, memo} · /pause {memo, company_fault} · /resume · /terminate {reason, terminate_date, settle_preview:boolean} · /change-grade {target_grade, start_date, months, pay_method, tax_email?} · DELETE /adm/ads/contracts/{id}(임시저장 건에 한함) | 상태 변경. approve dry_run=true → {start_date, inventory{region_used, region_cap, nation_used, nation_cap}, capacity_warnings[{item_code, short_by}], overlap{conflict:boolean, contract_no?}}(시작일 지연으로 동일 선박의 다른 계약과 기간 중복 시 승인 팝업에 사전 노출). terminate settle_preview=true → {terminate_date, cycle_no, cycle_days, used_days, list_price_used, due_amount, collected_supply, voided_invoices[], diff, action:'ADJ'|'REFUND'|'NONE', refund_method} | | GET /adm/ads/invoices · POST /adm/ads/invoices/{id}/deposits {amount, depositor_name, deposited_on, on_cap_full:'WAIT'|'REFUND'} · POST /adm/ads/deductions/{id}/reverse {reason} · PATCH /adm/ads/invoices/{id}/tax {tax_invoice_no, tax_issued_at} · POST /adm/ads/invoices/{id}/void {memo} | 청구·입금·세금계산서. 목록 응답에 summary{billed, collected, unpaid, overdue_21} 포함 | | GET /adm/ads/refunds?status= · POST /adm/ads/refunds/{id}/complete {memo} | 환급 목록 {list[{refund_idx, boat_name, contract_no, supply, vat, total, method, status, created_at, switch_due_at, payout_date, done_at}]}·계좌 환급 완료 | | POST /adm/payouts/preview {accounts_idx[]} → {boats[{boat_idx,gross,deduction,refund,net}], preview_token} · POST /adm/payouts {accounts_idx[], preview_token} · AD4097 | 지급 요청 미리보기·확정(차감 포함) | | GET /adm/ads/consults · PATCH /adm/ads/consults/{id} | 상담 신청 | | GET /adm/ads/service-orders?status=&item_code=&assignee=&boat=&page= · PATCH /adm/ads/service-orders/{id} {status?, assignee_admin?, due_date?, scheduled_at?, cancel_reason?, ops_shortfall_inc?} · POST /adm/ads/service-orders/{id}/results {file_keys[], result_url, result_note, disclosure_checked} | 작업. 목록 응답에 counts{REQ, MAT, WIP, REV, APV, DONE, CXL, overdue} 포함 · POST /adm/ads/service-orders {boat_idx, item_code, pay_method, memo}(어드민 대리 주문) | | GET /adm/ads/placements/stats?from=&to= · GET /adm/ads/placements/inventory?region=&grade=&start=&months= | 지면 현황·재고(AD-82 잔여 슬롯은 기간 파라미터로 계산) | | POST /adm/ads/contracts/{id}/requests {type:'EXT'|'CHG'|'TRM', target_grade?, memo} · PATCH /adm/ads/requests/{id} {status:'DONE'|'REJ'} | 1단계: 전화·영업으로 접수된 선주 요청을 운영자가 기록·처리 | | GET·PUT /adm/ads/prices · /adm/ads/caps · /adm/ads/service-items · /adm/ads/settings | 단가·상한·단건·스위치 | | GET·PUT /adm/ads/module-rules | 지면 12개 이름·스위치(금지어 검사) | | GET·PUT /adm/ads/contracts/{id}/creative · POST …/creative/review {result:OK|REJ, memo} | 카드 소재 저장·검수 |

11. 배치 (전부 Asia/Seoul, 서버 여러 대여도 한 번만 실행되게 DB 잠금, 실패 시 구글챗 「알림_광고」 알림, 같은 날 재실행해도 결과가 같게)

• 00시대 배치 생성 알림톡은 발송 큐에 추가 후 08:00 발송(선주 앱 알림함은 즉시 반영).
• 테스트: dev·stage 환경에 한해 열리는 배치 실행 API POST /dev/ads/batch/{name}?now=ISO일시로 기준 시각 변경 후 실행(운영 환경은 환경변수로 라우트 자체 미등록).

12. 알림 카탈로그

• 링크: 선주 모바일 링크 전체에 boat_idx 추가(예 /ads/invoices?boat_idx=6). id 기반 진입 화면은 응답의 boat_idx 기준으로 선택 선박 동기화.
• 수신 대상: 선주 = 업체 대표 휴대폰으로 알림톡(SOLAPI, 실패 시 문자 대체) + 선주 모바일 알림함(/alarm). 운영 = 구글챗 「알림_광고」 웹훅.
• 중복 방지: ad_notice_log unique(company_idx, code, target_id, kst_date). 미납 알림은 청구의 due_notice_at·overdue_at 기준 한 번만 발송.
• 템플릿 21종 카카오 비즈메시지 신규 등록(승인 3~5영업일, 10/30까지 신청). 1단계 템플릿의 버튼 경로는 1단계 화면으로 한정(AN10·AN18·AN21 → /ads, AN20 → /ads/orders). 2단계에서 신규 템플릿으로 변경.

13. 권한·감사·개인정보

• 선주: 대표 계정 = 전체 기능 사용 가능(1단계 화면 + 2단계 신청 화면). 직원 계정 = 조회 + 자료 업로드만 가능. 직원 계정 미노출 버튼: SJ-90 이용권 [맡기기], SJ-90E 등급 고르기, SJ-91 등급 신청 버튼, SJ-92 전체(진입 시 「대표 계정만 신청할 수 있어요」 안내 후 이전 화면 이동), SJ-94 하단 버튼, SJ-96 이용권 칩(조회만 가능, 탭 시 반응 없음), SJ-97 [이대로 올려 주세요]·[수정 요청], SJ-98 [신청하기]·[상담 신청].
• 어드민: 관리자 권한 등급 부재(현행)로 모든 관리자 처리 가능. 상태 변경·단가 수정·수동 단가·입금 확인·청구 취소·지급 차감·해지 시 ad_contract_history(field_changes 포함)와 admin_log에 처리자·사유·변경 전후 값 기록.
• 맞춤형 광고: 예약 이력 기반으로 선택하는 지면(P7, P1 탭 순서)에 한해 맞춤형 광고로 분류. 개인정보 처리방침에 「맞춤형 광고」 항목(이용 정보: 예약 지역·어종, 목적, 거부 방법) 추가, CW-61에서 끄기 가능. 위치 정보는 동의한 경우에 한해 해당 요청에만 사용, 저장하지 않음. 화면 노출 장소·검색 조건 기반으로 선택하는 지면(P4·P6·P13·P17 등)은 맞춤형으로 분류하지 않음 [법무 확인 D-28].
• 개인정보: 광고 로그에는 회원번호·기기 식별값만 저장, 이름·연락처 미저장. 선주 화면의 「광고로 들어온 예약」은 예약자명 「김*수」 마스킹 처리, 연락처 미노출. 원천 로그 13개월 보관, 일 집계 영구 보관 [처리방침 반영 여부 법무 확인 필요].

14. 예외와 동시성

15. 비기능 요건

• 서빙 API(/usr/ads/slots) 응답 p95 200ms 이하(노출 대상 캐시 60초 무효화 + 맥락 10분 캐시 + 세션 해시). 새소식 홈은 P6·P7·P8을 일괄 호출, 화면 렌더링 대기 없음(응답 지연 시 해당 슬롯만 채움, 레이아웃 밀림 방지 목적으로 P8 줄 높이 96 사전 확보).
• 이벤트 수집 API는 202 즉시 응답 후 큐에 추가. Redis 존재 시 Redis Stream, 미존재 시 ad_event_inbox 테이블(수신 원본 그대로 적재 → 1분 배치로 ad_event 이관)로 대체 [D-24]. 하루 최대 50만 건 기준.
• 고객웹 광고 모듈 실패 시 모듈만 미노출, 화면은 정상 노출 유지(서빙 API 타임아웃 1초).
• 움직임: 광고 카드 자동 넘김·자동 재생 미적용(기존 가로 넘김은 수동 조작만 허용).
• 금액 계산은 서버에서만 처리. 화면은 서버 값 그대로 사용.
• 접근성: AD 표시에 스크린리더가 「광고」로 읽도록 aria-label 적용(화면 노출 글자는 AD). 바텀시트 열림 시 제목으로 초점 이동, 닫힘 시 바텀시트를 연 버튼으로 초점 복귀. 토글은 role="switch" 적용. 지도 마커는 「광고, {선박명}」으로 읽힘. AD 표시와 마커의 터치 영역은 44×44 이상(노출 크기 25×14, 터치 영역만 확장).
• 셸 공유: 노출 추적·AD 표시·광고 안내 바텀시트는 공용 패키지 하나로 구성, 셸과 원격 앱(/booking, /map)이 동일 인스턴스 사용(session_id·anon_id 공유) [확인 필요: 8월통합 셸의 원격 앱 공유 방식]. 주소에 쿼리가 없는 경우 바텀시트는 ?sheet=ad-info로 열림.

16. 일정과 공수

16.1 일정

16.2 공수 (맨데이)

개발 검토(프론트·백엔드 각 1명) 의견 반영 값임.

인력 배치(본안 = 1단계 지면 12개 1/5 일괄 오픈) - 백엔드 53.5일 = 최상수 22.5일(계약·청구·차감·정산 연결·훅·알림·연간 일시 계약 21.0 + QA 수정 1.5, QA 수정은 12/14 이후) + 외부 백엔드 31.0일(서빙·맥락·이벤트·작업·어드민 API·테스트·QA 수정). 외부 계약 기간 11/2~12/24로 설정(온보딩 3일 제외 시 35일 중 31.0일). - 프론트 41.0일 = 송창석 27.0일(어드민 12.5 · 선주 6.5 · 고객웹 6.0 · QA 수정 2.0) + 외부 프론트 14.0일(공용 패키지 5.0 · CW-01·CW-60 4.0 · CW-50 P3 1.0 · CW-40 1.5 · CW-61 1.0 · QA 수정 1.0 · 인수인계 0.5, 계약 11/2~11/27 + QA 기간 1일). 송창석은 11/2~11/27에 AD-80~83 우선 완료 후 12/7 선QA 일정 대응, 외부 프론트는 11/2 첫 주에 공용 패키지 제작 [결정 필요 D-34]. - 착수 전 조건: D-19(백엔드 인력), D-34(프론트 인력), D-35(셸 공유·필드 확인), D-22(대표·직원 구분 컬럼), D-23(지급 후 이체 방식 실측), D-24(Redis 유무), D-25(업로드 저장소), D-28(맞춤형 광고 처리방침).

절단안(외부 프론트 미확보 시 적용, 11/2 확정) - 2/15(1.5단계)로 연기: P8 조황 카드와 CW-60(프론트 4.0 · 백엔드 0.5), P14 지도 사진 마커(프론트 1.5 · 백엔드 0.5), 성과 일별 그래프(프론트 1.0 · 백엔드 0.5), 메타 대행 결과 입력 화면(백엔드 1.0, 운영 시트), 월간 성과 알림 AN15(백엔드 1.0). - 결과: 프론트 34.5일(송창석 27.0 + 외부 프론트 7.5) · 백엔드 50.0일 · 1단계 지면 10개. 송창석 단독 진행 시 30영업일 초과로 절단안에서도 외부 프론트 필요.

17. 운영 체계

• 3개월 후 30척(A 5 · B 10 · C 15) 기준 월 작업량 = 조황 업로드 110건(A 40 · B 40 · C 30) · 인스타 게시 20건 · 릴스 5건 · 카카오 소식 칸 20칸 · 메타 대행 6건(A 5 + B 분기 1건 환산) · 네이버 키워드광고 계정 관리 15척(A 5 · B 10, C는 신청분) · 상품·일정 등록 15회 + 첫 회차 소개 정비 30건·촬영 최대 5회 [가정] → 1~1.5명분 필요. 네이버 키워드광고는 선박당 월 1~2시간(키워드·입찰가 조정, 월말 보고) 기준으로 산정.

18. 결정 필요

19. 리스크

20. 수용 기준 (QA 시나리오 요약 — 전체 47개는 QA 시트)

1. 영업이 AD-82에서 A등급 3개월·정산 차감·계약금 선수취 활성 상태로 대리 등록 시 → 확인 중, AN01. 승인 시 → 입금 대기, 1회차 660,000원 계좌 청구, AN04.
2. 입금 확인 → 집행 예정 → 시작일 00:00 집행 중 → 5분 이내 P1·P2·P3 등 A 지면 노출. 2회차 청구는 정산 차감 처리.
3. 동일 지역 A 6건 집행 중 상태에서 신청 시 → 대기(1번째). 한 건 만료 시 → 다음 날 00:20 확인 중 전환, AN16.
4. 직원 계정은 SJ-90E에 [상담 요청] 버튼 미노출, 상담 API를 직접 호출 시 AD4031 반환.
5. 회차 청구 660,000원(부가세 포함) 상태에서 운영자가 해당 선박 지급액 300,000원 행으로 지급 요청 시 → 미리보기 차감 300,000 · 최종 0, 확정 시 → 청구 PART 300,000. 다음 지급 요청 500,000 시 → 차감 360,000 · 최종 140,000 → PAID.
6. 지급 요청 두 번 클릭 시에도 차감은 한 번만 처리.
7. 청구 21일 미수 시 → UNPAID 정지, 5분 이내 전체 지면에서 제외, 입금 확인 시 → 재개, AN09.
8. P4: 검색어 「인천」, 일반 결과 38척(광고 A 2·B 3·C 2 포함) 시 → 목록 상단 묶음 A·A·B 노출(동일 세션 내 노출 순서 유지), 일반 목록은 광고 선박 포함 38척 그대로 유지, 「38건의 검색 결과」 노출. 정렬 기준을 가격순으로 변경해도 묶음은 최상단 유지, 일반 목록만 재정렬.
9. P2: 내일 잔여 좌석 6석 상품만 있는 광고 선박은 내일 탭 미노출.
10. 광고 카드 50% 노출 0.8초 후 스크롤로 화면 이탈 시 → 노출 0. 1.2초 시 → 노출 1. 동일 세션 내 재노출 시에도 1.
11. 광고 클릭 후 167시간째 결제 시 → 전환 1. 169시간째 결제 시 → 0. 비로그인 클릭 후 동일 기기에서 로그인·결제 시 → 전환 1(클릭과 결제 사이 최초 연결 회원 기준). 로그인 상태로 앱 실행 후 클릭·결제 시 → 전환 1(앱 시작 시점 identify).
12. 시작일 2027-01-31, 3개월 → 회차 01-31·02-28·03-31, 종료일 04-29.
13. 해지 정산 예시(5.7) 금액과 화면 미리보기 금액 일치.
14. 인스타 게시 작업: 결과물 「표시 확인」 체크 없이 「선주 확인」 단계로 전환 불가.
15. 결과물 확인 요청 후 72시간 무응답 시 → 자동 승인 → 게시 준비 전환, OP02.
16. 수정 요청 2번째 시 → AD4095 반환.
17. 월 처리 상한 도달 후 단건 신청 시 → AD4093 반환, 마감 문구 노출.
18. 선박 노출안함 처리 시 → 계약 일시정지(HIDDEN), 노출 재설정 시 → 재개.
19. 서빙 API 1.5초 지연 시 → 해당 모듈만 미노출, 검색 결과·출조 탭·홈은 정상 유지. P6 실패 시 날씨 카드는 그대로 유지.
20. 광고 안내 바텀시트 문구는 3.4와 일치, 뒤로가기 시 닫힘.
21. 입금 대기 중 시작일 경과 후 입금 확인 시 → 시작일을 입금 확인 다음 날로 변경, 종료일·회차 재계산.
22. 동일 선박에 기간이 겹치는 계약을 운영자 두 명이 동시 대리 등록 시 → 하나만 생성, 나머지 하나는 AD4091 반환.
23. 지급 미리보기 후 다른 운영자가 입금 확인 시 → 확정 요청 AD4097 반환, 미리보기 재실행 시 줄어든 차감액 반영.
24. 해지일을 오늘로 처리 시 → 오늘 23:59까지 노출, 다음 날 00:00 해지, 환급 금액은 5.7 예시와 일치.
25. 인스타 게시 승인 시 → 「게시 준비 중」 → 운영자 링크 입력 후 [완료 처리] → 완료, AN14.
26. 검색 결과 2페이지 이후 광고 미노출(묶음은 1페이지 상단에 한함).
27. 인천 A 6/6 · 대기 2건(1번 4. 5 시작 3개월, 2번 2. 5 시작 1개월). 2. 5~3. 4에 한해 1자리 잔여 시 → 1번은 기간(4. 5~7. 4) 판정 실패, 2번은 기간이 1번과 겹치지 않아 판정 진행 후 통과 → 2번 확인 중 전환. 1번과 기간이 겹치는 후순번은 건너뜀. 그 사이 신규 신청은 대기로 진입. 대기에서 올라온 확인 중 계약이 있는 동안 동일 슬롯으로 다음 대기자 승격 불가.
28. A → B 등급 변경(change-grade): 신규 계약 생성, 기존 계약 해지 예정 처리, 기존 계약 슬롯은 해지일 다음 날부터 빈 슬롯으로 처리되어 겹침 제약(AD4091) 대상 아님.
29. 해지일을 다음 회차 시작일 이후로 지정 시 → 해당 회차 청구는 회차 시작일에 생성, 미리보기 「해지일 전 청구 예정」에 포함. 해지일 이후 회차 청구는 미생성. 해지 확정 시 미회수 청구는 취소, 일부 회수 청구는 감액 후 완납 처리, 차액만 조정 청구 또는 환급.
30. 계좌 단건 신청 후 168시간 미입금 시 → 작업·청구 취소, AN20. 정산 차감 단건 미수 21일 경과 시 → 계약 정지 없이 작업만 보류 표시.
31. 00:00 배치 하루 실패 시 → 다음 날 실행에서 전날 시작 예정이던 계약·회차·청구 일괄 처리.
32. 운영 사정 취소 작업의 이용권은 복원, 자료 미제출 취소 작업의 이용권은 미복원. ops_shortfall 1 → 다음 회차 carried_in 1, 그다음 회차로는 이월 불가.
33. 660,000원 청구 중 300,000원 회수 상태에서 해지 시 → 해당 청구는 300,000원(공급가액 272,728 · 부가세 27,272)으로 감액 완납, 차액은 기회수 공급가액 기준으로 계산.
34. 대기 1번의 희망 시작일 경과 시에도 판정 기간을 오늘 + 2영업일부터 재설정. 희망 시작일 + 30일 경과 시 자동 취소, AN21. 서로 다른 지역 두 건이 전국 마지막 1자리를 동시 승인 시 하나만 성공.
35. 계좌 결제로 등급 변경 시 → 신규 계약 입금 대기 168시간 경과로 취소 → 원 계약 해지 예정 해제, 집행 중 유지, 이력 change_grade_rollback, OP01.
36. P2: 1. 22(금) 탭 하단에 지역 표기법(인천 = 7물때식) 기준 물때 노출, 카드 탭 시 → CW-30 진입, 달력 1. 22 선택 상태.
37. P3: 내일 출항 상품이 있는 A·B 광고 선박 2척 시 → 모듈 미노출. 4척 시 → 출항 시각순 4줄 노출, 모듈 헤더에 AD 표시.
38. P13: 날짜 1. 22로 「격포」 검색, 일반 결과 3건 시 → 결과 하단 「하루만 옮기면」 묶음 노출, 카드 「1. 23(토) 4석」 탭 시 → CW-30 &resDt=2027-01-23 진입. 일반 결과 5건 이상 시 묶음 미노출.
39. P17: CW-30에서 마감된 1. 22 탭 시 → 날짜 하단 「같은 바다로 나가는 배」 배너 노출 → CW-59에 동일 지역 1. 22 잔여 좌석 광고 선박 노출(현재 선박 제외) → 카드 탭 시 → 해당 선박 CW-30(&resDt=2027-01-22) 진입. 광고 선박 0척 시 AD 없는 배너로 일반 검색 안내.
40. P6: 관심장소 「영흥도」(인천), 예보 1. 21 1.8m · 1. 22 0.5m · 1. 23 1.0m, 광고 선박 잔여석 1. 21·1. 22 시 → 「1. 22(금) 파고 0.5m · N석」 노출. 5일 모두 1.5m 초과 시 배너 미노출(해당 지면은 기존 AD 배너 노출 또는 빈 영역 처리).
41. P7: 남은 예약 있음 시 → D-day 카드 노출. 남은 예약 0 + 지난 예약(인천 쭈꾸미) 시 → 인천 쭈꾸미 광고 선박 「다음 출조, 이 배는 어때요?」 카드 노출. CW-61에서 맞춤 광고 해제 시 → 다음 요청부터 P7 미노출, P1 탭 노출 순서에서 예약 지역 우선 제외.
42. P8: 광고 선박 4척이 72시간 이내 조황 등록 시 → 앞 3장만 광고(AD 표시), 4번째 광고 선박은 일반 카드에 최신순 노출(광고 표시 없음). 카드 탭 시 → CW-60 진입, [이 배 예약하기]만 클릭으로 집계.
43. P14: 지도에 광고 항구 5곳이 노출된 화면 → 사진 마커 3개 노출. 지도 이동 시 재선정. 마커 탭만 한 경우 클릭 0, 「선박 정보」 바텀시트 행 탭 시 클릭 1.
44. 출조 탭에서 placements=P1,P2,P3를 일괄 요청, 동일 선박이 세 모듈 조건에 모두 해당 시 P1·P2에 노출, P3에서는 제외 후 다음 후보로 채움. P2의 날짜 탭 5개에 동일 선박이 노출되어도 1번으로 집계. 동일 요청 재전송 시에도 결과 동일.
45. 카드 모양: A·B·C 계약 선박이 동일 지면에 노출 시 카드 모양은 동일, 노출 순서만 A → B → C. AD 표시는 모든 경우 유지.
46. 연간 일시 계약: 유어선 A로 대리 등록 시 → 승인 시점 총액 청구 5,544,000원(부가세 포함) 1건 생성, 종료일 = 12개월 + 30일, 1회차에 O1 이용권 1건, 7회차에 O1 1건 추가. 정산 차감 선택 불가.
47. S7: C등급 계약 선박이 네이버 키워드광고 대행을 광고비 200,000원으로 신청 시 → 수수료 30,000원(15%, 최소 금액과 동일)에 50% 할인 = 15,000원, 청구 215,000원(부가세 별도). A등급은 수수료 0원.

부록 A. 아이디어 선별 (215건 → 1단계 12 · 2단계 7 · 3단계 6)

7개 작업으로 나눠 수집한 아이디어. 지면 53(PL) · 카드 32(CD) · 맥락 35(CX) · 콘텐츠 29(CT) · 해외·국내 사례 28(BM) · 기발한 것 30(WD) · 법 검토 39(LG). 선별 기준은 네 가지. ① 고객이 이미 무언가를 결정한 순간인지 여부 ② 선주가 「우리 배가 이렇게 나간다」고 체감하는지 여부 ③ 「광고」 표시를 첫 시선에 배치 가능한지 여부 ④ 1단계 공수 범위 내인지 여부.

A.1 채택

A.2 보류·제외

A.3 참고한 사례에서 가져온 것

부록 B. 물때 표기 표 (P2)

음력 일 → 물때 이름. 서해(인천·경기·충남·전북)는 7물때식, 그 밖(전남·경남·경북·강원·제주)은 8물때식 적용. 서빙 API에서 tide 문구 생성. 「사리」는 7물때식 7물, 8물때식 8물 날에 표기 [확인 필요: 국립해양조사원 표기와 하루 차이 여부].

• 예: 2027-01-22(금)는 음력 12월 15일 → 서해 「6물」, 2027-01-23은 음력 16일 → 「7물 사리」.

부록 C. 피그마 섹션 노드

피그마 파일 「클로드 광고시스템」 페이지. 밴드 순서 OV(개요 15 + 흐름도 OV-16) → SJ(선주 모바일 17) → CW(고객웹 10 + 디자이너 핸드오프 HO-01) → AD(어드민 9). CW 목업은 8월통합 실컴포넌트 복제본(글꼴은 Noto Sans KR로 임시 교체, 디자이너가 Pretendard로 일괄 교체). 각 섹션 헤더 아래 진입·이탈 행의 화면 ID를 클릭 시 해당 섹션으로 이동.

21. 화면 정의서

화면 36개 · 번호는 Figma 정책 카드와 프로토타입 번호 영역과 같다(위 → 아래).

선주 모바일

고객웹

어드민

22. 개발 검토 결과

검토는 프론트엔드·백엔드 시니어 관점 리뷰어 2명이 v1.5 기획서(spec_core), 화면 정의서 36개, 프로토타입 코드를 읽고 2회 검토했다. 판정 기준은 「이 문서만 보고 착수할 수 있는가」다.

2차 지적은 모두 이 판에 반영했다.

착수 조건(기획서 밖 결정).

리뷰어가 다시 계산해 맞다고 확인한 숫자: 단가표와 월 금액, 회차 예시 4건, 해지 정산 예시 2건(조정 청구 290,322원 / 환급 154,356원 부가세 포함), 공수 합계(프론트 40.0 = 고객웹 18.5 + 선주 6.0 + 어드민 12.0 + QA 수정 3.5 · 백엔드 52.0 = 최상수 21.0 + 외부 31.0), 등급별 지면 수(A 12 · B 11 · C 6).