ent 파일 관리하는 방법 작성 (#94)

Co-authored-by: usbsync <[email protected]>

Author: kimorkim

source/entryjs/faq/2024-02-29-faq.md renamed to source/entryjs/etc/2024-02-29-faq.md

@@ -3,7 +3,7 @@ layout: page
 title: 자주 묻는 질문(FAQ)
 type: entryjs
 category: '기타'
-order: 2
+order: 3
 keywords: 
 genre: 
 description: 

source/entryjs/file/2024-07-24-ent.md

@@ -0,0 +1,149 @@
+---
+layout: page
+title: ENT파일 관리
+type: entryjs
+category: '파일 관리'
+order: 1
+keywords: 
+genre: 
+description: 
+thumbnail: 
+author: Entrylabs
+date: 2024-07-24
+updated: 2024-07-24
+---
+
+## 소개
+
+내 컴퓨터에 저장하기 기능은 사용자가 자신의 작품을 컴퓨터에 저장할 수 있도록 지원합니다. 이 기능은 작품의 JSON 데이터를 기반으로 필요한 assets 파일을 수집하고, 이를 하나의 압축 파일로 묶어 제공합니다. 최종적으로 생성된 파일은 .ent 확장자를 가지며, 사용자는 이를 다운로드하여 로컬 환경에서 쉽게 사용할 수 있습니다.
+
+## 프로젝트 데이터
+
+### 프로젝트 JSON
+
+프로젝트 JSON 데이터 생성은 [Entry.getStartProject()](/entryjs/api/2024-02-29-api.html#Entry-exportProject) 메서드를 사용하여 이루어집니다. 이 메서드는 현재 프로젝트의 모든 데이터를 JSON 형식으로 내보냅니다.
+
+> [Project Data](/entryjs/typedef/2024-03-15-project-data.html)
+
+### 프로젝트 에셋
+
+프로젝트 JSON에 에셋의 경로가 포함되어 있으며, 해당 경로의 에셋들을 모아 압축 파일로 만들게 됩니다.
+
+
+## .ent
+
+현재 `.ent`파일은 `tar`를 사용하여 압축을 진행하여 만들고 있으며 `memLevel`은 6을 사용하고 있습니다.
+
+> 엔트리에서는 [tar](https://www.npmjs.com/package/tar) 패키지를 사용하고 있습니다.
+
+
+###  파일의 구조
+
+```
+project.ent
+│
+└── temp                    # 프로젝트에 사용된 모든 에셋 파일들이 포함된 디렉토리
+    │
+    ├── project.json        # 프로젝트의 전체 데이터를 포함하는 JSON 파일
+    │
+    ├── 0a                  # assets의 폴더
+    ...                     # ...
+    └── fd                  # assets의 폴더
+```
+
+
+기본적으로 제일 상위의 `temp` 폴더가 있고 그 아래에 `project.json`과 에셋 폴더가 존재하는 방식입니다.
+자세히 살펴보려 하신다면 기본적으로 `.ent`파일은 `tar`로 압축된 파일이기때문에 `tar`로 압축해제가 가능합니다.
+이를 통해 내용을 확인하시면 됩니다.
+
+### 압축하기
+
+기본적으로 프로젝트 JSON의 [object](/entryjs/typedef/2024-03-15-object-data.html)에 파일의 경로가 다 남아 있으므로
+해당 경로를 통해서 파일을 `temp`폴더에 복사하고 `tar`로 작성하시면 됩니다.
+
+엔트리에서는 압축시 `tar`를 아래와 같이 사용중입니다.
+
+```js
+await tar.c(
+    {
+        file: destination, /* 파일 경로 */,
+        gzip: { memLevel: 6 },
+        cwd, /* 작업 위치 */
+        filter: (path, stat) => {
+            try {
+                return !stat.isSymbolicLink();
+            } catch (e) {
+                return false;
+            }
+        },
+        portable: true,
+    },
+    [fileList] /* temp 폴더 */
+);
+```
+
+### 압축풀기
+
+이제는 반대로 `tar`를 통해 압축을 풀고 풀어진 에셋을 정해진 위치에 넣고, `project.json`을 `db`에 넣어주면 됩니다.
+
+엔트리에서는 압축 해제시 `tar`를 아래와 같이 사용중입니다.
+```js
+await tar.x({
+    file: target, /* .ent파일 경로 */
+    cwd: destination, /* 압축해제 경로 */
+    filter: (path, entry) => {
+        const { type, size } = entry;
+        return type !== 'SymbolicLink' && maxSize > size && checkExtName(entry);
+    },
+})
+```
+
+## 주의사항
+`.ent`파일로 만드시고 `playentry.org`사이트에도 동일하게 사용을 하기 원하신다면 폴더 구조를 맞춰 주셔야 합니다.
+현재 엔트리에서는 기본적으로 `assets`을 아래과 같은 형식으로 관리하고 있습니다.
+
+### 에셋의 파일이름
+모든파일의 이름은 난수값의 이름으로 만들고 있습니다. 이때 [uid](https://www.npmjs.com/package/uid)와 [puid](https://www.npmjs.com/package/puid)를 혼합해서 생성하고 있습니다.
+
+```js
+const { uid } = require('uid');
+const Puid = require('puid');
+const puid = new Puid();
+const createFileId = () => uid(8) + puid.generate();
+```
+
+기본적으로 만들어진 `fileId`에서 앞의 4자를 이용해서 하위 폴더를 생성하는 방식입니다.
+만들어진 `fileId`가 `e49448cdlyy4s42e0013f820158i7nqj`인 경우
+`/e4/94/` 으로 앞의 2자 그 뒤의 2자로 폴더를 생성하고 `assets`을 그 안에 넣습니다.
+
+### 이미지
+`image`라는 폴더명으로 구분됩니다.
+
+> 만들어진 `fileId`가 `e49448cdlyy4s42e0013f820158i7nqj`인 경우 `/e4/94/image/e49448cdlyy4s42e0013f820158i7nqj.png`
+
+### 썸네일
+`thumb`라는 폴더명으로 구분됩니다.
+
+> 만들어진 `fileId`가 `e49448cdlyy4s42e0013f820158i7nqj`인 경우 `/e4/94/thumb/e49448cdlyy4s42e0013f820158i7nqj.png`
+
+### 사운드
+`sound`라는 폴더명으로 구분됩니다.
+
+> 만들어진 `fileId`가 `e49448cdlyy4s42e0013f820158i7nqj`인 경우 `/e4/94/sound/e49448cdlyy4s42e0013f820158i7nqj.mp3`
+
+### 경로가 다를 경우
+작업한 서버의 상황에 따라 엔트리와 파일경로 방식이 불일치해서 `.ent`가 호환이 안되는 경우 아래와 같은 방식으로 교정이 반드시 필요합니다.
+
+1. 작업할 `project.json`과 `assets`들을 `temp`폴더에 복사
+2. `.ent`파일을 만들때 프로젝트 JSON에 기록된 `assets`의 경로를 `Entry`와 동일하게 치환합니다.(이때 createFileId를 사용)
+3. JSON데이터를 치환함과 동시에 실제 `assets`의 경로도 동일하게 변경
+4. 해당 `assets`과 `project.json`을 tar로 압축
+
+과 같은 과정을 거쳐야 하고, 반대로 `.ent`파일을 작품으로 저장해야 할경우
+
+1. `.ent`파일의 압축을 푼다.
+2. `project.json`의 `assets` 경로를 서버의 환경에 맞게 치환한다.
+3. 이때 실제의 `assets`들의 경로도 변경한다.
+4. 해당 `assets`을 실제의 위치에 복사하고, `project.json`의 데이터를 `db`에 저장한다.
+
+와 같은 과정으로 저장해야 합니다.

themes/vue/layout/partials/toc.ejs

@@ -34,5 +34,6 @@
     <% makeList('API문서'); %>
     <% makeList('고급 기능 블록'); %>
     <% makeList('타입정의'); %>
+    <% makeList('파일 관리'); %>
     <% makeList('기타'); %>
 </ul>