드라이브: 폴더·파일·접근 권한·공유

제품 개발 기록으로 · 조직과 권한 · 인증

화면·SDK·서버·입력 스키마를 대조한 사용 설명입니다. 업로드·권한 변경·공유는 실행 검증하지 않았습니다.

목적과 진입 조건

조직 안에서 폴더에 파일을 올리고 필요한 직원·팀에 열람/편집 범위를 지정합니다. 관리자 워크스페이스의 드라이브 임베드 또는 앱 기본 경로 /drive/에서 엽니다. 임베드일 때 드라이브 자체 헤더는 숨깁니다. 내부 공유 주소 /drive/s/<token>도 로그인과 같은 조직 컨텍스트가 필요합니다.

목록·미리보기에는 teamDrive:read, 생성/공유에는 해당 API 권한과 대상의 편집 역할이 필요합니다. 권한 관리에는 대상별 접근 검사도 적용됩니다. 최상위에서 버튼이 보여도 서버 권한이 부족하면 생성이 거절될 수 있습니다. viewer는 보기, editor는 편집 권한이며 조직의 관리 권한과 개별 폴더 권한은 함께 확인합니다.

제공 조작과 입력

기능	조작	입력·범위
탐색	좌측 폴더명·펼침 버튼, 상단 경로, 「전체」	접근 가능한 폴더만 표시, 파일 수는 보이는 파일 기준
검색	좌측 폴더 검색, 우측 목록 검색, ×·Escape 해제	좌측은 폴더명, 우측은 현재 위치의 폴더명/설명·파일명/올린 사람
폭 조절	좌측 트리와 목록 사이 경계 드래그	180~480px, 기본 220px, 브라우저 저장
폴더 생성	「폴더 만들기」 또는 빈 곳/폴더 우클릭	이름 필수 1~100자, 설명 선택 최대 300자, 상위 폴더 선택
파일 업로드	「업로드」 또는 파일 드롭	PDF/HWP/DOC/DOCX/XLS/XLSX/PNG/JPG/JPEG, 파일당 최대 10MiB
미리보기	파일 행 한 번 클릭 또는 우클릭 「미리보기」	이미지/PDF는 본문 표시, 그 밖의 형식은 안내
새 탭·다운로드	미리보기의 버튼, 우클릭 다운로드	새 탭 열기와 파일 저장은 다른 조작
접근 관리	폴더 안 상단 「권한 관리」, 대상 우클릭	모드 변경, 팀/직원 + 보기/편집 역할 추가·제거
공유 링크	파일 우클릭 공유	생성·복사·폐기, 현재 UI에는 만료일 입력 없음

파일·폴더의 이름 변경·이동·다중 선택·삭제와 휴지통 복원·영구 삭제를 제공합니다. 전체 조직 파일 검색·페이지 넘기기·댓글 저장은 제공 조작과 구분합니다. 직원 앱은 조회만 지원합니다.

폴더 탐색·검색·폭 조절

1. 드라이브를 열고 폴더와 현재 위치 파일 로딩이 끝날 때까지 기다립니다. 「전체」는 조직 최상위 위치이며 하위 폴더의 모든 파일을 합친 검색 결과가 아닙니다.
2. 좌측 화살표로 자식을 펼치거나 폴더명을 눌러 해당 위치를 엽니다. 상단 경로의 상위 이름을 누르면 상위 위치로 이동합니다. 폴더 이동 시 목록 검색어와 선택 파일이 초기화됩니다.
3. 폴더를 찾으려면 좌측 검색, 현재 위치의 파일명·올린 사람 또는 폴더명·설명을 찾으려면 우측 검색을 사용합니다. 대소문자를 구분하지 않으며 일치 부분이 강조됩니다. 우측 검색으로 하위 폴더 안의 파일까지 찾는 것은 아닙니다.
4. × 또는 검색 입력에서 Escape로 검색을 해제합니다. 결과가 없을 때 검색어를 지우거나 다른 폴더로 이동합니다. 접근 권한으로 숨겨진 파일은 검색으로 우회하지 못합니다.
5. 폴더명이 잘리면 좌측 영역 오른쪽 경계를 잡아 드래그하고 놓습니다. 폭만 drive:railWidth에 저장됩니다. 저장소 접근이 차단되면 현재 화면에는 적용되지만 다음 진입에 유지되지 않을 수 있습니다. 파일이나 조직 설정이 바뀌는 것은 아닙니다.

폴더 만들기와 취소

