# 07. 자동 검수·자동 세팅 프로그램 설계안

> 질문: "나와 담당자가 신경 쓰지 않아도 자동으로 검수·세팅해주는 프로그램을 만들 수 있나?"
> 답: **만들 수 있다.** 단, "아이디/비번으로 관리자 화면을 조작하는 컴퓨터 유즈"는 최후 수단이고,
> 대부분은 더 안전하고 안정적인 방법(API·프론트 크롤링)으로 커버된다. 아래 순서로 만든다.

## 1. 설계 원칙

1. **검수(읽기)와 세팅(쓰기)을 분리한다.** 읽기는 전면 자동화, 쓰기는 반드시 사람 승인 게이트를 거친다.
   - 반품 기능을 "실수로 끄는" 자동화는 반품 기능이 "꺼진 걸 모르는" 것보다 더 위험하다.
2. **API 우선, 화면 조작은 최후.** 화면(DOM)은 카페24 개편 한 번에 깨진다. API는 계약이다.
3. **고객 화면 기준으로 검증한다.** 관리자 설정값이 아니라, 실제 고객이 보는 화면에서 버튼이 렌더링되는지를 본다. 이번 "1초 로그인 사고"는 관리자만 봐서는 못 잡는 유형이다.
4. **모든 실행은 로그와 리포트를 남긴다.** "자동화가 돌았는데 아무도 결과를 안 본다"는 같은 사고의 반복이다.

## 2. 계층별 수단 (커버리지 맵)

| 계층 | 수단 | 인증 | 커버 항목 |
|---|---|---|---|
| A. 프론트 크롤링 | Playwright (헤드리스 브라우저) | 불필요 (공개 페이지) | 카카오 로그인 버튼 렌더링, GA4/GTM/픽셀 스크립트 존재, OG/메타/JSON-LD, robots/sitemap/llms.txt, 페이지 속도, 품절 노출 |
| B. 플랫폼 API | 카페24 Admin API (OAuth 2.0, developers.cafe24.com) / 아임웹 API | API 키·토큰 (비번 불필요) | 주문·반품 상태 흐름, 상품/재고, 회원·쿠폰, 게시판, 일부 설정값 조회 |
| C. 외부 API | GA4 Data API, Meta Marketing API, 네이버 검색광고 API, Search Console API | 각 서비스 토큰 | UTM 위반 탐지, 소재별 성과 리포트, 픽셀 이벤트 품질, 색인 오류 |
| D. 관리자 화면 조작 (computer use) | Playwright + 관리자 계정 로그인 | **부운영자 계정** (아래 보안 요건) | API로 노출 안 되는 설정 화면의 검수·변경 (예: 일부 주문 설정, 스킨 관련 화면) |
| E. 실사용자 시나리오 테스트 | Playwright + 테스트 회원 계정 | 테스트 계정 | 가입→쿠폰지급→구매→반품신청 E2E. "진짜 되는지"의 최종 증명 |

**핵심: 이번에 발견된 5가지 문제 전부가 A+B+C로 잡힌다. D(비번 기반 화면 조작)가 필요한 범위는 생각보다 좁다.**

## 3. 단계별 구축 로드맵

### Phase 1 — 읽기 전용 프론트 감사 (구축 1~2주, 리스크 0)
- 수단 A만 사용. 자격증명 불필요 → 오늘이라도 시작 가능
- 매일 새벽 실행 → 체크리스트(audit-checklist.yaml) 평가 → 결과를 슬랙/카톡/이메일 리포트
- 리포트 형식: ✅ 통과 n건 / ⚠️ 경고 n건 / ❌ 실패 n건 + 실패 항목별 "관리자 어디서 고치는지" 링크

### Phase 2 — API 감사 + 성과 리포트 (구축 2~3주)
- 카페24 개발자센터에서 앱 등록 → OAuth 토큰 발급 (mall 관리자의 1회 승인 필요)
- GA4/광고 매체 API 연결 → UTM 위반 자동 탐지, 주간 소재 성과 리포트 자동 생성
- GA4 매출 vs 카페24 주문 API 매출 자동 대사

