From ae79a101a21f0e1227617f34e5876c5bff00e46e Mon Sep 17 00:00:00 2001
From: Wisesaturn <rfv1479@gmail.com>
Date: Sun, 27 Sep 2026 18:10:15 +0900
Subject: [PATCH 1/3] =?UTF-8?q?fix/#131:=20=EC=A0=9C=EB=AA=A9=EC=97=90=20?=
 =?UTF-8?q?=EA=B4=84=ED=98=B8=EA=B0=80=20=EB=93=A0=20=EA=B8=80=EC=9D=98=20?=
 =?UTF-8?q?=EC=9D=B4=EB=AF=B8=EC=A7=80=EA=B0=80=20=EB=B0=9C=ED=96=89=20?=
 =?UTF-8?q?=EB=95=8C=EB=A7=88=EB=8B=A4=20=EC=A7=80=EC=9B=8C=EC=A7=80?=
 =?UTF-8?q?=EB=8D=98=20=EB=AC=B8=EC=A0=9C=20=EC=88=98=EC=A0=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 📋 작업 내역

  - `features/publish/lib/toSafePathSegment.ts` 추가
    - NFC 정규화 후 문자와 숫자, `-`, `_` 이외의 문자를 `-` 로 바꾸고 이어진 `-` 를 하나로 합친다
  - `features/publish/lib/getStorageFolder.ts` 추가
    - `collection/category/title` 의 각 조각을 `toSafePathSegment` 로 정리해 폴더 경로를 만든다
  - `uploadImage.ts` 와 `deleteStore.ts` 가 `getStorageFolder` 로 같은 폴더를 만든다
  - `toStorageFileName.ts` 의 정리 단계를 `toSafePathSegment` 로 바꿨다
  - spec: `toSafePathSegment` 7건, `getStorageFolder` 3건. 올린 파일의 주소에서 `getStoragePaths` 가 꺼낸 경로가 실제 경로와 같은지 확인한다

- 💡 설계 이유

  - #129 는 파일 이름만 정리했다. 폴더 이름(`title`)은 `spaceToDash` 로 공백만 바뀌어 괄호가 남고, `getStoragePaths` 가 `)` 에서 폴더째 잘라 그 글의 썸네일과 본문 이미지가 발행할 때마다 모두 지워졌다. 운영의 `쌩 npm으로 MFE 구축하기 (1) : 개념` 썸네일이 404 인 것을 확인했다
  - 라우트가 넘기는 `title` 은 Firestore 문서 id 로도 쓰여 바꿀 수 없다. 그래서 Storage 경로를 만드는 곳에서만 정리하고, 올리는 쪽과 지우는 쪽이 어긋나지 않게 한 함수를 함께 쓴다
  - 파일 이름과 폴더 이름이 같은 규칙을 쓰도록 #129 의 치환을 `toSafePathSegment` 로 떼었다. 제목은 공백이 이미 `-` 로 바뀌어 있어 `-(1)-:-` 가 `---` 처럼 이어지므로 연속된 `-` 를 합친다
  - 괄호가 든 옛 폴더는 `deleteStore` 가 새 폴더만 보므로 남는다. 사용자와 확인해 이 이슈 범위에서 뺐다
---
 src/features/publish/api/deleteStore.ts       |  4 ++-
 src/features/publish/api/uploadImage.ts       |  7 ++--
 .../publish/lib/getStorageFolder.spec.ts      | 35 +++++++++++++++++++
 src/features/publish/lib/getStorageFolder.ts  | 17 +++++++++
 .../publish/lib/toSafePathSegment.spec.ts     | 34 ++++++++++++++++++
 src/features/publish/lib/toSafePathSegment.ts | 22 ++++++++++++
 src/features/publish/lib/toStorageFileName.ts |  9 +++--
 7 files changed, 118 insertions(+), 10 deletions(-)
 create mode 100644 src/features/publish/lib/getStorageFolder.spec.ts
 create mode 100644 src/features/publish/lib/getStorageFolder.ts
 create mode 100644 src/features/publish/lib/toSafePathSegment.spec.ts
 create mode 100644 src/features/publish/lib/toSafePathSegment.ts

diff --git a/src/features/publish/api/deleteStore.ts b/src/features/publish/api/deleteStore.ts
index b15f9a7..bc9aef9 100644
--- a/src/features/publish/api/deleteStore.ts
+++ b/src/features/publish/api/deleteStore.ts
@@ -4,6 +4,8 @@ import Logger from '@/commons/lib/logger';
 import { storage } from '@/commons/api/firebase.server';
 import { IFireStore } from '@/commons/types/global';
 
