title: content-orchestration 외부 연동 설계서 (L1) date: 2026-02-25T16:07:00+09:00 type: design layer: L1 status: in-review tags: [content-orchestration, external-integration, L1, brevo, getlate, telegram] author: ext-design-pl project: content-orchestration reviewed_by: "jarvis" reviewed_at: "2026-02-25T18:50:00+09:00" approved_by: "" approved_at: ""

content-orchestration 외부 연동 설계서 (L1)

Task ID: dc1d0d04-5bca-4d69-abc7-e0b4f3e40c79 작성일: 2026-02-25 작성자: ext-design-pl 근거 문서:

• L0: content-orchestration-biz-v4.md (비즈 기획서)
• L1: content-orchestration-design-db.md (DB 설계서, 검수 완료)
• L1: content-orchestration-design-pipeline.md (파이프라인 설계서, 승인)

1. 현황 분석

1-1. 현재 외부 연동 코드 현황

content-pipeline 프로젝트(projects/content-pipeline/src/)에 이미 구현된 외부 연동:

1-2. 환경 변수 현황

현재 .env에 설정된 외부 연동 관련 키:

1-3. 현재 한계점

2. 연동 대상별 상세 설계

2-1. Brevo API (뉴스레터 발송) — Phase 1

개요

API 엔드포인트 명세

1) 캠페인 생성 + 예약 발송

요청 파라미터:

응답:

{
  "id": 12345
}

2) 캠페인 즉시 발송

3) 캠페인 상태 조회 (신규 구현)

응답 주요 필드:

4) 구독자 추가

인증 방식

Rate Limit

Fallback 처리

DB 연계

발송 플로우

content_queue.status = 'approved'
    │
    ↓
content_distributions INSERT (channel_id='ch-brevo', platform_status='pending')
    │
    ↓
newsletters 테이블에서 HTML 콘텐츠 조회
    │
    ↓
Brevo createEmailCampaign(scheduledAt 포함)
    │
    ├─ 성공: content_distributions UPDATE
    │        platform_status='registered'
    │        platform_id={campaign_id}
    │        scheduled_at={예약시각}
    │
    └─ 실패: content_distributions UPDATE platform_status='failed'
             error_logs INSERT
    │
    ↓ (예약 시각 도래 후 Brevo 자체 발송)
    │
Brevo 캠페인 상태 폴링 (getCampaign)
    │
    ├─ status='sent': content_distributions UPDATE
    │                  platform_status='published'
    │                  published_at={실제발송시각}
    │
    └─ status='failed': error_logs INSERT + 에스컬레이션

2-2. AppPro.kr 블로그 DB (Turso 직접 INSERT) — Phase 1

개요

연동 방식 (API가 아닌 DB 직접 접근)

블로그는 외부 API가 아니라 apppro-kr Turso DB에 직접 INSERT한다. 기존 Vercel Cron(/api/cron/publish, 6시간 주기)이 scheduled_at 시간이 도래한 포스트를 published=1로 전환하여 자동 발행한다.

INSERT SQL:

INSERT INTO blog_posts (
  id, title, slug, content, excerpt, category, tags,
  author, published, publishedAt, metaDescription, createdAt, updatedAt
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, NULL, ?, ?, ?)

• published=0: 예약 상태 (Cron이 시간 되면 1로 전환)
• publishedAt=NULL: Cron이 발행 시 현재 시각으로 설정

인증 방식

Rate Limit

Fallback 처리

DB 연계

발행 플로우

content_queue.status = 'approved'
    │
    ↓
content_distributions INSERT (channel_id='ch-apppro-blog', platform_status='pending')
    │
    ↓
content_queue에서 title, content_body, 메타데이터 조회
    │
    ↓
apppro-kr Turso DB blog_posts INSERT (published=0)
    │
    ├─ 성공: content_distributions UPDATE
    │        platform_status='registered'
    │        platform_id={blog_post_id}
    │        scheduled_at={발행예약시각}
    │
    └─ 실패 (slug 중복): slug 변경 후 재시도
    └─ 실패 (DB 에러): error_logs INSERT
    │
    ↓ (Vercel Cron /api/cron/publish, 6시간 주기)
    │
