소셜 스키마 v4

토큰 ↔ 소셜 연결의 확정 명세. v3 대비 링크 도착점 구조와 전 컬렉션 필드 판정이 바뀌었습니다. 미결은 웹 하나뿐이고 별도 작업으로 이관했습니다. 근거 문서는 §7 문서 지도에 전부 연결해 두었습니다.

§1ERD

이 절이 답하는 것 — 컬렉션 7개가 서로를 어떻게 가리키는가.

§2판정 규칙 — 필드를 어디에 둘지

이 절이 답하는 것 — 새 필드가 생겼을 때 어디에 놓을지 어떻게 정하는가.

질문 1 · 이 필드로 쿼리하는가?  (filter · sort · join · group · index)
          아니오 →  개별(data)          예 → 질문 2
질문 2 · 값의 의미가 모든 subtype 에서 같은가?
          아니오 →  개별(data)          예 → 질문 3
질문 3 · 이 값의 원본(SoT)이 다른 곳에 있는가?
          예     →  최적화용            아니오 → 공용

채움률은 기준이 아닙니다. account_created_at 은 Instagram 이 구조적으로 주지 않지만 "계정 나이는 rug 1순위 신호" 라 공용입니다. 반대로 채움률이 100% 여도 의미가 갈리면 개별입니다 — views 는 TikTok 이 자동재생, X 가 노출, YouTube 가 30초 시청이라 이름을 통일하면 오염됩니다.

이름 규칙

_id  로 끝나면  →  항상 ObjectId. 우리가 발급하고, 우리 DB 안의 다른 행을 가리킨다
_key 로 끝나면  →  항상 외부 문자열. 남이 발급하고, 우리가 만들지 않는다

_id · creator_id · venue_id · parent_content_id · object_id       ObjectId
platform_key   '2070140594496626759'   그 플랫폼 안에서 이 대상을 가리키는 값
url_key        'foo.com'               URL 에서 뽑은 식별자 (sites 용, 웹 작업)

예외 token_address — address 는 ObjectId 로 오인될 수 없어 이름을 그대로 둔다

두 종류를 섞으면 함수 시그니처가 (id: string) 일 때 둘 다 통과해서 조용히 틀립니다.

필수 여부 3단계

필수 ●   값이 없으면 저장 자체가 안 된다
기본값   필수지만 기본값이 있어 항상 존재한다 (배열 → [], 객체 → {})
선택 ○   없을 수 있다

"기본값" 을 따로 두는 이유는 인덱스 때문입니다. 필드가 항상 존재하면 partial index 를 만들 수 없습니다 — partialFilterExpression 은 $ne 도 $size 도 지원하지 않아 "빈 배열 제외" 를 표현할 방법이 없습니다.

§3전제

이 절이 답하는 것 — 이 스키마가 성립하기 위해 파이프라인이 지켜야 할 약속.

1. URL 에 대응하는 객체는 관측 시점에 무조건 존재한다. unknown 도 객체로 저장한다.
2. 객체는 그 시점에 확인 가능한 모든 것을 확인한 상태로 만들어진다. fetch 가 가능하면 fetch 해서 platform_key 까지 풀어 기록하고, 불가능하면 URL 로 알 수 있는 데까지만 채운다.
3. 링크는 _id 로 연결한다. 어디에서(object) + 어떤 것(object_id).
4. 각 객체는 자신을 유래시킨 URL 목록을 관리한다. source_urls[].
5. 나중에 매핑이 바뀌면 재할당한다. 링크를 다시 끼운다.
6. _id 참조는 우리가 관측한 대상에만 쓴다. 관측하지 않은 언급(mentions[])은 값 그대로 저장한다 — 그러지 않으면 트윗 3,879건의 멘션마다 빈 계정 행이 생긴다.

기존 행을 찾는 순서

1. source_urls.url 로 찾는다        이미 본 URL 이면 여기서 끝
2. 없으면 platform_key 로 찾는다    다른 URL 로 같은 대상을 본 경우
3. 그래도 없으면 새 행

Instagram 처럼 나중에 platform_key 가 shortcode → 숫자 pk 로 바뀌어도 1번이 먼저라 기존 행을 찾습니다.

§4컬렉션 명세

이 절이 답하는 것 — 각 컬렉션이 어떤 필드를 갖고, 각 필드가 왜 그 자리에 있는가.

4.1 contents — 플랫폼 콘텐츠 공간의 좌표

트윗·영상만이 아니라 검색·미분류·단축링크까지 담습니다. TikTok 에서 유행하는 것은 search 로도 video 로도 표현되는데, 나누면 "이 소셜에서 무엇이 주목받나" 를 보려고 두 컬렉션을 확인해야 합니다. 그리고 unknown 은 모르는 사이트가 아니라 "아는 플랫폼인데 그 안 어디인지 모르는 것" 입니다 — 라우터가 모르는 호스트를 전부 website 로 떨어뜨리기 때문이고, 실측 398건이 전부 x.com(282)·tiktok.com(97)입니다.

