memi-board 0.9.1 → 0.10.1

package/README.md

@@ -14,7 +14,7 @@ Nuxt 4 + Nuxt UI + Firebase 프로젝트에 **클라이언트 전용 게시판**
 
 | 항목 | 요구 |
 |------|------|
-| 런타임 | Nuxt **4+** (3.x peer 는 허용하나 playground/검증은 4 기준) |
+| 런타임 | Nuxt **4+** |
 | UI | `@nuxt/ui` **4+** (컴포넌트가 `UButton` 등 auto-import 전제) |
 | 데이터 | Firebase **Firestore + Auth + Storage** |
 | Vue | `vue` 3.5+, `vuefire` 3.2+, `firebase` 12+ |
@@ -22,21 +22,20 @@ Nuxt 4 + Nuxt UI + Firebase 프로젝트에 **클라이언트 전용 게시판**
 
 **의도적으로 하지 않는 일:** Firebase 초기화, 라우트/미들웨어 등록, App Check 초기화, 서버 검열.
 
-## 구조 (0.4+)
+## 구조
 
 | 엔트리 | 역할 |
 |--------|------|
-| `memi-board` | **core** — `configureMemiBoard`, composables, types (**Vue 컴포넌트 export 없음**) |
-| `memi-board/nuxt` | **thin Nuxt 모듈** — SFC를 호스트 Vite에 등록 → `MemiBoardList` 등 auto-import |
+| `memi-board` | **Nuxt 모듈** — 설정, SFC auto-import, peer dedupe, `dayjs` 개발 서버 최적화 |
+| `memi-board/runtime` | composables, types, 유틸리티 (**Vue 컴포넌트 export 없음**) |
 
-런타임 설정은 모듈 options가 아니라 호스트 플러그인의 `configureMemiBoard()` 한곳.
+일반 사용자는 `nuxt.config.ts`의 `memiBoard`만 설정한다. 별도 Nuxt 플러그인은 필요 없다.
 
 ```
 호스트 Nuxt 앱
 ├── nuxt-vuefire + firebaseConfig     ← 인증·Firestore
 ├── (선택) App Check 플러그인         ← AI Logic Enforce 시 필수에 가까움
-├── memi-board/nuxt                   ← UI 등록
-├── plugins/memi-board.ts             ← configureMemiBoard
+├── memi-board                        ← Nuxt 모듈 + 런타임 설정
 ├── pages/board/*                     ← 라우트는 호스트 소유
 └── firestore.rules + storage.rules   ← docs 예시 병합 후 배포
 ```
@@ -46,10 +45,10 @@ Nuxt 4 + Nuxt UI + Firebase 프로젝트에 **클라이언트 전용 게시판**
 **사전 준비:** Node + pnpm, Firebase 프로젝트(Firestore·Storage·Auth). 처음부터면 → [docs/firebase-setup.md](docs/firebase-setup.md).
 
 ```bash
-pnpm add memi-board @nuxt/ui nuxt-vuefire vuefire firebase
+pnpm add memi-board @nuxt/ui nuxt-vuefire vuefire firebase dayjs
 ```
 
-`vuefire` / `firebase` / `nuxt-vuefire` 는 **호스트에 직접 설치** — peer 이중 인스턴스가 나면 인증·Firestore가 깨진다.
+`vuefire` / `firebase` / `nuxt-vuefire` / `dayjs`는 **호스트에 직접 설치**한다. TipTap은 `@nuxt/ui`와 `memi-board`가 관리하므로 호스트에서 별도로 설치하거나 버전을 맞출 필요가 없다.
 
 ### 1. modules + vuefire
 