blog_posts.published = 1, publishedAt = now
    │
    ↓ (발행 확인 폴링 — Phase 1)
    │
content_distributions UPDATE
    platform_status='published'
    platform_url='https://apppro.kr/blog/posts/{slug}'
    published_at={실제발행시각}

발행 확인 메커니즘 (신규)

Vercel Cron이 발행한 뒤 content_distributions를 갱신하기 위한 확인 로직:

content_distributions에서 platform_status='registered' AND channel_id='ch-apppro-blog' 조회
    │
    ↓
apppro-kr DB에서 해당 blog_post_id로 published 컬럼 확인
    │
    ├─ published=1: platform_status='published', published_at 갱신
    └─ published=0: 아직 대기 중 (다음 폴링에서 재확인)

• 확인 주기: Vercel Cron /api/cron/pipeline 실행 시 함께 체크 (1일 1회)
• 또는 별도 /api/cron/check-publish 엔드포인트 (Phase 2)

2-3. getlate.dev API (SNS 멀티플랫폼) — Phase 1~2

개요

API 엔드포인트 명세

1) 계정 조회

응답:

{
  "data": [
    {
      "accountId": "abc123",
      "platform": "twitter",
      "name": "AI AppPro",
      "username": "@apppro_ai"
    }
  ]
}

2) 포스트 생성 (즉시/예약)

요청 파라미터:

응답:

{
  "data": {
    "id": "post_xyz789",
    "content": "...",
    "status": "scheduled",
    "scheduledFor": "2026-02-26T12:00:00+09:00",
    "platforms": [
      {"platform": "twitter", "accountId": "abc123", "status": "scheduled"},
      {"platform": "linkedin", "accountId": "def456", "status": "scheduled"}
    ],
    "createdAt": "2026-02-25T16:00:00+09:00"
  }
}

3) 포스트 상태 조회 (Phase 2)

인증 방식

Rate Limit

플랫폼별 콘텐츠 변환 규칙

기존 publish-sns.ts의 convertToSnsContent() 함수에 정의된 규칙:

Fallback 처리

DB 연계

발행 플로우

content_queue.status = 'approved'
    │
    ↓
channels 테이블에서 type='sns' AND is_active=1 조회
    │
    ↓
getlate GET /accounts → 연결된 계정 확인
    │
    ↓
플랫폼별 콘텐츠 변환 (convertToSnsContent)
    │
    ↓
채널별 content_distributions INSERT (platform_status='pending')
    │
    ↓
getlate POST /posts (scheduledFor 포함, platforms 배열)
    │
    ├─ 성공: 플랫폼별 content_distributions UPDATE
    │        platform_status='registered'
    │        platform_id={getlate_post_id}
    │        scheduled_at={예약시각}
    │
    └─ 부분 실패: 성공 플랫폼은 registered, 실패 플랫폼은 failed
                  error_logs INSERT (실패 플랫폼별)
    │
    ↓ (예약 시각 도래 후 getlate 자체 발행)
    │
발행 확인 (Phase 2: GET /posts/{id} 폴링)
    │
    ↓
content_distributions UPDATE
    platform_status='published'
    platform_url={각 플랫폼 포스트 URL}
    published_at={실제발행시각}

2-4. Telegram Bot API (관리자 알림) — Phase 2

개요

연동 범위 (Phase 2)

Telegram 연동은 기존 보고 스크립트를 활용하되, 파이프라인에서 특정 이벤트 발생 시 자동 알림을 추가한다.

알림 유형:

구현 방식

기존 스크립트를 shell 명령으로 호출하는 방식을 유지한다. Telegram API를 직접 호출하지 않는다 (CLAUDE.md 규칙: "Telegram API 직접 호출 / secrets 접근 절대 금지").

파이프라인 이벤트 발생
    │
    ├─ CEO 검수 요청: exec(`ceo-reply.sh "🤖 [자비스] 콘텐츠 검수 요청\n제목: {title}\n미리보기: {url}" "vice-claude"`)
    │
    ├─ 에러 에스컬레이션: exec(`vice-reply.sh "🤖 [자비스] 파이프라인 에러\n컴포넌트: {component}\n에러: {message}" "error"`)
    │
    └─ 발행 완료: exec(`vice-reply.sh "🤖 [자비스] 콘텐츠 발행 완료\n제목: {title}\n채널: {channels}" "publish"`)