1. 폴더를 둘 위치로 이동해 「폴더 만들기」를 누릅니다. 폴더 우클릭에서 시작하면 해당 폴더를 상위 위치로 제안합니다.
2. 상위 폴더를 바꾸려면 선택기를 열고 검색 후 폴더 또는 최상위 위치를 선택합니다. 예: 최상위 아래 공통 안내, 설명 테스트용 업무 안내.
3. 이름을 입력하고 저장합니다. 앞뒤 공백은 제거하며 빈 이름은 거절합니다. 같은 상위 폴더에 동일한 이름이 있으면 중복 오류가 표시됩니다. 실패하면 모달의 오류를 확인해 이름·위치를 수정합니다.
4. 성공하면 폴더가 추가되고 새 폴더 안으로 이동합니다. 목록 재진입 후에도 존재하는지 확인해야 저장 결과 검증이 됩니다.
5. 취소·×·Escape로 닫을 수 있습니다. 작성한 내용이 있으면 확인창이 나오며 「계속 편집」은 모달 유지, 「닫기」는 저장하지 않고 닫기입니다. 저장 중에는 닫기를 막습니다. 상위 폴더 선택기에서 Escape를 누르면 먼저 선택기가 닫힙니다.

파일 올리고 확인하기

1. 업로드할 폴더를 열고 「업로드」를 눌러 파일을 선택하거나 목록 영역으로 파일을 끌어 놓습니다. 폴더 생성 때와 같은 위치인지 상단 경로로 확인합니다.
2. 확장자와 파일당 크기 제한을 확인합니다. 파일 선택을 취소하면 변화가 없습니다. 여러 파일 중 허용되지 않은 파일은 거절 안내를 띄우고 허용되는 파일은 처리합니다.
3. 파일은 순서대로 저장소에 업로드한 후 DriveFile 메타데이터를 생성합니다. 성공한 파일이 현재 목록에 추가되고 폴더 파일 수가 갱신됩니다. 파일 내용의 업로드와 DB 등록은 별도 단계입니다.
4. 중간 파일 실패 시 앞서 성공한 파일이 남을 수 있습니다. 전체가 원자적으로 취소되는 동작이 아닙니다. 현재 목록과 새로고침 후 목록을 비교해 실패한 파일만 다시 시도합니다. 이름이 같은 파일을 다시 올리는 것을 '기존 파일 교체'로 설명하지 않습니다.
5. 완료 안내 후 해당 파일 행을 눌러 미리보기 또는 다운로드로 내용을 확인합니다. 업로드 완료 안내만으로 다른 사용자의 접근까지 검증된 것은 아닙니다.

미리보기·다운로드

1. 파일 행을 한 번 누릅니다. 같은 파일을 빠르게 두 번 누르더라도 이미 열린 경우 URL을 중복 발급하지 않습니다. 과거 주석의 더블클릭 설명 대신 현재 바인딩을 따릅니다.
2. 이미지나 PDF는 미리보기 본문을 확인합니다. 다른 문서 형식은 미리보기 불가 안내와 열기/다운로드를 사용합니다. URL 발급 실패 시 「파일 URL을 가져오지 못했어요.」가 표시되며 창을 닫고 다시 시도할 수 있습니다.
3. 새 탭 버튼은 발급 URL을 새 탭으로 엽니다. 미리보기의 다운로드 버튼은 내용을 받아 원래 파일명으로 다운로드합니다. 우클릭 메뉴의 다운로드는 현재 구현상 URL을 새 탭으로 여는 경로이므로 브라우저에 따라 바로 저장되지 않을 수 있습니다.
4. 댓글 입력/등록 영역을 누르면 「댓글 기능은 아직 준비 중이에요.」를 안내합니다. 댓글은 항상 빈 배열로 시작하고 저장 API와 연결돼 있지 않습니다. 표시된 칸을 실제 협업 댓글 기능으로 안내하지 않습니다.
5. × 또는 Escape로 닫습니다. 닫아도 파일이나 공유 링크가 삭제되는 것은 아닙니다.

접근 범위와 담당자 지정

1. 폴더 안에서 상단 「권한 관리」를 누릅니다. 개별 파일·다른 폴더는 우클릭의 권한 관리로 엽니다. 최상위 전체에는 해당 폴더 버튼이 없습니다.
2. 대상 이름, 접근 모드, 직접/상속된 권한을 확인합니다. 선택지는 「조직 공개 (상위 상속)」(inherit)과 「제한 — 지정한 대상만」(restricted) 두 가지입니다. 조직 공개는 상위 접근을 상속하므로, 제한된 상위 폴더 아래에서 이 값을 조직 전체에 대한 무조건 공개로 해석하지 않습니다.
3. 모드를 바꾸면 별도 저장 버튼 없이 즉시 API 저장을 요청합니다. 완료 안내와 변경된 권한 목록을 확인합니다. 실패하면 오류가 표시되며 성공한 것으로 처리하지 않습니다.
4. 권한을 추가하려면 팀/직원을 고르고 대상과 보기/편집 역할을 선택한 뒤 추가합니다. 기본 대상 종류는 팀, 기본 역할은 보기입니다. 대상 선택 없이 추가되지 않습니다. 팀은 최대 100개, 직원 연락처는 최대 500개를 가져오는 현재 목록 한계가 있습니다.
5. 제거 가능한 직접 권한의 제거 버튼을 누르면 즉시 제거 후 목록을 다시 읽습니다. 상속 표시와 직접 부여를 구분합니다. 닫기는 이미 저장된 변경을 취소하지 않습니다.
6. 실제 다른 역할의 사용자가 볼 수 있는 범위는 그 계정으로 재진입해 확인해야 합니다. 팀/직원 목록 조회가 실패하면 대상 선택 목록이 비어도 폴더 권한 자체가 없다는 뜻은 아닙니다.

