memi-board 0.4.6 → 0.4.13

package/dist/runtime/components/Editor.vue

@@ -1,56 +1,191 @@
 <script setup lang="ts">
+/**
+ * 글쓰기 폼 — Nuxt UI UEditor + shineb PostEditor 패턴.
+ * @see https://ui.nuxt.com/docs/components/editor
+ * @see shineb app/components/PostEditor.vue
+ *
+ * 커스텀은 handlers.image(파일 업로드) + DOM paste/drop 만.
+ * TipTap Extension / PluginKey 는 쓰지 않음 (유지보수·충돌 회피).
+ */
 import { ref, computed, watch } from 'vue'
-import type { Attachment } from 'memi-board'
-import { useMemiBoardAuth } from 'memi-board'
-import { useMemiBoardPosts } from 'memi-board'
-import { useMemiBoardModeration } from 'memi-board'
-import { useMemiBoardSettings } from 'memi-board'
+import type { Attachment, EditorImageEntry } from 'memi-board'
+import {
+  useMemiBoardAuth,
+  useMemiBoardPosts,
+  useMemiBoardModeration,
+  useMemiBoardSettings,
+  useMemiBoardStorage,
+  EDITOR_IMAGE_MAX_BYTES,
+} from 'memi-board'
 import MemiBoardAttachments from './Attachments.vue'
 
 const props = defineProps<{
-  /** 지정하면 수정 모드 */
   postId?: string
-  /**
-   * path 등으로 카테고리가 이미 정해진 경우 (예: /board/:category/new).
-   * 설정되면 선택 UI 없이 이 값으로 저장한다.
-   */
   fixedCategory?: string
 }>()
 
 const emit = defineEmits<{ saved: [id: string], cancel: [] }>()
 
-const { user, isSignedIn } = useMemiBoardAuth()
+const { user, isSignedIn, isWriteRestricted, restrictedMessage } = useMemiBoardAuth()
 const { getPost, createPost, updatePost } = useMemiBoardPosts()
 const { checkText } = useMemiBoardModeration()
 const { categories, categoryLabel, ensureSettings, addCategory } = useMemiBoardSettings()
+const { uploadEditorImage } = useMemiBoardStorage()
 
 const title = ref('')
+/** UEditor content-type=html (shineb 와 동일) */
 const content = ref('')
 const tagsInput = ref('')
-/** boardSettings.categories 의 id (fixedCategory 없을 때만 선택) */
 const category = ref<string | undefined>(undefined)
 const attachments = ref<Attachment[]>([])
 
 const categoryItems = computed(() =>
   categories.value.map(c => ({ label: c.label, value: c.id })),
 )
-
-/** 실제 저장에 쓰는 카테고리 id */
 const effectiveCategory = computed(() => props.fixedCategory || category.value)
-
 const isEdit = computed(() => Boolean(props.postId))
 const categoryLocked = computed(() => Boolean(props.fixedCategory))
+
 const loading = ref(false)
 const saving = ref(false)
-/** 제출 중 안내 (검토 → 저장) */
 const submitHint = ref('')
 const error = ref('')
+const imageUploading = ref(false)
+const imageUploadError = ref('')
 
 const showAddCategory = ref(false)
 const newCategoryLabel = ref('')
 const addingCategory = ref(false)
 
 const attachmentNamespace = ref(props.postId ?? `new-${Date.now()}`)
