docs(readme): align with actual implementation

리뷰어 P2 지적 3건 반영:
- 데이터 위치: `data/videos/<videoId>/` 라는 잘못된 경로를 실제 구조
  `data/folders/<topName>[/<subName>]/<videoId>/` 로 교정. `data/jobs`,
  `data/tmp` 도 추가. "폴더 이름 바꿔도 파일 이동 없음" 문장은 실제로는
  rename 동작이 일어나므로 삭제.
- 공개 폴더 화면 설명: 1단계가 "서브폴더 + 영상 혼합" 이라고 적혀
  있었지만, views/folder.ejs 구현은 1단계=하위폴더만 / 2단계=영상만 으로
  분리됨. 두 단계별 렌더링을 정확히 기술.
- 관리자 폴더: "영상 카드 드래그 정렬" 항목은 plain admin folder 뷰에
  없으므로 제거. 드래그 정렬은 플레이리스트 임포트 화면 한정임을 명시.
- 랜덤 ID 형식: "8자 base32" → 실제 public/playlist.js 의 24자 hex
  (crypto.randomUUID 압축) 로 정정. 시퀀셜 zero-pad 동작도 보강 설명.

코드 변경 없음. `npm run build` 통과.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Claude (owner)
2026-06-01 10:50:05 +09:00
parent 5693e1c6b0
commit 90e227d857

View File

@@ -40,15 +40,15 @@ npm start
``` ```
data/ data/
app.db # 메인 sqlite (폴더 트리, 영상 메타, 잡 큐, 세션) app.db # 메인 sqlite (폴더 트리, 영상 메타, 세션)
videos/<videoId>/ # 영상 파일 (id 기준 평면 디렉터리) folders/<topName>[/<subName>]/<videoId>/ # 영상 파일
original.<ext> # 원본 (항상 보존) original.<ext> # 원본 (항상 보존)
edited.<ext> # 트림 저장 시 생성 edited.<ext> # 트림 저장 시 생성
uploads/ # 업로드 임시 (multer) jobs/ # 백그라운드 yt-dlp 다운로드 잡 상태
tmp/ # 작업 임시 tmp/ # 작업 임시 (업로드/변환 중간 산출물)
``` ```
폴더 트리 / 영상 메타는 모두 `app.db` 에서 관리합니다. 디스크 상 영상 파일은 영상 ID 기준 평면 구조라 폴더 이름을 바꿔도 파일 이동이 일어나지 않습니다. 폴더 트리 / 영상 메타는 `app.db` 에서 관리하고, 실제 영상 파일은 폴더 경로 + videoId 디렉터리에 저장됩니다. 폴더 이름을 바꾸면 디스크 디렉터리도 같이 rename 됩니다.
## URL 규칙 ## URL 규칙
@@ -71,8 +71,8 @@ data/
- 폴더를 누르면 `/folder/:폴더이름` 으로 이동. - 폴더를 누르면 `/folder/:폴더이름` 으로 이동.
### 폴더 화면 (`/folder/:topName[/:subName]`) ### 폴더 화면 (`/folder/:topName[/:subName]`)
- 최상위 폴더: 서브폴더와 영상이 섞여 나옵니다. 서브폴더는 카드, 영상은 썸네일 + 제목. - 1단계 폴더 화면: **하위 폴더 카드만** 보여줍니다 (영상은 2단계로 내려야 표시).
- 서브폴더(2단계): 영상만 나옵니다. (폴더 깊이는 최대 2단계까지) - 2단계 폴더 화면: **영상만** 보여줍니다 (썸네일 + 제목). 더 깊이 들어갈 수 없습니다.
- 영상 카드 클릭 → `/video/:topName[/:subName]/:videoId` 로 이동, 플레이어가 뜨고 재생. - 영상 카드 클릭 → `/video/:topName[/:subName]/:videoId` 로 이동, 플레이어가 뜨고 재생.
### 관리자 페이지 (`/op`) ### 관리자 페이지 (`/op`)
@@ -83,11 +83,12 @@ data/
### 관리자 폴더 화면 (`/op/folder/...`) ### 관리자 폴더 화면 (`/op/folder/...`)
- 영상/서브폴더 목록을 유튜브 스타일로 나열. 우클릭으로 수정/삭제. - 영상/서브폴더 목록을 유튜브 스타일로 나열. 우클릭으로 수정/삭제.
- 영상 ID 인라인 편집 가능 (전체 영상에 걸쳐 고유, 안전한 ID 형태만 허용. 변경하면 공유 URL 의 마지막 세그먼트가 같이 바뀝니다). - 영상 ID 인라인 편집 가능 (전체 영상에 걸쳐 고유, 안전한 ID 형태만 허용. 변경하면 공유 URL 의 마지막 세그먼트가 같이 바뀝니다).
- 영상 카드를 드래그해 정렬 순서 변경.
- 오른쪽 위 "영상 추가" → `/op/folder/.../video/editor` 로 이동. - 오른쪽 위 "영상 추가" → `/op/folder/.../video/editor` 로 이동.
- 2단계 폴더에서만 노출되는 "플레이리스트 임포트" 버튼: YouTube 플레이리스트 URL 을 넣으면 항목을 미리 보여주고 시작할 수 있습니다. - 2단계 폴더에서만 노출되는 "플레이리스트 임포트" 버튼: YouTube 플레이리스트 URL 을 넣으면 항목을 미리 보여주고 시작할 수 있습니다.
- 항목별 드래그 정렬, 제목/ID 인라인 편집. - 항목별 **드래그 정렬** (정렬 UI 는 플레이리스트 임포트 화면 한정), 제목 / ID 인라인 편집.
- ID 정책 토글: **랜덤** (8자 base32 자동) / **시퀀셜** (원래 순서 기준 1-N, zero-pad 옵션). - ID 정책 토글:
- **랜덤** — 항목별로 24자 hex (crypto.randomUUID 압축, 폴백은 16진수 24자) 자동 생성.
- **시퀀셜** — 원래 플레이리스트 순서 기준 1, 2, 3, ... 으로 부여. zero-pad 옵션을 켜면 항목 총개수 자릿수에 맞춰 `001, 002, ...` 처럼 패딩.
- "가져오기 시작" 누르면 각 항목이 큐에 들어가고 백그라운드에서 다운로드 + 후처리. - "가져오기 시작" 누르면 각 항목이 큐에 들어가고 백그라운드에서 다운로드 + 후처리.
### 영상추가 화면 (`/op/folder/.../video/editor`) ### 영상추가 화면 (`/op/folder/.../video/editor`)