create-entity-app-server 0.0.3

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

@@ -0,0 +1,2342 @@
+# 범용 게시판 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`)