+import getStorageFolder from '../lib/getStorageFolder';
+
 interface Props extends IFireStore {
   /** 지우지 않을 파일의 Storage 경로. 방금 저장한 문서가 가리키는 파일이다 (`getStoragePaths`) */
   keep: Set<string>;
@@ -17,7 +19,7 @@ interface Props extends IFireStore {
  */
 export default async function deleteStore(props: Props): Promise<void> {
   const { category, title, collection, keep } = props;
-  const folder = `${collection}/${category}/${title}`;
+  const folder = getStorageFolder({ collection, category, title });
 
   try {
     const res = await listAll(ref(storage, folder));
diff --git a/src/features/publish/api/uploadImage.ts b/src/features/publish/api/uploadImage.ts
index 207967b..88390ac 100644
--- a/src/features/publish/api/uploadImage.ts
+++ b/src/features/publish/api/uploadImage.ts
@@ -5,6 +5,7 @@ import Logger from '@/commons/lib/logger';
 import { storage } from '@/commons/api/firebase.server';
 import { IFireStore } from '@/commons/types/global';
 
+import getStorageFolder from '../lib/getStorageFolder';
 import toStorageFileName from '../lib/toStorageFileName';
 
 interface Props extends IFireStore {
@@ -63,10 +64,8 @@ export default async function uploadImage(props: Props): Promise<string> {
   // 유닉스 타임
   const hashTime = new Date().getTime();
 
-  const collectionRef = ref(
-    storage,
-    `${collection}/${category}/${title}/${filename}-${hashTime}.${formatExt}`,
-  );
+  const folder = getStorageFolder({ collection, category, title });
+  const collectionRef = ref(storage, `${folder}/${filename}-${hashTime}.${formatExt}`);
 
   // firebase에 올린 파일 주소 얻기
   const imgFirebaseUrl = await uploadBytes(collectionRef, data, metadata).then(async () => {
diff --git a/src/features/publish/lib/getStorageFolder.spec.ts b/src/features/publish/lib/getStorageFolder.spec.ts
new file mode 100644
index 0000000..4e1de75
--- /dev/null
+++ b/src/features/publish/lib/getStorageFolder.spec.ts
@@ -0,0 +1,35 @@
+/**
+ * `getStorageFolder` 는 `uploadImage` 가 이미지를 올리고 `deleteStore` 가 옛 파일을 지우는 폴더를 정한다.
+ *
+ * 제목에 괄호가 들어간 글은 폴더 이름에 괄호가 남아, 발행할 때마다 그 글의 썸네일과 본문 이미지가 모두 지워졌다 (#131).
+ * 올린 파일의 주소에서 `getStoragePaths` 가 꺼낸 경로가 실제 경로와 같아야 `deleteStore` 가 새 파일을 남긴다.
+ */
+import { describe, expect, it } from 'vitest';
+
+import getStorageFolder from './getStorageFolder';
+import getStoragePaths from './getStoragePaths';
+
+const MFE = {
+  collection: 'post',
+  category: 'frontend',
+  title: '쌩-npm으로-MFE-구축하기-(1)-:-개념',
+};
+
+describe('getStorageFolder 는 collection/category/title 폴더 경로를 만든다', () => {
+  it('제목의 괄호와 콜론을 - 로 바꾼다', () => {
+    expect(getStorageFolder(MFE)).toBe('post/frontend/쌩-npm으로-MFE-구축하기-1-개념');
+  });
+
+  it('안전한 제목은 그대로 쓴다', () => {
+    expect(
+      getStorageFolder({ collection: 'project', category: 'team-projects', title: '유클러버스' }),
+    ).toBe('project/team-projects/유클러버스');
+  });
+
+  it('올린 파일의 주소에서 꺼낸 경로가 실제 경로와 같다', () => {
+    const fullPath = `${getStorageFolder(MFE)}/thumbnail-mfe-1790488653891.webp`;
+    const url = `https://storage.googleapis.com/jaehan-flow.appspot.com/${encodeURIComponent(fullPath)}`;
+
+    expect(getStoragePaths(url)).toEqual(new Set([fullPath]));
+  });
+});
diff --git a/src/features/publish/lib/getStorageFolder.ts b/src/features/publish/lib/getStorageFolder.ts
new file mode 100644
index 0000000..3045384
--- /dev/null
+++ b/src/features/publish/lib/getStorageFolder.ts
@@ -0,0 +1,17 @@
+import { type IFireStore } from '@/commons/types/global';
+
+import toSafePathSegment from './toSafePathSegment';
+
+/**
+ * @description 문서의 이미지를 올리고 지우는 Storage 폴더 경로를 만든다.
+ * `uploadImage` 와 `deleteStore` 가 같이 쓴다. 둘이 다른 폴더를 보면 새 파일이 옛 파일로 지워지거나 옛 파일이 남는다.
+ * `title` 은 Firestore 문서 id 로도 쓰는 값이라 그대로 받고, Storage 경로에서만 정리한다 (#131)
+ * @param props 컬렉션, 카테고리, `spaceToDash` 를 적용한 제목
+ * @returns `collection/category/title` 형식의 폴더 경로
+ * @example
+ * getStorageFolder({ collection: 'post', category: 'frontend', title: '쌩-npm으로-MFE-구축하기-(1)-:-개념' });
+ * // 'post/frontend/쌩-npm으로-MFE-구축하기-1-개념'
+ */
+export default function getStorageFolder({ collection, category, title }: IFireStore): string {
+  return [collection, category, title].map(toSafePathSegment).join('/');
+}
diff --git a/src/features/publish/lib/toSafePathSegment.spec.ts b/src/features/publish/lib/toSafePathSegment.spec.ts
new file mode 100644
index 0000000..8dd5735
--- /dev/null
+++ b/src/features/publish/lib/toSafePathSegment.spec.ts
@@ -0,0 +1,34 @@
+/**
+ * `toSafePathSegment` 는 Storage 경로의 폴더 이름과 파일 이름을 정리하는 규칙 하나다.
+ *
+ * 여기서 괄호 같은 문자가 남으면 `getStoragePaths` 가 주소에서 경로를 잘못 잘라, 발행 직후 방금 올린
+ * 이미지를 옛 파일로 보고 지운다. 응답은 200 이고 이미지만 깨지므로 조용히 실패한다 (#129, #131).
+ */
+import { describe, expect, it } from 'vitest';
+
+import toSafePathSegment from './toSafePathSegment';
+
+describe('toSafePathSegment 는 경로 조각에 문자, 숫자, -, _ 만 남긴다', () => {
+  it.each([
+    ['괄호', 'team_(1)', 'team_-1-'],
+    ['콜론', 'a:b', 'a-b'],
+    ['공백', 'a b', 'a-b'],
+    ['슬래시', 'a/b', 'a-b'],
+  ])('%s 를 - 로 바꾼다', (_name, input, expected) => {
+    expect(toSafePathSegment(input)).toBe(expected);
+  });
+
+  it('바꾼 뒤 이어진 - 는 하나로 합친다', () => {
+    expect(toSafePathSegment('쌩-npm으로-MFE-구축하기-(1)-:-개념')).toBe(
+      '쌩-npm으로-MFE-구축하기-1-개념',
+    );
+  });
+
+  it('이미 안전한 조각은 그대로 둔다', () => {
+    expect(toSafePathSegment('함수-타입-선언하기')).toBe('함수-타입-선언하기');
+  });
+
+  it('자모가 나뉜 한글도 합쳐서 그대로 둔다', () => {
+    expect(toSafePathSegment('유클러버스'.normalize('NFD'))).toBe('유클러버스');
+  });
+});
diff --git a/src/features/publish/lib/toSafePathSegment.ts b/src/features/publish/lib/toSafePathSegment.ts
new file mode 100644
index 0000000..69daf4f
--- /dev/null
+++ b/src/features/publish/lib/toSafePathSegment.ts
@@ -0,0 +1,22 @@
+/** 경로 조각에 남길 문자. 이 밖의 문자가 이어지면 `-` 하나로 바꾼다 */
+const UNSAFE_CHARS_PATTERN = /[^\p{L}\p{N}_-]+/gu;
+
+/**
+ * @description Storage 경로 조각(폴더 이름, 파일 이름)에서 문자, 숫자, `-`, `_` 만 남기고 나머지를 `-` 로 바꾼다.
+ * 괄호처럼 `encodeURIComponent` 가 인코딩하지 않는 문자가 주소에 남으면 `getStoragePaths` 가
+ * 경로를 잘못 잘라, 방금 올린 파일이 옛 파일로 분류되어 지워진다 (#129, #131)
+ * @param name 경로 조각 하나. `/` 가 들어 있으면 `-` 로 바뀐다
+ * @returns 주소와 Storage 경로에서 모양이 같은 경로 조각
+ * @example
+ * toSafePathSegment('쌩-npm으로-MFE-구축하기-(1)-:-개념'); // '쌩-npm으로-MFE-구축하기-1-개념'
+ */
+export default function toSafePathSegment(name: string): string {
+  // 자모가 나뉜(NFD) 이름은 결합 문자가 `-` 로 바뀌지 않게 먼저 합친다
+  return (
+    name
+      .normalize('NFC')
+      .replace(UNSAFE_CHARS_PATTERN, '-')
+      // 공백을 `-` 로 바꾼 제목(`-(1)-:-`)에서 `-` 가 여럿 이어지지 않게 합친다
+      .replace(/-{2,}/g, '-')
+  );
+}
diff --git a/src/features/publish/lib/toStorageFileName.ts b/src/features/publish/lib/toStorageFileName.ts
index 163f2e5..07b52a7 100644
--- a/src/features/publish/lib/toStorageFileName.ts
+++ b/src/features/publish/lib/toStorageFileName.ts
@@ -1,5 +1,4 @@
-/** 파일 이름에 남길 문자. 이 밖의 문자가 이어지면 `-` 하나로 바꾼다 */
-const UNSAFE_CHARS_PATTERN = /[^\p{L}\p{N}_-]+/gu;
+import toSafePathSegment from './toSafePathSegment';
 
 /**
  * @description 이미지 주소에서 Storage 에 올릴 파일 이름을 만든다.
@@ -18,9 +17,9 @@ export default function toStorageFileName(src: string): string {
   // 2. 첫 `.` 앞까지만 남겨 확장자를 뗀다
   const basename = lastSegment.split('.')[0];
 
-  // 3. 퍼센트 인코딩을 풀고, 자모가 나뉜(NFD) 이름은 결합 문자가 `-` 로 바뀌지 않게 먼저 합친다
-  const decoded = decodeURIComponent(basename).normalize('NFC');
+  // 3. 퍼센트 인코딩을 푼다
+  const decoded = decodeURIComponent(basename);
 
   // 4. 문자, 숫자, `-`, `_` 이외의 문자를 `-` 로 바꾼다
-  return decoded.replace(UNSAFE_CHARS_PATTERN, '-');
+  return toSafePathSegment(decoded);
 }

From 939fa9798959e4d88d1cf3ac74ab7eb0ae6038cf Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Sun, 27 Sep 2026 09:10:50 +0000
Subject: [PATCH 2/3] chore/#132: bump version to 3.0.4

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index d3d908e..d7d1d26 100644
--- a/package.json
+++ b/package.json
@@ -4,7 +4,7 @@
   "private": true,
   "sideEffects": true,
   "type": "module",
-  "version": "3.0.3",
+  "version": "3.0.4",
   "packageManager": "pnpm@9.15.0",
   "keywords": [
     "react-router",

From be4b29168487a9c60a287d794eb801f241c37eed Mon Sep 17 00:00:00 2001
From: Wisesaturn <rfv1479@gmail.com>
Date: Sun, 27 Sep 2026 18:14:44 +0900
Subject: [PATCH 3/3] =?UTF-8?q?docs/#131:=20uploadImage=20JSDoc=20?=
 =?UTF-8?q?=EC=9D=84=20@description=20=EC=9C=BC=EB=A1=9C=20=EB=B0=94?=
 =?UTF-8?q?=EA=BF=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 📋 작업 내역

  - `features/publish/api/uploadImage.ts` 의 `@summary` 를 `@description` 으로 바꾸고, 비어 있던 `@param`, `@returns` 를 채우고 `@throws` 를 추가

- 💡 설계 이유

  - PR #132 코드 리뷰에서 나온 P4. `jsdoc.md` 는 기존 파일을 고칠 때 그 파일의 `@summary` 를 함께 바꾸라고 한다
  - 주소가 비었거나 이미지가 아닌 응답이면 에러를 던지므로 `jsdoc.md` 에 따라 `@throws` 를 적었다
---
 src/features/publish/api/uploadImage.ts | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/features/publish/api/uploadImage.ts b/src/features/publish/api/uploadImage.ts
index 88390ac..2b481ee 100644
--- a/src/features/publish/api/uploadImage.ts
+++ b/src/features/publish/api/uploadImage.ts
@@ -13,9 +13,10 @@ interface Props extends IFireStore {
 }
 
 /**
- * @summary firebase에 image를 업로드하는 함수
- * @param props
- * @returns
+ * @description 원본 이미지를 받아 webp(gif 는 그대로)로 바꾸고 Firebase Storage 의 문서 폴더에 올린다
+ * @param props 원본 이미지 주소와 문서 폴더(collection/category/title)
+ * @returns 올린 파일의 GCP 공개 주소
+ * @throws 주소가 비었거나 이미지가 아닌 응답을 받으면 에러
  */
 export default async function uploadImage(props: Props): Promise<string> {
   const { src, collection, category, title } = props;