인증 방식

Rate Limit

Fallback 처리

DB 연계

Telegram은 channels 테이블에 등록하지 않는다 (배포 채널이 아닌 관리 알림용). pipeline_logs의 metadata에 알림 전송 결과를 기록한다.

2-5. 외부 플랫폼 (티스토리, 미디엄, EO 등) — Phase 3

개요

Phase 3에서 추가 예정인 외부 콘텐츠 플랫폼 연동. 현재는 설계 개요만 기록하며, 실제 구현 시점에 상세 설계를 작성한다.

플랫폼별 연동 방법 요약

Phase 3 연동 원칙

1. API 우선: API가 있는 플랫폼(티스토리, 미디엄)부터 연동
2. Playwright는 최후수단: API 없는 플랫폼은 캡차/보안 이슈로 불안정. 최후순위
3. channels 테이블 확장: 새 플랫폼 추가 시 channels INSERT만으로 활성화
4. 콘텐츠 변환: 플랫폼별 포맷 변환 로직 추가 (마크다운 → HTML 등)

3. 공통 설계 사항

3-1. channels 테이블 기반 동적 채널 관리

모든 외부 연동은 channels 테이블을 통해 관리한다. 채널 추가/비활성화를 코드 수정 없이 DB 조작만으로 가능하게 한다.

Phase 1 시드 데이터:

SNS 채널(ch-twitter, ch-linkedin)은 초기에 is_active=0으로 설정. getlate.dev에서 계정 연결 확인 후 is_active=1로 전환.

3-2. content_distributions 연계 패턴 (공통)

모든 외부 연동은 동일한 패턴으로 content_distributions에 기록한다:

1. 배포 시작: INSERT (content_id, channel_id, platform_status='pending')
2. 외부 등록 성공: UPDATE platform_status='registered', platform_id, scheduled_at
3. 발행 확인: UPDATE platform_status='published', platform_url, published_at
4. 실패: UPDATE platform_status='failed', error_message, retry_count++

상태 전이 규칙:

pending ──→ registered ──→ published
   │              │
   │              └──→ failed (발행 실패)
   │
   └──→ failed (등록 실패)

failed ──→ pending (재시도 시 새 레코드 INSERT)

3-3. error_logs 연계 패턴 (공통)

모든 외부 연동 에러는 동일한 패턴으로 error_logs에 기록한다:

에스컬레이션 기준:

3-4. 환경 변수 → channels.credentials_ref 매핑

channels.credentials_ref 값    →   참조하는 환경 변수
─────────────────────────────────────────────────
"BREVO_API_KEY"               →   process.env.BREVO_API_KEY
"GETLATE_API_KEY"             →   process.env.GETLATE_API_KEY
"TURSO_DB_TOKEN"              →   process.env.TURSO_DB_TOKEN
"TISTORY_ACCESS_TOKEN"        →   process.env.TISTORY_ACCESS_TOKEN (Phase 3)
"MEDIUM_INTEGRATION_TOKEN"    →   process.env.MEDIUM_INTEGRATION_TOKEN (Phase 3)

런타임에서 채널의 인증 정보를 가져오는 로직:

channels 테이블에서 credentials_ref 조회
    → process.env[credentials_ref] 값 참조
    → null이면 해당 채널 skip (mock 모드)

3-5. mock 모드 통일

모든 외부 연동은 API 키 미설정 시 mock 모드로 동작한다:

4. Phase별 구현 시점

Phase 1 (MVP, 1주) — 필수 연동

Phase 1 제한:

• Brevo 캠페인 상태 폴링은 수동 확인 (대시보드에서 campaign_id 표시)
• getlate 발행 확인 폴링 없음 (registered → published 수동 전환)
• Telegram 알림 없음

Phase 2 (2주) — 알림 + 상태 추적

Phase 3 (3주+) — 외부 플랫폼 확장

5. 연동 코드 구조 (content-orchestration 레포)

