# 승인 사용자·다중 팀·전술 영상 공유 설계 조사

2026-09-07 · 조사/설계 제안. 이번 작업은 문서 작성이며 서비스 구현·배포·외부 API 등록은 수행하지 않았다.

## 권장 결론

승인된 계정이 여러 팀을 소유하거나 참여하고, 각 팀에 전술을 저장한다. 공유 원본은 MP4로 생성한다. 사용자가 확정한 핵심 요구는 **방금 만든 전술을 MP4 첨부영상으로 카카오톡 단체방에 보내고, 수신자가 링크 이동 없이 카카오톡에서 재생하는 것**이다. 주 동작은 '영상 공유'이며 링크 공유는 요구를 충족하는 대안이나 fallback으로 취급하지 않는다. GIF는 후순위 비교 후보다.

## 사용자 확정 요구에 따른 설계 변경

이 절이 아래 초기 비교/조사 내용보다 우선한다. 아래 링크 공유 설명은 조사 기록으로 남기며 제품 기본 경로로 채택하지 않는다.

- 완료 흐름: 전술 작성 → 영상 공유 → 현재 버전 MP4 생성/준비 → 공유창에서 카카오톡·단체방 선택 → 영상 첨부 전송 → 수신자가 카카오톡에서 재생.
- 전송할 내용은 URL이나 JSON이 아닌 MP4 파일이다. 수신자의 웹사이트 로그인·팀 가입·외부 웹 플레이어 진입을 요구하지 않는다.
- 브라우저에서 Web Share 파일 전송을 먼저 검증한다. OS 공유창과 카카오톡 대화방 선택은 사용자 조작이다. 기존 단체방을 앱이 자동으로 지정하거나 무인 전송하는 요구로 해석하지 않는다.
- 파일 생성/준비에는 시간이 필요할 수 있다. 준비 완료 후 새 사용자 탭으로 OS 공유창을 열어 사용자 활성화 제한을 만족한다. 실제 측정 없이 최초 공유를 즉시 완료한다고 약속하지 않는다.
- 파일 공유 미지원 환경에서 다운로드 후 수동 첨부는 임시 보조 경로일 뿐, 핵심 UX 완료로 간주하지 않는다. 주요 대상 환경에서 직접 공유가 불안정하면 네이티브 앱 또는 하이브리드 앱의 파일 공유 브리지를 검토한다. 이때도 실제 카카오톡 수신 영상으로 검증해야 한다.
- MVP 통과 기준은 iOS/Android 실제 기기에서 생성 MP4가 기존 카카오톡 단체방에 첨부되고, 수신자가 외부 링크 없이 카카오톡에서 재생하는 것이다. 공유 API 호출 성공이나 파일 전송 가능 검사만으로 완료 처리하지 않는다.
- 검증 시 MP4가 일반 파일로만 표시되는지, 영상 썸네일과 재생 UI를 제공하는지 확인한다. 링크 없이 탭하여 재생하는 것이 요구이며 무조건 자동 재생을 의미하지 않는다.
- 발신자는 서비스 승인/팀 권한을 검사한다. 수신자는 카카오톡 영상 수신자이며 서비스 접근권한과 별개다. 전송한 파일은 앱에서 회수하거나 만료시킬 수 없다.

카카오톡 메시지에 웹사이트 링크를 보낸 것과 MP4 첨부파일을 보낸 것은 다른 경험이다. 일반 Kakao Share 템플릿을 사용해 임의 MP4를 카카오톡 채팅방 안에서 자동 재생시키는 기능을 전제로 설계하면 안 된다.

## 현재 프로젝트와 필요한 변화

현재는 Vite + Vanilla JS + Three.js의 로컬 편집 앱이며 `src/playRepository.js`에서 브라우저 localStorage에 전술을 저장한다. 사용자 인증, 사용 승인, 팀, 서버 저장, 공유 링크, 영상 렌더링 서버는 없다.

새 UI에 팀 이름만 추가해서는 기기 간 동기화나 팀별 접근 제어가 성립하지 않는다. 인증/승인 API, 데이터베이스, 파일 저장소, 영상 생성 작업 처리가 필요하다. 현 전술 JSON 구조는 유지하고 서버 저장 레코드에 소유 팀과 버전 정보를 덧붙이는 방향이 적합하다.

## 계정 및 팀 UX

흐름: 로그인 → 서비스 사용 승인 확인 → 내 팀 → 팀 전술함 → 편집/재생 → 공유.

