kotalk/문서/112-technical-operations-release-trust-atlas.md

112. Technical Operations Release Trust Atlas

이 문서는 현재 KoTalk 문서 세트를 기준으로, 다음 확장 라운드에서 필요한 기술/운영/릴리즈/신뢰 설계 문서를 아틀라스 형태로 정리한다.

목표는 단순히 문서 수를 늘리는 것이 아니라, 아래 네 가지를 문서 단위로 분리해 구현과 운영의 기준점으로 쓰는 것이다.

• 기능 설계와 운영 설계를 분리한다.
• 제품 UX 문서와 API/인프라 문서를 연결한다.
• 릴리즈와 다운로드, 관찰성, 복구를 실서비스 품질 기준으로 끌어올린다.
• Android 병렬 채널, 공개 다운로드, 원격 Releases, 운영 복구를 하나의 체계로 묶는다.

아틀라스 구조

아래 8개 범주로 문서를 확장한다.

1. 검색과 재발견
2. 보관함과 장기 보존
3. 세션/인증/디바이스 연속성
4. 오프라인/동기화/전송 복구
5. 릴리즈/다운로드/멀티채널 배포
6. 운영 복구/로그/관찰성
7. API 계약/버전/이벤트 정합성
8. 권한/보안/신뢰 통제

각 범주 안에서 제품 UX 명세, 시스템 계약, 운영 플레이북, QA/릴리즈 게이트까지 최소 4층 구조를 갖는 것이 이상적이다.

현재 문서 세트의 상태 요약

이미 존재하는 강한 축:

• 검색 UX 철학과 결과 표현: 24, 58, 69
• 세션/복구 UX: 25, 27, 51, 79, 104, 109
• 오프라인/아웃박스 규칙: 78
• Android 병렬 전략/배포 표면: 15, 30, 54, 110
• 공개 릴리즈 표면/스크린샷: 45, 55, 루트 RELEASING.md
• 운영/지원/신뢰 언어: 39, 47, 57, 98

아직 부족한 축:

• 검색을 실제 인덱스/랭킹/권한/증분 갱신 구조까지 내린 기술 설계
• 보관함의 저장소 모델, 수명주기, 사용자 제어, 다운로드/내보내기 설계
• 세션을 토큰-디바이스-브라우저-복구 정책까지 분리한 계약 문서
• 오프라인 큐 충돌 해결과 재동기화 정책의 기술 명세
• 공개 다운로드/원격 Releases/버전 메타데이터의 일관성 표준
• 운영 복구에서 무엇을 보고 어떻게 판단하는가를 정한 관찰성 문서
• REST/WSS/배치 작업/릴리즈 메타 파일을 함께 묶는 API 버전 정책
• 권한, 감사 로그, 관리자 액션, 비밀정보 보관, 다운로드 서명 검증 설계

범주별 신규 문서 제안

1. 검색과 재발견

113-search-architecture-indexing-and-ranking-spec.md

• 목적: 검색 UX 문서를 실제 시스템 구조로 연결한다.
• 다룰 내용:
  • 대화/메시지/파일/링크/사용자 인덱스 구조
  • 증분 인덱싱과 백필 정책
  • 최근성, 고정, 안읽음, 참여도 기반 랭킹
  • 권한 필터와 비공개 대화 가시성
  • 모바일/데스크톱 검색 응답 축약 규칙

114-search-query-contract-saved-searches-and-analytics.md

• 목적: 검색 입력, 필터, 저장 검색, 최근 검색, 분석 이벤트를 하나의 계약으로 묶는다.
• 다룰 내용:
  • 쿼리 파서 규칙
  • 저장 검색의 사용자 모델
  • 검색 실패/무결과/제안어 정책
  • 검색 성공률/첫 클릭 시간 지표

115-search-qa-relevance-benchmark-and-golden-datasets.md

• 목적: 검색 품질을 회귀 테스트 가능하게 만든다.
• 다룰 내용:
  • 골든 쿼리 세트
  • 업무형/친근형 검색 시나리오
  • 정답 문서 집합과 허용 오차
  • 릴리즈 전 relevance gate