### Phase 3 — E2E 시나리오 테스트 (구축 2주)
- 테스트 회원 계정 + 100원 테스트 상품으로 주 1회: 가입 → 쿠폰 확인 → 구매 → 반품 신청까지 자동 수행
- "반품이 안 되는지 몰랐다"를 구조적으로 재발 불가능하게 만드는 단계

### Phase 4 — 관리자 화면 자동화 (검수 → 승인 후 세팅)
- 부운영자 계정으로 관리자 화면을 읽기 검수 (설정값 스크린샷+파싱 → 기대값과 비교)
- 세팅(쓰기)은 2단계 승인: 프로그램이 "변경안 + 변경 전/후 스크린샷"을 제출 → 담당자가 승인 버튼 → 실행 → 실행 후 고객 화면 재검증
- 완전 무인 쓰기는 저위험 항목(예: 메타태그 문구)부터 화이트리스트로 점진 허용

## 4. 자격증명·보안 요건 (컴퓨터 유즈 권한을 주기 전에 반드시)

1. **대표운영자 계정을 절대 주지 말 것.** 카페24 부운영자 계정을 새로 만들어 필요한 메뉴 권한만 부여 (권한 축소가 사고 반경을 결정한다)
2. 비밀번호는 코드·스프레드시트에 저장 금지 → **macOS Keychain 또는 1Password CLI**에서 실행 시점에만 로드
3. 관리자 보안 설정의 **접속 허용 IP**에 자동화 실행 서버 IP만 추가 (탈취되어도 타 IP에서 무용지물)
4. 2단계 인증(OTP)이 걸려 있으면 자동 로그인이 매번 막힌다 → 부운영자 계정에 대한 처리 방침을 먼저 결정 (IP 제한 + 강한 비번으로 대체할지)
5. 모든 자동화 세션의 행동 로그(어느 화면에서 무엇을 클릭/변경했는지)와 스크린샷을 보관
6. 쓰기 작업은 실행 전 스냅샷(변경 전 설정값)을 저장해 **원클릭 롤백** 가능하게

## 5. 시스템 구성 (제안)

```
┌─ 스케줄러 (cron / GitHub Actions / launchd) ── 매일 06:00
│
├─ audit-runner
│   ├─ front-crawler (Playwright) ──── 체크 A군
│   ├─ cafe24-api-client ───────────── 체크 B군
│   ├─ analytics-clients ───────────── 체크 C군 (GA4·Meta·네이버)
│   └─ e2e-scenarios (주 1회) ──────── 체크 E군
│
├─ evaluator: audit-checklist.yaml의 기대값과 대조 → pass/warn/fail 판정
├─ reporter: 슬랙/카카오워크/이메일로 일일 리포트 + 실패 시 즉시 알림
└─ fixer (Phase 4): 변경안 생성 → 승인 대기 → 실행 → 재검증 → 롤백 스냅샷
```

- 언어/스택 제안: TypeScript + Playwright (E2E 생태계 성숙), 실행은 사내 맥미니 or GitHub Actions
- 검수 항목은 코드가 아니라 **audit-checklist.yaml**(동봉)에 선언 → 담당자가 항목 추가/수정 가능

## 6. 시작하기 위해 결정·준비가 필요한 것

| # | 항목 | 담당 |
|---|---|---|
| 1 | 자사몰 플랫폼 확정 (카페24인지 아임웹인지, 둘 다인지) + 쇼핑몰 URL | 운영 |
| 2 | 카페24 개발자센터 앱 등록 권한 (Admin API용) — 비번 공유보다 이게 먼저 | 운영 |
| 3 | 부운영자 계정 생성 + 최소 권한 + IP 제한 (섹션 4) | 운영 |
| 4 | 테스트 상품(100원)·테스트 회원 계정 | 운영 |
| 5 | 리포트 받을 채널 (슬랙? 카톡? 이메일?) | 공동 |
| 6 | 알림 기준 합의 (무엇이 "즉시 알림"이고 무엇이 "일일 리포트"인지) | 공동 |

위 1~5가 준비되면 Phase 1(자격증명 불필요)은 즉시 개발 착수 가능하다.