소셜 스키마 v5 — 확정 명세

컬렉션 6개의 최종 필드 구성과 그 구성을 정한 판정 규칙. (2026-08-07 object_raw 제거로 7 → 6)

v4 를 전수조사해 메모 22건과 추가 발견 7건을 판정한 결과다. "왜 그렇게 됐나" 는 docs/features/social-recording-refactor/schema-refactor-plan.md 가, "무엇이 됐나" 는 이 문서가 담는다.

§1v4 에서 무엇이 바뀌었나

이 절이 답하는 것 — 한 문장으로 요약하면 무엇이 달라졌는가.

큰 변화 다섯

§2ERD

이 절이 답하는 것 — 컬렉션들이 서로를 어떻게 가리키는가. (그림의 object_raw 상자는 2026-08-07 에 제거됐음을 표시한 채로 남겨둔다 — 지웠던 자리를 알아야 옛 코드·문서를 읽을 때 헷갈리지 않는다.)

§3판정 규칙

이 절이 답하는 것 — 새 필드를 만들 때 어디에 두고, 무엇을 두지 않는가.

규칙 ① 시각 필드는 created_at/updated_at 이 답할 수 없을 때만 둔다

두 단계로 판정한다.

1. 이 필드가 created_at 과 구조적으로 갈리는가. 갈리지 않으면 두지 않는다.
2. 갈린다면 그 차이가 우리 인프라의 성질인가 세상의 성질인가. 인프라의 성질(큐 지연·재시도 간격·처리 소요)이면 두지 않는다. 세상의 성질(체인 최초 전송 시각·소셜 게시 시각·소셜의 크롤 시각)이면 둔다.

규칙 ② 저장되는 URL 은 예외 없이 정규화된 값이다

url 로 끝나는 필드에 값이 있다는 것 자체가 "정규화에 성공했다" 를 뜻한다. 예외 필드도, raw_ 류 접두어도 두지 않는다.

정규화에 실패한 URL 은 버린다. 실패하는 실제 경우는 우리 코드의 버그가 아니라 쓰레기 입력이다 — tracker 의 소셜 필드는 토큰 발행자가 채우는 자유 텍스트라 "none"·"TBA" 같은 값이 온다. 예외를 던지지 않고 그 URL 만 건너뛴 뒤 경고 로그를 남긴다.

URL 필드는 넷뿐이다. tokens.social_urls[].url · token_links.entry_url · contents.outbound_urls[] · accounts.outbound_urls[].

규칙 ③ 값을 어디에 둘지 — 최상위 · data · 버림

세 번째가 경계를 지킨다. 타입화의 비용은 필드 개수가 아니라 중첩에서 온다 — 어떤 소셜이 객체 배열을 돌려주면 서브클래스를 또 만들어야 하고, 그러면 부가 정보 하나에 클래스 트리가 생긴다.

승격 규칙: data 안의 값이 쿼리·정렬의 축이 되는 순간 최상위 필드로 올린다. data 는 "아직 축이 아닌 것" 의 대기실이다.

규칙 ④ 정체성 축은 (platform, platform_key) 하나다

1월  토큰 A 가 t.me/foo 를 검. 메시지 0 → subtype = shell
     → venues 행 생성 (tg, shell, foo)

3월  토큰 B 가 t.me/foo 를 검. 커뮤니티 활성화 → subtype = channel
     → findByPlatformKey(tg, channel, foo) 가 못 찾음
     → venues 행 하나 더 생성 (tg, channel, foo)

§4컬렉션 명세

이 절이 답하는 것 — 각 컬렉션의 최종 필드 구성.

모든 컬렉션이 BaseModel 을 상속해 _id·created_at·updated_at 을 갖는다. 아래 표에는 적지 않는다. ● 필수 · ○ 선택.

tokens

token_links

contents

같은 트윗을 가리키는 두 URL:
  https://x.com/elonmusk/status/123456/photo/1?s=20   ← 공유 버튼 링크
  https://x.com/elonmusk/status/123456                ← 주소창 복사

정규화 후에도 다른 문자열이다. 경로 접미사와 모르는 파라미터가 남는다.
그런데 분류는 둘 다 sourceKey = "123456" 을 준다 — segments.indexOf('status')
로 위치를 찾아 그 다음 값만 읽기 때문이다.