내부 공유 링크

1. 파일을 우클릭하고 공유를 엽니다. 편집 역할이 있어야 공유 링크 목록과 생성/폐기를 사용할 수 있습니다.
2. 링크 생성 버튼을 누르고 생성된 행을 확인합니다. 현재 UI는 만료일을 전송하지 않아 만료 없음으로 생성합니다. 서버가 만료일을 받는다는 이유로 만료일 설정 UI를 안내하지 않습니다.
3. 복사 버튼으로 주소를 복사합니다. 이 주소는 조직 안의 로그인 사용자에게 해당 파일의 보기 접근을 허용합니다. 익명 공개 다운로드나 조직 밖 공유가 아닙니다.
4. 수신자는 같은 조직으로 로그인한 뒤 주소를 열어 미리보기를 확인합니다. 해당 폴더 전체의 편집 권한까지 생기지 않습니다. 로그인 리다이렉트 이후 원래 주소 복원은 실제 세션 조건별 확인이 필요합니다.
5. 폐기를 누르면 링크가 비활성화되고 목록에서 사라집니다. 파일은 남습니다. 만료·폐기·잘못된 조직·없어진 파일은 유효하지 않은 링크 안내로 이어집니다. 모달을 닫는 것만으로 링크가 폐기되지는 않습니다.

연결과 유지보수

파일 바이너리는 저장소, 위치·명칭은 DriveFolder/DriveFile, 개별 접근은 DriveAccessGrant, 링크는 DriveShareLink가 소유합니다. 조직과 권한의 팀 구성 변경은 접근 판정에 영향을 줄 수 있습니다. 전자서명 첨부나 CS 신고의 진단 파일은 같은 저장소 서비스를 사용할 수 있지만 드라이브의 파일 목록과 동일한 데이터가 아닙니다.

근거와 변경 기록

• 현재 조작과 상태 · 목록 화면
• API와 조직·대상별 권한 검사 · 입력 제한
• 폴더 트리·미리보기 변경 설명

별도 현재 기능 문서가 없던 드라이브의 탐색·업로드·권한·내부 공유를 신규 정리했습니다. 참고 이미지에 없는 상단 권한 관리 진입, 한 번 클릭 미리보기, 댓글 미구현과 다운로드 경로 차이를 명시했습니다. 후속 실행 검증은 서로 다른 역할의 접근·공유 링크 폐기, 여러 파일 중간 실패, 로그인 후 공유 경로 복원입니다. 폴더 폭 드래그와 업로드는 동작 영상이 필요한 경로이며 신규 녹화는 아직 없습니다.

화면에서 위치 찾기

1↓2↓3↓4↓

드라이브의 폴더 트리와 파일 목록입니다. 상단 권한 관리 컨트롤은 이 이미지에 포함되지 않습니다. 원본 크게 보기

1. 좌측 폴더 이름을 눌러 위치를 엽니다.
2. 현재 위치의 목록 검색어를 입력합니다.
3. 파일 업로드를 누르고 허용되는 파일을 선택합니다.
4. 업로드된 파일 행을 한 번 눌러 내용을 확인합니다.

폴더·접근 범위 기능 영상

관리자 드라이브 가이드에 5단계 영상을 연결했습니다. Codex가 관리자 「드라이브」 → 「폴더 만들기」에서 최상위의 「영상 교육 자료」·설명 「온보딩 예제 전용 문서함」을 저장했습니다. 상위 「전체」로 돌아가 같은 폴더를 다시 열어 저장 결과를 확인했습니다.

폴더의 「권한 관리」에서 제한 모드로 바꾸고 창을 닫았다 다시 열어 유지되는지 확인한 뒤 상위 상속으로 복원했습니다. 모드 변경은 즉시 저장되므로 창 닫기를 취소로 설명하지 않습니다. 관리자 안의 /drive/ 임베드가 같은 조직의 DriveFolder와 접근 설정을 사용합니다. 파일 업로드·직원/팀 직접 권한·다른 계정의 접근·공유 링크·다운로드는 이번 영상 범위가 아닙니다.