+const uploadedEditorImages = ref<EditorImageEntry[]>([])
+const editorRef = ref<{ editor?: unknown } | null>(null)
+
+function imageNamespace(): string {
+  return props.postId || attachmentNamespace.value
+}
+
+async function doUploadImage(file: File): Promise<EditorImageEntry> {
+  if (!file.type.startsWith('image/')) {
+    throw new Error('이미지 파일만 업로드할 수 있습니다.')
+  }
+  if (file.size > EDITOR_IMAGE_MAX_BYTES) {
+    throw new Error(`이미지는 ${EDITOR_IMAGE_MAX_BYTES / 1024 / 1024}MB 이하여야 합니다.`)
+  }
+  const entry = await uploadEditorImage(file, imageNamespace())
+  uploadedEditorImages.value.push(entry)
+  return entry
+}
+
+async function uploadAndSetImage(editor: any, file: File) {
+  imageUploading.value = true
+  imageUploadError.value = ''
+  try {
+    const entry = await doUploadImage(file)
+    editor.chain().focus().setImage({ src: entry.originalUrl }).run()
+  }
+  catch (e) {
+    imageUploadError.value = (e as Error).message || '이미지 업로드에 실패했습니다.'
+  }
+  finally {
+    imageUploading.value = false
+  }
+}
+
+function pickAndUploadImage(editor: any) {
+  const input = document.createElement('input')
+  input.type = 'file'
+  input.accept = 'image/*'
+  input.onchange = () => {
+    const file = input.files?.[0]
+    if (file) void uploadAndSetImage(editor, file)
+  }
+  input.click()
+}
+
+/** 공식 handlers API — 기본 image(URL prompt) 를 파일 업로드로 교체 (shineb) */
+const handlers = {
+  image: {
+    canExecute: (editor: any) => editor.can().setImage({ src: '' }),
+    isActive: (editor: any) => editor.isActive('image'),
+    isDisabled: (editor: any) =>
+      !editor.extensionManager?.extensions?.some((ext: any) => ext.name === 'image'),
+    execute: (editor: any) => {
+      pickAndUploadImage(editor)
+      return editor.chain()
+    },
+  },
+}
+
+const toolbarItems = [
+  [
+    { kind: 'heading', level: 1, icon: 'i-lucide-heading-1' },
+    { kind: 'heading', level: 2, icon: 'i-lucide-heading-2' },
+    { kind: 'heading', level: 3, icon: 'i-lucide-heading-3' },
+  ],
+  [
+    { kind: 'mark', mark: 'bold', icon: 'i-lucide-bold' },
+    { kind: 'mark', mark: 'italic', icon: 'i-lucide-italic' },
+    { kind: 'mark', mark: 'underline', icon: 'i-lucide-underline' },
+    { kind: 'mark', mark: 'strike', icon: 'i-lucide-strikethrough' },
+    { kind: 'mark', mark: 'code', icon: 'i-lucide-code' },
+  ],
+  [
+    { kind: 'bulletList', icon: 'i-lucide-list' },
+    { kind: 'orderedList', icon: 'i-lucide-list-ordered' },
+    { kind: 'blockquote', icon: 'i-lucide-quote' },
+    { kind: 'codeBlock', icon: 'i-lucide-square-code' },
+  ],
+  [
+    { kind: 'link', icon: 'i-lucide-link' },
+    { kind: 'image', icon: 'i-lucide-image' },
+  ],
+  [
+    { kind: 'horizontalRule', icon: 'i-lucide-minus' },
+    { kind: 'undo', icon: 'i-lucide-undo-2' },
+    { kind: 'redo', icon: 'i-lucide-redo-2' },
+    { kind: 'clearFormatting', icon: 'i-lucide-remove-formatting' },
+  ],
+] as const
+
+function isContentEmpty(html: string): boolean {
+  const plain = html
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+  return !plain
+}
+
+function resolveEditor(): any | null {
+  const ed = (editorRef.value as any)?.editor
+  return ed?.value ?? ed ?? null
+}
+
+/** 앱 레벨 paste/drop (TipTap Extension 아님 — shineb 툴바 업로드와 동일 업로드 경로) */
+function onEditorRootPaste(e: ClipboardEvent) {
+  const items = Array.from(e.clipboardData?.items ?? [])
+  const imageItem = items.find(i => i.type.startsWith('image/'))
+  if (!imageItem) return
+  const file = imageItem.getAsFile()
+  const editor = resolveEditor()
+  if (!file || !editor) return
+  e.preventDefault()
+  void uploadAndSetImage(editor, file)
+}
+
+function onEditorRootDrop(e: DragEvent) {
+  const files = Array.from(e.dataTransfer?.files ?? [])
+  const image = files.find(f => f.type.startsWith('image/'))
+  const editor = resolveEditor()
+  if (!image || !editor) return
+  e.preventDefault()
+  void uploadAndSetImage(editor, image)
+}
+
+function onEditorRootDragOver(e: DragEvent) {
+  if (Array.from(e.dataTransfer?.types ?? []).includes('Files')) e.preventDefault()
+}
 
 async function loadPost(id: string) {
   loading.value = true
@@ -141,7 +276,7 @@ function friendlyWriteError(e: unknown): string {
 
 async function handleSubmit() {
   error.value = ''
-  if (!title.value.trim() || !content.value.trim()) {
+  if (!title.value.trim() || isContentEmpty(content.value)) {
     error.value = '제목과 내용을 입력해 주세요.'
     return
   }
@@ -158,13 +293,17 @@ async function handleSubmit() {
     error.value = '목록에 있는 카테고리를 선택해 주세요.'
     return
   }
+  if (isWriteRestricted.value) {
+    error.value = restrictedMessage.value
+      || '콘텐츠 경고가 누적되어 글·댓글 작성이 잠시 제한됐어요.'
+    return
+  }
 
   saving.value = true
   submitHint.value = '내용을 검토하는 중…'
   try {
-    const text = `${title.value}\n${content.value}`
-    const moderation = await checkText(text)
-
+    const plain = content.value.replace(/<[^>]+>/g, ' ')
+    const moderation = await checkText(`${title.value}\n${plain}`)
     if (moderation.flagged) {
       error.value = moderation.reason || '게시할 수 없는 내용이 포함되어 있습니다.'
       return
@@ -218,7 +357,6 @@ async function handleSubmit() {
     class="flex flex-col gap-4"
     @submit.prevent="handleSubmit"
   >
-    <!-- path 로 카테고리 고정 시: 표시만 / 아니면 선택+추가 -->
     <div
       v-if="categoryLocked"
       class="flex items-center gap-2 text-sm"
@@ -286,12 +424,54 @@ async function handleSubmit() {
       size="lg"
       required
     />
-    <UTextarea
-      v-model="content"
-      placeholder="내용을 입력하세요"
-      :rows="12"
-      required
-    />
+
+    <div
+      class="rounded-xl border border-default overflow-hidden"
+      @paste="onEditorRootPaste"
+      @drop="onEditorRootDrop"
+      @dragover="onEditorRootDragOver"
+    >
+      <UAlert
+        v-if="imageUploadError"
+        color="error"
+        variant="subtle"
+        icon="i-lucide-circle-alert"
+        title="업로드 실패"
+        :description="imageUploadError"
+        class="rounded-none rounded-t-xl"
+      />
+
+      <UEditor
+        ref="editorRef"
+        v-model="content"
+        content-type="html"
+        :handlers="handlers"
+        placeholder="본문을 입력하세요…"
+        :ui="{ content: 'min-h-64 p-4' }"
+        class="w-full"
+      >
+        <template #default="{ editor }">
+          <UEditorToolbar
+            :editor="editor"
+            :items="toolbarItems"
+            class="border-b border-default p-2"
+          />
+          <UEditorDragHandle :editor="editor" />
+        </template>
+      </UEditor>
+
+      <p
+        v-if="imageUploading"
+        class="flex items-center gap-2 border-t border-default px-4 py-2 text-xs text-muted"
+      >
+        <UIcon
+          name="i-lucide-loader-circle"
+          class="size-3.5 animate-spin"
+        />
+        이미지 업로드 중…
+      </p>
+    </div>
+
     <UInput
       v-model="tagsInput"
       placeholder="태그 (쉼표로 구분)"
@@ -303,6 +483,12 @@ async function handleSubmit() {
       editable
     />
 
+    <p
+      v-if="isWriteRestricted && restrictedMessage"
+      class="text-sm text-warning"
+    >
+      {{ restrictedMessage }}
+    </p>
     <p
       v-if="error"
       class="text-sm text-error"
@@ -320,9 +506,11 @@ async function handleSubmit() {
       <UButton
         type="submit"
         :loading="saving"
+        :disabled="isWriteRestricted || imageUploading"
         :label="isEdit ? '수정 완료' : '게시하기'"
       />
       <UButton
+        type="button"
         variant="ghost"
         color="neutral"
         label="취소"

package/dist/types.d.ts

@@ -6,6 +6,18 @@ export interface Attachment {
     size: number;
     type: string;
 }
+/**
+ * 에디터 본문 이미지 업로드 결과 (원본 + 썸네일).
+ * Storage: `{prefix}/posts/{postId}/images/...` · `.../images/thumbnails/...`
+ * 본문 markdown 에는 originalUrl 만 넣고, 썸네일은 목록 카드 등에 활용 가능.
+ * 수정 중 버려진 파일은 호스트 스케줄러로 정리 (본문에 없는 path).
+ */
+export interface EditorImageEntry {
+    originalUrl: string;
+    originalPath: string;
+    thumbnailUrl: string;
+    thumbnailPath: string;
+}
 /** MVP: 차단된 글은 쓰기 자체가 일어나지 않으므로 항상 'approved'만 저장된다. */
 export type ModerationStatus = 'approved';
 export interface PostModel {
@@ -54,7 +66,7 @@ export interface BoardSettingsModel {
     updatedAt?: Timestamp;
 }
 /** 검열이 어느 단계에서 끝났는지 (호스트/로깅용, UI 노출 없음) */
-export type ModerationVia = 'empty' | 'disabled' | 'local' | 'ai' | 'ai-error-allow' | 'ai-error-block';
+export type ModerationVia = 'empty' | 'disabled' | 'local' | 'ai' | 'restricted' | 'ai-error-allow' | 'ai-error-block';
 export interface ModerationResult {
     flagged: boolean;
     category: 'none' | 'abuse' | 'spam' | 'adult' | 'violence' | 'other';

package/dist/utils/compressImage.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Canvas API로 썸네일용 이미지 압축 (shineb 와 동일).
+ */
+export declare function compressImage(file: File | Blob, { maxWidth, quality }?: {
+    maxWidth?: number;
+    quality?: number;
+}): Promise<Blob>;

package/dist/utils/extractEditorImageUrls.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 에디터 본문(markdown 또는 html)에서 이미지 URL 추출.
+ * 고아 파일 정리 스케줄러·저장 시 참조 비교에 사용.
+ */
+export declare function extractEditorImageUrls(content: string): string[];

package/dist/utils/moderation-prompt.d.ts

@@ -1,4 +1,13 @@
-export declare const MODERATION_SYSTEM = "\uB2F9\uC2E0\uC740 \uAC8C\uC2DC\uD310 \uCF58\uD150\uCE20\uB97C \uC2EC\uC0AC\uD558\uB294 \uC5C4\uACA9\uD55C \uBAA8\uB354\uB808\uC774\uD130\uC785\uB2C8\uB2E4.\n\uC544\uB798 \uD14D\uC2A4\uD2B8\uC5D0 \uC695\uC124\u00B7\uBE44\uC18D\uC5B4\u00B7\uC131\uD76C\uB871\u00B7\uD610\uC624\u00B7\uC704\uD611\u00B7\uC2A4\uD338\u00B7\uB3C4\uBC30\uC131 \uAD11\uACE0\uAC00 \uC788\uC73C\uBA74 \uBC18\uB4DC\uC2DC \uAC70\uBD80(flagged=true)\uD569\uB2C8\uB2E4.\n\nflagged=true \uC608:\n- \uC695\uC124/\uBE44\uC18D\uC5B4: \uC528\uBC1C, \uC2DC\uBC1C, \uBCD1\uC2E0, \uC9C0\uB784, \uC886, \uAC1C\uC0C8\uB07C, \uC874\uB098, fuck, shit, bitch \uB4F1\n- \uC131\uC801 \uBAA8\uC695, \uD610\uC624 \uBC1C\uC5B8, \uD611\uBC15\n- \uAC8C\uC2DC\uD310 \uC8FC\uC81C\uC640 \uBB34\uAD00\uD55C \uB3C4\uBC30\uC131 \uAD11\uACE0/\uC2A4\uD338\n\nflagged=false:\n- \uAC8C\uC2DC\uD310 \uC8FC\uC81C\uC5D0 \uB9DE\uB294 \uC815\uC0C1\uC801\uC778 \uAE00/\uB313\uAE00 (\uAC15\uD55C \uC758\uACAC\uC774\uB098 \uC815\uB2F9\uD55C \uBE44\uD310\uC740 \uD5C8\uC6A9)\n\nJSON\uB9CC \uCD9C\uB825:\n{\"flagged\":boolean,\"category\":\"none\"|\"abuse\"|\"spam\"|\"adult\"|\"violence\"|\"other\",\"reason\":string}\n- flagged=true\uBA74 category\uB294 \uC0C1\uD669\uC5D0 \uB9DE\uAC8C \uACE0\uB974\uACE0, reason\uC740 \uD55C\uAD6D\uC5B4 1\uBB38\uC7A5 (\uC608: \"\uC695\uC124\uC774 \uD3EC\uD568\uB418\uC5B4 \uC788\uC5B4 \uAC8C\uC2DC\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.\")\n- flagged=false\uBA74 category\uB294 \"none\", reason\uC740 \"\"";
+export declare const MODERATION_SYSTEM = "\uB2F9\uC2E0\uC740 \uAC8C\uC2DC\uD310 \uCF58\uD150\uCE20\uB97C \uC2EC\uC0AC\uD558\uB294 \uC5C4\uACA9\uD55C \uBAA8\uB354\uB808\uC774\uD130\uC785\uB2C8\uB2E4.\n\uC544\uB798 \uD14D\uC2A4\uD2B8\uC5D0 \uC695\uC124\u00B7\uBE44\uC18D\uC5B4\u00B7\uC131\uD76C\uB871\u00B7\uD610\uC624\u00B7\uC704\uD611\u00B7\uC2A4\uD338\u00B7\uB3C4\uBC30\uC131 \uAD11\uACE0\uAC00 \uC788\uC73C\uBA74 \uBC18\uB4DC\uC2DC \uAC70\uBD80(flagged=true)\uD569\uB2C8\uB2E4.\n\nflagged=true \uC608:\n- \uC695\uC124/\uBE44\uC18D\uC5B4: \uC528\uBC1C, \uC2DC\uBC1C, \uBCD1\uC2E0, \uC9C0\uB784, \uC886, \uAC1C\uC0C8\uB07C, \uC874\uB098, fuck, shit, bitch \uB4F1\n- \uC131\uC801 \uBAA8\uC695, \uD610\uC624 \uBC1C\uC5B8, \uD611\uBC15\n- \uAC8C\uC2DC\uD310 \uC8FC\uC81C\uC640 \uBB34\uAD00\uD55C \uB3C4\uBC30\uC131 \uAD11\uACE0/\uC2A4\uD338\n\nflagged=false:\n- \uAC8C\uC2DC\uD310 \uC8FC\uC81C\uC5D0 \uB9DE\uB294 \uC815\uC0C1\uC801\uC778 \uAE00/\uB313\uAE00 (\uAC15\uD55C \uC758\uACAC\uC774\uB098 \uC815\uB2F9\uD55C \uBE44\uD310\uC740 \uD5C8\uC6A9)\n\nJSON\uB9CC \uCD9C\uB825:\n{\"flagged\":boolean,\"category\":\"none\"|\"abuse\"|\"spam\"|\"adult\"|\"violence\"|\"other\",\"reason\":string}\n- flagged=true\uBA74 category\uB97C \uACE0\uB974\uACE0, reason\uC740 \uD55C\uAD6D\uC5B4\uB85C **\uBB34\uC5C7\uC774 \uBB38\uC81C\uC778\uC9C0** \uAD6C\uCCB4\uC801\uC73C\uB85C 1\uBB38\uC7A5\n  (\uC608: \"\uC695\uC124(\uBE44\uC18D\uC5B4)\uC774 \uD3EC\uD568\uB418\uC5B4 \uAC8C\uC2DC\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.\", \"\uAD11\uACE0\u00B7\uC2A4\uD338\uC131 \uBB38\uAD6C\uAC00 \uC788\uC5B4 \uAC8C\uC2DC\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.\")\n  \uC695\uC124 \uB2E8\uC5B4 \uC804\uCCB4\uB97C \uADF8\uB300\uB85C \uAE38\uAC8C \uC778\uC6A9\uD558\uC9C0 \uB9D0\uACE0, \uC720\uD615(\uC695\uC124/\uD610\uC624/\uC2A4\uD338 \uB4F1)\uC744 \uBD84\uBA85\uD788 \uBC1D\uD78C\uB2E4.\n- flagged=false\uBA74 category\uB294 \"none\", reason\uC740 \"\"";
+/** 사용자 안내용 카테고리 라벨 */
+export declare const MODERATION_CATEGORY_LABELS: Record<string, string>;
+/** 차단 사유를 사용자에게 읽기 쉽게 정리 */
+export declare function formatModerationUserReason(opts: {
+    reason?: string;
+    category?: string;
+    via?: string;
+    localHit?: string;
+}): string;
 /** API 없이도 1차로 걸러내는 한국어/영어 비속어 (부분 문자열 매칭) */
 export declare const DEFAULT_LOCAL_BLOCKLIST: string[];
 export declare function buildLocalBlockRegex(patterns: string[]): RegExp;

package/dist/utils/moderation-strike.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 게시판 검열 차단 누적 → 일시 이용 제한 (호스트 contentWarning 과 동일 모델).
+ * - 콘텐츠 차단(로컬/AI flagged) 시 +1
+ * - 유효 경고 ≥ threshold(기본 3) → 글/댓글 작성 불가
+ * - 24h마다 lazy 차감 (moderationBlockAt 기준)
+ */
+export declare const DEFAULT_BLOCK_BAN_THRESHOLD = 3;
+export declare const DEFAULT_BLOCK_BAN_DECAY_MS: number;
+export declare function effectiveModerationBlockCount(count: number | null | undefined, blockAtMs: number | null | undefined, nowMs?: number, decayMs?: number): number;
+/** 제한 해제 시각(ms). 제한 없으면 null. */
+export declare function moderationWriteRestrictedUntilMs(count: number | null | undefined, blockAtMs: number | null | undefined, nowMs?: number, threshold?: number, decayMs?: number): number | null;
+export declare function isModerationWriteRestricted(count: number | null | undefined, blockAtMs: number | null | undefined, nowMs?: number, threshold?: number, decayMs?: number): boolean;
+export declare function formatRestrictedUntilLabel(untilMs: number, nowMs?: number): string;
+export declare function toBlockAtMs(value: unknown): number | null;

package/dist/utils/renderMarkdown.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 게시글 상세용 가벼운 마크다운 → HTML (TipTap 없이).
+ * 목록 이동 시 UEditor destroy/recreate 로 나는
+ * "Adding different instances of a keyed plugin" 를 피한다.
+ * 신뢰된 작성자 콘텐츠 전제 — 기본 이스케이프 후 허용 패턴만 복원.
+ */
+/**
+ * GFM-ish 최소 변환. 코드 펜스·목록·제목·인용·hr·단락.
+ */
+export declare function renderMarkdownToHtml(markdown: string): string;

package/dist/utils/storagePath.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Firebase Storage download URL → object path.
+ * 예: .../o/board%2Fposts%2Fid%2Fimages%2Fx.png?alt=media → board/posts/id/images/x.png
+ */
+export declare function storagePathFromDownloadUrl(url: string): string | null;
+/** path 에서 posts/{ns}/... 의 ns 추출 */
+export declare function postNamespaceFromStoragePath(path: string): string | null;

package/docs/firebase-setup.md

@@ -0,0 +1,106 @@
+# Firebase 프로젝트 준비 (처음 설치하는 경우)
+
+이 모듈을 처음 붙이는 프로젝트, 특히 Firebase를 아직 안 써본 프로젝트라면 README의 "설치" 섹션만으로는 부족하다. 여기 순서대로 하면 된다.
+
+## 1. 사전 준비
+
+- Node.js + pnpm (또는 npm/yarn)
+- Nuxt **4.0 이상**, `@nuxt/ui` **4.0 이상**
+- Firebase CLI: `npm i -g firebase-tools` 후 `firebase login`
+
+## 2. Firebase 프로젝트 만들기 (아직 없다면)
+
+1. [Firebase 콘솔](https://console.firebase.google.com)에서 새 프로젝트를 만든다.
+2. **Firestore Database**를 사용 설정한다 (Native mode).
+3. **Storage**를 사용 설정한다.
+4. **Authentication**을 사용 설정하고, Sign-in method에서 쓸 provider(Google/Apple/이메일-비밀번호)를 켠다.
+
+이미 있는 Firebase 프로젝트에 붙이는 거라면 이 단계는 건너뛰고, 위 세 서비스가 켜져 있는지만 확인한다.
+
+## 3. `firebaseConfig` 값 가져오기
+
+Firebase 콘솔 → 프로젝트 설정(톱니바퀴) → **일반** 탭 → "내 앱" 섹션 → 웹 앱이 없으면 추가 → "SDK 설정 및 구성"에서 `apiKey`/`authDomain`/`projectId`/`storageBucket`/`messagingSenderId`/`appId` 값을 그대로 복사해 `nuxt.config.ts`의 `vuefire.config`에 붙여넣는다(memi-board가 아니라 호스트의 nuxt-vuefire 설정이다 — README [설치](../README.md#설치) 참고).
+
+## 4. 호스트 프로젝트를 Firebase CLI에 연결
+
+프로젝트 루트에 아직 `firebase.json`/`.firebaserc`가 없다면:
+
+```bash
+firebase init firestore storage
+```
+
+또는 수동으로 만든다:
+
+```json
+// .firebaserc
+{ "projects": { "default": "<your-project-id>" } }
+```
+
+```json
+// firebase.json
+{
+  "firestore": { "rules": "firestore.rules" },
+  "storage": { "rules": "storage.rules" }
+}
+```
+
+이미 Firebase CLI를 쓰고 있는 프로젝트라면, `firebase.json`에 `firestore.rules`/`storage.rules` 경로가 이미 지정돼 있는지만 확인하면 된다.
+
+## 5. 게시판 Security Rules 병합 + 배포
+
+README의 [Security Model](../README.md#security-model--반드시-읽어야-하는-부분) 섹션대로 `docs/firestore.rules.example`/`docs/storage.rules.example`을 프로젝트 규칙 파일에 병합한 뒤:
+
+```bash
+firebase deploy --only firestore:rules,storage
+```
+
+**병합만 하고 배포를 안 하면 글쓰기·댓글에서 `permission-denied`가 난다** — 가장 흔한 설치 실수다.
+
+## 6. 로그인 공급자 설정
+
+### Google
+
+Firebase 콘솔 → Authentication → Sign-in method에서 Google을 활성화하기만 하면 된다. 추가 설정 없음.
+
+### Apple
+
+Google보다 손이 더 간다:
+
+1. Firebase 콘솔에서 Apple 로그인을 활성화한다.
+2. [Apple Developer](https://developer.apple.com/account) 계정에서 **Services ID**를 새로 만든다.
+3. 그 Services ID의 "Web Authentication Configuration"에 콜백 도메인을 등록한다 — Domains에 `{authDomain}`(Firebase 프로젝트의 authDomain, 보통 `<project-id>.firebaseapp.com`), Return URL에 `https://{authDomain}/__/auth/handler`.
+4. Apple Developer의 **Keys**에서 "Sign in with Apple" 키를 새로 만든다 (기존에 다른 용도 키가 있어도 별도로 새로 만들어야 한다).
+5. Team ID, 방금 만든 키의 Key ID, 그 키의 개인 키(`.p8` 파일 내용)를 Firebase 콘솔의 Apple 로그인 설정 화면에 입력한다.
+
+자세한 건 [Firebase 공식 가이드](https://firebase.google.com/docs/auth/web/apple)를 따른다. 이 설정 없이 Apple 로그인 버튼을 누르면 에러가 난다.
+
+## 7. Firebase AI Logic(Gemini) 활성화 — AI 검열용
+
+1. Firebase 콘솔 → **AI Logic** 에서 활성화하고, **Gemini Developer API** 를 사용하도록 설정한다.
+2. **요금제**: Spark에서도 되는 경우가 있으나 제한·쿼터가 있을 수 있다. 부족하면 Blaze.
+3. 모델: 호스트 `configureMemiBoard({ moderation: { model: 'gemini-3.5-flash-lite' } })` 권장.  
+   `gemini-2.5-flash` 는 **신규 프로젝트에서 "no longer available to new users"** 로 404 날 수 있다.
+4. `moderation.enabled` 기본이 `true` 이므로 활성화 후 글쓰기 시 자동 호출된다. 끄려면 `enabled: false`.
+
+## 8. App Check 설정 (AI Logic Enforce 시 사실상 필수)
+
+AI Logic / `firebaseml` 이 **Enforce** 이면 App Check 토큰 없이 검열 API가 실패한다. memi-board는 App Check를 초기화하지 않는다 — **호스트 책임**.
+
+1. Firebase 콘솔 → App Check → **웹 앱**에 reCAPTCHA v3 등록 (사이트 키·시크릿).  
+   등록하는 웹 앱의 **appId** 가 호스트 `vuefire.config.appId` 와 같아야 한다.
+2. 호스트 클라이언트 플러그인에서 `initializeAppCheck` + `ReCaptchaV3Provider` (README App Check 절 예시).  
+   `vuefire.appCheck` 옵션만 쓰는 방법도 있으나, AI Logic 연동 이슈 시 명시적 `initializeAppCheck` 를 쓴다.
+3. **로컬:** `self.FIREBASE_APPCHECK_DEBUG_TOKEN = true`(콘솔에 UUID 출력 후 App Check → 디버그 토큰 등록) 또는 등록된 고정 UUID.
+4. **프로덕션:** 디버그 토큰 사용 금지. reCAPTCHA 도메인에 실제 호스트 도메인 등록.
+5. (선택) Firestore/Storage Enforce — 켜면 토큰 없는 요청 거부. AI Logic 과 별개 토글이다.
+
+## 9. Firestore 복합 인덱스 (카테고리 필터 사용 시)
+
+`MemiBoardList` 에 `category` prop 을 넘기면 `category + createdAt` 복합 인덱스가 필요하다.  
+콘솔 에러의 인덱스 생성 링크를 따르거나, 호스트 `firestore.indexes.json` 에 추가 후:
+
+```bash
+firebase deploy --only firestore:indexes
+```
+
+컬렉션 ID 예: `collectionPrefix` 가 `board` 이면 `boardPosts`.

package/docs/firestore.rules.example

@@ -0,0 +1,97 @@
+// memi-board Firestore Security Rules 예시
+//
+// 이 모듈은 서버가 없는 클라이언트 전용 아키텍처이므로, 모든 권한 검증은 여기 규칙이 전부다.
+// 호스트 프로젝트의 firestore.rules에 아래 내용을 병합해서 배포해야 게시판이 실제로 안전해진다.
+//
+// collectionPrefix 를 'memiBoard'가 아닌 다른 값(예: board)으로 쓰면
+// 아래 memiBoardPosts / memiBoardUsers / memiBoardSettings 이름을
+// {prefix}Posts / {prefix}Users / {prefix}Settings 로 전부 바꿔야 한다.
+// 예: board → boardPosts, boardUsers, boardSettings
+
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+
+    function isSignedIn() {
+      return request.auth != null;
+    }
+    function isAdmin() {
+      return isSignedIn() &&
+        get(/databases/$(database)/documents/memiBoardUsers/$(request.auth.uid)).data.role == 'admin';
+    }
+    function isOwner(resource) {
+      return isSignedIn() && request.auth.uid == resource.data.authorUid;
+    }
+
+    match /memiBoardPosts/{postId} {
+      allow read: if true;
+
+      allow create: if isSignedIn()
+        && request.resource.data.authorUid == request.auth.uid
+        && request.resource.data.moderationStatus == 'approved';
+
+      // 작성자 본인 또는 관리자만 수정/삭제 가능
+      allow update, delete: if isOwner(resource) || isAdmin();
+
+      match /body/{docId} {
+        allow read: if true;
+        allow write: if isOwner(get(/databases/$(database)/documents/memiBoardPosts/$(postId))) || isAdmin();
+      }
+
+      match /comments/{commentId} {
+        allow read: if true;
+
+        allow create: if isSignedIn()
+          && request.resource.data.authorUid == request.auth.uid
+          && request.resource.data.moderationStatus == 'approved';
+
+        // 댓글 작성자·부모 게시글 작성자·게시판 관리자 모두 삭제 가능.
+        // 부모 글을 삭제할 때 작성자가 다른 사용자의 댓글도 함께 정리할 수 있어야 한다.
+        allow delete: if isOwner(resource)
+          || isOwner(get(/databases/$(database)/documents/memiBoardPosts/$(postId)))
+          || isAdmin();
+
+        // 댓글 수정은 지원하지 않는다 (삭제 후 재작성만 가능) — Editor에서 UI 자체도 제공하지 않음
+        allow update: if false;
+      }
+    }
+
+    // 게시판 역할 문서.
+    // 본인은 role:'user'로만 생성/유지할 수 있고, 자기 role을 'admin'으로 바꿀 수 없다.
+    // 관리자 승격은 Firebase 콘솔에서 해당 uid 문서의 role 필드를 직접 'admin'으로 바꿔야 한다
+    // (이 모듈은 관리자 승격 UI를 제공하지 않는다).
+    // moderationBlockCount/At: 검열 차단 누적(+1만). 감소·리셋은 admin.
+    match /memiBoardUsers/{uid} {
+      allow read: if isSignedIn();
+      allow create: if isSignedIn()
+        && request.auth.uid == uid
+        && request.resource.data.role == 'user'
+        && (!('moderationBlockCount' in request.resource.data)
+            || request.resource.data.moderationBlockCount == 0
+            || request.resource.data.moderationBlockCount == 1);
+      allow update: if isAdmin()
+        || (isSignedIn()
+          && request.auth.uid == uid
+          && request.resource.data.role == resource.data.role
+          && (
+            !request.resource.data.diff(resource.data).affectedKeys()
+              .hasAny(['moderationBlockCount', 'moderationBlockAt'])
+            || (
+              request.resource.data.diff(resource.data).affectedKeys()
+                .hasOnly(['moderationBlockCount', 'moderationBlockAt', 'updatedAt'])
+              && request.resource.data.moderationBlockCount
+                == resource.data.get('moderationBlockCount', 0) + 1
+            )
+          ));
+    }
+
+    // 게시판 설정(카테고리 등) — 읽기 전체 공개.
+    // 로그인 사용자가 글쓰기 폼에서 카테고리를 추가할 수 있다 (categories + updatedAt 만).
+    match /memiBoardSettings/{docId} {
+      allow read: if true;
+      allow create, update: if isSignedIn()
+        && request.resource.data.keys().hasOnly(['categories', 'updatedAt'])
+        && request.resource.data.categories is list;
+    }
+  }
+}