accounts

venues

metric_series

object_raw 컬렉션 제거 (2026-08-07)

지표 클래스 셋

export class ContentMetrics {          // 23필드, 전부 optional
  // X — viewCount·likeCount 는 YouTube 공용
  viewCount?  likeCount?  replyCount?  retweetCount?  quoteCount?  bookmarkCount?
  // TikTok — commentCount 는 YouTube 공용
  playCount?  diggCount?  commentCount?  shareCount?  collectCount?  repostCount?
  // Instagram — commentsCount 는 Reddit 공용
  likesCount?  commentsCount?  videoViewCount?  videoPlayCount?
  // Reddit
  upVotes?  score?  upvoteRatio?  numCrossposts?
  // GitHub — 러그 검증 채널이라 도달·호응 축에 매핑하지 않는다
  stars?  forks?  openIssues?
}
export class AccountMetrics { followers?: number }
export class VenueMetrics   { members?:   number }

키 이름은 지어내지 않고 각 fetcher 반환 타입의 실제 필드명을 그대로 쓴다. 통일하는 순간 TikTok 의 자동재생과 YouTube 의 30초 시청이 같은 칸에 들어간다.

§5인덱스 — 21 → 19

이 절이 답하는 것 — 어떤 조회가 인덱스로 끝나는가.

§6제너레이터 계약

이 절이 답하는 것 — 소셜별 제너레이터가 지켜야 할 것.

여러 판정이 제너레이터에 조건을 걸었다. 흩어진 것을 하나로 모으면 이렇다.

generate(url, opts, observedAt): Promise<{
  status: FetchStatus;              // 유료·미지원 판정을 스스로 한다
  attempted: boolean;               // 외부를 실제로 불렀는가
  graph: SocialObjectGraph | null;
}>

반환 트리가 지켜야 할 것 넷

1. 모든 객체에 platform_key 가 있어야 한다. 계정·베뉴는 기존 계약이었고, 이제 콘텐츠까지 확대된다. 키를 만들 수 없으면 그 객체를 넣지 않는다.
2. 지표와 data 는 필드 단위로 명시 매핑한다. 스프레드로 넘기지 않는다.
3. 모든 URL 은 정규화된 값이다. outbound_urls 는 본문에서 추출한 값이라 제너레이터가 직접 정규화해야 한다 — 라우터를 거치지 않는 유일한 URL 경로다.
4. subtype 은 fetch 후 판정이며 정체성이 아니다. 같은 대상을 다시 만나면 subtype 이 달라질 수 있다.

라우터와 게이트의 변화

"모르겠다" 는 route() 가 null 을 반환하는 것으로 표현한다. SocialPlatform 에 UNKNOWN 을 추가하지 않는다 — platform 은 token_links 에 저장돼 집계 축으로 쓰이는데 거기 unknown 이 섞이면 정체불명 버킷이 생긴다. 판정 실패는 값이 아니라 값의 부재다.

담당 fetcher 를 못 찾은 정상 URL 은 web 으로 떨어진다. 웹은 "아직 분류되지 않은 URL 을 담는 잠정 버킷"(§1.11)이고, 담당 Generator 가 없어 unsupported 로 끝난다.

§7미결 · 후속 작업

이 절이 답하는 것 — 이번에 정하지 않은 것과, 그것을 언제 정하는가.

미결 3건

지식으로 남기는 요구사항 — 삭제한 구조가 되살아날 때 지킬 것

subtype 어휘 — 절반 이상이 지금 생성될 수 없다

R-002 로 실패가 행을 만들지 않고, 미지원 타입에는 제너레이터가 없다. 담당 제너레이터가 없으면 그 subtype 은 영영 생기지 않는다.

삭제하지 않고 주석으로 표시만 한다. search 는 T-012 가 열려 있다 — 실측에서 tiktok_search 1회 호출($0.038)이 주제 적합 10/10 · 서로 다른 작성자 10명 · 총 조회 194만을 돌려줘 "검색 URL 은 객체가 없다" 는 전제가 반증됐다.

VenueSubtype 은 전량 살아 있다 — community(X) · subreddit(Reddit) · channel·portal·shell·guard_group(Telegram).

§8문서 지도