@@ -59,8 +58,21 @@ export default defineNuxtConfig({
   modules: [
     '@nuxt/ui',
     'nuxt-vuefire',
-    'memi-board/nuxt',
+    'memi-board',
   ],
+  memiBoard: {
+    // Firestore: {prefix}Posts, {prefix}Users, {prefix}Settings
+    collectionPrefix: 'board',
+    auth: { providers: ['google', 'apple'] }, // + 'emailPassword'
+    moderation: {
+      enabled: true,
+      model: 'gemini-3.5-flash-lite',
+      onError: 'block', // 'allow' | 'block'
+      moderateImages: false,
+      useLimitedUseAppCheckTokens: false,
+      // localBlocklist: ['금칙어'],
+    },
+  },
   vuefire: {
     // 콘솔 → 프로젝트 설정 → 내 앱 → 웹 앱 SDK snippet 과 동일해야 함
     // (appId 가 다른 웹 앱이면 App Check / AI Logic 이 실패한다)
@@ -74,33 +86,18 @@ export default defineNuxtConfig({
     },
     auth: { enabled: true },
   },
+  routeRules: {
+    // 게시판은 Firebase Auth/Firestore를 사용하는 클라이언트 전용 화면이다.
+    '/board/**': { ssr: false },
+    '/board-settings': { ssr: false },
+    '/board-users': { ssr: false },
+  },
 })
 ```
 
-### 2. configureMemiBoard
-
-```ts
-// app/plugins/memi-board.ts
-import { configureMemiBoard } from 'memi-board'
-
-export default defineNuxtPlugin(() => {
-  configureMemiBoard({
-    // Firestore: {prefix}Posts, {prefix}Users, {prefix}Settings
-    collectionPrefix: 'board',
-    auth: { providers: ['google', 'apple'] }, // + 'emailPassword'
-    moderation: {
-      enabled: true,
-      model: 'gemini-3.5-flash-lite', // 권장. 2.5-flash 는 신규 프로젝트에서 미제공일 수 있음
-      onError: 'block', // 'allow' | 'block' — AI 실패 시 저장 허용/거부 (기본 allow)
-      moderateImages: false,
-      useLimitedUseAppCheckTokens: false, // App Check 세션 토큰으로도 가능
-      // localBlocklist: ['금칙어'],
-    },
-  })
-})
-```
+`memiBoard` 옵션은 Nuxt 모듈이 런타임 플러그인으로 자동 전달한다. `app/plugins/memi-board.ts`를 만들지 않는다.
 
-### 3. Tailwind `@source` (필수)
+### 2. Tailwind `@source` (필수)
 
 패키지 SFC 안의 클래스가 purge되지 않도록:
 
@@ -111,7 +108,7 @@ export default defineNuxtPlugin(() => {
 @source "../../../node_modules/memi-board/dist/runtime/components";
 ```
 
-### 4. Security Rules + 인덱스 배포
+### 3. Security Rules + 인덱스 배포
 
 1. [docs/firestore.rules.example](docs/firestore.rules.example) → 호스트 `firestore.rules`에 병합  
    (`memiBoard*` 이름을 쓰는 `collectionPrefix`에 맞게 치환)
@@ -145,15 +142,29 @@ export default defineNuxtPlugin(() => {
 
 > ⚠️ npm 패키지 tarball에도 `docs/` 가 포함된다(0.4.7+). 구버전이면 GitHub의 `docs/`를 보면 된다.
 
+### 4. 최초 관리자와 카테고리 만들기
+
+Rules는 일반 사용자가 스스로 관리자가 되는 것을 막는다. 따라서 최초 한 번은 다음 순서가 필요하다.
+
+1. 아래 게시판 페이지를 만든 뒤 Google 또는 Apple로 로그인한다.
+2. Firebase Console → Firestore에서 `{prefix}Users/{uid}` 문서를 찾는다.
+3. 해당 문서의 `role`을 문자열 `admin`으로 변경한다.
+   - `collectionPrefix: 'board'`라면 `boardUsers/{uid}`
+   - UID는 Firebase Console → Authentication → Users에서도 확인할 수 있다.
+4. `/board-settings`에서 첫 카테고리를 만든다. 카테고리가 없으면 글을 작성할 수 없다.
+5. 이후 역할 변경은 `/board-users`의 `MemiBoardUsers`에서 처리한다.
+
+> 최초 관리자 지정은 신뢰할 수 있는 프로젝트 운영자가 Firebase Console에서만 수행한다. 클라이언트 코드에 관리자 UID나 우회 규칙을 넣지 않는다.
+
 ## 사용법
 
 라우팅·미들웨어는 **호스트 소유**. 컴포넌트는 모듈 auto-import (`MemiBoardList` 등).  
-`import { MemiBoardEditor } from 'memi-board'` 는 **안 된다** — core 엔트리는 composable/types 만 export.
+`import { MemiBoardEditor } from 'memi-board/runtime'`는 **안 된다**. 컴포넌트는 모듈이 auto-import하고, composable과 type만 `memi-board/runtime`에서 명시적으로 가져올 수 있다.
 
 ```vue
 <!-- app/pages/board/index.vue -->
 <script setup lang="ts">
-import { useMemiBoardAuth } from 'memi-board'
+import { useMemiBoardAuth } from 'memi-board/runtime'
 const { isSignedIn } = useMemiBoardAuth()
 </script>
 
@@ -161,7 +172,10 @@ const { isSignedIn } = useMemiBoardAuth()
   <div>
     <UButton v-if="isSignedIn" to="/board/new" label="새 글쓰기" />
     <!-- 단순: 상세 /board/{id} -->
-    <MemiBoardList post-link-base="/board" />
+    <MemiBoardList
+      post-link-base="/board"
+      introduction="우리 서비스의 소식과 이야기를 나누는 게시판입니다."
+    />
     <!-- 카테고리 path: get-post-link 권장 -->
     <!--
     <MemiBoardList
@@ -205,7 +219,7 @@ export default defineNuxtRouteMiddleware(async () => {
 <script setup lang="ts">
 definePageMeta({ middleware: 'board-auth' })
 const router = useRouter()
-// MemiBoardEditor 는 auto-import (import from 'memi-board' 불필요)
+// MemiBoardEditor 는 auto-import (import from 'memi-board/runtime' 불필요)
 </script>
 
 <template>
@@ -219,6 +233,26 @@ const router = useRouter()
 
 전체 페이지 예시는 `playground/app/pages/board/` 참고.
 
+### 관리 페이지
+
+기본 Rules는 게시판의 `{prefix}Users/{uid}.role == 'admin'`을 검사한다. 컴포넌트도 같은 role을 확인하므로 기본 설치에서는 `authorized`를 전달하지 않는다.
+
+```vue
+<!-- app/pages/board-settings.vue -->
+<template>
+  <MemiBoardSettings />
+</template>
+```
+
+```vue
+<!-- app/pages/board-users.vue -->
+<template>
+  <MemiBoardUsers />
+</template>
+```
+
+호스트의 별도 사이트 관리자 체계를 연동할 때만 `authorized`를 사용할 수 있다. 이 prop은 UI 표시만 허용하며 Firestore Rules를 우회하지 않는다. 이 경우에도 해당 사용자를 게시판 admin으로 등록하거나 호스트 Rules를 같은 관리자 체계에 맞게 수정해야 한다. 관리 URL이 일반 사용자에게 노출되지 않도록 호스트 라우트 가드를 추가하는 것을 권장한다.
+
 ### 제공하는 API
 
 **컴포넌트 (auto-import):**  
@@ -230,7 +264,9 @@ const router = useRouter()
 본문은 Nuxt UI **`UEditor`**(TipTap, `content-type="html"`). 호스트 `@nuxt/ui` 4.x 에 Editor 포함 필요.
 
 **에디터 이미지:** 툴바 / 붙여넣기 / 드롭 → Firebase Storage  
-`{prefix}/posts/{postId}/images/*` + `.../images/thumbnails/*` (원본+썸네일).  
+`{prefix}/posts/{postId}/images/*` + `.../images/thumbnails/*` (최적화 이미지+썸네일).
+
+본문 이미지는 휴대폰 원본 기준 최대 25MB까지 선택할 수 있다. 5MB를 넘으면 브라우저에서 최대 2560px·JPEG 85%로 최적화하고, 결과가 여전히 5MB를 넘으면 2048px·75%로 한 번 더 줄인 뒤 업로드한다. 5MB 이하 이미지는 원본을 유지한다.
 본문 HTML에는 원본 URL. 수정 중 버려진 파일은 호스트 스케줄러로 정리 (`extractEditorImageUrls` 로 본문 참조 비교).
 
 **composables:**  
@@ -323,13 +359,16 @@ export default defineNuxtPlugin(() => {
 ## 다른 프로젝트에 붙일 때 체크리스트
 
 - [ ] 동일 스택: Nuxt 4 + `@nuxt/ui` 4 + `nuxt-vuefire` + Firebase
-- [ ] `pnpm add memi-board` 및 peer 직접 설치
-- [ ] `modules`에 `memi-board/nuxt`
-- [ ] `configureMemiBoard` 플러그인 (`collectionPrefix` 충돌 없게)
+- [ ] `pnpm add memi-board @nuxt/ui nuxt-vuefire vuefire firebase dayjs`
+- [ ] `modules`에 `@nuxt/ui`, `nuxt-vuefire`, `memi-board`
+- [ ] 게시판·관리 경로에 `ssr: false`
+- [ ] `nuxt.config.ts`의 `memiBoard` 설정 (`collectionPrefix` 충돌 없게)
 - [ ] CSS `@source` …/memi-board/dist/runtime/components
 - [ ] Rules 예시 병합 + **deploy**
 - [ ] 카테고리 필터 사용 시 indexes deploy
 - [ ] 페이지·미들웨어 직접 작성 (또는 playground 복사)
+- [ ] 최초 로그인 후 Firebase Console에서 `{prefix}Users/{uid}.role = 'admin'`
+- [ ] 설정 페이지에서 첫 카테고리 생성
 - [ ] (검열) AI Logic 활성화 + 권장 모델 + App Check
 - [ ] `pnpm why vuefire` 로 이중 인스턴스 없는지 확인
 
@@ -351,7 +390,25 @@ App Check 토큰, `appId` 일치, 모델명(3.x), AI Logic 활성화, 네트워
 
 ### monorepo `link:` / `file:` 로 개발할 때
 
-패키지 쪽 `node_modules`의 vuefire가 잡히면 이중 인스턴스. 호스트에서 `vite.resolve.dedupe` + 필요 시 alias/optimizeDeps. 배포 전에는 **npm 버전**으로 설치하는 것을 권장.
+링크하기 전에 패키지 의존성과 `dist`를 준비한다.
+
+```bash
+# memi-board 저장소
+pnpm install
+pnpm build
+
+# 호스트 저장소
+pnpm add link:../memi-board
+```
+
+`src/components` 수정은 Nuxt 모듈이 링크 소스를 직접 읽으므로 즉시 반영된다. `src/module.ts` 또는 core composable을 수정하면 `pnpm build`를 다시 실행하고 호스트 개발 서버를 재시작한다. 모듈이 Vue·Vue Router·VueFire·Firebase·TipTap dedupe와 `dayjs` 최적화를 자동 적용한다. 배포 전에는 의존성을 **npm 버전**으로 되돌린다.
+
+링크 상태에서 새 Tailwind 클래스를 바로 시험하려면 호스트 CSS에 소스 경로를 하나 더 둔다.
+
+```css
+@source "../../../node_modules/memi-board/src/components";
+@source "../../../node_modules/memi-board/dist/runtime/components";
+```
 
 ## 로컬 개발 (이 리포)
 
@@ -370,6 +427,16 @@ firebase emulators:start --project demo-memi-board
 NUXT_PUBLIC_USE_EMULATORS=1 pnpm dev
 ```
 
+## npm 배포
+
+npm의 6자리 OTP를 인자로 전달하면 빌드, 타입 검사, 패키지 dry-run을 모두 통과한 뒤에만 배포한다.
+
+```bash
+pnpm release 123456
+```
+
+`pnpm publish 123456`은 pnpm이 `123456`을 OTP가 아닌 폴더 경로로 해석하므로 사용하지 않는다.
+
 ## 버전 · 라이선스
 
 - UI: `<MemiBoardVersionHistory />`

package/dist/composables/useMemiBoardAuth.d.ts

@@ -22,6 +22,7 @@ export interface UseMemiBoardAuthReturn {
     signOut: () => Promise<void>;
     canEdit: (post: Pick<PostModel, 'authorUid'>) => boolean;
     canDelete: (post: Pick<PostModel, 'authorUid'>) => boolean;
+    canEditComment: (comment: Pick<CommentModel, 'authorUid'>) => boolean;
     canDeleteComment: (comment: Pick<CommentModel, 'authorUid'>) => boolean;
     /** 콘텐츠 검열 차단 1회 기록 후 메시지 조각 반환 */
     recordContentModerationBlock: () => Promise<{

package/dist/composables/useMemiBoardComments.d.ts

@@ -9,6 +9,7 @@ export interface AddCommentInput {
 export interface AddReplyInput extends AddCommentInput {
     parent: CommentModel;
 }
+export declare const COMMENT_BODY_MAX_LENGTH = 1000;
 /** 10개씩 순차 조회한 뒤 마지막 페이지에서만 최신 1개를 실시간 구독한다. */
 export declare function useMemiBoardComments(postId: string | Ref<string>, options?: {
     subscribe?: boolean;
@@ -20,6 +21,8 @@ export declare function useMemiBoardComments(postId: string | Ref<string>, optio
     loadMore: () => Promise<void>;
     addComment: (input: AddCommentInput) => Promise<void>;
     addReply: (input: AddReplyInput) => Promise<void>;
+    updateComment: (commentId: string, body: string) => Promise<void>;
+    setCommentBlinded: (commentId: string, isBlinded: boolean, moderatorUid: string) => Promise<void>;
     deleteComment: (comment: CommentModel) => Promise<void>;
 };
 /** 펼친 스레드의 답글을 5개씩 일회성 조회한다. */
@@ -46,6 +49,36 @@ export declare function useMemiBoardReplies(postId: string, rootId: string): {
             };
             valueOf: () => string;
         };
+        updatedAt?: {
+            readonly seconds: number;
+            readonly nanoseconds: number;
+            toDate: () => Date;
+            toMillis: () => number;
+            isEqual: (other: import('firebase/firestore').Timestamp) => boolean;
+            toString: () => string;
+            toJSON: () => {
+                seconds: number;
+                nanoseconds: number;
+                type: string;
+            };
+            valueOf: () => string;
+        } | undefined;
+        isBlinded?: boolean | undefined;
+        moderatedAt?: {
+            readonly seconds: number;
+            readonly nanoseconds: number;
+            toDate: () => Date;
+            toMillis: () => number;
+            isEqual: (other: import('firebase/firestore').Timestamp) => boolean;
+            toString: () => string;
+            toJSON: () => {
+                seconds: number;
+                nanoseconds: number;
+                type: string;
+            };
+            valueOf: () => string;
+        } | undefined;
+        moderatedBy?: string | undefined;
         parentId?: string | null | undefined;
         rootId?: string | undefined;
         depth?: number | undefined;
@@ -75,6 +108,36 @@ export declare function useMemiBoardReplies(postId: string, rootId: string): {
             };
             valueOf: () => string;
         };
+        updatedAt?: {
+            readonly seconds: number;
+            readonly nanoseconds: number;
+            toDate: () => Date;
+            toMillis: () => number;
+            isEqual: (other: import('firebase/firestore').Timestamp) => boolean;
+            toString: () => string;
+            toJSON: () => {
+                seconds: number;
+                nanoseconds: number;
+                type: string;
+            };
+            valueOf: () => string;
+        } | undefined;
+        isBlinded?: boolean | undefined;
+        moderatedAt?: {
+            readonly seconds: number;
+            readonly nanoseconds: number;
+            toDate: () => Date;
+            toMillis: () => number;
+            isEqual: (other: import('firebase/firestore').Timestamp) => boolean;
+            toString: () => string;
+            toJSON: () => {
+                seconds: number;
+                nanoseconds: number;
+                type: string;
+            };
+            valueOf: () => string;
+        } | undefined;
+        moderatedBy?: string | undefined;
         parentId?: string | null | undefined;
         rootId?: string | undefined;
         depth?: number | undefined;

package/dist/composables/useMemiBoardStorage.d.ts

@@ -1,6 +1,8 @@
 import { Attachment, EditorImageEntry } from '../types';
 /** 에디터 이미지 최대 크기 (바이트) */
 export declare const EDITOR_IMAGE_MAX_BYTES: number;
+/** 휴대폰 원본 이미지 선택 허용 크기. 큰 이미지는 업로드 전에 최적화한다. */
+export declare const EDITOR_IMAGE_SOURCE_MAX_BYTES: number;
 export declare function useMemiBoardStorage(): {
     uploadAttachment: (file: File, postId: string, onProgress?: (ratio: number) => void) => {
         promise: Promise<Attachment>;

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-/** Core API — composables / config / types only. UI SFC 는 memi-board/nuxt 모듈이 등록. */
+/** Runtime API — composables / config / types only. UI SFC는 루트 Nuxt 모듈이 등록. */
 export { configureMemiBoard, useMemiBoardConfig } from './config';
 export type { MemiBoardConfig, MemiBoardAuthOptions, MemiBoardModerationOptions } from './config';
 export { useMemiBoardAuth } from './composables/useMemiBoardAuth';
 export { useMemiBoardPosts } from './composables/useMemiBoardPosts';
 export type { CreatePostInput, UpdatePostInput } from './composables/useMemiBoardPosts';
-export { useMemiBoardComments, useMemiBoardReplies } from './composables/useMemiBoardComments';
+export { COMMENT_BODY_MAX_LENGTH, useMemiBoardComments, useMemiBoardReplies } from './composables/useMemiBoardComments';
 export type { AddCommentInput, AddReplyInput } from './composables/useMemiBoardComments';
 export { useMemiBoardModeration } from './composables/useMemiBoardModeration';
 export { useMemiBoardStorage } from './composables/useMemiBoardStorage';
@@ -12,7 +12,7 @@ export { useMemiBoardSettings, DEFAULT_CATEGORIES } from './composables/useMemiB
 export { useMemiBoardUsers, BOARD_USER_ROLES } from './composables/useMemiBoardUsers';
 export { versionHistory } from './data/versionHistory';
 export type { VersionHistoryEntry } from './data/versionHistory';
-export { formatDate } from './utils/formatDate';
+export { formatDate, formatFullDate, formatRelativeDate, formatTimestampDetails } from './utils/formatDate';
 export { slugify } from './utils/slugify';
 export { DEFAULT_BLOCK_BAN_THRESHOLD, DEFAULT_BLOCK_BAN_DECAY_MS, effectiveModerationBlockCount, isModerationWriteRestricted, moderationWriteRestrictedUntilMs, formatRestrictedUntilLabel, } from './utils/moderation-strike';
 export type { Attachment, EditorImageEntry, ModerationStatus, PostModel, PostDetail, CommentModel, BoardUserRole, BoardUserModel, BoardCategory, BoardListView, BoardWriteRole, BoardSettingsModel, ModerationResult, } from './types';
@@ -20,4 +20,4 @@ export { compressImage } from './utils/compressImage';
 export { extractEditorImageUrls } from './utils/extractEditorImageUrls';
 export { renderMarkdownToHtml } from './utils/renderMarkdown';
 export { storagePathFromDownloadUrl, postNamespaceFromStoragePath } from './utils/storagePath';
-export { EDITOR_IMAGE_MAX_BYTES } from './composables/useMemiBoardStorage';
+export { EDITOR_IMAGE_MAX_BYTES, EDITOR_IMAGE_SOURCE_MAX_BYTES } from './composables/useMemiBoardStorage';