2. 보관함과 장기 보존

116-vault-information-architecture-and-user-mental-model.md

• 목적: 보관함을 단순 북마크 묶음이 아니라 목적지로 정의한다.
• 다룰 내용:
  • 파일, 링크, 북마크, 나중에 답장, 저장 메시지의 섹션 구조
  • 사용자 관점 명명 규칙
  • 모바일/데스크톱 탐색 차이

117-vault-storage-lifecycle-export-and-retention-spec.md

• 목적: 보관함 데이터의 저장/삭제/내보내기 정책을 정한다.
• 다룰 내용:
  • 영구 저장과 임시 저장의 경계
  • 자동 만료와 사용자 수동 삭제
  • 내려받기, ZIP 묶음, 링크 만료 정책
  • MinIO 객체 보관 규칙과 메타데이터

118-vault-permissions-sharing-and-sensitive-content-policy.md

• 목적: 보관함 내 공유와 민감 콘텐츠 규칙을 명확히 한다.
• 다룰 내용:
  • 개인 저장 vs 대화 기반 저장
  • 링크 재공유 권한
  • 민감 파일 마스킹과 관리자 접근 제한

3. 세션/인증/디바이스 연속성

119-session-token-device-and-recovery-architecture.md

• 목적: 현재 세션 UX 문서를 인증 시스템 계약으로 내린다.
• 다룰 내용:
  • access/refresh/session ticket 구조
  • 디바이스 식별자와 브라우저 세션 차이
  • 회전, 만료, 폐기, 재발급 정책
  • 마지막 정상 화면 유지 조건

120-auth-journey-matrix-by-channel-web-windows-android.md

• 목적: Web/Windows/Android의 가입/로그인/복구 차이를 한 표로 정리한다.
• 다룰 내용:
  • 채널별 로그인 진입
  • 초대코드, 이메일 확인, 추후 passkey 확장 경로
  • 채널별 오류 문구, 재시도, 세션 정리 위치

121-device-management-remote-signout-and-risk-controls.md

• 목적: 내 공간의 기기 관리와 원격 로그아웃 정책을 정한다.
• 다룰 내용:
  • 등록 기기 목록
  • 마지막 활동 시각
  • 의심 로그인 감지
  • 사용자 알림과 차단/해제 흐름

4. 오프라인/동기화/전송 복구

122-offline-sync-engine-conflict-resolution-spec.md

• 목적: 오프라인 규칙을 실제 동기화 엔진 설계로 구체화한다.
• 다룰 내용:
  • local-first state
  • sync cursor와 증분 복구
  • 충돌 해결 우선순위
  • 전송/수정/읽음 이벤트 재정렬 규칙

123-outbox-retry-idempotency-and-message-dedup-policy.md

• 목적: 전송 실패 복구와 중복 메시지 방지를 계약으로 묶는다.
• 다룰 내용:
  • idempotency key
  • retry backoff
  • 중복 감지 기준
  • 사용자 표면의 실패/재전송 상태

124-offline-qa-lab-network-fault-injection-playbook.md

• 목적: 오프라인/불안정 네트워크를 재현하는 QA 문서를 만든다.
• 다룰 내용:
  • 2G/패킷 손실/짧은 단절/장시간 오프라인
  • 모바일 브라우저 백그라운드/복귀
  • Windows 재기동 후 복구

5. 릴리즈/다운로드/멀티채널 배포

125-release-metadata-schema-and-version-manifest-contract.md

• 목적: 웹, Windows, Android, 다운로드 호스트, 원격 Releases를 하나의 버전 메타 파일로 연결한다.
• 다룰 내용:
  • version.json 스키마
  • commit SHA, build date, artifact URL, checksum, screenshot set
  • latest/previous/stable channel 정의

126-download-host-routing-signing-and-integrity-spec.md

• 목적: download-vstalk.phy.kr를 릴리즈 인프라로 정의한다.
• 다룰 내용:
  • /windows/latest, /android/latest, /releases/<version>/...
  • HTTPS, MIME, 캐시 전략
  • checksum, signature, manifest 제공 방식
  • 손상 파일/잘못된 latest 포인터 복구 절차

