Note Site Provenance

Note→Site 출처와 새 사본 생성 계약

기준일: 2026-09-20. 연결 이슈: #291. 상태: 코드 조사와 구현 범위 제안. 구현·브라우저 재현·고객 검증은 하지 않았다. 조사 기준: main 558714a818ae8f0dcffc8436d8e7e30a66c93442.

제품 판단

첫 범위는 저장된 Note의 출처를 확인하고 새 Site 사본을 만드는 흐름이다. 사용자가 이미 편집한 Site는 그대로 둔다. 목적은 자료 재사용 시 확인 비용과 잘못된 원본 사용을 줄이는 것이다. 시간 절감과 구매 의향은 아직 검증하지 않았다.

버튼은 ‘원본으로 새 Site 사본 만들기’로 표현한다. ‘동기화’, ‘최신 Site’, ‘자동 갱신’은 피한다. 원본이 같아도 사용자가 Site를 따로 편집했을 수 있다. 상태는 ‘마지막 확인 시 원본과 같음’처럼 확인 범위와 시점을 드러낸다.

확인한 코드와 영향

확인한 사실	구현 시 의미
noteToSite는 Note를 읽고 첫 Site 본문에 복사한다. 페이지 참조를 거절하고 Site 스키마를 검사한 뒤 저장한다.	지원하지 않는 내용을 조용히 버리지 않는 현재 경계를 유지한다.
Site 본문 저장 후 별도 catalog에 copiedFrom과 references를 쓴다.	두 번째 저장 실패 시 본문만 남을 수 있는 경로다. 이번에 장애를 실행해서 재현한 결과는 아니다.
require는 저장소에서 스냅샷을 읽는다. noteToSite는 원본 휴지통 상태나 생성 직전 변경을 다시 확인하지 않는다.	다른 탭의 변경·휴지통 이동을 고려해야 한다. 다른 탭의 미저장 입력은 포함한다고 약속할 수 없다.
저장소 revision은 문서별 증가값이며 구형 행은 0으로 읽힌다. Note 즐겨찾기와 휴지통 변경도 같은 저장소에 쓴다.	revision 변화만으로 ‘본문이 바뀜’을 판정하면 잘못된 알림이 생길 수 있다.
복원은 새 ID를 만들고 copiedFrom을 복원 전 문서 ID로 바꾼다. 참조 ID는 함께 복원한 문서로 바꾼다.	기존 한 필드로 변환 출처와 복원 출처를 모두 표현하기 어렵다. 새 ID의 revision을 이전 ID의 revision과 비교하면 안 된다.
제품 저장소 이름은 제품별 고정값이다. workspace ID는 catalog와 URL에 쓰인다.	주소에 workspace를 넣는 것만으로 데이터 격리·팀 권한이 생기지는 않는다.

근거: 복사·변환, Note 메타데이터 저장, 백업 복원, 저장소 revision과 스냅샷, 제품 저장소·주소.

최소 데이터 계약 제안

구체적인 필드 이름과 저장 위치는 구현 설계에서 정한다. 아래 의미는 구분한다.

• 변환 출처: 원본 주소, 읽은 저장 revision, 변환 입력의 지문, 변환기 버전, 생성 시각.
• 변환 입력: 저장된 Note의 제목과 변환 대상 내용. 즐겨찾기·열어 본 시각은 제외한다. 입력 정규화 규칙도 버전을 가진다. 지문으로 비교할 범위가 다르면 ‘확인할 수 없음’으로 처리한다.
• 생성 작업: 작업 ID와 예정 Site ID. 실패 후 같은 작업을 재개할 때 새 UUID를 계속 만들지 않는다.
• 복원 출처: 복원 전 주소와 백업 맥락. 변환 출처와 별도로 남긴다.
• 확인 상태: 마지막 확인 시각, 원본 사용 가능 여부, 비교 결과. 저장 revision은 감사와 경쟁 변경 확인에 쓰고, 내용 비교는 정해진 변환 입력으로 한다.

원본 버전이 없는 기존 사본에는 현재 revision을 소급 기록하지 않는다. 같은 번호라는 이유로 최신 상태를 추정하지 않는다. 원본을 다시 읽어서 새 변환을 완료한 사본부터 증거를 남긴다.

상태와 사용자 흐름

상황	표시와 동작
같은 주소·비교 규칙으로 원본 입력이 같음	마지막 확인 시 원본과 같음. Site 편집 내용이 같다는 뜻은 아니다.
원본 제목 또는 변환 대상 내용이 다름	원본 변경됨. 새 사본 미리보기 제공.
구형 사본·비교 규칙 불일치·복원 후 비교 기준 미확립	원본 버전 확인 불가. 최신으로 표시하지 않음.
원본 없음·휴지통·읽기 실패	원본 사용 불가. 기존 Site는 유지. 원인에 맞는 복구 안내.