제거 — content_key(정체성이 _id 로 이동) · source_type(platform+subtype 으로 분해) · source_key(source_urls[] 로 대체) · ext(data 로 개명, 네임스페이스 제거) · form · fetch_status(source_urls[].status 와 중복) · data.productType

4.2 accounts — 누가

제거 — subtype · moderation.unavailable_reason · account_key · ext. account_type(gh User/Organization)과 source_ref(프로필 직접 조회가 아님을 남기는 값)는 data 로 내렸다 — 조직 계정 여부가 신호인지 검정 기록이 없고, 신뢰도 정보는 쿼리 축이 아니다. metrics.content_count 도 data 로 내렸다 — Reddit 이 안 주고 세는 대상이 플랫폼마다 다르다(x statusesCount 는 리트윗 포함).

4.3 venues — 어디서

제거 — channel_state(subtype 이 담당) · data.nameMatch(token_links 로 이동) · data.subredditSubscribers(metrics.members 와 중복) · venue_key · ext

4.4 token_links — 토큰 ↔ 객체 · append-only

제거 — content_key(유실 문제의 원인) · source_field(발행자가 칸을 구분해 쓰지 않는다 — website 칸에 Reddit 18·GitHub 15·TikTok 검색 6건. discovered 는 출처 불명, adhoc 은 실측 0건)

4.5 metric_series — 지표 시계열 · 대상당 1행

관측마다 새 행이 아니라 한 행의 배열에 쌓습니다. 속도 계산이 읽기 1회로 끝나고 배열이 이미 순서대로입니다. 한 포인트가 약 150 B 라 설계 상한인 200 포인트여도 30 KB 입니다.

감수한 것 — 플랫폼 코호트 백분위를 인덱스 range scan 으로 못 낸다($unwind 필요). 백분위는 원래 파생 레이어(metric_ranks)에서 주기적으로 계산할 값이다.

4.6 content_raw — 무손실 원본 · 1:1

제거 — platform(키 단건 조회만 하는 컬렉션이라 필터 필드가 필요 없다) · object_key · object_type. 컬렉션 이름이 내용과 어긋난다 — content_raw 인데 content·creator·venue 셋을 담는다. object_raw 로 개명할지는 §6.

4.7 tokens — 얇은 상태

제거 — trigger_reason · unclassified_links[](모든 URL 이 객체가 되므로 역할 소멸 — 이 필드의 존재 자체가 "비객체를 담을 곳이 없다" 는 증상이었다) · price·ath_price·alpha_score(계속 변하므로 사본은 쓰는 순간 낡았고 백테스트를 오염시킨다)

§5인덱스 초안

이 절이 답하는 것 — 확정된 쿼리 축에서 직접 따라 나오는 인덱스.

§6미결 · 선행 과제

이 절이 답하는 것 — 아직 정하지 않은 것과, 구현 전에 고쳐야 할 코드.

6.1 웹 — 별도 작업으로 이관

1. 웹 URL 도 contents 에 넣는다.   platform='web' · subtype='site'
2. tokens.web{} · fingerprints[] 는 현행 그대로 둔다
3. contents(web) 에 도메인 층 필드를 만들지 않는다 (site_id 도 아직 없음)

6.2 판정 세션 이후 확정한 6건

필드 판정 문서(§7)를 얼린 뒤 남아 있던 미결입니다. 이 문서가 최신이고, 판정 문서에는 "보류" 로 남아 있습니다.

6.3 선행 과제 — 구현 전에 고쳐야 하는 코드

instagram  /stories/{handle}/{storyId}   sourceKey = segments[2]      storyId 로 수정됨
reddit     /r/{sub}/s/{shareId}          sourceType = reddit_share    share 로 분리됨

6.4 이 설계로도 풀리지 않는 것

• 영원히 fetch 못 하는 대상의 정체 — Instagram 은 결제 전까지 응답 id 를 못 얻어 URL 이상을 알 수 없다
• 관측 이전의 사실 — 링크를 건 시점과 관측 시점 사이에 지워졌으면 복원 불가
• 재할당의 원자성 — Phase 1.6 에서 트랜잭션을 제외했으므로 중간에 죽으면 링크 일부만 재연결된 상태가 남는다. 다만 링크는 여전히 유효한 객체를 가리키므로 조회가 깨지지는 않고, 재분류 배치를 다시 돌리면 수렴한다
• 스키마 이전에 쌓인 데이터 — tokens.unclassified_links[] 로만 남은 것들은 원본 소셜 필드가 다른 레포에 있어 재수집 없이는 복원되지 않는다

§7문서 지도

이 절이 답하는 것 — 어느 판단이 어느 문서에 근거를 두고 있는가.

이 문서가 다루지 않는 것 — 모델·리포지토리 클래스 설계(기존 be-system-design.md §3 이 유효), 마이그레이션(실데이터가 없어 해당 없음), 파생 계층(metric_ranks·엔티티 해석·지문 클러스터).