127-gitea-releases-artifact-publishing-and-mirroring-runbook.md

• 목적: 원격 Releases와 다운로드 미러 게시를 같은 절차로 운영한다.
• 다룰 내용:
  • 태그 생성
  • 릴리즈 노트
  • 자산 업로드
  • 실패 시 재게시와 롤백

128-android-parallel-channel-release-governance.md

• 목적: Android 채널을 병렬이되 종속적이지 않게 운영하는 기준을 만든다.
• 다룰 내용:
  • Windows/Web/Android 버전 정렬 정책
  • APK universal/split 전략
  • Android 스크린샷/체크섬/권한 공지 기준
  • 채널 간 known gaps 공개 원칙

6. 운영 복구/로그/관찰성

129-operational-observability-signal-map.md

• 목적: 운영자가 무엇을 봐야 하는지 정의한다.
• 다룰 내용:
  • API, WSS, DB, Redis, MinIO, Caddy, download host 핵심 지표
  • 세션 재발급 실패율, 연결 수, 오류율, 메시지 지연
  • 제품 상태 페이지와 내부 대시보드 연결

130-log-schema-redaction-and-retention-policy.md

• 목적: 로그를 남기되 과수집하지 않는 기준을 만든다.
• 다룰 내용:
  • 구조화 로그 필드
  • PII 마스킹
  • trace/correlation ID
  • 보관 기간과 삭제 정책

131-incident-response-runbook-and-service-recovery-tiers.md

• 목적: 장애 대응을 단계형으로 정리한다.
• 다룰 내용:
  • Sev 등급
  • 최초 감지, 공지, 완화, 복구, 사후 보고
  • 세션 장애, DB 장애, 다운로드 호스트 장애, 잘못된 릴리즈 배포별 플레이북

132-backup-restore-drills-and-disaster-recovery-verification.md

• 목적: 백업과 복구를 문서가 아니라 실제 연습 대상으로 만든다.
• 다룰 내용:
  • PostgreSQL/MinIO 백업
  • 릴리즈 자산 백업
  • 월간 복구 훈련 체크리스트

7. API 계약/버전/이벤트 정합성

133-rest-api-versioning-error-envelope-and-pagination-contract.md

• 목적: 현재 API 문서를 릴리즈 가능한 계약으로 정리한다.
• 다룰 내용:
  • 버전 정책
  • 공통 오류 envelope
  • cursor pagination
  • rate limit 헤더

134-websocket-event-taxonomy-delivery-order-and-replay-spec.md

• 목적: 실시간 이벤트의 종류와 전달 순서를 명확히 한다.
• 다룰 내용:
  • message, receipt, typing, presence, system event 분류
  • ordering, ack, replay, reconnect cursor
  • 중복 수신과 누락 복구

135-client-server-capability-negotiation-and-feature-flags.md

• 목적: 채널별 구현 차이를 API로 안전하게 흡수한다.
• 다룰 내용:
  • capability handshake
  • experimental feature flags
  • 최소 지원 버전
  • Android/Web/Windows 기능 차이 공개 원칙

8. 권한/보안/신뢰 통제

136-role-permission-matrix-and-admin-boundaries.md

• 목적: 일반 사용자, 방 관리자, 서비스 운영자 권한을 분리한다.
• 다룰 내용:
  • 대화방 수준 권한
  • 관리자 도구 접근 범위
  • 읽기/삭제/추방/공지 권한

137-secret-management-key-rotation-and-build-signing-policy.md

• 목적: 운영 비밀정보와 산출물 서명 정책을 정한다.
• 다룰 내용:
  • .env 제거 계획
  • 비밀정보 저장소
  • 키 회전 주기
  • Windows/Android 빌드 서명 자격증명 관리

138-audit-trail-sensitive-actions-and-user-visible-history.md

• 목적: 민감 액션의 감사 추적과 사용자 가시성을 정한다.
• 다룰 내용:
  • 관리자 액션 로그
  • 원격 로그아웃
  • 다운로드 게시/삭제
  • 사용자에게 보여줄 이력 범위