1. ‘저장된 Note 기준’임을 안내하고 원본과 상태를 확인한다.
2. 쓰기 없이 변환한다. 결과 미리보기와 지원 불가 사유를 보여 준다.
3. 확인한 입력과 변환기 버전에 연결된 계획을 만든다.
4. 생성 직전에 원본을 다시 읽는다. 내용이 바뀌면 계획을 폐기하고 다시 미리 본다. 휴지통이나 읽기 실패도 생성을 중단한다. revision만 바뀌고 변환 입력이 같다면 그 사실을 확인한 뒤 처리한다.
5. 새 Site에 계획의 입력 증거를 남긴다. 기존 Site의 본문·ID·게시 상태는 바꾸지 않는다.
6. 생성 결과와 확인 시점을 알린다. 본문만 저장된 경우에는 부분 완료와 복구 경로를 알린다.

Note와 Site는 서로 다른 DB다. 생성 직전 재확인만으로 두 DB 사이의 원자적 ‘항상 최신’을 보장할 수 없다. 이 범위의 보장은 확인한 스냅샷의 사본 생성이다. 재확인 이후 원본이 바뀌어도 출처 증거는 유지하며, 다음 확인에서 변경을 알린다. 이 제한은 #291의 ‘오래된 계획 적용 금지’ 인수 기준을 해석할 때 명시해야 한다.

저장 실패와 복원

미리보기·스키마 검사를 통과하기 전에는 본문, catalog, 복구 작업을 쓰지 않는다. 검사 후에는 예정 Site ID와 출처를 복구 가능한 형태로 남겨야 한다. 본문 실패, 출처 실패, 새로 고침 후 재개를 각각 구분한다.

저장 위치는 설계 검토가 필요하다. 같은 Site 행에 출처를 함께 저장하면 첫 저장을 묶을 수 있다. 다만 이후 모든 저장 경로가 출처를 보존하는지 먼저 확인해야 한다. 별도 작업 기록을 쓰면 재개·정리를 설계해야 한다. 현재 keep은 전달한 행으로 저장하며 임의 메타데이터를 자동 병합하지 않는다. 출처 필드만 추가하고 보존을 가정하면 안 된다.

복구의 완료 기준은 다음과 같다. 실패 메시지에서 이미 생성한 사본을 찾을 수 있다. 같은 작업의 재시도가 불필요한 사본을 늘리지 않는다. 다른 탭에서 편집한 사본을 복구 과정에서 지우거나 덮어쓰지 않는다. 부분 저장 상태에서 백업해도 남은 자료와 출처 증거를 잃지 않는다.

함께 복원한 Note로 이동하는 링크는 새 ID로 연결할 수 있다. 다만 제목·페이지 ID·저장 revision은 복원 과정에서 달라진다. 첫 구현은 과거 변환 출처를 보존하고 복원 후 비교 상태를 ‘확인 불가’로 둔다. 새 변환을 완료하면 새로운 비교 기준을 만든다. 주소를 바꾼 뒤 옛 revision을 그대로 비교하는 방식은 제외한다.

#291 안의 권장 구현 순서

1. 출처·복구 기반: 출처 읽기/쓰기, 구형 사본의 미상 처리, 작업 재개, 백업·복원 의미를 구현한다. 이 단계만으로 #291을 닫지 않는다.
2. 상태·미리보기: 원본 확인, 변환 입력 비교, 지원 불가 안내, 생성 직전 재확인을 구현한다.
3. 새 사본 생성 흐름: 결과 안내와 기존 Site 보존을 데스크톱에서 검증한다.

변경의 중심은 office-workspace다. shared 저장소나 Site 저장 경로는 출처 보존과 복구 계약에 필요한 부분만 검토한다. 원본 내용을 기존 편집기에 삽입하는 기능은 별도다. #262/#273과 열린 PR #313의 변환 경계를 확인하되, 아직 병합되지 않은 API를 main에 있다고 가정하지 않는다. PR #316의 Site 내부 Note 저장 수정도 이 사본 생성과 구분한다.

검증 계획과 증거의 한계

검사	통과 조건
지원하는 제목·본문 복사	원본 바이트 보존, 새 Site 열림, 읽은 입력 증거 일치
페이지 참조·지원 불가 블록	사유 표시, 모든 관련 저장소 쓰기 0회
즐겨찾기만 변경	revision은 바뀌어도 본문 변경 알림 없음
미리보기 뒤 원본 내용 수정·휴지통 이동	다시 확인 요구, 새 사본 생성 없음
Site를 별도 편집한 후 새 사본 생성	기존 Site 바이트·ID·게시 상태 보존
본문 저장 실패·출처 저장 실패·재시작	부분 완료 구분, 같은 작업 재개, 사본 중복 방지
구형 사본·일부 문서만 있는 백업·전체 복원	잘못된 최신 판정 없음, 출처/이동 링크 의미 분리

기존 workspace.spec.ts는 Note 본문을 Site에서 여는 경우와 원본 보존을 검사한다. 같은 파일에 참조·휴지통·백업 복원 검사도 있다. 이 회차는 검사 코드를 읽었으며 실행하지 않았다. 읽은 두 파일 workspace.spec.ts, workspace-feedback.spec.ts에서는 위 새 출처 계약과 두 단계 저장 실패를 인수하는 검사를 확인하지 못했다. 저장소 전체에 관련 검사가 없다는 뜻은 아니다.

이 문서는 구현을 시작할 때 사용할 범위 제안이다. 고객 우선순위는 #289의 증거로 보완한다. 자동 동기화, 병합, 공개 재게시, 팀 권한, 모바일 화면 검사는 포함하지 않는다.