이름 변경·이동·여러 항목 선택

항목	내용
사용자	해당 항목의 편집 권한을 가진 직원. 보기 권한만 있으면 변경 메뉴를 사용할 수 없습니다.
진입	관리자 드라이브 목록에서 항목 우클릭, 또는 행 앞 체크박스 선택
결과 확인	현재 목록·왼쪽 폴더 트리·상단 경로와 이동할 폴더 안의 실제 항목

1. 「이름 변경」에서 폴더 이름·설명을 고치고 저장합니다. 같은 위치에 같은 폴더 이름이 있으면 이름을 바꿉니다. 파일은 새 이름을 입력하고 확인하며, 확장자를 지웠거나 허용하지 않는 확장자를 넣으면 원래 확장자가 붙을 수 있으므로 결과 파일명을 확인합니다. 빈 이름·확장자만 있는 이름은 사용할 수 없습니다.
2. 위치를 바꿀 때는 이름 수정 대신 「이동」에서 도착 폴더를 고르고 확인합니다. 행을 왼쪽 폴더 트리·「전체」·목록의 폴더에 끌어 놓을 수도 있습니다. 외부 파일을 끌어오는 업로드와 구분합니다.
3. 자기 자신·하위 폴더로 이동할 수 없고 도착지의 편집 권한·동일 폴더 이름을 확인해야 합니다. 실패 사유를 보완해 다시 선택합니다. 이동 창 취소는 위치를 바꾸지 않습니다.
4. 행 앞 체크박스로 여러 항목을 고르면 선택 줄에서 일괄 이동·삭제·선택 해제를 합니다. 머리글 선택은 검색에 보이는 행만 대상으로 합니다. 폴더나 검색어를 바꾸면 선택이 초기화됩니다. 보기 전용 항목이 섞이면 일괄 변경이 잠깁니다.

삭제·휴지통·복원

1. 삭제할 항목과 하위 폴더·파일 개수를 확인하고 「삭제」 확인을 완료합니다. 폴더 삭제는 하위 항목을 포함하며 하위 항목의 편집 권한도 필요합니다. 확인창 취소는 삭제하지 않습니다.
2. 왼쪽 「휴지통」에서 이름·원래 위치·지운 사람·날짜를 확인합니다. 같은 삭제로 함께 지워진 하위 항목은 묶음의 위쪽 항목을 통해 복원합니다.
3. 「복원」 후 원래 폴더를 다시 엽니다. 원래 상위 폴더가 없으면 「전체」로 복원될 수 있고, 같은 폴더 이름이 있으면 이름에 「(복원)」이 붙습니다. 더 먼저 따로 지운 하위 항목을 함께 되살리는 동작은 아닙니다.
4. 「영구 삭제」 또는 「휴지통 비우기」는 되돌릴 수 없습니다. 기본 보관 기간은 삭제 후 30일이며 운영 설정에 따라 달라질 수 있습니다. 필요한 항목은 기간 안에 복원합니다.

복원은 관리 권한이 있거나, 본인이 지운 항목이면서 복원 위치를 편집할 수 있어야 합니다. 삭제된 파일의 공유 링크도 함께 비활성화됩니다. 복원 시 같은 삭제 묶음의 권한·공유 정보도 복구합니다.

직원 앱에서 파일 보기

「더보기 > 드라이브」에서 폴더와 상단 경로를 누르고 현재 위치를 검색합니다. 이미지는 앱 안에서, PDF는 웹에서는 앱 안에서 볼 수 있습니다. 네이티브 앱의 PDF·한글·오피스 문서는 기기 뷰어를 사용하므로 설치된 앱에 따라 열기 동작을 확인해야 합니다. 업로드·이름 변경·이동·삭제·권한 수정은 이 화면에서 하지 않습니다. 미리보기를 닫은 뒤 상위 폴더나 더보기로 돌아갑니다. 권한이 없는 파일은 링크를 알고 있어도 열 수 없습니다.

변경 근거와 검증 경계

PR #999·#1001·#1002·#1003·#1006·#1008·#1009·#1014의 화면·SDK와 team-drive.router.ts, drive-access.service.ts, drive-trash-retention.ts를 대조했습니다. 파일 바이트는 API의 현재 접근 검사 뒤 전달되고 기기 뷰어용 티켓은 짧은 유효기간을 가집니다. 공유 링크만으로 인증을 생략하지 않습니다. 촬영된 조작과 별개로 네이티브 뷰어·보관 만료·저장소 삭제 실패·다른 사용자의 권한 거절은 추가 확인합니다.