content-orchestration/
└── src/
    └── lib/
        ├── integrations/
        │   ├── brevo.ts           ← Brevo 연동 래퍼 (content_distributions 연계)
        │   ├── blog-publisher.ts  ← 블로그 DB INSERT 래퍼
        │   ├── sns-publisher.ts   ← getlate SNS 래퍼
        │   ├── telegram.ts        ← Telegram 알림 (스크립트 호출, Phase 2)
        │   └── types.ts           ← 공통 인터페이스 (PublishResult, ChannelConfig 등)
        ├── pipeline/
        │   └── publish.ts         ← 통합 배포 오케스트레이터 (channels → integrations 호출)
        └── db/
            └── content-os.ts      ← Turso 클라이언트 (기존)

통합 배포 오케스트레이터 흐름:

publishContent(contentId: string)
    │
    ├─ channels 테이블에서 is_active=1 채널 목록 조회
    │
    ├─ 채널별 content_distributions INSERT (pending)
    │
    ├─ 채널 type별 분기:
    │   ├─ type='blog' → blog-publisher.ts
    │   ├─ type='newsletter' → brevo.ts
    │   └─ type='sns' → sns-publisher.ts
    │
    ├─ 결과별 content_distributions UPDATE
    │
    ├─ 전체 결과 pipeline_logs 기록
    │
    └─ 에러 시 error_logs 기록 + 필요 시 에스컬레이션

6. 전체 연동 요약 매트릭스

리뷰 로그

[ext-design-pl 초안 작성] 2026-02-25 16:07

• 현재 외부 연동 코드 4개 파일 분석 완료 (publish.ts, publish-blog.ts, publish-sns.ts, lib/brevo.ts, lib/getlate.ts)
• 환경 변수 현황 파악 (10개 외부 연동 관련 키)
• 한계점 7건 정리
• Phase 1 연동 3건 상세 설계: Brevo API (캠페인 생성+예약+상태조회), 블로그 DB (Turso INSERT+발행확인), getlate.dev (멀티플랫폼 예약+플랫폼별 변환)
• Phase 2 연동 1건 설계: Telegram Bot (스크립트 간접 호출, API 직접 호출 금지)
• Phase 3 연동 개요: 티스토리(Open API), 미디엄(API), 네이버(Playwright, 최후순위)
• 공통 설계: channels 기반 동적 관리, content_distributions 연계 패턴, error_logs 패턴, mock 모드 통일, credentials_ref 매핑
• 연동 코드 구조: integrations/ 디렉토리 기반 래퍼 패턴
• 자비스 1차 검수 요청

[자비스 1차 검수] 2026-02-25 18:50

검수 결과: 수정 없이 승인 ✅

검수 항목:

1. ✅ 현황 분석 완료 — 기존 4개 연동 파일 전수 분석, 환경 변수 10개 현황, 한계점 7건 정리
2. ✅ Phase 분리 명확 — Phase 1(Brevo/블로그/getlate), Phase 2(Telegram/상태폴링), Phase 3(티스토리/미디엄/네이버)
3. ✅ Telegram 보안 정책 준수 — API 직접 호출 금지, vice-reply.sh/ceo-reply.sh 간접 호출로 설계
4. ✅ mock 모드 통일 — API 키 미설정 시 에러 없이 MOCK_MODE 기록, 파이프라인 중단 없음
5. ✅ channels 기반 동적 관리 — credentials_ref 패턴으로 코드 수정 없이 채널 추가/비활성화
6. ✅ content_distributions 패턴 통일 — pending→registered→published 상태 전이 일관성
7. ✅ error_logs 에스컬레이션 기준 명확 — auth_fail 즉시, 3회 연속 실패 시 에스컬레이션
8. ✅ Phase 1 시드 데이터 정의 — ch-apppro-blog, ch-brevo(active), ch-twitter/linkedin(inactive 초기값)
9. ✅ Fallback 처리 상세 — Brevo 발송한도 초과 시 다음날 재예약, slug 중복 자동 해결
10. ✅ env vars 현황 — CONTENT_OS_DB_URL/TOKEN 포함 모두 .env에 설정됨 확인

추가 확인 사항: env 파일에서 CONTENT_OS_DB_URL/TOKEN 설정 완료 확인 → CEO 블로킹 없음