문서와 버전

문서는 단일 API의 호스트 표현입니다. 조직 내 프로젝트에 속하고 덮어쓰기 대신 시간에 따라 버전을 쌓습니다.

계층

Organization -> Project -> Document -> Versions

문서는 조직 바로 아래 또는 프로젝트 내에 만들 수 있고 프로젝트와 조직별로 나열됩니다.

상태 라이프사이클

문서는 네 상태를 거칩니다.

상태	의미	공개 서비스
ACTIVE	온라인	문서와 MCP 제공(각 활성 표시에 따름)
PAUSED	일시정지	공개 서비스 불가
ARCHIVED	보관하지만 현행 아님	제공 안 함
DELETED	소프트 삭제	제공 안 함

허용 전환:

pause:    ACTIVE  -> PAUSED
resume:   PAUSED  -> ACTIVE
archive:  ACTIVE / PAUSED -> ARCHIVED
restore:  ARCHIVED -> ACTIVE
delete:   ACTIVE / PAUSED / ARCHIVED -> DELETED

일시정지는 문서를 내렸다 재개하는 가장 빠른 방법이고, 보관은 이력은 유지하지만 현행으로 다루지 않습니다. 삭제는 소프트 삭제로 핵심 데이터가 즉시 파기되지 않습니다.

버전은 불변

스펙이 바뀌면 새 버전을 만듭니다. 원본은 절대 교체되지 않습니다.

v1 -> v2 -> v3 -> v4

각 버전은 기록합니다.

• 파일의 객체 저장소 내 저장 키.
• SHA-256 체크섬.
• 콘텐츠 유형, 크기, 생성 시각.

이것이 이력, 롤백, 비교, 특정 버전에 대한 문서/MCP 재생성을 뒷받침합니다.

현재 링크와 버전 고정 링크

• 현재 문서를 가리키는 링크는 최신 버전 추종.
• 버전 고정 링크는 특정 버전을 참조해 독자 발 아래 바뀌지 않음.

릴리스 노트나 계약에서 불변 참조가 필요하면 고정 링크, 항상 최신이 필요하면 현재 링크를 씁니다.

소스

문서 내용은 어떤 소스에서 오고 업로드와 Git이 문서 모델에 하드코딩되지 않도록 추상화됩니다.

• Upload——파일 직접 추가.
• Git——URL, 브랜치, 파일 경로로 저장소 연결.

Git 소스는 동기화 활성 여부와 마지막 동기화 시각을 추적합니다.

• 저장소 URL과 파일 경로 필수로 연결(브랜치 선택).
• 요청 시 동기화해 최신 내용을 새 버전으로 가져옴.

소스 메타데이터는 문서와 함께 유지돼 항상 업로드인지 저장소인지 판단하고 마지막 동기화를 확인할 수 있습니다.

저장

실제 파일은 조직/문서/버전 배치로 객체 저장소에 있고 데이터베이스는 메타데이터(저장 키, 체크섬, 콘텐츠 유형, 크기)만 갖습니다. 파일은 저장소에서 기본 공개 읽기 불가이고 공개 접근은 문서의 게시 경로를 통합니다.

왜 중요한가

불변 버전과 소프트 삭제 라이프사이클의 조합으로 이력을 잃지 않고 빠르게 반복하며, 멈추려 한 문서를 실수로 공개하지 않습니다. 임시 중단은 일시정지, 장기 보관은 보관, 안정성 중요 시 링크 고정입니다.

관련: 노출 작업、접근 통제、사용자 지정 도메인.