- 로그인 수단은 카카오 로그인을 우선 후보로 제안한다. 카카오톡 공유를 하기 위해 서비스 로그인도 반드시 카카오여야 하는 것은 아니다.
- 로그인 성공과 서비스 사용 승인을 분리한다. 운영자 초대 또는 가입 후 승인으로 `pending/approved/suspended`를 관리한다. 미승인 사용자는 승인 대기 화면까지만 접근한다.
- 첫 진입에는 '첫 팀 만들기', 기존 사용자는 최근 사용 팀을 바로 열고 상단 팀 전환기를 제공한다.
- 계정 하나로 여러 팀을 만들고 전환할 수 있다. 팀명·선택적 색상/로고만으로 생성 가능하게 한다. 한 팀을 만든 뒤에도 항상 '+ 팀 만들기'를 제공한다.
- 팀 전술함은 전술 썸네일, 이름, 수정일, 태그, 영상 준비 여부를 표시한다. '새 전술'은 현재 팀에 자동 귀속된다.
- 편집 상단에 `팀명 / 전술명`을 표시해 다른 팀에 저장하는 실수를 줄인다. 다른 팀으로는 이동보다 '복사'를 기본으로 제공하며 목적지 편집 권한을 검사한다.
- PC는 좌측 팀 전환/전술함 + 넓은 편집 화면. 모바일은 상단 팀 전환기 + 전술 카드 목록 + 새 전술 버튼, 편집은 별도 화면으로 구성한다.
- 기존 기기 전술은 사용자가 선택한 팀으로 '이 기기의 전술 가져오기'를 제공한다. 서버 저장 성공 전 기존 데이터를 지우지 않으며 중복 가져오기를 방지한다.

## 권한과 데이터

초기 역할 제안: 팀 소유자(팀/멤버 관리), 편집자(전술 작성·영상 생성·허용된 공유), 열람자(팀 전술 보기). 서비스 운영자의 승인 권한은 팀 소유자 역할과 별도다. 팀 초대는 서비스 이용 승인을 우회하지 않는다.

| 레코드 | 핵심 관계/필드 |
| --- | --- |
| User | 로그인 제공자 식별자, 서비스 승인 상태 |
| Team | 팀 ID, 이름, 생성자 |
| TeamMember | 팀 ID + 사용자 ID, 역할, 가입 상태 |
| Play | 팀 ID, 전술 JSON, 현재 버전, 작성/수정자 |
| PlayRevision | 변경하지 않는 전술 스냅샷 |
| VideoExport | 전술 버전, 카메라/선수/화질 설정, 대기·처리·완료·실패 상태, 영상/썸네일 경로 |
| ShareLink | 공유 영상/버전, 열람 정책, 만료, 철회 상태, 추측하기 어려운 토큰 |

모든 팀 데이터·영상 생성·공유 설정 API에서 서비스 승인 및 해당 팀 권한을 서버가 확인한다. 클라이언트의 teamId나 숨긴 버튼을 권한으로 신뢰하지 않는다. 기존 전술의 offense/defense는 작전판 진영이며, 새 Team 엔터티와 구분한다.

## GIF / MP4 / 링크 비교

| 형식 | 적합한 점 | 제약 | 판단 |
| --- | --- | --- | --- |
| GIF | 짧은 반복 미리보기 | 3D 장면·텍스트의 화질/용량 부담, 재생 위치·속도 조절에 부적합, 수신 앱의 재생 방식에 종속 | 후순위 옵션 |
| MP4 파일 | 휴대폰에서 공유·저장하는 일반 영상, 작전판/POV 모두 가능 | 생성·전송 시간, 배포한 파일은 회수 불가 | 기본 영상 포맷 |
| 영상 재생 링크 | 작은 메시지, 열람 권한·만료·철회 가능, 웹 재생 컨트롤 제공 | 네트워크 필요, 채팅방 안 첨부영상과 다르게 링크를 열어 재생 | 기본 카카오 공유 방식 |

