create-entity-app-server 0.0.3 → 0.0.4

package/docs/design/board-api-design.md

@@ -1,2342 +0,0 @@
-# 범용 게시판 API 설계
-
-> **작성일**: 2026-03-06  
-> **상태**: 🔍 검토 중  
-> **관련**: `gateway-server-architecture.md`, `plugin-models.md`
-
----
-
-## 목차
-
-1. [개요](#1-개요)
-2. [용어 정의](#2-용어-정의)
-3. [아키텍처 흐름](#3-아키텍처-흐름)
-4. [엔티티 설계](#4-엔티티-설계)
-5. [앱서버 Routes 설계](#5-앱서버-routes-설계)
-6. [API 상세 스펙](#6-api-상세-스펙)
-7. [권한 및 보안](#7-권한-및-보안)
-8. [확장 고려사항](#8-확장-고려사항)
-
----
-
-## 1. 개요
-
-여러 프로젝트(codeshop, elim_crm, elim_gas 등)에서 공통으로 사용할 수 있는 **범용 게시판 API**를 설계한다.
-각 프로젝트는 **entity-app-server**(Fastify/TypeScript)를 사용하며,
-게시판은 앱서버의 `routes/board/` 에 구현한다.
-
-### 핵심 요구사항
-
-- 게시판 종류를 동적으로 생성/관리 (카테고리)
-- 게시글 CRUD + 목록 조회 (페이징, 검색, 정렬)
-- **답글**: 게시글에 대한 계층형 답변. `board_post` 엔티티에서 `parent_seq`로 자기참조 트리 구성 (depth 무제한)
-- **댓글**: 게시글·답글 내부의 짧은 코멘트 (단일 depth)
-- 파일 첨부
-- 조회수 카운트
-- 고정글(pin) 지원
-- 권한 제어 (읽기/쓰기/관리)
-
----
-
-## 2. 용어 정의
-
-| 용어         | 엔티티                              | 설명                                                                                        |
-| ------------ | ----------------------------------- | ------------------------------------------------------------------------------------------- |
-| **게시글**   | `board_post`                        | 게시판의 원글. `parent_seq=null`, `depth=0`.                                                |
-| **답글**     | `board_post`                        | 게시글에 대한 계층형 답변. **동일 엔티티** `board_post`에서 `parent_seq`로 트리를 형성한다. |
-| **댓글**     | `board_comment`                     | 게시글 또는 답글에 달리는 짧은 코멘트. 단일 depth.                                          |
-| **카테고리** | `board_category`                    | 게시판 종류 (공지사항, 자유게시판, Q&A 등)                                                  |
-| **첨부파일** | `file_meta` (엔티티 서버 files API) | 게시글에 첨부된 파일. 엔티티 서버의 파일 스토리지를 사용한다.                               |
-
-> **핵심**: 원글과 답글은 모두 `board_post` 엔티티 하나에 저장된다. 목록은 하나의 API로 원글·답글을 함께 조회하며,
-> `parent_seq` / `depth` / `root_seq` 필드로 계층 구조를 표현한다.
-
-```
-board_post (seq:42, parent_seq=null, depth=0)          ← 원글
-├── board_post (seq:10, parent_seq=42, root_seq=42, depth=1)  ← 답글
-│   ├── board_post (seq:15, parent_seq=10, root_seq=42, depth=2)  ← 대답변
-│   │   └── 댓글 (board_comment, post_seq=15)                   ← 대답변 코멘트
-│   └── 댓글 (board_comment, post_seq=10)                       ← 답글 코멘트
-├── board_post (seq:11, parent_seq=42, root_seq=42, depth=1)  ← 답글 B
-├── 댓글 1 (board_comment, post_seq=42)                        ← 원글 코멘트
-├── 댓글 2 (board_comment, post_seq=42)
-└── 첨부파일 (file_meta)  ← /v1/files/board_post/upload?entity_seq=42
-```
-
----
-
-## 3. 아키텍처 흐름
-
-```
-┌──────────────┐     ┌───────────────────────┐     ┌──────────────────┐
-│   Frontend   │────▶│     App Server         │────▶│  Entity Server   │
-│  (Vue/React) │◀────│  (Fastify/TypeScript)  │◀────│    (Go/Fiber)    │
-└──────────────┘     └───────────────────────┘     └──────────────────┘
-                      │                              │
-                      │ entity-app-server            │ Entities:
-                      │ routes/board/route.ts        │   board_category
-                      │                              │   board_post
-                      │ 역할:                         │   board_comment
-                      │  - JWT 인증 (auth plugin)     │   (parent_seq 자기참조)
-                      │  - 입력 검증                   │
-                      │  - 권한 확인                   │ Files API:
-                      │  - 파일: files API 프록시      │   /v1/files/board_post/*
-                      │  - entityServer.* SDK 호출     │ 역할:
-                      │  - 응답 가공                   │  - CRUD 처리
-                      │                              │  - 데이터 검증
-                      │ @gateway/api 사용:            │  - Hook 실행
-                      │  ok(), fail(), entityServer   │  - 이력 관리
-                      └──────────────────────────────┘
-```
-
-### 요청 흐름 예시: 게시글 작성
-
-```
-Frontend                    App Server (Fastify)              Entity Server (Go)
-   │                            │                                   │
-   │  POST /api/v1/board/{category}/submit  │                                   │
-   │  { title, content, parent_seq, ... }   │                                   │
-   │───────────────────────────▶│                                   │
-   │                            │  1. preHandler: authenticate      │
-   │                            │  2. 입력 검증                      │
-   │                            │  3. 카테고리 권한 확인              │
-   │                            │                                   │
-   │                            │  entityServer.submit("board_post",│
-   │                            │    { category_seq, title, ... })  │
-   │                            │──────────────────────────────────▶│
-   │                            │                                   │  validate
-   │                            │                                   │  insert
-   │                            │                                   │  run hooks
-   │                            │         { seq, ... }              │
-   │                            │◀──────────────────────────────────│
-   │       ok({ seq })          │                                   │
-   │◀───────────────────────────│                                   │
-```
-
----
-
-## 4. 엔티티 설계
-
-### 4.1 board_category (게시판 카테고리)
-
-게시판 종류를 정의한다. 공지사항, 자유게시판, Q&A 등.
-
-```json
-{
-    "name": "board_category",
-    "description": "게시판 카테고리 (게시판 종류 정의)",
-    "fields": {
-        "name": {
-            "index": true,
-            "required": true,
-            "unique": true,
-            "comment": "게시판 이름 (예: notice, free, qna)"
-        },
-        "label": {
-            "required": true,
-            "comment": "표시 이름 (예: 공지사항, 자유게시판)"
-        },
-        "description": {
-            "comment": "게시판 설명"
-        },
-        "status": {
-            "index": true,
-            "type": ["active", "inactive"],
-            "default": "active",
-            "comment": "게시판 활성 상태"
-        },
-        "sort_order": {
-            "type": "uint",
-            "default": "0",
-            "comment": "정렬 순서"
-        },
-        "read_role": {
-            "type": ["all", "member", "admin"],
-            "default": "all",
-            "comment": "읽기 권한"
-        },
-        "write_role": {
-            "type": ["all", "member", "admin"],
-            "default": "member",
-            "comment": "쓰기 권한"
-        },
-        "reply_enabled": {
-            "type": ["Y", "N"],
-            "default": "Y",
-            "comment": "답글 허용 여부"
-        },
-        "comment_enabled": {
-            "type": ["Y", "N"],
-            "default": "Y",
-            "comment": "댓글 허용 여부"
-        },
-        "file_enabled": {
-            "type": ["Y", "N"],
-            "default": "Y",
-            "comment": "파일 첨부 허용 여부"
-        },
-        "guest_write_enabled": {
-            "type": ["Y", "N"],
-            "default": "N",
-            "comment": "비회원 글작성 허용 여부 (비밀번호 인증)"
-        },
-        "like_enabled": {
-            "type": ["Y", "N"],
-            "default": "N",
-            "comment": "좋아요/추천 허용 여부"
-        },
-        "rating_enabled": {
-            "type": ["Y", "N"],
-            "default": "N",
-            "comment": "별점 허용 여부"
-        },
-        "accept_enabled": {
-            "type": ["Y", "N"],
-            "default": "N",
-            "comment": "답변 채택 허용 여부 (Q&A 게시판용)"
-        },
-        "push_on_write": {
-            "type": ["Y", "N"],
-            "default": "N",
-            "comment": "글 등록 시 관리자 push 알림 여부 (문의게시판 등)"
-        },
-        "view_count_mode": {
-            "type": ["always", "session", "daily", "once"],
-            "default": "daily",
-            "comment": "조회수 카운트 방식. always=매 조회, session=세션당 1회, daily=1일 1인 1회(기본), once=1인 1회(영구)"
-        },
-        "anonymous_enabled": {
-            "type": ["Y", "N"],
-            "default": "N",
-            "comment": "익명 게시판 여부. Y이면 작성자 표시를 '익명'으로 강제, user_seq는 응답에서 숨김"
-        }
-    }
-}
-```
-
-### 4.2 board_post (게시글 · 답글)
-
-원글과 답글을 **동일 엔티티**에서 관리한다. `parent_seq=null`이면 원글(depth=0),
-값이 있으면 답글이다. 목록 API는 `category_seq` 기준으로 전체(원글+답글)를 한 번에 반환하며,
-프론트엔드에서 `parent_seq`와 `depth`를 이용해 트리 구조로 조립한다.
-
-```json
-{
-    "name": "board_post",
-    "description": "게시판 원글 및 답글 (자기참조 트리)",
-    "fields": {
-        "category_seq": {
-            "index": true,
-            "required": true,
-            "type": "uint",
-            "comment": "게시판 카테고리 seq"
-        },
-        "user_seq": {
-            "index": true,
-            "type": "uint",
-            "comment": "작성자 user seq (비회원이면 null)"
-        },
-        "author_name": {
-            "required": true,
-            "comment": "작성자 표시 이름 (회원: 닉네임, 비회원: 입력값)"
-        },
-        "guest_password": {
-            "comment": "비회원 비밀번호 (bcrypt 해시, 비회원 글만 사용)"
-        },
-        "title": {
-            "index": true,
-            "required": true,
-            "comment": "제목"
-        },
-        "content": {
-            "required": true,
-            "comment": "본문 (HTML or Markdown)"
-        },
-        "status": {
-            "index": true,
-            "type": ["published", "draft", "deleted"],
-            "default": "published",
-            "comment": "글 상태"
-        },
-        "pinned": {
-            "index": true,
-            "type": ["Y", "N"],
-            "default": "N",
-            "comment": "상단 고정 여부"
-        },
-        "view_count": {
-            "type": "uint",
-            "default": "0",
-            "comment": "조회수"
-        },
-        "reply_count": {
-            "type": "uint",
-            "default": "0",
-            "comment": "답글 수 (캐시)"
-        },
-        "comment_count": {
-            "type": "uint",
-            "default": "0",
-            "comment": "댓글 수 (캐시)"
-        },
-        "file_count": {
-            "type": "uint",
-            "default": "0",
-            "comment": "첨부파일 수 (캐시, 앱서버에서 업로드/삭제 시 갱신)"
-        },
-        "parent_seq": {
-            "index": true,
-            "type": "uint",
-            "comment": "부모 글 seq (null=원글, 값 있으면 답글)"
-        },
-        "root_seq": {
-            "index": true,
-            "type": "uint",
-            "comment": "최상위 원글 seq (답글 조회 필터링용, 원글은 자기 자신 seq)"
-        },
-        "depth": {
-            "type": "uint",
-            "default": "0",
-            "comment": "깊이 (0=원글, 1=직접 답변, 2=대답변, ...)"
-        },
-        "like_count": {
-            "type": "uint",
-            "default": "0",
-            "comment": "좋아요 수 (캐시)"
-        },
-        "rating_sum": {
-            "type": "uint",
-            "default": "0",
-            "comment": "별점 합계 (캐시, rating_avg = rating_sum / rating_count)"
-        },
-        "rating_count": {
-            "type": "uint",
-            "default": "0",
-            "comment": "별점 참여 수 (캐시)"
-        },
-        "accepted": {
-            "index": true,
-            "type": ["Y", "N"],
-            "default": "N",
-            "comment": "채택된 답변 여부 (accept_enabled 게시판의 답글에만 사용)"
-        }
-    },
-    "fk": {
-        "category_seq": "board_category.seq",
-        "user_seq": "user.seq",
-        "parent_seq": "board_post.seq",
-        "root_seq": "board_post.seq"
-    },
-    "hooks": {
-        "after_insert": [
-            {
-                "description": "답글 작성 시 원글의 reply_count 증가 (원글 = root_seq 기준. depth에 관계없이 모든 하위 답글을 원글 1건으로 카운트)",
-                "type": "update",
-                "entity": "board_post",
-                "condition": "${new.parent_seq} != null",
-                "match": { "seq": "${new.root_seq}" },
-                "data": { "reply_count": "${target.reply_count + 1}" }
-            },
-            {
-                "description": "글 등록 시 카테고리 push_on_write=Y이면 관리자에게 push 알림",
-                "type": "push",
-                "condition": "${category.push_on_write} == 'Y'",
-                "target": "role:admin",
-                "title": "[${category.label}] 새 글이 등록되었습니다",
-                "body": "${new.author_name}: ${new.title}",
-                "data": {
-                    "type": "board_post",
-                    "seq": "${new.seq}",
-                    "category": "${category.name}"
-                }
-            }
-        ],
-        "after_delete": [
-            {
-                "description": "답글 삭제 시 원글의 reply_count 감소 (root_seq 기준)",
-                "type": "update",
-                "entity": "board_post",
-                "condition": "${old.parent_seq} != null",
-                "match": { "seq": "${old.root_seq}" },
-                "data": { "reply_count": "${target.reply_count - 1}" }
-            }
-        ]
-    }
-}
-```
-
-### 4.3 board_comment (댓글)
-
-게시글 또는 답글에 달리는 짧은 코멘트. 원글·답글 모두 `board_post` 엔티티이므로
-`post_seq` 하나로 대상을 지정한다. `root_seq`는 원글의 전체 댓글을 한 번에 조회할 때 사용한다.
-
-```json
-{
-    "name": "board_comment",
-    "description": "게시글/답글 댓글 (단일 depth)",
-    "fields": {
-        "post_seq": {
-            "index": true,
-            "required": true,
-            "type": "uint",
-            "comment": "댓글 대상 board_post seq (원글 또는 답글)"
-        },
-        "root_seq": {
-            "index": true,
-            "required": true,
-            "type": "uint",
-            "comment": "최상위 원글 seq (해당 원글의 전체 댓글 조회용)"
-        },
-        "user_seq": {
-            "index": true,
-            "required": true,
-            "type": "uint",
-            "comment": "작성자 user seq"
-        },
-        "author_name": {
-            "required": true,
-            "comment": "작성자 표시 이름"
-        },
-        "content": {
-            "required": true,
-            "comment": "댓글 내용"
-        },
-        "status": {
-            "index": true,
-            "type": ["active", "deleted"],
-            "default": "active",
-            "comment": "댓글 상태"
-        },
-        "rating_sum": {
-            "type": "uint",
-            "default": "0",
-            "comment": "별점 합계 (캐시, rating_avg = rating_sum / rating_count)"
-        },
-        "rating_count": {
-            "type": "uint",
-            "default": "0",
-            "comment": "별점 참여 수 (캐시)"
-        }
-    },
-    "fk": {
-        "post_seq": "board_post.seq",
-        "root_seq": "board_post.seq",
-        "user_seq": "user.seq"
-    },
-    "hooks": {
-        "after_insert": [
-            {
-                "description": "댓글 작성 시 대상 board_post.comment_count 증가",
-                "type": "update",
-                "entity": "board_post",
-                "match": { "seq": "${new.post_seq}" },
-                "data": { "comment_count": "${target.comment_count + 1}" }
-            }
-        ],
-        "after_delete": [
-            {
-                "description": "댓글 삭제 시 대상 board_post.comment_count 감소",
-                "type": "update",
-                "entity": "board_post",
-                "match": { "seq": "${old.post_seq}" },
-                "data": { "comment_count": "${target.comment_count - 1}" }
-            }
-        ]
-    }
-}
-```
-
-### 4.4 첨부파일 — 엔티티 서버 Files API
-
-`board_file` 별도 엔티티를 만들지 않는다. 엔티티 서버의 내장 파일 스토리지(`/v1/files/:entity/*`)를 사용하며,
-`board_post` 엔티티를 스코프로 하여 `entity_seq`(게시글 seq)로 파일을 연결한다.
-
-**엔티티 서버 Files API 라우트:**
-
-| 동작     | 엔드포인트                                  | 설명                                            |
-| -------- | ------------------------------------------- | ----------------------------------------------- |
-| 업로드   | `POST /v1/files/board_post/upload`          | `entity_seq={postSeq}`, `field_name=attachment` |
-| 목록     | `POST /v1/files/board_post/list`            | `ref_seq={postSeq}`                             |
-| 다운로드 | `GET /v1/files/{uuid}`                      | 브라우저 인라인 뷰 (공개 파일)                  |
-| 다운로드 | `POST /v1/files/board_post/download/{uuid}` | API 다운로드 (항상 attachment)                  |
-| 삭제     | `POST /v1/files/board_post/delete/{uuid}`   |                                                 |
-| 메타     | `POST /v1/files/board_post/meta/{uuid}`     |                                                 |
-
-**앱서버 SDK 사용:**
-
-```typescript
-// 업로드
-const res = await entityServer.fileUpload("board_post", file, {
-    refSeq: postSeq,
-    isPublic: false,
-});
-// res.uuid  → 파일 식별자
-// res.data  → FileMeta (uuid, original_name, mime_type, size, account_seq, created_time 등)
-
-// 목록
-const list = await entityServer.fileList("board_post", { refSeq: postSeq });
-
-// 삭제
-await entityServer.fileDelete("board_post", uuid);
-```
-
-**file_count 갱신**: `board_post.file_count`는 별도 hook이 없으므로, 업로드·삭제 후 앱서버 핸들러에서
-`entityServer.submit("board_post", { seq: postSeq, file_count: newCount })` 로 갱신한다.
-
-### 4.5 board_like (좋아요 · 추천)
-
-게시글 또는 답글에 대한 좋아요. `post_seq + user_seq` 유니크로 중복 방지.
-비회원은 좋아요 불가 (IP 기반 방식 필요 시 `guest_ip` 필드 추가 가능).
-
-```json
-{
-    "name": "board_like",
-    "description": "게시글/답글 좋아요",
-    "fields": {
-        "post_seq": {
-            "index": true,
-            "required": true,
-            "type": "uint",
-            "comment": "대상 board_post seq"
-        },
-        "user_seq": {
-            "index": true,
-            "required": true,
-            "type": "uint",
-            "comment": "좋아요한 user seq"
-        }
-    },
-    "unique": ["post_seq", "user_seq"],
-    "fk": {
-        "post_seq": "board_post.seq",
-        "user_seq": "user.seq"
-    },
-    "hooks": {
-        "after_insert": [
-            {
-                "type": "update",
-                "entity": "board_post",
-                "match": { "seq": "${new.post_seq}" },
-                "data": { "like_count": "${target.like_count + 1}" }
-            }
-        ],
-        "after_delete": [
-            {
-                "type": "update",
-                "entity": "board_post",
-                "match": { "seq": "${old.post_seq}" },
-                "data": { "like_count": "${target.like_count - 1}" }
-            }
-        ]
-    }
-}
-```
-
-### 4.6 board_rating (별점)
-
-게시글·답글·댓글 모두에 별점을 줄 수 있다. `target_type` + `target_seq` + `user_seq` 유니크로 중복 방지.
-hook은 `target_type`에 따라 `board_post` 또는 `board_comment`의 캐시 필드를 갱신한다.
-평균은 `rating_sum / rating_count`로 계산한다.
-
-```json
-{
-    "name": "board_rating",
-    "description": "게시글/답글/댓글 별점 (1~5)",
-    "fields": {
-        "target_type": {
-            "index": true,
-            "required": true,
-            "type": ["post", "comment"],
-            "comment": "별점 대상 유형 (post=게시글/답글, comment=댓글)"
-        },
-        "target_seq": {
-            "index": true,
-            "required": true,
-            "type": "uint",
-            "comment": "대상 엔티티 seq (board_post.seq 또는 board_comment.seq)"
-        },
-        "user_seq": {
-            "index": true,
-            "required": true,
-            "type": "uint",
-            "comment": "평가한 user seq"
-        },
-        "score": {
-            "required": true,
-            "type": ["1", "2", "3", "4", "5"],
-            "comment": "별점 (1~5)"
-        }
-    },
-    "unique": ["target_type", "target_seq", "user_seq"],
-    "fk": {
-        "user_seq": "user.seq"
-    },
-    "hooks": {
-        "after_insert": [
-            {
-                "description": "게시글/답글 별점 캐시 갱신",
-                "type": "update",
-                "entity": "board_post",
-                "condition": "${new.target_type} == 'post'",
-                "match": { "seq": "${new.target_seq}" },
-                "data": {
-                    "rating_sum": "${target.rating_sum + new.score}",
-                    "rating_count": "${target.rating_count + 1}"
-                }
-            },
-            {
-                "description": "댓글 별점 캐시 갱신",
-                "type": "update",
-                "entity": "board_comment",
-                "condition": "${new.target_type} == 'comment'",
-                "match": { "seq": "${new.target_seq}" },
-                "data": {
-                    "rating_sum": "${target.rating_sum + new.score}",
-                    "rating_count": "${target.rating_count + 1}"
-                }
-            }
-        ],
-        "after_update": [
-            {
-                "description": "게시글/답글 별점 수정 시 합계 보정",
-                "type": "update",
-                "entity": "board_post",
-                "condition": "${new.target_type} == 'post'",
-                "match": { "seq": "${new.target_seq}" },
-                "data": {
-                    "rating_sum": "${target.rating_sum - old.score + new.score}"
-                }
-            },
-            {
-                "description": "댓글 별점 수정 시 합계 보정",
-                "type": "update",
-                "entity": "board_comment",
-                "condition": "${new.target_type} == 'comment'",
-                "match": { "seq": "${new.target_seq}" },
-                "data": {
-                    "rating_sum": "${target.rating_sum - old.score + new.score}"
-                }
-            }
-        ],
-        "after_delete": [
-            {
-                "description": "게시글/답글 별점 취소 캐시 보정",
-                "type": "update",
-                "entity": "board_post",
-                "condition": "${old.target_type} == 'post'",
-                "match": { "seq": "${old.target_seq}" },
-                "data": {
-                    "rating_sum": "${target.rating_sum - old.score}",
-                    "rating_count": "${target.rating_count - 1}"
-                }
-            },
-            {
-                "description": "댓글 별점 취소 캐시 보정",
-                "type": "update",
-                "entity": "board_comment",
-                "condition": "${old.target_type} == 'comment'",
-                "match": { "seq": "${old.target_seq}" },
-                "data": {
-                    "rating_sum": "${target.rating_sum - old.score}",
-                    "rating_count": "${target.rating_count - 1}"
-                }
-            }
-        ]
-    }
-}
-```
-
-### 4.7 board_tag (태그)
-
-게시글에 붙이는 태그. `name`은 소문자 슬러그(`javascript`, `vue-js`), `label`은 표시명.
-`use_count`는 `board_post_tag` hook으로 자동 갱신된다.
-
-```json
-{
-    "name": "board_tag",
-    "description": "게시글 태그",
-    "fields": {
-        "name": {
-            "index": true,
-            "required": true,
-            "unique": true,
-            "comment": "태그 슬러그 (예: javascript, vue-js) — lowercase, 하이픈 허용"
-        },
-        "label": {
-            "required": true,
-            "comment": "표시명 (예: JavaScript, Vue.js)"
-        },
-        "use_count": {
-            "type": "uint",
-            "default": "0",
-            "comment": "사용 횟수 캐시 (board_post_tag hook으로 갱신)"
-        }
-    }
-}
-```
-
-### 4.8 board_post_tag (게시글-태그 연결)
-
-`board_post`와 `board_tag`의 M:N 연결 테이블.
-삽입/삭제 시 hook으로 `board_tag.use_count`를 갱신한다.
-
-```json
-{
-    "name": "board_post_tag",
-    "description": "게시글-태그 연결 (M:N)",
-    "fields": {
-        "post_seq": {
-            "index": true,
-            "required": true,
-            "type": "uint",
-            "comment": "board_post seq"
-        },
-        "tag_seq": {
-            "index": true,
-            "required": true,
-            "type": "uint",
-            "comment": "board_tag seq"
-        }
-    },
-    "unique": ["post_seq", "tag_seq"],
-    "fk": {
-        "post_seq": "board_post.seq",
-        "tag_seq": "board_tag.seq"
-    },
-    "hooks": {
-        "after_insert": [
-            {
-                "type": "update",
-                "entity": "board_tag",
-                "match": { "seq": "${new.tag_seq}" },
-                "data": { "use_count": "${target.use_count + 1}" }
-            }
-        ],
-        "after_delete": [
-            {
-                "type": "update",
-                "entity": "board_tag",
-                "match": { "seq": "${old.tag_seq}" },
-                "data": { "use_count": "${target.use_count - 1}" }
-            }
-        ]
-    }
-}
-```
-
-### 4.9 board_report (신고)
-
-게시글·댓글에 대한 신고를 기록한다. `target_type + target_seq + user_seq` 복합 unique로 중복 신고를 방지한다.
-
-```json
-{
-    "name": "board_report",
-    "description": "게시글·댓글 신고",
-    "fields": {
-        "target_type": {
-            "type": ["post", "comment"],
-            "required": true,
-            "comment": "신고 대상 유형"
-        },
-        "target_seq": {
-            "index": true,
-            "required": true,
-            "type": "uint",
-            "comment": "대상 seq (board_post 또는 board_comment)"
-        },
-        "user_seq": {
-            "index": true,
-            "required": true,
-            "type": "uint",
-            "comment": "신고한 회원 seq"
-        },
-        "reason": {
-            "type": ["spam", "abuse", "illegal", "other"],
-            "required": true,
-            "comment": "신고 사유"
-        },
-        "detail": {
-            "comment": "신고 상세 내용 (선택)"
-        },
-        "status": {
-            "type": ["pending", "resolved", "dismissed"],
-            "default": "pending",
-            "comment": "처리 상태. pending=미처리, resolved=처리완료, dismissed=기각"
-        }
-    },
-    "unique": ["target_type", "target_seq", "user_seq"]
-}
-```
-
-### 4.10 board_read_log (읽음 표시)
-
-회원이 게시글을 읽은 기록을 저장한다. `post_seq + user_seq` 복합 unique로 중복 기록을 방지한다.
-`read_time`을 업데이트 방식(upsert)으로 처리하여 목록 화면에서 새글 표시나 안 읽은 글 필터에 활용한다.
-
-```json
-{
-    "name": "board_read_log",
-    "description": "게시글 읽음 기록",
-    "fields": {
-        "post_seq": {
-            "index": true,
-            "required": true,
-            "type": "uint",
-            "comment": "board_post seq"
-        },
-        "user_seq": {
-            "index": true,
-            "required": true,
-            "type": "uint",
-            "comment": "읽은 회원 seq"
-        },
-        "read_time": {
-            "type": "datetime",
-            "comment": "가장 최근에 읽은 시각 (upsert 시 갱신)"
-        }
-    },
-    "unique": ["post_seq", "user_seq"],
-    "fk": {
-        "post_seq": "board_post.seq"
-    }
-}
-```
-
-### 4.11 board_mention (멘션)
-
-게시글·댓글 본문의 `@username` 언급을 파싱하여 저장한다.
-삽입 hook으로 해당 회원에게 Push 알림을 발송한다.
-
-```json
-{
-    "name": "board_mention",
-    "description": "게시글·댓글 멘션 기록",
-    "fields": {
-        "source_type": {
-            "type": ["post", "comment"],
-            "required": true,
-            "comment": "멘션이 포함된 소스 유형"
-        },
-        "source_seq": {
-            "index": true,
-            "required": true,
-            "type": "uint",
-            "comment": "소스 seq (board_post 또는 board_comment)"
-        },
-        "mentioned_user_seq": {
-            "index": true,
-            "required": true,
-            "type": "uint",
-            "comment": "멘션된 회원 seq"
-        },
-        "is_read": {
-            "type": ["Y", "N"],
-            "default": "N",
-            "comment": "알림 읽음 여부"
-        }
-    },
-    "unique": ["source_type", "source_seq", "mentioned_user_seq"],
-    "hooks": {
-        "after_insert": [
-            {
-                "type": "push",
-                "target": "user:${new.mentioned_user_seq}",
-                "title": "회원이 나를 멘션했습니다",
-                "body": "${new.source_type} #${new.source_seq}",
-                "data": {
-                    "type": "mention",
-                    "source_type": "${new.source_type}",
-                    "source_seq": "${new.source_seq}"
-                }
-            }
-        ]
-    }
-}
-```
-
----
-
-### 엔티티 관계도
-
-```
-board_category
-    │
-    │ 1:N
-    ▼
-board_post ◀──────────────────── board_post    ─── user
-    │         parent_seq (자기참조)   (답글, depth≥1)    │
-    │         root_seq (원글 직추적)                     │ (user_seq FK)
-    │                                                   │
-    │ 1:N (post_seq FK)                                 │
-    ├──▶ board_comment ────────────────────────────────┘
-    │    (post_seq → 대상 글, root_seq → 원글)
-    │
-    │ 1:N (post_seq FK)
-    ├──▶ board_like    (post_seq + user_seq unique)
-    │
-    │
-    │ 1:N (target_type='comment', target_seq=comment.seq)
-    ├──▶ board_rating  (target_type='comment', target_seq=comment.seq)
-    │
-    │ 1:N (post_seq FK)
-    ├──▶ board_rating  (target_type='post', target_seq=post.seq, target_type+target_seq+user_seq unique, score 1~5)
-    │
-    │ 1:N (post_seq FK)
-    ├──▶ board_post_tag ────▶ board_tag  (name unique, use_count 캐시)
-    │
-    │ 1:N (target_type='post', target_seq=post.seq)
-    ├──▶ board_report  (target_type+target_seq+user_seq unique, status: pending/resolved/dismissed)
-    │
-    │ 1:N (target_type='comment', target_seq=comment.seq)
-    ├──▶ board_report  (댓글 신고)
-    │
-    │ 1:N (post_seq FK)
-    ├──▶ board_read_log  (post_seq + user_seq unique, read_time 갱신)
-    │
-    │ 1:N (source_type='post', source_seq=post.seq)
-    ├──▶ board_mention  (source_type+source_seq+mentioned_user_seq unique, hook → push)
-    │
-    │ 1:N (entity_seq FK, 엔티티 서버 files API)
-    └──▶ file_meta              ← /v1/files/board_post/upload?entity_seq={seq}
-```
-
----
-
-## 5. 앱서버 Routes 설계
-
-### 5.1 라우트 구조
-
-`src/app/routes/board/` 디렉토리에 Fastify 라우트로 구현한다.
-
-```typescript
-// src/app/routes/board/route.ts
-import type { FastifyInstance } from "fastify";
-import * as posts from "./handlers/posts.ts";
-import * as comments from "./handlers/comments.ts";
-import * as files from "./handlers/files.ts";
-import * as categories from "./handlers/categories.ts";
-import * as likes from "./handlers/likes.ts";
-import * as ratings from "./handlers/ratings.ts";
-import * as tags from "./handlers/tags.ts";
-import * as reports from "./handlers/reports.ts";
-import * as mentions from "./handlers/mentions.ts";
-
-export default async function boardRoutes(app: FastifyInstance) {
-    // ── 카테고리 ──
-    app.get("/categories", categories.list);
-    app.get("/categories/:seq", categories.detail);
-    app.post(
-        "/categories",
-        { preHandler: app.authenticate },
-        categories.create,
-    );
-    app.put(
-        "/categories/:seq",
-        { preHandler: app.authenticate },
-        categories.update,
-    );
-    app.delete(
-        "/categories/:seq",
-        { preHandler: app.authenticate },
-        categories.remove,
-    );
-
-    // ── 게시글 · 답글 (board_post 통합) ──
-    app.get("/:category/list", posts.list);
-    app.get("/posts/:seq", posts.detail);
-    app.post(
-        "/:category/submit",
-        { preHandler: app.authenticate },
-        posts.create,
-    );
-    app.put("/posts/:seq", { preHandler: app.authenticate }, posts.update);
-    app.delete("/posts/:seq", { preHandler: app.authenticate }, posts.remove);
-
-    // ── 댓글 (post_seq = 원글 또는 답글 board_post seq) ──
-    app.get("/posts/:postSeq/comments", comments.list);
-    app.post(
-        "/posts/:postSeq/comments/submit",
-        { preHandler: app.authenticate },
-        comments.create,
-    );
-    app.put(
-        "/comments/:seq",
-        { preHandler: app.authenticate },
-        comments.update,
-    );
-    app.delete(
-        "/comments/:seq",
-        { preHandler: app.authenticate },
-        comments.remove,
-    );
-
-    // ── 파일 (엔티티 서버 files API 프록시) ──
-    app.get("/posts/:postSeq/files", files.list);
-    app.post(
-        "/posts/:postSeq/files",
-        { preHandler: app.authenticate },
-        files.upload,
-    );
-    app.delete("/files/:uuid", { preHandler: app.authenticate }, files.remove);
-    // 다운로드는 엔티티 서버 /v1/files/{uuid} 로 직접 리다이렉트 또는 프록시
-    app.get("/files/:uuid", files.view);
-
-    // ── 비회원 글작성 ──
-    app.post("/:category/guest-submit", posts.guestCreate);
-    app.post("/posts/:seq/guest-auth", posts.guestAuth); // 비밀번호 확인 → 임시 토큰 반환
-
-    // ── 좋아요 토글 (이미 좋아요 → 취소, 없으면 추가) ──
-    app.post(
-        "/posts/:seq/like",
-        { preHandler: app.authenticate },
-        likes.toggle,
-    );
-
-    // ── 답변 채택 (원글 작성자 또는 관리자만) ──
-    app.post(
-        "/posts/:seq/accept",
-        { preHandler: app.authenticate },
-        posts.accept,
-    );
-
-    // ── 별점 등록 / 수정 (게시글·답글 또는 댓글) ──
-    app.post(
-        "/posts/:seq/rating",
-        { preHandler: app.authenticate },
-        ratings.upsert,
-    );
-    app.post(
-        "/comments/:seq/rating",
-        { preHandler: app.authenticate },
-        ratings.upsert,
-    );
-
-    // ── 태그 ──
-    app.get("/tags", tags.list);
-    app.put(
-        "/posts/:seq/tags",
-        { preHandler: app.authenticate },
-        tags.setPostTags,
-    );
-
-    // ── 신고 ──
-    app.post(
-        "/posts/:seq/report",
-        { preHandler: app.authenticate },
-        reports.submit,
-    );
-    app.post(
-        "/comments/:seq/report",
-        { preHandler: app.authenticate },
-        reports.submit,
-    );
-
-    // ── 읽음 표시 ──
-    app.post(
-        "/posts/:seq/read",
-        { preHandler: app.authenticate },
-        posts.markRead,
-    );
-
-    // ── 멘션 ──
-    app.get("/mentions", { preHandler: app.authenticate }, mentions.list);
-    app.patch(
-        "/mentions/:seq/read",
-        { preHandler: app.authenticate },
-        mentions.markRead,
-    );
-}
-```
-
-> 모든 엔드포인트는 `/api/v1/board/*` 으로 매핑된다 (폴더명 기반 자동 prefix).
-
-### 5.2 핸들러 디렉토리 구조
-
-```
-src/app/routes/board/
-├── route.ts                  # 라우트 정의
-└── handlers/
-    ├── posts.ts              # 게시글 CRUD + 비회원 작성/인증 + 답변 채택 + 읽음 표시
-    ├── comments.ts           # 댓글 CRUD
-    ├── files.ts              # 파일 — entityServer.fileUpload/fileList/fileDelete 사용
-    ├── likes.ts              # 좋아요 토글 (board_like)
-    ├── ratings.ts            # 별점 등록/수정 (board_rating)
-    ├── tags.ts               # 태그 목록 조회 / 게시글 태그 일괄 설정 (board_tag, board_post_tag)
-    ├── reports.ts            # 신고 제출 (board_report) — 게시글·댓글 공용
-    ├── mentions.ts           # 멘션 목록/읽음 처리 (board_mention)
-    └── categories.ts         # 카테고리 관리
-```
-
-### 5.3 핸들러 구현 예시
-
-```typescript
-// src/app/routes/board/handlers/posts.ts
-import { FastifyRequest, FastifyReply } from "fastify";
-import { ok, fail, entityServer } from "@gateway/api";
-
-export async function list(
-    req: FastifyRequest<{
-        Params: { category: string };
-        Querystring: {
-            page?: number;
-            per_page?: number;
-            search?: string;
-            root_seq?: number; // root_seq 필터: 특정 원글의 답글만 조회
-            depth?: number; // depth 필터: 0=원글만, 생략=전체
-        };
-    }>,
-    reply: FastifyReply,
-) {
-    const { category } = req.params;
-    const { page = 1, per_page = 20, search, root_seq, depth } = req.query;
-
-    const cat = await entityServer.find("board_category", {
-        name: category,
-        status: "active",
-    });
-    if (cat.count === 0)
-        return reply.send(fail("카테고리를 찾을 수 없습니다."));
-
-    const filter: Record<string, unknown> = {
-        category_seq: cat.items[0].seq,
-        status: "published",
-    };
-    if (root_seq !== undefined) filter.root_seq = root_seq;
-    if (depth !== undefined) filter.depth = depth;
-
-    const resp = await entityServer.list("board_post", {
-        filter,
-        search,
-        page,
-        limit: per_page,
-        sort: "created_time",
-        order: "desc",
-    });
-
-    return reply.send(ok(resp));
-}
-
-export async function create(
-    req: FastifyRequest<{
-        Params: { category: string };
-        Body: {
-            title: string;
-            content: string;
-            parent_seq?: number; // 답글일 때 설정
-            pinned?: string;
-            status?: string; // "published" | "draft"
-            tags?: string[]; // 태그 name 배열
-        };
-    }>,
-    reply: FastifyReply,
-) {
-    const { category } = req.params;
-    const { title, content, parent_seq, pinned, status, tags } = req.body;
-    const userSeq = req.user.account_seq;
-
-    const cat = await entityServer.find("board_category", {
-        name: category,
-        status: "active",
-    });
-    if (cat.count === 0)
-        return reply.send(fail("카테고리를 찾을 수 없습니다."));
-
-    const catItem = cat.items[0];
-
-    // pinned는 관리자만 설정 가능
-    if (pinned === "Y" && !req.user.is_admin)
-        return reply.send(fail("글 고정은 관리자만 가능합니다."));
-
-    // 답글일 때 root_seq, depth 자동 가산
-    let root_seq: number | undefined;
-    let depth = 0;
-    if (parent_seq) {
-        const parent = await entityServer.find("board_post", {
-            seq: parent_seq,
-        });
-        if (parent.count === 0)
-            return reply.send(fail("부모 글을 찾을 수 없습니다."));
-        const p = parent.items[0];
-        root_seq = p.root_seq ?? p.seq;
-        depth = (p.depth ?? 0) + 1;
-    }
-
-    // 익명 게시판이면 author_name 강제 치환
-    const isAnonymous = catItem.anonymous_enabled === "Y";
-    const authorName = isAnonymous ? "익명" : req.user.name;
-
-    const resp = await entityServer.submit("board_post", {
-        category_seq: catItem.seq,
-        user_seq: userSeq,
-        author_name: authorName,
-        title,
-        content,
-        status: status || "published",
-        parent_seq: parent_seq ?? null,
-        root_seq: root_seq ?? null, // 원글은 insert 후 seq로 갱신 필요
-        depth,
-        pinned: parent_seq ? "N" : pinned || "N",
-    });
-
-    // 원글이면 root_seq = 자기 seq
-    if (!parent_seq) {
-        await entityServer.submit("board_post", {
-            seq: resp.seq,
-            root_seq: resp.seq,
-        });
-    }
-
-    // 태그 연결
-    if (tags && tags.length > 0) {
-        await setPostTags(resp.seq, tags);
-    }
-
-    // @username 멘션 파싱 및 board_mention 삽입
-    const mentionPattern = /@([a-zA-Z0-9_]+)/g;
-    let match: RegExpExecArray | null;
-    while ((match = mentionPattern.exec(content)) !== null) {
-        const username = match[1];
-        const user = await entityServer.find("user", { username });
-        if (user.count > 0) {
-            await entityServer.submit("board_mention", {
-                source_type: "post",
-                source_seq: resp.seq,
-                mentioned_user_seq: user.items[0].seq,
-            });
-        }
-    }
-
-    return reply.code(201).send(ok({ seq: resp.seq }));
-}
-```
-
-### 5.4 비회원 글작성 핸들러 예시
-
-```typescript
-// src/app/routes/board/handlers/posts.ts (추가 함수)
-import bcrypt from "bcrypt";
-
-export async function guestCreate(
-    req: FastifyRequest<{
-        Params: { category: string };
-        Body: {
-            title: string;
-            content: string;
-            guest_name: string;
-            guest_password: string; // 평문 — 핸들러에서 bcrypt 해시 처리
-        };
-    }>,
-    reply: FastifyReply,
-) {
-    const { category } = req.params;
-    const { title, content, guest_name, guest_password } = req.body;
-
-    const cat = await entityServer.find("board_category", {
-        name: category,
-        status: "active",
-    });
-    if (cat.count === 0)
-        return reply.send(fail("카테고리를 찾을 수 없습니다."));
-
-    const catItem = cat.items[0];
-    if (catItem.guest_write_enabled !== "Y")
-        return reply.send(
-            fail("이 게시판은 비회원 글작성이 허용되지 않습니다."),
-        );
-
-    const hashed = await bcrypt.hash(guest_password, 10);
-
-    const resp = await entityServer.submit("board_post", {
-        category_seq: catItem.seq,
-        user_seq: null, // 비회원
-        author_name: guest_name,
-        guest_password: hashed,
-        title,
-        content,
-        depth: 0,
-    });
-
-    // root_seq = 자기 seq
-    await entityServer.submit("board_post", {
-        seq: resp.seq,
-        root_seq: resp.seq,
-    });
-
-    return reply.code(201).send(ok({ seq: resp.seq }));
-}
-
-export async function guestAuth(
-    req: FastifyRequest<{
-        Params: { seq: string };
-        Body: { guest_password: string };
-    }>,
-    reply: FastifyReply,
-) {
-    const seq = Number(req.params.seq);
-    const { guest_password } = req.body;
-
-    const post = await entityServer.find("board_post", { seq });
-    if (post.count === 0) return reply.send(fail("게시글을 찾을 수 없습니다."));
-
-    const item = post.items[0];
-    if (!item.guest_password)
-        return reply.send(fail("비회원 게시글이 아닙니다."));
-
-    const ok_ = await bcrypt.compare(guest_password, item.guest_password);
-    if (!ok_) return reply.send(fail("비밀번호가 일치하지 않습니다."));
-
-    // 임시 허가 토큰 (서명된 JWT, 만료 30분)
-    const token = await reply.jwtSign(
-        { guest_post_seq: seq },
-        { expiresIn: "30m" },
-    );
-    return reply.send(ok({ token }));
-}
-
-export async function accept(
-    req: FastifyRequest<{ Params: { seq: string } }>,
-    reply: FastifyReply,
-) {
-    const seq = Number(req.params.seq);
-    const userSeq = req.user.account_seq;
-
-    const post = await entityServer.find("board_post", { seq });
-    if (post.count === 0) return reply.send(fail("게시글을 찾을 수 없습니다."));
-    const item = post.items[0];
-
-    // 원글은 채택할 수 없다 (답글만 채택 가능)
-    if (item.parent_seq === null)
-        return reply.send(
-            fail("원글은 채택할 수 없습니다. 답글만 채택 가능합니다."),
-        );
-
-    // 원글 작성자 또는 관리자만 채택 가능
-    // 원글(root)의 작성자를 확인해야 하므로 root_seq로 원글 조회
-    const rootPost = await entityServer.find("board_post", {
-        seq: item.root_seq,
-    });
-    if (rootPost.count === 0)
-        return reply.send(fail("원글을 찾을 수 없습니다."));
-    if (rootPost.items[0].user_seq !== userSeq && !req.user.is_admin)
-        return reply.send(fail("채택 권한이 없습니다."));
-
-    // 같은 root_seq 내 기존 채택 해제
-    if (item.root_seq) {
-        const prevAccepted = await entityServer.find("board_post", {
-            root_seq: item.root_seq,
-            accepted: "Y",
-        });
-        for (const p of prevAccepted.items) {
-            await entityServer.submit("board_post", {
-                seq: p.seq,
-                accepted: "N",
-            });
-        }
-    }
-
-    await entityServer.submit("board_post", { seq, accepted: "Y" });
-    return reply.send(ok(null));
-}
-```
-
-```typescript
-// src/app/routes/board/handlers/likes.ts
-import type { FastifyRequest, FastifyReply } from "fastify";
-import { ok, fail, entityServer } from "@gateway/api";
-
-export async function toggle(
-    req: FastifyRequest<{ Params: { seq: string } }>,
-    reply: FastifyReply,
-) {
-    const postSeq = Number(req.params.seq);
-    const userSeq = req.user.account_seq;
-
-    const existing = await entityServer.find("board_like", {
-        post_seq: postSeq,
-        user_seq: userSeq,
-    });
-
-    if (existing.count > 0) {
-        // 이미 좋아요 → 취소
-        await entityServer.remove("board_like", { seq: existing.items[0].seq });
-        return reply.send(ok({ liked: false }));
-    } else {
-        // 좋아요 추가
-        await entityServer.submit("board_like", {
-            post_seq: postSeq,
-            user_seq: userSeq,
-        });
-        return reply.send(ok({ liked: true }));
-    }
-}
-```
-
-```typescript
-// src/app/routes/board/handlers/tags.ts
-import type { FastifyRequest, FastifyReply } from "fastify";
-import { ok, fail, entityServer } from "@gateway/api";
-
-export async function list(
-    req: FastifyRequest<{
-        Querystring: { search?: string; limit?: number };
-    }>,
-    reply: FastifyReply,
-) {
-    const { search, limit = 20 } = req.query;
-    const resp = await entityServer.list("board_tag", {
-        search,
-        limit,
-        sort: "use_count",
-        order: "desc",
-    });
-    return reply.send(ok(resp));
-}
-
-export async function setPostTags(
-    req: FastifyRequest<{
-        Params: { seq: string };
-        Body: { tags: string[] }; // tag name(슬러그) 배열
-    }>,
-    reply: FastifyReply,
-) {
-    const postSeq = Number(req.params.seq);
-    const { tags: tagNames } = req.body;
-
-    // 기존 board_post_tag 전체 삭제 (replace 방식)
-    const existing = await entityServer.list("board_post_tag", {
-        filter: { post_seq: postSeq },
-        limit: 100,
-    });
-    for (const pt of existing.items) {
-        await entityServer.remove("board_post_tag", { seq: pt.seq });
-    }
-
-    const result: string[] = [];
-    for (const name of tagNames) {
-        const slug = name.toLowerCase().replace(/\s+/g, "-");
-        // 태그 조회 또는 자동 생성
-        let tagRes = await entityServer.find("board_tag", { name: slug });
-        if (tagRes.count === 0) {
-            const created = await entityServer.submit("board_tag", {
-                name: slug,
-                label: name,
-            });
-            tagRes = await entityServer.find("board_tag", { seq: created.seq });
-        }
-        await entityServer.submit("board_post_tag", {
-            post_seq: postSeq,
-            tag_seq: tagRes.items[0].seq,
-        });
-        result.push(slug);
-    }
-
-    return reply.send(ok({ tags: result }));
-}
-```
-
-```typescript
-// src/app/routes/board/handlers/ratings.ts
-import type { FastifyRequest, FastifyReply } from "fastify";
-import { ok, fail, entityServer } from "@gateway/api";
-
-/**
- * /posts/:seq/rating  → target_type: "post"
- * /comments/:seq/rating → target_type: "comment"
- * routeConfig.url 에서 target_type을 판별한다.
- */
-export async function upsert(
-    req: FastifyRequest<{
-        Params: { seq: string };
-        Body: { score: number }; // 1~5
-    }>,
-    reply: FastifyReply,
-) {
-    const targetSeq = Number(req.params.seq);
-    const userSeq = req.user.account_seq;
-    const { score } = req.body;
-
-    const targetType = req.routeOptions.url.includes("/comments/")
-        ? "comment"
-        : "post";
-
-    if (score < 1 || score > 5)
-        return reply.send(fail("별점은 1~5 사이여야 합니다."));
-
-    const existing = await entityServer.find("board_rating", {
-        target_type: targetType,
-        target_seq: targetSeq,
-        user_seq: userSeq,
-    });
-
-    if (existing.count > 0) {
-        // 기존 별점 수정 → after_update hook이 rating_sum 보정
-        await entityServer.submit("board_rating", {
-            seq: existing.items[0].seq,
-            score: String(score),
-        });
-        return reply.send(ok({ updated: true }));
-    } else {
-        await entityServer.submit("board_rating", {
-            target_type: targetType,
-            target_seq: targetSeq,
-            user_seq: userSeq,
-            score: String(score),
-        });
-        return reply.send(ok({ created: true }));
-    }
-}
-```
-
-```typescript
-// src/app/routes/board/handlers/reports.ts
-import type { FastifyRequest, FastifyReply } from "fastify";
-import { ok, fail, entityServer } from "@gateway/api";
-
-/**
- * POST /posts/:seq/report  → target_type: "post"
- * POST /comments/:seq/report → target_type: "comment"
- * routeOptions.url 에서 target_type을 판별한다.
- */
-export async function submit(
-    req: FastifyRequest<{
-        Params: { seq: string };
-        Body: {
-            reason: "spam" | "abuse" | "illegal" | "other";
-            detail?: string;
-        };
-    }>,
-    reply: FastifyReply,
-) {
-    const targetSeq = Number(req.params.seq);
-    const userSeq = req.user.account_seq;
-    const { reason, detail } = req.body;
-
-    const targetType = req.routeOptions.url.includes("/comments/")
-        ? "comment"
-        : "post";
-
-    // 대상 존재 여부 확인 (없으면 404)
-    const targetEntity =
-        targetType === "comment" ? "board_comment" : "board_post";
-    const target = await entityServer.find(targetEntity, { seq: targetSeq });
-    if (target.count === 0)
-        return reply.code(404).send(fail("신고 대상을 찾을 수 없습니다."));
-
-    // 동일 대상에 대한 중복 신고 방지
-    const existing = await entityServer.find("board_report", {
-        target_type: targetType,
-        target_seq: targetSeq,
-        user_seq: userSeq,
-    });
-    if (existing.count > 0) return reply.send(fail("이미 신고한 대상입니다."));
-
-    await entityServer.submit("board_report", {
-        target_type: targetType,
-        target_seq: targetSeq,
-        user_seq: userSeq,
-        reason,
-        detail: detail ?? null,
-    });
-
-    return reply.code(201).send(ok({ reported: true }));
-}
-```
-
-```typescript
-// src/app/routes/board/handlers/mentions.ts
-import type { FastifyRequest, FastifyReply } from "fastify";
-import { ok, fail, entityServer } from "@gateway/api";
-
-export async function list(
-    req: FastifyRequest<{ Querystring: { is_read?: "Y" | "N" } }>,
-    reply: FastifyReply,
-) {
-    const userSeq = req.user.account_seq;
-    const { is_read } = req.query;
-
-    const filter: Record<string, unknown> = { mentioned_user_seq: userSeq };
-    if (is_read) filter.is_read = is_read;
-
-    const resp = await entityServer.list("board_mention", {
-        filter,
-        sort: "created_time",
-        order: "desc",
-    });
-    return reply.send(ok(resp));
-}
-
-export async function markRead(
-    req: FastifyRequest<{ Params: { seq: string } }>,
-    reply: FastifyReply,
-) {
-    const seq = Number(req.params.seq);
-
-    const mention = await entityServer.find("board_mention", { seq });
-    if (mention.count === 0)
-        return reply.code(404).send(fail("멘션을 찾을 수 없습니다."));
-    if (mention.items[0].mentioned_user_seq !== req.user.account_seq)
-        return reply.code(403).send(fail("본인 멘션만 처리할 수 있습니다."));
-
-    await entityServer.submit("board_mention", { seq, is_read: "Y" });
-    return reply.send(ok({ read: true }));
-}
-```
-
-> **익명 처리**: `posts.ts` create/guestCreate 핸들러에서 카테고리의 `anonymous_enabled = "Y"` 여부를 확인하여
-> `author_name`을 `"익명"`으로 강제 저장하고, 응답 시 `user_seq`를 `null`로 마스킹한다.
-> 댓글도 동일하게 익명 게시판이면 `author_name = "익명"`, 응답 시 `user_seq = null` 마스킹.
-> `user_seq`는 DB에는 실제 값으로 저장되며, 관리자의 신고 처리와 본인 확인에만 내부적으로 사용된다.
-
-> **읽음 표시**: `posts.ts markRead` 핸들러에서 `board_read_log`를 upsert(`post_seq + user_seq` unique)하여
-> `read_time`을 현재 시각으로 갱신한다. 상세 조회(GET /posts/:seq) 시 자동으로 호출할 수도 있고,
-> 클라이언트에서 명시적으로 `POST /posts/:seq/read`를 호출하는 방식 중 카테고리 설정으로 선택한다.
-
-> **멘션 처리**: `comments.ts create` 및 `posts.ts create` 핸들러에서 `content` 내 `@username` 패턴을
-> 정규식으로 파싱하고, 해당 username을 가진 회원을 조회한 후 `board_mention`을 삽입한다.
-> 삽입 hook이 자동으로 Push 알림을 발송하므로 핸들러에서 별도 처리는 필요 없다.
->
-> **멘션 수정 시 정리 규칙**: 글/댓글 수정 시 멘션을 재파싱하며, 기존 멘션 중 수정 후 본문에 없는 것은 삭제,
-> 새로 추가된 멘션만 `board_mention`에 삽입한다 (diff 방식). 이미 읽은 멘션의 삭제는 문제없다.
-
-### 5.5 앱서버 핸들러 역할
-
-| 역할                   | 설명                                                                                                                      |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| **인증**               | `preHandler: app.authenticate` — JWT 검증                                                                                 |
-| **입력 검증**          | title 길이, content HTML sanitize 등                                                                                      |
-| **권한 확인**          | 카테고리별 read_role/write_role 대조, 본인 확인                                                                           |
-| **Entity Server 호출** | `entityServer.*` SDK로 CRUD 위임                                                                                          |
-| **응답 가공**          | `ok()`, `fail()` 래퍼로 응답 형식 통일                                                                                    |
-| **조회수 처리**        | `view_count_mode`에 따라 카운트 증가. `daily`(기본): Redis TTL 86400s 키로 중복 방지. 회원은 `user_seq`, 비회원은 IP 기반 |
-
----
-
-## 6. API 상세 스펙
-
-모든 엔드포인트의 base path: `/api/v1/board`
-
-### 6.1 게시글 목록 조회
-
-```
-GET /api/v1/board/{category}/list?page=1&per_page=20&search={keyword}&sort=created_time&order=desc&root_seq={seq}&depth={n}
-```
-
-**Query Parameters:**
-
-| 파라미터 | 타입   | 기본값       | 설명                                          |
-| -------- | ------ | ------------ | --------------------------------------------- |
-| category | string | (path)       | 카테고리 name (URL path)                      |
-| page     | int    | 1            | 페이지 번호                                   |
-| per_page | int    | 20           | 페이지당 건수                                 |
-| search   | string | -            | 제목+내용 통합 검색                           |
-| sort     | string | created_time | 정렬 기준                                     |
-| order    | string | desc         | asc / desc                                    |
-| pinned   | string | -            | Y: 고정글만                                   |
-| root_seq | int    | -            | 특정 원글의 답글만 조회 (트리 펼치기)         |
-| depth    | int    | -            | 0: 원글만, 생략: 전체 (원글+답글 flat 목록)   |
-| status   | string | published    | `draft`: 내 임시저장 목록 (인증 필요, 본인만) |
-
-> **주의**: 기본 목록(`depth` 생략)은 원글과 답글을 **모두 flat하게** 반환한다.
-> 프론트엔드에서 `parent_seq`와 `depth`를 이용해 트리 구조로 조립한다.
-> `status=draft` 조회 시 앱서버 핸들러에서 `user_seq: req.user.account_seq` 필터를 강제하여 본인 임시저장만 반환한다.
-
-**Response:**
-
-```json
-{
-    "success": true,
-    "data": {
-        "items": [
-            {
-                "seq": 42,
-                "category_seq": 1,
-                "user_seq": 10,
-                "author_name": "홍길동",
-                "title": "공지사항입니다",
-                "status": "published",
-                "pinned": "Y",
-                "parent_seq": null,
-                "root_seq": 42,
-                "depth": 0,
-                "view_count": 123,
-                "reply_count": 3,
-                "comment_count": 5,
-                "like_count": 12,
-                "rating_sum": 18,
-                "rating_count": 5,
-                "accepted": "N",
-                "file_count": 2,
-                "tags": ["javascript", "vue"],
-                "created_time": "2026-03-06T09:00:00Z",
-                "updated_time": "2026-03-06T09:00:00Z"
-            },
-            {
-                "seq": 10,
-                "category_seq": 1,
-                "user_seq": 11,
-                "author_name": "김철수",
-                "title": "답변드립니다",
-                "status": "published",
-                "pinned": "N",
-                "parent_seq": 42,
-                "root_seq": 42,
-                "depth": 1,
-                "view_count": 20,
-                "reply_count": 0,
-                "comment_count": 2,
-                "like_count": 3,
-                "rating_sum": 4,
-                "rating_count": 1,
-                "accepted": "Y",
-                "file_count": 0,
-                "tags": [],
-                "created_time": "2026-03-06T10:00:00Z",
-                "updated_time": "2026-03-06T10:00:00Z"
-            }
-        ],
-        "pagination": {
-            "page": 1,
-            "per_page": 20,
-            "total": 156,
-            "total_pages": 8
-        }
-    }
-}
-```
-
-> **참고**: 목록 조회 시 `content`는 제외하여 전송량을 줄인다.
-> 원글(`parent_seq=null`)과 답글이 flat하게 섞여 있으므로, 프론트엔드에서 `parent_seq`로 트리 조립.
-
-### 6.2 게시글 상세 조회
-
-```
-GET /api/v1/board/posts/{seq}
-```
-
-**Response:**
-
-```json
-{
-    "success": true,
-    "data": {
-        "seq": 42,
-        "category_seq": 1,
-        "user_seq": 10,
-        "author_name": "홍길동",
-        "title": "공지사항입니다",
-        "content": "<p>본문 내용...</p>",
-        "status": "published",
-        "pinned": "Y",
-        "parent_seq": null,
-        "root_seq": 42,
-        "depth": 0,
-        "view_count": 124,
-        "reply_count": 3,
-        "comment_count": 5,
-        "like_count": 12,
-        "rating_sum": 18,
-        "rating_count": 5,
-        "accepted": "N",
-        "file_count": 2,
-        "created_time": "2026-03-06T09:00:00Z",
-        "updated_time": "2026-03-06T09:00:00Z",
-        "files": [
-            {
-                "uuid": "550e8400-e29b-41d4-a716-446655440000",
-                "original_name": "첨부자료.pdf",
-                "mime_type": "application/pdf",
-                "size": 204800,
-                "account_seq": 10,
-                "created_time": "2026-03-06T09:00:00Z"
-            }
-        ],
-        "tags": ["javascript", "vue"],
-        "is_mine": true
-    }
-}
-```
-
-> 상세 조회 시 앱서버에서 `view_count_mode`에 따라 조건부로 `view_count`를 +1 갱신 후 응답한다.
->
-> | mode      | 동작                                                                   |
-> | --------- | ---------------------------------------------------------------------- |
-> | `always`  | 매 요청마다 증가                                                       |
-> | `session` | 요청 헤더의 세션/쿠키 기준, 없으면 설정 후 1회 증가                    |
-> | `daily`   | Redis `view:{postSeq}:{userSeq\|ip}` 키 TTL 86400s — 키 없을 때만 증가 |
-> | `once`    | Redis `view:{postSeq}:{userSeq\|ip}` 키 영구 저장 — 키 없을 때만 증가  |
-
-### 6.3 게시글 작성 (원글 · 답글 공통)
-
-```
-POST /api/v1/board/{category}/submit
-Content-Type: application/json
-
-{
-    "title": "공지사항입니다",
-    "content": "<p>본문 내용</p>",
-    "parent_seq": null,
-    "pinned": "N",
-    "status": "published",
-    "tags": ["javascript", "vue"]
-}
-```
-
-> `parent_seq`가 null이면 원글, 값이 있으면 답글로 처리된다.
-> 앱서버에서 부모 글의 `root_seq`, `depth`를 조회하여 자동 계산한다.
-> `status: "draft"` 로 전송하면 임시저장되며, 목록에 노출되지 않는다.
-> `tags` 배열이 있으면 `setPostTags`를 내부 호출하여 태그를 연결한다 (없으면 태그 변경 없음).
-
-### 6.4 게시글 수정
-
-```
-PUT /api/v1/board/posts/{seq}
-Content-Type: application/json
-
-{
-    "title": "수정된 제목",
-    "content": "<p>수정된 본문</p>",
-    "status": "published",
-    "tags": ["javascript"]
-}
-```
-
-> 임시저장 글을 발행할 때는 `status: "published"` 를 함께 전송한다.
-> `tags` 배열을 포함하면 태그를 일괄 교체한다 (생략 시 기존 태그 유지).
-
-### 6.5 게시글 삭제
-
-```
-DELETE /api/v1/board/posts/{seq}
-```
-
-> soft delete — `status: "deleted"` 처리.
-
-### 6.6 댓글 목록
-
-```
-GET /api/v1/board/posts/{postSeq}/comments?page=1&per_page=50
-```
-
-> `postSeq`는 원글 또는 답글의 board_post seq 모두 가능.
-
-**Response:**
-
-```json
-{
-    "success": true,
-    "data": {
-        "items": [
-            {
-                "seq": 100,
-                "post_seq": 42,
-                "user_seq": 15,
-                "author_name": "박영희",
-                "content": "좋은 글이네요!",
-                "rating_sum": 8,
-                "rating_count": 2,
-                "created_time": "2026-03-06T11:00:00Z",
-                "updated_time": "2026-03-06T11:00:00Z"
-            }
-        ],
-        "pagination": {
-            "page": 1,
-            "per_page": 50,
-            "total": 5,
-            "total_pages": 1
-        }
-    }
-}
-```
-
-> 익명 게시판(`anonymous_enabled = "Y"`) 댓글의 경우:
->
-> - `author_name`은 `"익명"`으로 강제 대체되어 저장된다.
-> - `user_seq`는 내부적으로 DB에 저장되지만, **응답 시 `null`로 마스킹**하여 반환한다 (본인 식별/신고 처리에만 내부 사용).
-
-### 6.7 댓글 작성
-
-```
-POST /api/v1/board/posts/{postSeq}/comments/submit
-Content-Type: application/json
-
-{
-    "content": "댓글 내용입니다."
-}
-```
-
-> `postSeq`가 원글이면 원글에, 답글이면 해당 답글에 달린다.
-> 앱서버에서 `post_seq = postSeq`, `root_seq = root_seq_of_post` 자동 설정.
-
-### 6.8 파일 목록
-
-```
-GET /api/v1/board/posts/{postSeq}/files
-```
-
-**Response:**
-
-```json
-{
-    "success": true,
-    "data": {
-        "items": [
-            {
-                "uuid": "550e8400-e29b-41d4-a716-446655440000",
-                "original_name": "첨부자료.pdf",
-                "mime_type": "application/pdf",
-                "size": 204800,
-                "account_seq": 10,
-                "is_public": false,
-                "created_time": "2026-03-06T09:00:00Z"
-            }
-        ],
-        "total": 2
-    }
-}
-```
-
-> 앱서버 핸들러에서 `entityServer.fileList("board_post", { refSeq: postSeq })` 호출.
-
-### 6.9 파일 업로드
-
-```
-POST /api/v1/board/posts/{postSeq}/files
-Content-Type: multipart/form-data
-
-file: (binary)
-```
-
-**Response:**
-
-```json
-{
-    "success": true,
-    "data": {
-        "uuid": "550e8400-e29b-41d4-a716-446655440000",
-        "original_name": "첨부자료.pdf",
-        "mime_type": "application/pdf",
-        "size": 204800,
-        "account_seq": 10,
-        "created_time": "2026-03-06T09:00:00Z"
-    }
-}
-```
-
-> 앱서버 핸들러 처리:
->
-> 1. `entityServer.fileUpload("board_post", file, { refSeq: postSeq })` 호출
-> 2. 업로드 성공 후 `board_post.file_count` +1 갱신
-
-### 6.10 파일 뷰 / 다운로드
-
-```
-# 브라우저 인라인 뷰 (이미지, PDF 등 바로보기)
-GET /api/v1/board/files/{uuid}
-
-# 강제 다운로드
-GET /api/v1/board/files/{uuid}?download
-```
-
-> 앱서버 핸들러에서 엔티티 서버 `GET /v1/files/{uuid}` 로 리다이렉트 또는 프록시.
-
-### 6.11 파일 삭제
-
-```
-DELETE /api/v1/board/files/{uuid}
-```
-
-> 앱서버 핸들러 처리:
->
-> 1. `entityServer.fileDelete("board_post", uuid)` 호출
-> 2. 삭제 성공 후 `board_post.file_count` -1 갱신
-
-### 6.12 비회원 글 작성
-
-```
-POST /api/v1/board/{category}/guest-submit
-Content-Type: application/json
-
-{
-    "title": "문의드립니다",
-    "content": "<p>본문 내용</p>",
-    "guest_name": "홍길동",
-    "guest_password": "1234"
-}
-```
-
-> 카테고리의 `guest_write_enabled = "Y"` 일 때만 허용.
-> `guest_password`는 핸들러에서 bcrypt 해시 후 저장. 응답에는 비밀번호 미포함.
-
-**Response:**
-
-```json
-{ "success": true, "data": { "seq": 55 } }
-```
-
-### 6.13 비회원 본인 확인 (비밀번호 → 임시 토큰)
-
-```
-POST /api/v1/board/posts/{seq}/guest-auth
-Content-Type: application/json
-
-{ "guest_password": "1234" }
-```
-
-**Response:**
-
-```json
-{
-    "success": true,
-    "data": {
-        "token": "<jwt — expires 30m>",
-        "note": "이 토큰을 Authorization: Bearer 헤더에 담아 수정/삭제 요청"
-    }
-}
-```
-
-> 수정·삭제 시 이 토큰을 Authorization 헤더에 담아 `posts.update` / `posts.remove` 에서 `req.user.guest_post_seq` 확인.
-
-### 6.14 좋아요 토글
-
-```
-POST /api/v1/board/posts/{seq}/like
-Authorization: Bearer <token>
-```
-
-**Response:**
-
-```json
-{ "success": true, "data": { "liked": true } }
-```
-
-> 이미 좋아요된 상태면 취소(`liked: false`), 없으면 추가(`liked: true`).
-> hook에 의해 `board_post.like_count` 자동 증감.
-
-### 6.15 답변 채택
-
-```
-POST /api/v1/board/posts/{seq}/accept
-Authorization: Bearer <token>
-```
-
-**Response:**
-
-```json
-{ "success": true, "data": null }
-```
-
-> 원글 작성자 또는 관리자만 가능. 같은 `root_seq` 내 기존 채택글은 자동 해제.
-> `board_post.accepted = "Y"` 로 설정.
-> **원글(`parent_seq = null`)은 채택할 수 없다 — 답글(`depth ≥ 1`)만 채택 대상이다.**
-
-### 6.16 별점 등록 / 수정
-
-게시글·답글과 댓글 모두 별점을 줄 수 있다.
-
-**게시글·답글:**
-
-```
-POST /api/v1/board/posts/{seq}/rating
-Authorization: Bearer <token>
-Content-Type: application/json
-
-{ "score": 4 }
-```
-
-**댓글:**
-
-```
-POST /api/v1/board/comments/{seq}/rating
-Authorization: Bearer <token>
-Content-Type: application/json
-
-{ "score": 4 }
-```
-
-**Response (신규):**
-
-```json
-{ "success": true, "data": { "created": true } }
-```
-
-**Response (수정):**
-
-```json
-{ "success": true, "data": { "updated": true } }
-```
-
-> `score`는 1~5 정수. 동일 `target_type + target_seq + user_seq`로 재요청 시 수정 처리.
-> hook에 의해 대상(`board_post` 또는 `board_comment`)의 `rating_sum`, `rating_count` 자동 갱신.
-> 평균 별점: `rating_sum / rating_count` (프론트엔드에서 계산).
-
-### 6.17 태그 목록 조회
-
-```
-GET /api/v1/board/tags?search={keyword}&limit=20
-```
-
-**Response:**
-
-```json
-{
-    "success": true,
-    "data": {
-        "items": [
-            {
-                "seq": 1,
-                "name": "javascript",
-                "label": "JavaScript",
-                "use_count": 42
-            },
-            { "seq": 2, "name": "vue-js", "label": "Vue.js", "use_count": 18 }
-        ]
-    }
-}
-```
-
-> `use_count` 내림차순 정렬. `search`로 태그 이름/라벨 검색 가능. 입력 자동완성에 활용.
-
-### 6.18 게시글 태그 일괄 설정
-
-```
-PUT /api/v1/board/posts/{seq}/tags
-Authorization: Bearer <token>
-Content-Type: application/json
-
-{ "tags": ["javascript", "vue-js"] }
-```
-
-**Response:**
-
-```json
-{ "success": true, "data": { "tags": ["javascript", "vue-js"] } }
-```
-
-> `tags`는 tag `name`(슬러그) 배열. 존재하지 않는 태그는 자동 생성 (label = name).
-> 기존 `board_post_tag`를 **전체 삭제 후 재연결** (replace 방식).
-> 빈 배열 `[]` 전송 시 태그 전체 해제.
-> 게시글 작성(6.3)/수정(6.4) 시 `tags` 필드를 함께 보내면 이 로직을 내부 호출한다.
-
-### 6.19 신고
-
-게시글 또는 댓글을 신고한다. 한 회원이 동일 대상에 중복 신고할 수 없다.
-
-```
-POST /api/v1/board/posts/{seq}/report
-POST /api/v1/board/comments/{seq}/report
-Authorization: Bearer <token>
-Content-Type: application/json
-
-{
-  "reason": "spam",       // "spam" | "abuse" | "illegal" | "other"
-  "detail": "..."         // 선택. reason이 "other"일 때 상세 내용
-}
-```
-
-**Response:**
-
-```json
-{ "success": true, "data": { "reported": true } }
-```
-
-**Error cases:**
-
-- `400` — 이미 신고한 대상 (`"이미 신고한 대상입니다."`)
-- `404` — 존재하지 않는 게시글/댓글
-
-### 6.19.1 신고 관리 (관리자)
-
-신고 목록 조회 및 상태 변경. 관리자 전용.
-
-```
-GET /api/v1/board/admin/reports?status=pending&page=1&per_page=20
-Authorization: Bearer <admin-token>
-```
-
-**Response:**
-
-```json
-{
-    "success": true,
-    "data": {
-        "items": [
-            {
-                "seq": 1,
-                "target_type": "post",
-                "target_seq": 42,
-                "user_seq": 15,
-                "reason": "spam",
-                "detail": null,
-                "status": "pending",
-                "created_time": "2026-03-06T12:00:00Z"
-            }
-        ],
-        "pagination": {
-            "page": 1,
-            "per_page": 20,
-            "total": 3,
-            "total_pages": 1
-        }
-    }
-}
-```
-
-신고 상태 변경:
-
-```
-PATCH /api/v1/board/admin/reports/{seq}
-Authorization: Bearer <admin-token>
-Content-Type: application/json
-
-{ "status": "resolved" }   // "resolved" | "dismissed"
-```
-
-```json
-{ "success": true, "data": null }
-```
-
-> `status`를 `resolved`로 변경하면 해당 게시글/댓글을 숨김 처리(`status: "hidden"`) 할 수 있고,
-> `dismissed`로 변경하면 신고를 기각한다.
-
-### 6.20 읽음 표시
-
-회원이 게시글을 읽음 처리한다. `board_read_log`에 upsert 방식으로 기록한다.
-상세 조회(6.2) 시 앱서버에서 자동 호출할 수 있고, 클라이언트가 명시적으로 호출할 수도 있다.
-
-```
-POST /api/v1/board/posts/{seq}/read
-Authorization: Bearer <token>
-```
-
-**Response:**
-
-```json
-{ "success": true, "data": { "read": true } }
-```
-
-> 비회원은 읽음 표시를 하지 않는다 (인증 필수).
-> 목록 조회 시 `read` 여부는 `board_read_log` 조인으로 `is_read: true/false` 응답에 포함할 수 있다.
-> **upsert 동시성 처리**: unique(`post_seq + user_seq`) 제약에 의해 `INSERT ON DUPLICATE KEY UPDATE read_time = NOW()` 또는
-> Entity Server의 `submit`이 unique 충돌 시 자동 update하는 방식으로 race condition을 방지한다.
-
-### 6.21 멘션 알림 목록
-
-로그인한 회원의 읽지 않은 멘션 목록을 조회한다.
-
-```
-GET /api/v1/board/mentions?is_read=N
-Authorization: Bearer <token>
-```
-
-**Response:**
-
-```json
-{
-    "success": true,
-    "data": {
-        "items": [
-            {
-                "seq": 1,
-                "source_type": "comment",
-                "source_seq": 42,
-                "source_title": "공지사항입니다",
-                "source_author_name": "홍길동",
-                "source_content_preview": "@당신의아이디 확인 부탁드립니다...",
-                "is_read": "N",
-                "created_time": "2025-01-01T00:00:00Z"
-            }
-        ],
-        "total": 1
-    }
-}
-```
-
-> `source_title`은 멘션 소스가 속한 게시글 제목, `source_author_name`은 멘션을 작성한 사람,
-> `source_content_preview`는 본문 앞부분 50자 미리보기. 프론트엔드 알림 UI 구성에 활용.
-
-멘션 확인(읽음 처리):
-
-```
-PATCH /api/v1/board/mentions/{seq}/read
-Authorization: Bearer <token>
-```
-
-```json
-{ "success": true, "data": { "read": true } }
-```
-
-> 멘션 목록 조회/읽음 처리 모두 인증이 필요하며, 본인 멘션만 조회/처리 가능해야 한다.
-
-## 7. 권한 및 보안
-
-### 7.1 권한 매트릭스
-
-| 동작                                           | 비회원                    | 일반 회원                              | 관리자 |
-| ---------------------------------------------- | ------------------------- | -------------------------------------- | ------ |
-| 목록 조회                                      | read_role 에 따름         | ✅                                     | ✅     |
-| 상세 조회                                      | read_role 에 따름         | ✅                                     | ✅     |
-| 글 작성 (원글·답글, 회원)                      | ❌                        | write_role 에 따름                     | ✅     |
-| 글 작성 (비회원 — `guest_write_enabled = "Y"`) | ✅ (비밀번호 필수)        | —                                      | ✅     |
-| 글 수정                                        | ✅ (guest-auth 토큰 필요) | 본인만                                 | ✅     |
-| 글 삭제                                        | ✅ (guest-auth 토큰 필요) | 본인만                                 | ✅     |
-| 댓글 작성                                      | ❌                        | ✅                                     | ✅     |
-| 댓글 삭제                                      | ❌                        | 본인만                                 | ✅     |
-| 파일 업로드                                    | ❌                        | write_role 에 따름                     | ✅     |
-| 파일 삭제                                      | ❌                        | 본인(글 작성자)만                      | ✅     |
-| 좋아요                                         | ❌                        | ✅ (`like_enabled = "Y"`)              | ✅     |
-| 별점 (게시글·답글)                             | ❌                        | ✅ (`rating_enabled = "Y"`)            | ✅     |
-| 별점 (댓글)                                    | ❌                        | ✅ (`rating_enabled = "Y"`)            | ✅     |
-| 답변 채택                                      | ❌                        | 원글 작성자만 (`accept_enabled = "Y"`) | ✅     |
-| 글 고정(pin)                                   | ❌                        | ❌                                     | ✅     |
-| 신고                                           | ❌                        | ✅ (중복 신고 불가)                    | ✅     |
-| 신고 관리 (목록·상태변경)                      | ❌                        | ❌                                     | ✅     |
-| 읽음 표시                                      | ❌                        | ✅ (자동 또는 명시적)                  | ✅     |
-| 카테고리 관리                                  | ❌                        | ❌                                     | ✅     |
-
-### 7.2 보안 고려사항
-
-- **XSS 방지**: content 필드는 앱서버 핸들러에서 HTML sanitize 처리
-- **비회원 비밀번호**: `guest_password`는 bcrypt(cost=10) 해시 후 저장. 조회/수정/삭제 시 `bcrypt.compare` 검증. 평문을 응답·로그에 절대 포함하지 않는다.
-- **비회원 임시 토큰**: `guest-auth` 응답 JWT는 `guest_post_seq` claim만 포함, 만료 30분. 해당 글 수정/삭제에만 사용 가능.
-- **파일 업로드**: 엔티티 서버에서 MIME 타입 검증, SHA-256 중복 감지 처리. 앱서버에서 파일 크기 사전 제한
-- **SQL Injection**: Entity Server의 parameterized query로 방어
-- **Rate Limiting**: 앱서버 rate-limit 설정 (글 작성/댓글 작성/좋아요)
-- **CSRF**: 앱서버 CSRF 플러그인 (`X-CSRF-Token` 헤더)
-- **패킷 암호화**: 앱서버 packet-encrypt 플러그인 (선택)
-
----
-
-## 8. 확장 고려사항
-
-현재 구현된 확장 기능 (이미 설계에 포함):
-
-| 기능          | 위치                                                                                                        |
-| ------------- | ----------------------------------------------------------------------------------------------------------- |
-| 비회원 글작성 | 섹션 4.1 `guest_write_enabled`, 섹션 5.4 `guestCreate` 핸들러                                               |
-| 좋아요/추천   | 섹션 4.5 `board_like`, 섹션 5.4 `likes.ts` 핸들러                                                           |
-| Push 알림     | 섹션 4.2 `board_post.after_insert` hook (`push_on_write = "Y"`)                                             |
-| 답변 채택     | 섹션 4.2 `board_post.accepted`, 섹션 5.4 `posts.accept` 핸들러                                              |
-| 별점          | 섹션 4.6 `board_rating`, 섹션 5.4 `ratings.ts` 핸들러                                                       |
-| 임시저장      | `board_post.status = "draft"`, 6.1 `status=draft` 쿼리 파라미터, 6.3/6.4 `status` 필드                      |
-| 태그          | 섹션 4.7 `board_tag`, 4.8 `board_post_tag`, 6.17 목록, 6.18 일괄 설정, `tags.ts` 핸들러                     |
-| 신고          | 섹션 4.9 `board_report`, 6.19 신고 API, 6.19.1 관리자 신고 관리 API, `reports.ts` 핸들러 (게시글·댓글 공용) |
-| 읽음 표시     | 섹션 4.10 `board_read_log`, 6.20 읽음 표시 API, `posts.markRead` 핸들러                                     |
-| 멘션          | 섹션 4.11 `board_mention`, 6.21 멘션 목록 API, 댓글/글 작성 시 `@` 파싱 후 자동 삽입                        |
-| 익명          | 섹션 4.1 `anonymous_enabled`, 핸들러에서 `author_name` 강제·`user_seq` 마스킹                               |
-
-향후 필요 시 추가 가능한 기능들:
-
-| 기능          | 구현 방안                                                |
-| ------------- | -------------------------------------------------------- |
-| 에디터 이미지 | 앱서버에 이미지 업로드 라우트 추가 → content 내 URL 삽입 |
-
----
-
-## 참고
-
-- Entity Server CRUD SDK: `entityServer.list()`, `entityServer.submit()` 등 (`@gateway/api`)
-- 앱서버 라우트 패턴: `src/app/routes/board/route.ts` (Fastify auto-prefix `/api/v1/board/`)
-- 기존 패턴 참고: `routes/account/`, `plugins/smtp/` 등의 핸들러 구조
-- 엔티티 정의: `src/app/routes/entities/*.json` 에 배치 (board_category, board_post, board_comment, board_like, board_rating, board_tag, board_post_tag, board_report, board_read_log, board_mention)
-- 파일 스토리지: 엔티티 서버 내장 files API (`/v1/files/board_post/*`), 별도 엔티티 불필요
-- 파일 SDK: `entityServer.fileUpload()`, `entityServer.fileList()`, `entityServer.fileDelete()` (`entity-server-client`)