139-security-review-checklist-and-release-gates.md

• 목적: 보안 검토를 릴리즈 전에 필수화한다.
• 다룰 내용:
  • 인증/권한/로그/스토리지/다운로드 서명 체크리스트
  • 취약점 triage
  • 보안 회귀 테스트

우선순위

P0

이 단계는 실서비스 신뢰와 직접 연결된다.

• 119-session-token-device-and-recovery-architecture.md
• 122-offline-sync-engine-conflict-resolution-spec.md
• 125-release-metadata-schema-and-version-manifest-contract.md
• 126-download-host-routing-signing-and-integrity-spec.md
• 129-operational-observability-signal-map.md
• 133-rest-api-versioning-error-envelope-and-pagination-contract.md
• 134-websocket-event-taxonomy-delivery-order-and-replay-spec.md
• 137-secret-management-key-rotation-and-build-signing-policy.md

P1

이 단계는 업무형 사용성과 운영 반복성을 크게 끌어올린다.

• 113-search-architecture-indexing-and-ranking-spec.md
• 116-vault-information-architecture-and-user-mental-model.md
• 117-vault-storage-lifecycle-export-and-retention-spec.md
• 120-auth-journey-matrix-by-channel-web-windows-android.md
• 123-outbox-retry-idempotency-and-message-dedup-policy.md
• 127-gitea-releases-artifact-publishing-and-mirroring-runbook.md
• 131-incident-response-runbook-and-service-recovery-tiers.md
• 136-role-permission-matrix-and-admin-boundaries.md
• 138-audit-trail-sensitive-actions-and-user-visible-history.md

P2

이 단계는 운영 성숙도와 장기 확장성을 높인다.

• 114-search-query-contract-saved-searches-and-analytics.md
• 115-search-qa-relevance-benchmark-and-golden-datasets.md
• 118-vault-permissions-sharing-and-sensitive-content-policy.md
• 121-device-management-remote-signout-and-risk-controls.md
• 124-offline-qa-lab-network-fault-injection-playbook.md
• 128-android-parallel-channel-release-governance.md
• 130-log-schema-redaction-and-retention-policy.md
• 132-backup-restore-drills-and-disaster-recovery-verification.md
• 135-client-server-capability-negotiation-and-feature-flags.md
• 139-security-review-checklist-and-release-gates.md

권장 작성 순서

1. 세션, API, WSS, 오프라인, 다운로드 메타 계약부터 정리한다.
2. 그 다음 관찰성/로그/장애 복구 플레이북을 묶는다.
3. 이후 검색/보관함/Android 채널을 제품+시스템 양면으로 확장한다.
4. 마지막으로 QA 골든셋과 보안 릴리즈 게이트를 붙여 반복 운영 체계를 완성한다.

전문 관점별 소유권 제안

• Product Manager: 116, 120, 128
• UX Researcher: 113, 114, 116, 118
• API Designer: 119, 133, 134, 135
• Infrastructure/SRE: 125, 126, 127, 129, 131, 132
• Security Auditor: 136, 137, 138, 139
• QA Lead: 115, 124, 139

결론

다음 문서 확장은 아이디어 문서를 더 쌓는 방향보다, 이미 잡힌 UX와 구현을 신뢰 가능한 시스템/운영/릴리즈 계약으로 내리는 방향이어야 한다.

특히 지금 시점의 가장 큰 공백은 아래 네 가지다.

• 검색이 강한 UX 기획에 비해 기술 인덱스/랭킹 문서가 약하다.
• 보관함이 목적지로 도입됐지만 저장/권한/보존 수명주기 문서가 없다.
• 세션과 오프라인 복구는 UX 원칙은 있으나 토큰/이벤트/충돌 해결 계약이 분리돼 있지 않다.
• 릴리즈와 다운로드가 실제 서비스 표면이 되었는데도, 메타데이터/서명/미러링/복구 표준이 아직 독립 문서로 부족하다.

따라서 다음 라운드 문서 확장은 검색, 세션, 오프라인, 릴리즈 메타, 관찰성, API, 권한/보안을 중심으로 진행하는 것이 가장 효율적이다.