MP4와 링크는 대안 관계가 아니다. 같은 MP4 자산을 링크 재생과 파일 공유 양쪽에서 사용한다. GIF 대비 영상의 용량 효율은 장면마다 다르므로 실제 작전판·POV 클립으로 비교한다. [Google web.dev](https://web.dev/articles/replace-gifs-with-videos?hl=en)

## 카카오톡 링크 공유

권장 흐름: 공유 패널 → 썸네일/전술명/열람 범위 확인 → '카카오톡으로 링크 보내기' → 카카오톡에서 대화방 선택 → 수신자가 '전술 보기' 클릭 → 모바일 웹 플레이어.

- Kakao JavaScript SDK의 `Kakao.Share.sendDefault()` 등으로 피드 카드를 보낸다. 썸네일·제목·재생 페이지 URL을 사용한다.
- Kakao Developers 앱, JavaScript 키와 사용 도메인 설정, 접근 가능한 HTTPS 재생 페이지가 필요하다. 비밀 키는 프런트엔드에 넣지 않는다.
- SDK의 공유 API와 친구 메시지 API는 다르다. 사용자가 기존 단체방을 골라 공유하는 요구에는 Share가 맞다. 우리 앱의 Team과 카카오톡 단체방은 자동 연결되지 않는다.
- 일반 템플릿은 링크 카드다. 썸네일에 재생 아이콘을 넣어도 임의 MP4의 채팅방 내 자동 재생을 보장하지 않는다.
- 재생 페이지는 `<video controls playsinline>`와 포스터 이미지를 사용한다. 자동 재생에 의존하지 않고 눈에 띄는 재생 버튼을 제공한다.
- 영상 준비 완료 후 공유한다. 공유된 링크가 생성 실패 화면으로 열리지 않도록 한다. 썸네일 캐시는 수정 가능성을 고려해 버전별 주소를 사용한다.

근거: [Kakao Share 이해하기](https://developers.kakao.com/docs/ko/kakaotalk-share/common), [JavaScript 연동](https://developers.kakao.com/docs/ko/kakaotalk-share/js-link), [FAQ](https://developers.kakao.com/docs/en/kakaotalk-share/faq).

## 영상 파일을 카카오톡으로 바로 공유

권장 흐름: 생성된 MP4 준비 → '영상 파일 공유' 탭 → OS 공유창 → 카카오톡 선택 → 대화방 선택 → 전송.

- 웹에서는 MP4를 `File`로 준비한 후 `navigator.canShare({ files: [file] })`를 검사하고 `navigator.share({ files: [file] })`로 OS 공유창을 연다.
- 표준 Web Share API에서 목적 앱이나 채팅방을 카카오톡으로 강제 지정할 수 없다. 사용자가 공유 대상을 선택한다.
- 웹사이트 HTTPS, 브라우저의 파일 공유 지원, 사용자 탭이 필요하다. `canShare` 통과는 카카오톡 설치·대상 노출·전송 완료·채팅방 렌더링을 모두 보장하지 않는다.
- 영상 생성이나 다운로드를 오래 기다린 뒤 같은 최초 탭으로 공유창을 열려고 하면 사용자 활성화가 만료될 수 있다. 파일까지 준비된 다음 버튼을 활성화하고 새 탭에서 공유 호출한다.
- 지원하지 않으면 '영상 다운로드'와 '카카오톡 링크 공유'를 제공한다. 카카오톡 인앱브라우저에서 막히는 경우 외부 브라우저에서 여는 안내도 제공한다.
- 생성 완료 상태와 파일 다운로드 완료 상태를 구분한다. 첫 생성은 즉시 끝나지 않는다. 수정본·설정별 결과를 재사용하여 반복 공유의 대기 시간을 줄인다.
- Share Promise 종료를 대화방 전송 완료로 단정하지 않는다. 취소와 실패도 분리한다.

카카오 공식 문서도 템플릿 없이 파일을 공유하려면 OS 공유 기능을 사용하라고 안내한다. 다만 웹의 OS 공유 연결은 브라우저마다 차이가 있으므로 실기기 검증이 필요하다. [Kakao OS 공유 안내](https://developers.kakao.com/docs/ko/kakaotalk-share/common), [W3C Web Share](https://www.w3.org/TR/web-share/), [파일 공유 지원 검사](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/share).

## 영상 생성 방식

중요 기능이므로 최종 배포 구조는 서버 작업으로 렌더링하는 방식을 권장한다. 모바일 성능·백그라운드 전환·브라우저 코덱 차이에 영향을 덜 받는다. 아래는 제안 구조이며 실제 처리 속도는 측정해야 한다.

1. 승인/팀 권한 확인 후 전술 버전과 출력 설정을 스냅샷으로 고정한다.
2. 렌더링 작업을 등록한다. 동일 버전 + 설정 + 렌더러 버전의 완료 결과는 재사용한다.
3. 전용 Three.js 렌더 화면에서 고정 시간 간격으로 전술을 샘플링해 프레임을 생성한다. DOM 편집 UI가 아닌 코트/선수/영상용 표기만 출력한다.
4. FFmpeg로 MP4(H.264, yuv420p, 빠른 재생 시작을 위한 faststart)와 포스터를 만든다. 기본 제안은 가로 1280×720, 30fps, 무음이며 실제 글자 크기·파일 크기를 보고 조정한다.
5. 비공개 파일 저장소에 저장하고 열람 정책에 따라 미디어 URL을 발급한다. 재생 페이지의 범위 요청 지원으로 탐색을 제공한다.
6. 공유 패널에 준비 완료와 미리보기를 표시한다.

초기 기술 검증은 `canvas.captureStream()` + `MediaRecorder`로 가능하지만 브라우저별 출력 코덱 지원을 검사해야 한다. WebM 파일 확장자만 MP4로 바꾸는 것은 변환이 아니다. 모바일에서 FFmpeg WASM으로 모든 변환을 처리하는 방식을 기본 경로로 삼지 않는다. 서버 렌더링은 운영비와 WebGL 실행 환경 확인이 필요하므로 짧은 실제 클립으로 먼저 검증한다.

출력 카메라는 기본 '작전판 전체', 선택 옵션 '지정 선수 시점'을 제안한다. POV는 선수 ID를 출력 설정에 고정하고 공유 카드에 명시한다. 화면을 세로 영상으로 단순 크롭해 양쪽 선수를 잃지 않도록 한다. 공유한 영상은 특정 버전으로 고정하고 이후 편집으로 조용히 내용이 바뀌지 않게 한다.

근거: [MediaRecorder](https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder), [FFmpeg MP4 문서](https://ffmpeg.org/ffmpeg-formats.html).

## 승인제와 공유 열람 정책

기본 전술함/공유는 승인된 팀 멤버만 볼 수 있도록 한다. 로그인 후 원래 공유 페이지로 복귀해야 한다.

수신자가 가입 없이 곧바로 보게 하려면 별도 '링크를 가진 사람은 열람' 정책을 팀 소유자가 명시적으로 허용해야 한다. 이 정책은 서비스 전체 승인제의 의도적 예외이므로 구현 전에 제품 정책을 확정해야 한다. 편집권이나 팀 목록까지 공개하지 않고 해당 버전 영상만 공개한다.

민감한 팀 전술은 공개 썸네일에 노출하지 않는다. 팀 전용 링크의 카카오 카드에는 일반 코트 이미지를 사용할 수 있다. 파일 저장소는 비공개로 두고, 공유 페이지에서 정책 검사 후 짧은 유효기간의 재생 URL을 발급한다. 철회는 이후 열람을 막는 기능이며 이미 다운로드되거나 카카오톡으로 전송된 MP4/GIF는 회수할 수 없다.

## 구현 순서와 완료 기준

1. **공유 기술 검증:** 대표 작전판/POV MP4 1개씩으로 iPhone Safari, Android Chrome, iOS/Android 카카오톡 인앱브라우저에서 링크·파일 공유·수신 재생을 확인한다. 파일 크기와 생성/준비/전송 시간을 기록한다. 문서만으로 '모든 모바일 즉시 공유'를 약속하지 않는다.
2. **서비스 기반:** 로그인·운영자 승인·여러 팀 생성/전환·팀별 전술 저장·역할 검사·로컬 데이터 가져오기.
3. **기본 공유:** 버전별 MP4 생성, 상태/재시도, 재생 페이지, 팀 전용 링크, 카카오 카드 공유, 파일 공유 및 다운로드 fallback.
4. **선택 확장:** 명시적으로 허용된 외부 열람 링크, 만료·철회, 짧은 GIF, 화질/시점 프리셋.

검증에는 미승인 사용자, 비멤버의 팀 ID 접근, 승인 취소, 중복 영상 생성 요청, 수정 중 영상 생성, 공유 취소, 앱 미설치, 느린 네트워크, 만료 링크, 세션 만료, 기존 카카오 미리보기 캐시, 파일 다운로드 후 재공유를 포함한다.

사용자가 팀 A/B를 생성하고 각 전술이 올바른 팀에 저장되는지, 다른 팀으로 전환해도 섞이지 않는지, 한 계정의 다른 기기에서 같은 내용을 보는지를 확인한다. 코드 구현은 AGENTS.md에 따라 GPT-5.6 Luna에게 위임한다.