Commit @fa3bd2d7a7ecdbe838411cfd23f3cd126f4a3e98

fa3bd2d

app/(protected)/(basic)/system/banned-words/_actions.ts (added)

+++ app/(protected)/(basic)/system/banned-words/_actions.ts

...	...	@@ -0,0 +1,93 @@
	1	+'use server';
	2	+
	3	+import { revalidatePath } from 'next/cache';
	4	+import { redirect } from 'next/navigation';
	5	+import { verifySession } from '@/lib/auth/dal';
	6	+import {
	7	+ createBannedWord,
	8	+ deleteBannedWord,
	9	+ uploadBannedWordExcel,
	10	+} from '@/lib/data/repositories/banned-word-repository';
	11	+import {
	12	+ DUPLICATE_WORD_MESSAGE,
	13	+ validateBannedWord,
	14	+ type BannedWordFormState,
	15	+ type ExcelUploadResult,
	16	+} from '@/lib/domain/banned-word-form';
	17	+import { BANNED_WORDS_PATH } from '@/lib/domain/banned-word-query';
	18	+
	19	+const SAVE_FAILED_MESSAGE = '등록하지 못했습니다. 잠시 후 다시 시도해 주세요.';
	20	+const DELETE_FAILED_MESSAGE = '삭제하지 못했습니다. 잠시 후 다시 시도해 주세요.';
	21	+const UPLOAD_FAILED_MESSAGE =
	22	+ '엑셀 파일을 등록하지 못했습니다. 잠시 후 다시 시도해 주세요.';
	23	+
	24	+function readString(formData: FormData, key: string): string {
	25	+ const value = formData.get(key);
	26	+ return typeof value === 'string' ? value : '';
	27	+}
	28	+
	29	+/** 기획 SYS_WRD_002 ② — 등록이 끝나면 목록으로 돌아간다. */
	30	+export async function createBannedWordAction(
	31	+ _prevState: BannedWordFormState,
	32	+ formData: FormData
	33	+): Promise<BannedWordFormState> {
	34	+ await verifySession();
	35	+
	36	+ const validation = validateBannedWord(readString(formData, 'word'));
	37	+ if (!validation.ok) {
	38	+ return { status: 'error', errors: validation.errors };
	39	+ }
	40	+
	41	+ let result;
	42	+ try {
	43	+ result = await createBannedWord(validation.value);
	44	+ } catch {
	45	+ return { status: 'error', message: SAVE_FAILED_MESSAGE };
	46	+ }
	47	+
	48	+ if (result.status === 'duplicate') {
	49	+ return { status: 'error', errors: { word: DUPLICATE_WORD_MESSAGE } };
	50	+ }
	51	+
	52	+ revalidatePath(BANNED_WORDS_PATH);
	53	+ redirect(BANNED_WORDS_PATH);
	54	+}
	55	+
	56	+export async function deleteBannedWordAction(
	57	+ id: number
	58	+): Promise<{ status: 'success' } \| { status: 'error'; message: string }> {
	59	+ await verifySession();
	60	+
	61	+ try {
	62	+ await deleteBannedWord(id);
	63	+ } catch {
	64	+ return { status: 'error', message: DELETE_FAILED_MESSAGE };
	65	+ }
	66	+
	67	+ revalidatePath(BANNED_WORDS_PATH);
	68	+ return { status: 'success' };
	69	+}
	70	+
	71	+export async function uploadBannedWordExcelAction(
	72	+ formData: FormData
	73	+): Promise<
	74	+ \| { status: 'success'; result: ExcelUploadResult }
	75	+ \| { status: 'error'; message: string }
	76	+> {
	77	+ await verifySession();
	78	+
	79	+ const file = formData.get('file');
	80	+ if (!(file instanceof File) \|\| file.size === 0) {
	81	+ return { status: 'error', message: '엑셀 파일을 첨부해 주세요.' };
	82	+ }
	83	+
	84	+ let result: ExcelUploadResult;
	85	+ try {
	86	+ result = await uploadBannedWordExcel(file);
	87	+ } catch {
	88	+ return { status: 'error', message: UPLOAD_FAILED_MESSAGE };
	89	+ }
	90	+
	91	+ revalidatePath(BANNED_WORDS_PATH);
	92	+ return { status: 'success', result };
	93	+}

fa3bd2d

app/(protected)/(basic)/system/banned-words/_components/banned-word-excel-modal.tsx (added)

+++ app/(protected)/(basic)/system/banned-words/_components/banned-word-excel-modal.tsx

...	...	@@ -0,0 +1,110 @@
	1	+'use client';
	2	+
	3	+import { useRef, useState, useTransition } from 'react';
	4	+import { FoxAlert } from '@fox/core/components/fox-alert';
	5	+import { FoxButton } from '@fox/core/components/fox-button';
	6	+import { FoxFileUpload } from '@fox/core/components/fox-file-upload';
	7	+import { FoxLinkButton } from '@fox/core/components/fox-link-button';
	8	+import { FoxModal } from '@fox/core/components/fox-modal';
	9	+import { useFeedback } from '@/app/_hooks/use-feedback';
	10	+import { BANNED_WORD_EXCEL_TEMPLATE_PATH } from '@/lib/domain/banned-word-query';
	11	+import { uploadBannedWordExcelAction } from '../_actions';
	12	+
	13	+interface BannedWordExcelModalProps {
	14	+ onClose: () => void;
	15	+}
	16	+
	17	+export function BannedWordExcelModal({ onClose }: BannedWordExcelModalProps) {
	18	+ const { showToast } = useFeedback();
	19	+ const formRef = useRef<HTMLFormElement>(null);
	20	+ const [errors, setErrors] = useState<string[]>([]);
	21	+ const [isPending, startUpload] = useTransition();
	22	+
	23	+ function submit() {
	24	+ const form = formRef.current;
	25	+ if (!form) {
	26	+ return;
	27	+ }
	28	+
	29	+ setErrors([]);
	30	+ startUpload(async () => {
	31	+ const result = await uploadBannedWordExcelAction(new FormData(form));
	32	+
	33	+ if (result.status === 'error') {
	34	+ showToast({ variant: 'danger', message: result.message });
	35	+ return;
	36	+ }
	37	+
	38	+ if (result.result.errors.length > 0) {
	39	+ setErrors(result.result.errors);
	40	+ return;
	41	+ }
	42	+
	43	+ showToast({
	44	+ variant: 'success',
	45	+ message: `금칙어 ${result.result.successCount}건을 등록했습니다.`,
	46	+ });
	47	+ onClose();
	48	+ });
	49	+ }
	50	+
	51	+ return (
	52	+ <FoxModal
	53	+ open
	54	+ size="sm"
	55	+ title="엑셀등록"
	56	+ onClose={onClose}
	57	+ actions={
	58	+ <>
	59	+ <FoxButton type="default" size="md" label="취소" onAction={onClose} />
	60	+ <FoxButton
	61	+ type="primary"
	62	+ size="md"
	63	+ label={isPending ? '등록 중...' : '등록'}
	64	+ disabled={isPending}
	65	+ onAction={submit}
	66	+ />
	67	+ </>
	68	+ }
	69	+ >
	70	+ <form ref={formRef}>
	71	+ <FoxAlert
	72	+ type="information"
	73	+ message="양식을 내려받아 금칙어명을 채운 뒤 올려 주세요. 한 줄이라도 형식이 맞지 않으면 전체가 등록되지 않습니다."
	74	+ />
	75	+
	76	+ <FoxLinkButton
	77	+ type="secondary"
	78	+ size="sm"
	79	+ href={BANNED_WORD_EXCEL_TEMPLATE_PATH}
	80	+ label="업로드 양식 내려받기"
	81	+ />
	82	+
	83	+ <FoxFileUpload
	84	+ mode="default"
	85	+ name="file"
	86	+ label="엑셀 파일"
	87	+ requirement="required"
	88	+ selectLabel="파일선택"
	89	+ placeholder="파일을 선택해 주세요."
	90	+ accept=".xlsx,.xls"
	91	+ />
	92	+
	93	+ {errors.length > 0 && (
	94	+ <FoxAlert
	95	+ type="danger"
	96	+ urgent
	97	+ title="엑셀 검증에 실패해 등록되지 않았습니다."
	98	+ message={
	99	+ <ul>
	100	+ {errors.map((error) => (
	101	+ <li key={error}>{error}</li>
	102	+ ))}
	103	+ </ul>
	104	+ }
	105	+ />
	106	+ )}
	107	+ </form>
	108	+ </FoxModal>
	109	+ );
	110	+}

fa3bd2d

app/(protected)/(basic)/system/banned-words/_components/banned-word-list.tsx (added)

+++ app/(protected)/(basic)/system/banned-words/_components/banned-word-list.tsx

...	...	@@ -0,0 +1,183 @@
	1	+'use client';
	2	+
	3	+import { useRouter } from 'next/navigation';
	4	+import { useState, useTransition } from 'react';
	5	+import { FoxButton } from '@fox/core/components/fox-button';
	6	+import { FoxButtonGroup } from '@fox/core/components/fox-button-group';
	7	+import { FoxIconButton } from '@fox/core/components/fox-icon-button';
	8	+import {
	9	+ FoxListContainer,
	10	+ type FoxListColumn,
	11	+} from '@fox/core/components/fox-list-container';
	12	+import { FoxSelectText } from '@fox/core/components/fox-select-text';
	13	+import {
	14	+ FoxPlusIcon,
	15	+ FoxTrashIcon,
	16	+ FoxUploadSimpleIcon,
	17	+} from '@fox/core/icons';
	18	+import { useFeedback } from '@/app/_hooks/use-feedback';
	19	+import { formatOptionalValue, type BannedWord } from '@/lib/domain/banned-word';
	20	+import {
	21	+ BANNED_WORD_NEW_PATH,
	22	+ BANNED_WORD_PAGE_SIZE_OPTIONS,
	23	+ buildBannedWordHref,
	24	+ type BannedWordPageSize,
	25	+ type BannedWordQuery,
	26	+} from '@/lib/domain/banned-word-query';
	27	+import { deleteBannedWordAction } from '../_actions';
	28	+import { BannedWordExcelModal } from './banned-word-excel-modal';
	29	+
	30	+interface BannedWordListProps {
	31	+ items: BannedWord[];
	32	+ query: BannedWordQuery;
	33	+ currentPage: number;
	34	+ totalPages: number;
	35	+ totalCount: number;
	36	+}
	37	+
	38	+export function BannedWordList({
	39	+ items,
	40	+ query,
	41	+ currentPage,
	42	+ totalPages,
	43	+ totalCount,
	44	+}: BannedWordListProps) {
	45	+ const router = useRouter();
	46	+ const { showAlert, hideAlert, showToast } = useFeedback();
	47	+ const [isExcelOpen, setIsExcelOpen] = useState(false);
	48	+ const [isDeleting, startDeleting] = useTransition();
	49	+
	50	+ function go(patch: Partial<BannedWordQuery>) {
	51	+ router.replace(buildBannedWordHref(query, { ...patch, page: 1 }));
	52	+ }
	53	+
	54	+ function runDelete(word: BannedWord) {
	55	+ hideAlert();
	56	+ startDeleting(async () => {
	57	+ const result = await deleteBannedWordAction(word.id);
	58	+ if (result.status === 'error') {
	59	+ showToast({ variant: 'danger', message: result.message });
	60	+ return;
	61	+ }
	62	+ showToast({ variant: 'success', message: '금칙어를 삭제했습니다.' });
	63	+ });
	64	+ }
	65	+
	66	+ function confirmDelete(word: BannedWord) {
	67	+ showAlert({
	68	+ variant: 'danger',
	69	+ title: '금칙어를 삭제하시겠습니까?',
	70	+ message: `"${word.word}"를 삭제합니다. 삭제 후에는 되돌릴 수 없습니다.`,
	71	+ actions: (
	72	+ <FoxButtonGroup size="md">
	73	+ <FoxButton type="default" size="md" label="취소" onAction={hideAlert} />
	74	+ <FoxButton
	75	+ type="primary"
	76	+ size="md"
	77	+ label="삭제"
	78	+ onAction={() => runDelete(word)}
	79	+ />
	80	+ </FoxButtonGroup>
	81	+ ),
	82	+ });
	83	+ }
	84	+
	85	+ const columns: FoxListColumn<BannedWord>[] = [
	86	+ {
	87	+ key: 'no',
	88	+ header: '번호',
	89	+ width: 100,
	90	+ render: (_row, index) => (currentPage - 1) * query.pageSize + index + 1,
	91	+ },
	92	+ { key: 'word', header: '금지 키워드', width: 400, emphasis: true },
	93	+ {
	94	+ key: 'createdAt',
	95	+ header: '등록일',
	96	+ width: 200,
	97	+ render: (row) => formatOptionalValue(row.createdAt),
	98	+ },
	99	+ {
	100	+ key: 'actions',
	101	+ header: '관리',
	102	+ width: 100,
	103	+ render: (row) => (
	104	+ <FoxIconButton
	105	+ type="default"
	106	+ size="sm"
	107	+ icon={<FoxTrashIcon />}
	108	+ label={isDeleting ? '삭제 중' : '삭제'}
	109	+ disabled={isDeleting}
	110	+ onAction={() => confirmDelete(row)}
	111	+ />
	112	+ ),
	113	+ },
	114	+ ];
	115	+
	116	+ return (
	117	+ <>
	118	+ <FoxListContainer<BannedWord>
	119	+ title="금칙어관리"
	120	+ breadcrumb={[
	121	+ { label: '홈', href: '/' },
	122	+ { label: '시스템관리' },
	123	+ { label: '금칙어관리' },
	124	+ ]}
	125	+ caption="금칙어 목록"
	126	+ columns={columns}
	127	+ rows={items}
	128	+ rowKey={(row) => String(row.id)}
	129	+ totalCount={totalCount}
	130	+ emptyMessage="검색결과가 없습니다."
	131	+ sorts={
	132	+ <FoxSelectText
	133	+ size="sm"
	134	+ ariaLabel="페이지 크기"
	135	+ options={BANNED_WORD_PAGE_SIZE_OPTIONS.map((size) => ({
	136	+ value: String(size),
	137	+ label: `${size}개씩 보기`,
	138	+ }))}
	139	+ value={String(query.pageSize)}
	140	+ onValueChange={(value) =>
	141	+ go({ pageSize: Number(value) as BannedWordPageSize })
	142	+ }
	143	+ />
	144	+ }
	145	+ searchFields={[]}
	146	+ keyword={query.keyword}
	147	+ searchPlaceholder="금칙어를 입력하세요."
	148	+ toolbarActions={
	149	+ <>
	150	+ <FoxButton
	151	+ type="secondary"
	152	+ size="md"
	153	+ leadingIcon={<FoxUploadSimpleIcon />}
	154	+ label="엑셀등록"
	155	+ onAction={() => setIsExcelOpen(true)}
	156	+ />
	157	+ <FoxButton
	158	+ type="primary"
	159	+ size="md"
	160	+ leadingIcon={<FoxPlusIcon />}
	161	+ label="등록"
	162	+ onAction={() => router.push(BANNED_WORD_NEW_PATH)}
	163	+ />
	164	+ </>
	165	+ }
	166	+ page={currentPage}
	167	+ totalPages={totalPages}
	168	+ buildHref={(patch) =>
	169	+ buildBannedWordHref(query, { page: Number(patch.page ?? 1) })
	170	+ }
	171	+ onQueryChange={(patch) => {
	172	+ if (patch.keyword !== undefined) {
	173	+ go({ keyword: String(patch.keyword ?? '') });
	174	+ }
	175	+ }}
	176	+ />
	177	+
	178	+ {isExcelOpen && (
	179	+ <BannedWordExcelModal onClose={() => setIsExcelOpen(false)} />
	180	+ )}
	181	+ </>
	182	+ );
	183	+}

fa3bd2d

app/(protected)/(basic)/system/banned-words/excel-template/route.ts (added)

+++ app/(protected)/(basic)/system/banned-words/excel-template/route.ts

...	...	@@ -0,0 +1,36 @@
	1	+import { getSessionAccessToken, verifySession } from '@/lib/auth/dal';
	2	+import { backendFetchStream } from '@/lib/http/backend-fetch';
	3	+
	4	+const TEMPLATE_PATH = '/api/v1/mngr/benWord/excel/template';
	5	+const DOWNLOAD_FAILED_MESSAGE =
	6	+ '양식을 내려받지 못했습니다. 잠시 후 다시 시도해 주세요.';
	7	+const XLSX_CONTENT_TYPE =
	8	+ 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
	9	+
	10	+export async function GET() {
	11	+ await verifySession();
	12	+
	13	+ const accessToken = await getSessionAccessToken();
	14	+ const result = await backendFetchStream(TEMPLATE_PATH, {
	15	+ accessToken: accessToken ?? undefined,
	16	+ });
	17	+
	18	+ if (!result.ok) {
	19	+ return new Response(DOWNLOAD_FAILED_MESSAGE, {
	20	+ status: 502,
	21	+ headers: { 'Content-Type': 'text/plain; charset=utf-8' },
	22	+ });
	23	+ }
	24	+
	25	+ const upstream = result.data;
	26	+
	27	+ return new Response(upstream.body, {
	28	+ status: 200,
	29	+ headers: {
	30	+ 'Content-Type': upstream.headers.get('content-type') ?? XLSX_CONTENT_TYPE,
	31	+ 'Content-Disposition':
	32	+ upstream.headers.get('content-disposition') ??
	33	+ 'attachment; filename="banned-words-template.xlsx"',
	34	+ },
	35	+ });
	36	+}

fa3bd2d

app/(protected)/(basic)/system/banned-words/new/_components/banned-word-form.module.scss (added)

+++ app/(protected)/(basic)/system/banned-words/new/_components/banned-word-form.module.scss

...	...	@@ -0,0 +1,14 @@
	1	+@use "@fox/styles/abstracts" as fox;
	2	+
	3	+.page {
	4	+ display: flex;
	5	+ flex-direction: column;
	6	+ gap: fox.gap(6);
	7	+}
	8	+
	9	+.actions {
	10	+ display: flex;
	11	+ justify-content: center;
	12	+ gap: fox.gap(3);
	13	+ padding-block-start: fox.spacing(top-md);
	14	+}

fa3bd2d

app/(protected)/(basic)/system/banned-words/new/_components/banned-word-form.tsx (added)

+++ app/(protected)/(basic)/system/banned-words/new/_components/banned-word-form.tsx

...	...	@@ -0,0 +1,89 @@
	1	+'use client';
	2	+
	3	+import { useRouter } from 'next/navigation';
	4	+import { useActionState, useRef } from 'react';
	5	+import { FoxAlert } from '@fox/core/components/fox-alert';
	6	+import { FoxButton } from '@fox/core/components/fox-button';
	7	+import { FoxInput } from '@fox/core/components/fox-input';
	8	+import { FoxPageHeader } from '@fox/core/components/fox-page-header';
	9	+import { FoxTable } from '@fox/core/components/fox-table';
	10	+import { FoxTableCell } from '@fox/core/components/fox-table-cell';
	11	+import { FoxTableRow } from '@fox/core/components/fox-table-row';
	12	+import { submitFormAction } from '@/app/_hooks/submit-form-action';
	13	+import {
	14	+ INITIAL_BANNED_WORD_FORM_STATE,
	15	+ WORD_MAX_LENGTH,
	16	+} from '@/lib/domain/banned-word-form';
	17	+import { BANNED_WORDS_PATH } from '@/lib/domain/banned-word-query';
	18	+import { createBannedWordAction } from '../../_actions';
	19	+import styles from './banned-word-form.module.scss';
	20	+
	21	+export function BannedWordForm() {
	22	+ const router = useRouter();
	23	+ const formRef = useRef<HTMLFormElement>(null);
	24	+ const [state, formAction, isPending] = useActionState(
	25	+ createBannedWordAction,
	26	+ INITIAL_BANNED_WORD_FORM_STATE
	27	+ );
	28	+
	29	+ const errors = state.status === 'error' ? (state.errors ?? {}) : {};
	30	+
	31	+ return (
	32	+ <div className={styles.page}>
	33	+ <FoxPageHeader
	34	+ title="금칙어 등록"
	35	+ breadcrumb={[
	36	+ { label: '홈', href: '/' },
	37	+ { label: '시스템관리' },
	38	+ { label: '금칙어관리', href: BANNED_WORDS_PATH },
	39	+ { label: '금칙어 등록' },
	40	+ ]}
	41	+ />
	42	+
	43	+ <FoxAlert
	44	+ type="information"
	45	+ message="키워드를 등록한 이후부터 해당 키워드를 사용하는 경우 바로 적용됩니다."
	46	+ />
	47	+
	48	+ <form
	49	+ ref={formRef}
	50	+ onSubmit={(event) => submitFormAction(event, formAction)}
	51	+ >
	52	+ <FoxTable type="form" caption="금칙어 등록">
	53	+ <FoxTableRow>
	54	+ <FoxTableCell head width={200}>
	55	+ 키워드 *
	56	+ </FoxTableCell>
	57	+ <FoxTableCell>
	58	+ <FoxInput
	59	+ size="md"
	60	+ name="word"
	61	+ aria-label="키워드"
	62	+ placeholder="키워드를 입력하세요."
	63	+ maxLength={WORD_MAX_LENGTH}
	64	+ invalid={Boolean(errors.word)}
	65	+ message={errors.word}
	66	+ />
	67	+ </FoxTableCell>
	68	+ </FoxTableRow>
	69	+ </FoxTable>
	70	+
	71	+ <div className={styles.actions}>
	72	+ <FoxButton
	73	+ type="primary"
	74	+ size="md"
	75	+ label={isPending ? '등록 중...' : '등록'}
	76	+ disabled={isPending}
	77	+ onAction={() => formRef.current?.requestSubmit()}
	78	+ />
	79	+ <FoxButton
	80	+ type="default"
	81	+ size="md"
	82	+ label="목록"
	83	+ onAction={() => router.push(BANNED_WORDS_PATH)}
	84	+ />
	85	+ </div>
	86	+ </form>
	87	+ </div>
	88	+ );
	89	+}

fa3bd2d

app/(protected)/(basic)/system/banned-words/new/page.tsx (added)

+++ app/(protected)/(basic)/system/banned-words/new/page.tsx

...	...	@@ -0,0 +1,10 @@
	1	+import { verifySession } from '@/lib/auth/dal';
	2	+import { BannedWordForm } from './_components/banned-word-form';
	3	+
	4	+export const dynamic = 'force-dynamic';
	5	+
	6	+export default async function Page() {
	7	+ await verifySession();
	8	+
	9	+ return <BannedWordForm />;
	10	+}

fa3bd2d

app/(protected)/(basic)/system/banned-words/page.tsx (added)

+++ app/(protected)/(basic)/system/banned-words/page.tsx

...	...	@@ -0,0 +1,30 @@
	1	+import { verifySession } from '@/lib/auth/dal';
	2	+import { fetchBannedWords } from '@/lib/data/repositories/banned-word-repository';
	3	+import { parseBannedWordQuery } from '@/lib/domain/banned-word-query';
	4	+import { BannedWordList } from './_components/banned-word-list';
	5	+
	6	+export const dynamic = 'force-dynamic';
	7	+
	8	+interface PageProps {
	9	+ searchParams: Promise<Record<string, string \| string[] \| undefined>>;
	10	+}
	11	+
	12	+export default async function Page({ searchParams }: PageProps) {
	13	+ await verifySession();
	14	+
	15	+ const query = parseBannedWordQuery(await searchParams);
	16	+ const { items, totalCount } = await fetchBannedWords(query);
	17	+
	18	+ const totalPages = Math.max(1, Math.ceil(totalCount / query.pageSize));
	19	+ const currentPage = Math.min(query.page, totalPages);
	20	+
	21	+ return (
	22	+ <BannedWordList
	23	+ items={items}
	24	+ query={query}
	25	+ currentPage={currentPage}
	26	+ totalPages={totalPages}
	27	+ totalCount={totalCount}
	28	+ />
	29	+ );
	30	+}

fa3bd2d

app/(protected)/(basic)/system/menus/_actions.ts (added)

+++ app/(protected)/(basic)/system/menus/_actions.ts

...	...	@@ -0,0 +1,112 @@
	1	+'use server';
	2	+
	3	+import { revalidatePath } from 'next/cache';
	4	+import { verifySession } from '@/lib/auth/dal';
	5	+import { uploadAttachment } from '@/lib/data/repositories/file-repository';
	6	+import {
	7	+ createSystemMenu,
	8	+ deleteSystemMenu,
	9	+ updateSystemMenu,
	10	+} from '@/lib/data/repositories/system-menu-repository';
	11	+import { FILE_MODULE } from '@/lib/domain/file-module';
	12	+import {
	13	+ validateSystemMenu,
	14	+ type SystemMenuFormState,
	15	+} from '@/lib/domain/system-menu-form';
	16	+
	17	+const SYSTEM_MENUS_PATH = '/system/menus';
	18	+const SAVE_FAILED_MESSAGE = '저장하지 못했습니다. 잠시 후 다시 시도해 주세요.';
	19	+const DELETE_FAILED_MESSAGE = '삭제하지 못했습니다. 잠시 후 다시 시도해 주세요.';
	20	+const UPLOAD_FAILED_MESSAGE = '아이콘을 올리지 못했습니다. 잠시 후 다시 시도해 주세요.';
	21	+
	22	+function readString(formData: FormData, key: string): string {
	23	+ const value = formData.get(key);
	24	+ return typeof value === 'string' ? value : '';
	25	+}
	26	+
	27	+function parseFormNumber(formData: FormData, key: string): number {
	28	+ const trimmed = readString(formData, key).trim();
	29	+ return trimmed === '' ? NaN : Number(trimmed);
	30	+}
	31	+
	32	+/**
	33	+ * 아이콘 칸의 결과 파일 아이디. 새 파일을 고르면 올려서 그 아이디를, 아니면 기존 아이디를
	34	+ * 쓴다. 비운 경우 빈 문자열을 보내 컬럼을 지운다.
	35	+ */
	36	+async function resolveIconId(
	37	+ formData: FormData,
	38	+ fileKey: string,
	39	+ currentKey: string
	40	+): Promise<string> {
	41	+ const picked = formData.get(fileKey);
	42	+
	43	+ if (picked instanceof File && picked.size > 0) {
	44	+ return uploadAttachment(picked, FILE_MODULE.menuIcon.id);
	45	+ }
	46	+
	47	+ return readString(formData, currentKey);
	48	+}
	49	+
	50	+async function readValues(formData: FormData) {
	51	+ return {
	52	+ id: readString(formData, 'id'),
	53	+ parentId: readString(formData, 'parentId'),
	54	+ parentIdPath: readString(formData, 'parentIdPath'),
	55	+ name: readString(formData, 'name'),
	56	+ sortOrder: parseFormNumber(formData, 'sortOrder'),
	57	+ roleId: readString(formData, 'roleId'),
	58	+ isTopActive: readString(formData, 'isTopActive') === 'Y',
	59	+ url: readString(formData, 'url'),
	60	+ description: readString(formData, 'description'),
	61	+ largeIconId: await resolveIconId(formData, 'largeIcon', 'largeIconId'),
	62	+ smallIconId: await resolveIconId(formData, 'smallIcon', 'smallIconId'),
	63	+ isActive: readString(formData, 'isActive') === 'Y',
	64	+ };
	65	+}
	66	+
	67	+export async function saveSystemMenuAction(
	68	+ _prevState: SystemMenuFormState,
	69	+ formData: FormData
	70	+): Promise<SystemMenuFormState> {
	71	+ await verifySession();
	72	+
	73	+ let values;
	74	+ try {
	75	+ values = await readValues(formData);
	76	+ } catch {
	77	+ return { status: 'error', message: UPLOAD_FAILED_MESSAGE };
	78	+ }
	79	+
	80	+ const validation = validateSystemMenu(values);
	81	+ if (!validation.ok) {
	82	+ return { status: 'error', errors: validation.errors };
	83	+ }
	84	+
	85	+ try {
	86	+ if (validation.values.id) {
	87	+ await updateSystemMenu(validation.values);
	88	+ } else {
	89	+ await createSystemMenu(validation.values);
	90	+ }
	91	+ } catch {
	92	+ return { status: 'error', message: SAVE_FAILED_MESSAGE };
	93	+ }
	94	+
	95	+ revalidatePath(SYSTEM_MENUS_PATH);
	96	+ return { status: 'success' };
	97	+}
	98	+
	99	+export async function deleteSystemMenuAction(
	100	+ menuId: string
	101	+): Promise<{ status: 'success' } \| { status: 'error'; message: string }> {
	102	+ await verifySession();
	103	+
	104	+ try {
	105	+ await deleteSystemMenu(menuId);
	106	+ } catch {
	107	+ return { status: 'error', message: DELETE_FAILED_MESSAGE };
	108	+ }
	109	+
	110	+ revalidatePath(SYSTEM_MENUS_PATH);
	111	+ return { status: 'success' };
	112	+}

fa3bd2d

app/(protected)/(basic)/system/menus/_components/menu-form-modal.tsx (added)

+++ app/(protected)/(basic)/system/menus/_components/menu-form-modal.tsx

...	...	@@ -0,0 +1,285 @@
	1	+'use client';
	2	+
	3	+import { useActionState, useEffect, useRef, useState } from 'react';
	4	+import { FoxButton } from '@fox/core/components/fox-button';
	5	+import { FoxFileUpload } from '@fox/core/components/fox-file-upload';
	6	+import { FoxFormLabel } from '@fox/core/components/fox-form-label';
	7	+import { FoxHelperText } from '@fox/core/components/fox-helper-text';
	8	+import { FoxInput } from '@fox/core/components/fox-input';
	9	+import { FoxModal } from '@fox/core/components/fox-modal';
	10	+import { FoxSelect } from '@fox/core/components/fox-select';
	11	+import { FoxToggleSwitch } from '@fox/core/components/fox-toggle-switch';
	12	+import { submitFormAction } from '@/app/_hooks/submit-form-action';
	13	+import { useFeedback } from '@/app/_hooks/use-feedback';
	14	+import { fileModuleAccept, FILE_MODULE } from '@/lib/domain/file-module';
	15	+import {
	16	+ formatParentLabel,
	17	+ type SystemMenu,
	18	+ type SystemMenuNode,
	19	+} from '@/lib/domain/system-menu';
	20	+import {
	21	+ DESCRIPTION_MAX_LENGTH,
	22	+ INITIAL_SYSTEM_MENU_FORM_STATE,
	23	+ NAME_MAX_LENGTH,
	24	+ URL_MAX_LENGTH,
	25	+} from '@/lib/domain/system-menu-form';
	26	+import { saveSystemMenuAction } from '../_actions';
	27	+import styles from './menu-form.module.scss';
	28	+
	29	+interface MenuFormModalProps {
	30	+ mode: 'create' \| 'edit';
	31	+ /** 수정 대상. 추가일 때는 비어 있다. */
	32	+ menu?: SystemMenuNode;
	33	+ /** 추가일 때의 상위 메뉴. 수정일 때는 대상의 상위다. */
	34	+ parent: SystemMenu \| null;
	35	+ roleOptions: { value: string; label: string }[];
	36	+ onClose: () => void;
	37	+}
	38	+
	39	+const ICON_ACCEPT = fileModuleAccept(FILE_MODULE.menuIcon);
	40	+const ICON_HINT =
	41	+ '이미지 파일만 업로드 가능 (jpg, png, svg 등). 앱 화면에서 메뉴 표시 시 사용됩니다.';
	42	+
	43	+export function MenuFormModal({
	44	+ mode,
	45	+ menu,
	46	+ parent,
	47	+ roleOptions,
	48	+ onClose,
	49	+}: MenuFormModalProps) {
	50	+ const isCreate = mode === 'create';
	51	+ const { showToast } = useFeedback();
	52	+ const formRef = useRef<HTMLFormElement>(null);
	53	+ const [state, formAction, isPending] = useActionState(
	54	+ saveSystemMenuAction,
	55	+ INITIAL_SYSTEM_MENU_FORM_STATE
	56	+ );
	57	+
	58	+ const [roleId, setRoleId] = useState(menu?.roleId ?? roleOptions[0]?.value ?? '');
	59	+ const [isTopActive, setIsTopActive] = useState(menu?.isTopActive ?? false);
	60	+ const [isActive, setIsActive] = useState(menu?.isActive ?? true);
	61	+ // 새창여부는 저장할 컬럼이 없어 화면에만 둔다(사용자 확정).
	62	+ const [opensNewWindow, setOpensNewWindow] = useState(false);
	63	+ const [largeIconId, setLargeIconId] = useState(menu?.largeIconId ?? '');
	64	+ const [smallIconId, setSmallIconId] = useState(menu?.smallIconId ?? '');
	65	+
	66	+ useEffect(() => {
	67	+ if (state.status === 'success') {
	68	+ showToast({
	69	+ variant: 'success',
	70	+ message: isCreate ? '메뉴를 등록했습니다.' : '메뉴를 수정했습니다.',
	71	+ });
	72	+ onClose();
	73	+ }
	74	+ }, [state, showToast, onClose, isCreate]);
	75	+
	76	+ const errors = state.status === 'error' ? (state.errors ?? {}) : {};
	77	+ const parentLabel = formatParentLabel(parent);
	78	+
	79	+ function iconFiles(id: string, name: string \| null, url: string \| null) {
	80	+ return id
	81	+ ? [{ id, name: name ?? '등록된 아이콘', previewUrl: url ?? undefined }]
	82	+ : [];
	83	+ }
	84	+
	85	+ return (
	86	+ <FoxModal
	87	+ open
	88	+ size="md"
	89	+ title={isCreate ? '신규 등록' : '메뉴 수정'}
	90	+ onClose={onClose}
	91	+ actions={
	92	+ <>
	93	+ <FoxButton type="default" size="md" label="취소" onAction={onClose} />
	94	+ <FoxButton
	95	+ type="primary"
	96	+ size="md"
	97	+ label={isPending ? '저장 중...' : isCreate ? '저장' : '수정'}
	98	+ disabled={isPending}
	99	+ onAction={() => formRef.current?.requestSubmit()}
	100	+ />
	101	+ </>
	102	+ }
	103	+ >
	104	+ <form
	105	+ ref={formRef}
	106	+ onSubmit={(event) => submitFormAction(event, formAction)}
	107	+ className={styles.fields}
	108	+ >
	109	+ <input type="hidden" name="id" value={menu?.id ?? ''} />
	110	+ <input type="hidden" name="parentId" value={parent?.id ?? ''} />
	111	+ <input type="hidden" name="parentIdPath" value={parent?.idPath ?? ''} />
	112	+ <input type="hidden" name="roleId" value={roleId} />
	113	+ <input type="hidden" name="isTopActive" value={isTopActive ? 'Y' : 'N'} />
	114	+ <input type="hidden" name="isActive" value={isActive ? 'Y' : 'N'} />
	115	+ <input type="hidden" name="largeIconId" value={largeIconId} />
	116	+ <input type="hidden" name="smallIconId" value={smallIconId} />
	117	+
	118	+ {/* 기획 ① 상위 메뉴가 없으면(최상위 등록) 이 칸을 감춘다. */}
	119	+ {parentLabel && (
	120	+ <div className={styles.field}>
	121	+ <FoxInput
	122	+ size="md"
	123	+ label="상위메뉴명"
	124	+ requirement="required"
	125	+ value={parentLabel}
	126	+ readOnly
	127	+ state="view"
	128	+ />
	129	+ </div>
	130	+ )}
	131	+
	132	+ <div className={styles.field}>
	133	+ <FoxInput
	134	+ size="md"
	135	+ name="name"
	136	+ label="메뉴명"
	137	+ requirement="required"
	138	+ defaultValue={menu?.name ?? ''}
	139	+ placeholder="메뉴명을 입력하세요."
	140	+ maxLength={NAME_MAX_LENGTH}
	141	+ invalid={Boolean(errors.name)}
	142	+ message={errors.name}
	143	+ />
	144	+ </div>
	145	+
	146	+ <div className={styles.field}>
	147	+ <div className={styles.narrow}>
	148	+ <FoxInput
	149	+ size="md"
	150	+ name="sortOrder"
	151	+ type="number"
	152	+ inputMode="numeric"
	153	+ min={1}
	154	+ label="메뉴순번"
	155	+ requirement="required"
	156	+ defaultValue={String(menu?.sortOrder ?? 1)}
	157	+ invalid={Boolean(errors.sortOrder)}
	158	+ message={errors.sortOrder}
	159	+ />
	160	+ </div>
	161	+ </div>
	162	+
	163	+ <div className={styles.field}>
	164	+ <FoxSelect
	165	+ size="md"
	166	+ label="메뉴권한"
	167	+ requirement="required"
	168	+ options={roleOptions}
	169	+ value={roleId}
	170	+ onValueChange={setRoleId}
	171	+ error={Boolean(errors.roleId)}
	172	+ hint={errors.roleId}
	173	+ />
	174	+ </div>
	175	+
	176	+ <div className={styles.field}>
	177	+ <FoxFormLabel as="span" requirement="required">
	178	+ 최상위권한활성
	179	+ </FoxFormLabel>
	180	+ <FoxToggleSwitch
	181	+ size="md"
	182	+ label={isTopActive ? '활성' : '비활성'}
	183	+ checked={isTopActive}
	184	+ onChange={setIsTopActive}
	185	+ />
	186	+ </div>
	187	+
	188	+ <div className={styles.field}>
	189	+ <FoxInput
	190	+ size="md"
	191	+ name="url"
	192	+ label="메뉴링크"
	193	+ requirement="required"
	194	+ defaultValue={menu?.url ?? ''}
	195	+ placeholder="메뉴링크를 입력하세요."
	196	+ maxLength={URL_MAX_LENGTH}
	197	+ invalid={Boolean(errors.url)}
	198	+ message={errors.url}
	199	+ />
	200	+ </div>
	201	+
	202	+ <div className={styles.field}>
	203	+ <FoxFormLabel as="span" requirement="required">
	204	+ 새창여부
	205	+ </FoxFormLabel>
	206	+ <FoxToggleSwitch
	207	+ size="md"
	208	+ label={opensNewWindow ? '예' : '아니오'}
	209	+ checked={opensNewWindow}
	210	+ onChange={setOpensNewWindow}
	211	+ />
	212	+ {/* TODO(백엔드): TB_SYS_MENU에 새창여부 컬럼이 없어 저장되지 않는다. */}
	213	+ <FoxHelperText
	214	+ type="information"
	215	+ message="저장되지 않는 항목입니다. 백엔드에 컬럼이 추가되면 연결됩니다."
	216	+ />
	217	+ </div>
	218	+
	219	+ <div className={styles.field}>
	220	+ <FoxInput
	221	+ size="md"
	222	+ name="description"
	223	+ label="메뉴설명"
	224	+ requirement="required"
	225	+ defaultValue={menu?.description ?? ''}
	226	+ placeholder="메뉴설명을 입력하세요."
	227	+ maxLength={DESCRIPTION_MAX_LENGTH}
	228	+ invalid={Boolean(errors.description)}
	229	+ message={errors.description}
	230	+ />
	231	+ </div>
	232	+
	233	+ <div className={styles.field}>
	234	+ <FoxFileUpload
	235	+ mode="image"
	236	+ name="largeIcon"
	237	+ label="큰 아이콘"
	238	+ selectLabel="파일선택"
	239	+ accept={ICON_ACCEPT}
	240	+ defaultFiles={iconFiles(
	241	+ largeIconId,
	242	+ menu?.largeIconName ?? null,
	243	+ menu?.largeIconUrl ?? null
	244	+ )}
	245	+ onRemove={() => setLargeIconId('')}
	246	+ />
	247	+ <span className={styles.iconHint}>{ICON_HINT}</span>
	248	+ </div>
	249	+
	250	+ <div className={styles.field}>
	251	+ <FoxFileUpload
	252	+ mode="image"
	253	+ name="smallIcon"
	254	+ label="작은 아이콘"
	255	+ selectLabel="파일선택"
	256	+ accept={ICON_ACCEPT}
	257	+ defaultFiles={iconFiles(
	258	+ smallIconId,
	259	+ menu?.smallIconName ?? null,
	260	+ menu?.smallIconUrl ?? null
	261	+ )}
	262	+ onRemove={() => setSmallIconId('')}
	263	+ />
	264	+ <span className={styles.iconHint}>{ICON_HINT}</span>
	265	+ </div>
	266	+
	267	+ <div className={styles.field}>
	268	+ <FoxFormLabel as="span" requirement="required">
	269	+ 활성여부
	270	+ </FoxFormLabel>
	271	+ <FoxToggleSwitch
	272	+ size="md"
	273	+ label={isActive ? '사용' : '미사용'}
	274	+ checked={isActive}
	275	+ onChange={setIsActive}
	276	+ />
	277	+ </div>
	278	+
	279	+ {state.status === 'error' && state.message && (
	280	+ <FoxHelperText type="danger" message={state.message} />
	281	+ )}
	282	+ </form>
	283	+ </FoxModal>
	284	+ );
	285	+}

fa3bd2d

app/(protected)/(basic)/system/menus/_components/menu-form.module.scss (added)

+++ app/(protected)/(basic)/system/menus/_components/menu-form.module.scss

...	...	@@ -0,0 +1,25 @@
	1	+@use "@fox/styles/abstracts" as fox;
	2	+
	3	+.fields {
	4	+ display: flex;
	5	+ inline-size: 100%;
	6	+ flex-direction: column;
	7	+}
	8	+
	9	+.field {
	10	+ display: flex;
	11	+ inline-size: 100%;
	12	+ flex-direction: column;
	13	+ gap: fox.gap(3);
	14	+ padding-block: fox.padding(6);
	15	+ border-block-end: fox.border(1) solid fox.color(border-neutral-subtler);
	16	+}
	17	+
	18	+.narrow {
	19	+ inline-size: 20rem;
	20	+}
	21	+
	22	+.iconHint {
	23	+ color: fox.color(font-neutral-subtler);
	24	+ font-size: fox.font-size(label-sm);
	25	+}

fa3bd2d

app/(protected)/(basic)/system/menus/_components/menu-row-actions.tsx (added)

+++ app/(protected)/(basic)/system/menus/_components/menu-row-actions.tsx

...	...	@@ -0,0 +1,82 @@
	1	+'use client';
	2	+
	3	+import { useTransition } from 'react';
	4	+import { FoxButton } from '@fox/core/components/fox-button';
	5	+import { FoxButtonGroup } from '@fox/core/components/fox-button-group';
	6	+import { FoxIconButton } from '@fox/core/components/fox-icon-button';
	7	+import {
	8	+ FoxPencilSimpleIcon,
	9	+ FoxPlusIcon,
	10	+ FoxTrashIcon,
	11	+} from '@fox/core/icons';
	12	+import { useFeedback } from '@/app/_hooks/use-feedback';
	13	+import type { SystemMenuNode } from '@/lib/domain/system-menu';
	14	+import { deleteSystemMenuAction } from '../_actions';
	15	+import styles from './menu-tree.module.scss';
	16	+
	17	+interface MenuRowActionsProps {
	18	+ node: SystemMenuNode;
	19	+ onEdit: (node: SystemMenuNode) => void;
	20	+ onAddChild: (node: SystemMenuNode) => void;
	21	+}
	22	+
	23	+export function MenuRowActions({ node, onEdit, onAddChild }: MenuRowActionsProps) {
	24	+ const { showAlert, hideAlert, showToast } = useFeedback();
	25	+ const [isDeleting, startDeleting] = useTransition();
	26	+
	27	+ function runDelete() {
	28	+ hideAlert();
	29	+ startDeleting(async () => {
	30	+ const result = await deleteSystemMenuAction(node.id);
	31	+ if (result.status === 'error') {
	32	+ showToast({ variant: 'danger', message: result.message });
	33	+ return;
	34	+ }
	35	+ showToast({ variant: 'success', message: '메뉴를 삭제했습니다.' });
	36	+ });
	37	+ }
	38	+
	39	+ function confirmDelete() {
	40	+ showAlert({
	41	+ variant: 'danger',
	42	+ title: '메뉴를 삭제하시겠습니까?',
	43	+ message:
	44	+ node.children.length > 0
	45	+ ? `"${node.name}" 아래에 하위 메뉴 ${node.children.length}개가 있습니다. 삭제 후에는 되돌릴 수 없습니다.`
	46	+ : `"${node.name}" 메뉴를 삭제합니다. 삭제 후에는 되돌릴 수 없습니다.`,
	47	+ actions: (
	48	+ <FoxButtonGroup size="md">
	49	+ <FoxButton type="default" size="md" label="취소" onAction={hideAlert} />
	50	+ <FoxButton type="primary" size="md" label="삭제" onAction={runDelete} />
	51	+ </FoxButtonGroup>
	52	+ ),
	53	+ });
	54	+ }
	55	+
	56	+ return (
	57	+ <div className={styles.actions}>
	58	+ <FoxIconButton
	59	+ type="default"
	60	+ size="sm"
	61	+ icon={<FoxPencilSimpleIcon />}
	62	+ label="수정"
	63	+ onAction={() => onEdit(node)}
	64	+ />
	65	+ <FoxIconButton
	66	+ type="default"
	67	+ size="sm"
	68	+ icon={<FoxPlusIcon />}
	69	+ label="하위 메뉴 추가"
	70	+ onAction={() => onAddChild(node)}
	71	+ />
	72	+ <FoxIconButton
	73	+ type="default"
	74	+ size="sm"
	75	+ icon={<FoxTrashIcon />}
	76	+ label={isDeleting ? '삭제 중' : '삭제'}
	77	+ disabled={isDeleting}
	78	+ onAction={confirmDelete}
	79	+ />
	80	+ </div>
	81	+ );
	82	+}

fa3bd2d

app/(protected)/(basic)/system/menus/_components/menu-tree-list.tsx (added)

+++ app/(protected)/(basic)/system/menus/_components/menu-tree-list.tsx

...	...	@@ -0,0 +1,182 @@
	1	+'use client';
	2	+
	3	+import { useMemo, useState } from 'react';
	4	+import {
	5	+ FoxListContainer,
	6	+ type FoxListColumn,
	7	+} from '@fox/core/components/fox-list-container';
	8	+import { FoxStatusIndicator } from '@fox/core/components/fox-status-indicator';
	9	+import {
	10	+ FoxCaretDownIcon,
	11	+ FoxCaretRightIcon,
	12	+ FoxFileIcon,
	13	+ FoxFolderIcon,
	14	+} from '@fox/core/icons';
	15	+import {
	16	+ buildMenuTree,
	17	+ collectNodeIds,
	18	+ collectRoleOptions,
	19	+ flattenOpenNodes,
	20	+ formatActiveLabel,
	21	+ formatOptionalValue,
	22	+ type SystemMenu,
	23	+ type SystemMenuNode,
	24	+} from '@/lib/domain/system-menu';
	25	+import { MenuFormModal } from './menu-form-modal';
	26	+import { MenuRowActions } from './menu-row-actions';
	27	+import styles from './menu-tree.module.scss';
	28	+
	29	+interface MenuTreeListProps {
	30	+ items: SystemMenu[];
	31	+}
	32	+
	33	+type FormTarget =
	34	+ \| { mode: 'edit'; node: SystemMenuNode }
	35	+ \| { mode: 'create'; parent: SystemMenuNode };
	36	+
	37	+/** 깊이만큼 이름을 밀어 넣는다. 표 칸이라 여백은 인라인으로 준다. */
	38	+const INDENT_REM = 2;
	39	+
	40	+export function MenuTreeList({ items }: MenuTreeListProps) {
	41	+ const tree = useMemo(() => buildMenuTree(items), [items]);
	42	+ const roleOptions = useMemo(() => collectRoleOptions(items), [items]);
	43	+ const byId = useMemo(() => new Map(items.map((item) => [item.id, item])), [items]);
	44	+
	45	+ const [closedIds, setClosedIds] = useState<Set<string>>(new Set());
	46	+ const [target, setTarget] = useState<FormTarget \| null>(null);
	47	+
	48	+ const isOpen = (id: string) => !closedIds.has(id);
	49	+
	50	+ function toggle(id: string) {
	51	+ setClosedIds((prev) => {
	52	+ const next = new Set(prev);
	53	+ if (next.has(id)) {
	54	+ next.delete(id);
	55	+ } else {
	56	+ next.add(id);
	57	+ }
	58	+ return next;
	59	+ });
	60	+ }
	61	+
	62	+ const allBranchIds = useMemo(() => collectNodeIds(tree), [tree]);
	63	+ const isAllOpen = closedIds.size === 0;
	64	+
	65	+ function toggleAll() {
	66	+ setClosedIds(isAllOpen ? new Set(allBranchIds) : new Set());
	67	+ }
	68	+
	69	+ const rows = flattenOpenNodes(tree, isOpen);
	70	+
	71	+ const columns: FoxListColumn<SystemMenuNode>[] = [
	72	+ { key: 'id', header: '번호', width: 100 },
	73	+ {
	74	+ key: 'toggle',
	75	+ header: (
	76	+ <button
	77	+ type="button"
	78	+ className={styles.toggle}
	79	+ aria-label={isAllOpen ? '모두 접기' : '모두 펼치기'}
	80	+ aria-expanded={isAllOpen}
	81	+ onClick={toggleAll}
	82	+ >
	83	+ {isAllOpen ? <FoxCaretDownIcon /> : <FoxCaretRightIcon />}
	84	+ </button>
	85	+ ),
	86	+ width: 60,
	87	+ render: (row) =>
	88	+ row.children.length > 0 ? (
	89	+ <button
	90	+ type="button"
	91	+ className={styles.toggle}
	92	+ aria-label={`${row.name} ${isOpen(row.id) ? '접기' : '펼치기'}`}
	93	+ aria-expanded={isOpen(row.id)}
	94	+ onClick={() => toggle(row.id)}
	95	+ >
	96	+ {isOpen(row.id) ? <FoxCaretDownIcon /> : <FoxCaretRightIcon />}
	97	+ </button>
	98	+ ) : null,
	99	+ },
	100	+ {
	101	+ key: 'name',
	102	+ header: '메뉴명',
	103	+ width: 420,
	104	+ emphasis: true,
	105	+ render: (row) => (
	106	+ <span
	107	+ className={styles.name}
	108	+ style={{ paddingInlineStart: `${row.depth * INDENT_REM}rem` }}
	109	+ >
	110	+ <span className={styles.icon}>
	111	+ {row.children.length > 0 ? <FoxFolderIcon /> : <FoxFileIcon />}
	112	+ </span>
	113	+ {row.name}
	114	+ </span>
	115	+ ),
	116	+ },
	117	+ { key: 'sortOrder', header: '메뉴순번', width: 120, align: 'center' },
	118	+ {
	119	+ key: 'isActive',
	120	+ header: '활성여부',
	121	+ width: 120,
	122	+ render: (row) => (
	123	+ <FoxStatusIndicator
	124	+ type={row.isActive ? 'success' : 'danger'}
	125	+ label={formatActiveLabel(row.isActive)}
	126	+ />
	127	+ ),
	128	+ },
	129	+ {
	130	+ key: 'roleName',
	131	+ header: '권한',
	132	+ width: 160,
	133	+ render: (row) => formatOptionalValue(row.roleName),
	134	+ },
	135	+ {
	136	+ key: 'actions',
	137	+ header: '관리',
	138	+ width: 140,
	139	+ render: (row) => (
	140	+ <MenuRowActions
	141	+ node={row}
	142	+ onEdit={(node) => setTarget({ mode: 'edit', node })}
	143	+ onAddChild={(node) => setTarget({ mode: 'create', parent: node })}
	144	+ />
	145	+ ),
	146	+ },
	147	+ ];
	148	+
	149	+ return (
	150	+ <>
	151	+ <FoxListContainer<SystemMenuNode>
	152	+ title="메뉴관리"
	153	+ breadcrumb={[
	154	+ { label: '홈', href: '/' },
	155	+ { label: '시스템관리' },
	156	+ { label: '메뉴관리' },
	157	+ ]}
	158	+ caption="메뉴 목록"
	159	+ columns={columns}
	160	+ rows={rows}
	161	+ rowKey={(row) => row.id}
	162	+ totalCount={items.length}
	163	+ emptyMessage="등록된 메뉴가 없습니다."
	164	+ searchHidden
	165	+ />
	166	+
	167	+ {target && (
	168	+ <MenuFormModal
	169	+ mode={target.mode}
	170	+ menu={target.mode === 'edit' ? target.node : undefined}
	171	+ parent={
	172	+ target.mode === 'edit'
	173	+ ? (target.node.parentId ? (byId.get(target.node.parentId) ?? null) : null)
	174	+ : target.parent
	175	+ }
	176	+ roleOptions={roleOptions}
	177	+ onClose={() => setTarget(null)}
	178	+ />
	179	+ )}
	180	+ </>
	181	+ );
	182	+}

fa3bd2d

app/(protected)/(basic)/system/menus/_components/menu-tree.module.scss (added)

+++ app/(protected)/(basic)/system/menus/_components/menu-tree.module.scss

...	...	@@ -0,0 +1,55 @@
	1	+@use "@fox/styles/abstracts" as fox;
	2	+
	3	+// 트리 한 줄 — 깊이만큼 들여쓰고 캐럿·아이콘·이름이 차례로 선다.
	4	+.name {
	5	+ display: flex;
	6	+ align-items: center;
	7	+ gap: fox.gap(2);
	8	+}
	9	+
	10	+.toggle {
	11	+ display: inline-flex;
	12	+ flex-shrink: 0;
	13	+ align-items: center;
	14	+ justify-content: center;
	15	+ inline-size: fox.icon(4);
	16	+ block-size: fox.icon(4);
	17	+ border: none;
	18	+ background: none;
	19	+ color: fox.color(icon-neutral-default);
	20	+ cursor: pointer;
	21	+
	22	+ > svg {
	23	+ inline-size: fox.icon(3);
	24	+ block-size: fox.icon(3);
	25	+ }
	26	+
	27	+ &:focus-visible {
	28	+ outline: fox.border(2) solid fox.color(border-theme-primary);
	29	+ outline-offset: fox.border(1);
	30	+ }
	31	+}
	32	+
	33	+// 자식이 없는 줄도 자리를 잡아 이름 시작 위치가 흔들리지 않게 한다.
	34	+.togglePlaceholder {
	35	+ display: inline-block;
	36	+ flex-shrink: 0;
	37	+ inline-size: fox.icon(4);
	38	+}
	39	+
	40	+.icon {
	41	+ display: inline-flex;
	42	+ flex-shrink: 0;
	43	+ color: fox.color(icon-neutral-subtle);
	44	+
	45	+ > svg {
	46	+ inline-size: fox.icon(3);
	47	+ block-size: fox.icon(3);
	48	+ }
	49	+}
	50	+
	51	+.actions {
	52	+ display: flex;
	53	+ align-items: center;
	54	+ gap: fox.gap(1);
	55	+}

fa3bd2d

app/(protected)/(basic)/system/menus/page.tsx (added)

+++ app/(protected)/(basic)/system/menus/page.tsx

...	...	@@ -0,0 +1,13 @@
	1	+import { verifySession } from '@/lib/auth/dal';
	2	+import { fetchSystemMenus } from '@/lib/data/repositories/system-menu-repository';
	3	+import { MenuTreeList } from './_components/menu-tree-list';
	4	+
	5	+export const dynamic = 'force-dynamic';
	6	+
	7	+export default async function Page() {
	8	+ await verifySession();
	9	+
	10	+ const items = await fetchSystemMenus();
	11	+
	12	+ return <MenuTreeList items={items} />;
	13	+}

fa3bd2d

lib/data/repositories/banned-word-repository.ts (added)

+++ lib/data/repositories/banned-word-repository.ts

...	...	@@ -0,0 +1,192 @@
	1	+import 'server-only';
	2	+import { cache } from 'react';
	3	+import { getSessionAccessToken } from '@/lib/auth/dal';
	4	+import { BackendRequestError, backendFetch } from '@/lib/http/backend-fetch';
	5	+import type { BannedWord } from '@/lib/domain/banned-word';
	6	+import type { BannedWordQuery } from '@/lib/domain/banned-word-query';
	7	+import type { ExcelUploadResult } from '@/lib/domain/banned-word-form';
	8	+
	9	+/**
	10	+ * 금칙어 Repository — `TB_SYS_BEN_WORD`.
	11	+ *
	12	+ * ```
	13	+ * GET /api/v1/mngr/benWord/pagination searchCondition=1 + searchKeyword로 부분검색
	14	+ * POST /api/v1/mngr/benWord 어노테이션 없음 → form. 중복이면 실패 응답
	15	+ * DELETE /api/v1/mngr/benWord/{benWordSn} soft delete(DEL_YN)
	16	+ * POST /api/v1/mngr/benWord/excel multipart, 파트 이름 `file`
	17	+ * ```
	18	+ *
	19	+ * ⚠️ 백엔드 결함(보고함, 미수정)
	20	+ * 1. 목록 정렬이 기획과 반대다. `ROW_NUMBER() OVER (ORDER BY frst_reg_dt DESC)`로 매긴 rnum을
	21	+ * 다시 `ORDER BY RNUM DESC`로 뒤집어 오래된 것이 먼저 온다. 기획은 최신순이다. 그래서
	22	+ * 페이징을 백엔드에 맡기지 않고 한 번에 받아 여기서 정렬·절단한다(rnum 1 = 최신).
	23	+ * 2. `DELETE`의 인자에 `@PathVariable`이 없다. 경로만 보내면 benWordSn이 null이라 아무것도
	24	+ * 지워지지 않는다. 경로와 쿼리에 같은 값을 함께 실어 보낸다 — 어노테이션이 붙어도 그대로
	25	+ * 동작한다.
	26	+ */
	27	+
	28	+const BEN_WORD_PATH = '/api/v1/mngr/benWord';
	29	+
	30	+// TODO(백엔드): 정렬이 고쳐지면 서버 페이징으로 되돌린다. 그전까지는 이 상한을 넘는 금칙어가
	31	+// 생기면 목록이 조용히 잘린다.
	32	+const FETCH_LIMIT = 1000;
	33	+
	34	+function isRecord(value: unknown): value is Record<string, unknown> {
	35	+ return value !== null && typeof value === 'object';
	36	+}
	37	+
	38	+function readString(source: Record<string, unknown>, key: string): string \| null {
	39	+ const value = source[key];
	40	+ return typeof value === 'string' && value.length > 0 ? value : null;
	41	+}
	42	+
	43	+function toBannedWord(raw: unknown): BannedWord[] {
	44	+ if (!isRecord(raw)) {
	45	+ return [];
	46	+ }
	47	+
	48	+ const id = Number(raw.benWordSn);
	49	+ if (!Number.isInteger(id)) {
	50	+ return [];
	51	+ }
	52	+
	53	+ return [
	54	+ {
	55	+ id,
	56	+ word: readString(raw, 'benWordNm') ?? '',
	57	+ createdAt: readString(raw, 'frstRegDtStr'),
	58	+ },
	59	+ ];
	60	+}
	61	+
	62	+/** rnum 1이 최신이라 오름차순이 곧 최신순이다. */
	63	+function byNewestFirst(raw: unknown): number {
	64	+ return isRecord(raw) ? Number(raw.rnum ?? 0) : 0;
	65	+}
	66	+
	67	+const fetchAllBannedWords = cache(
	68	+ async (keyword: string): Promise<BannedWord[]> => {
	69	+ const accessToken = await getSessionAccessToken();
	70	+
	71	+ const result = await backendFetch<unknown>(`${BEN_WORD_PATH}/pagination`, {
	72	+ method: 'GET',
	73	+ query: {
	74	+ pageIndex: 1,
	75	+ recordCountPerPage: FETCH_LIMIT,
	76	+ ...(keyword ? { searchCondition: '1', searchKeyword: keyword } : {}),
	77	+ },
	78	+ accessToken: accessToken ?? undefined,
	79	+ cache: 'no-store',
	80	+ });
	81	+
	82	+ if (!result.ok) {
	83	+ throw new BackendRequestError(result);
	84	+ }
	85	+
	86	+ const data = result.data;
	87	+ if (!isRecord(data) \|\| !Array.isArray(data.list)) {
	88	+ throw new Error('금칙어 목록 응답의 형식이 올바르지 않습니다.');
	89	+ }
	90	+
	91	+ return [...data.list]
	92	+ .sort((a, b) => byNewestFirst(a) - byNewestFirst(b))
	93	+ .flatMap(toBannedWord);
	94	+ }
	95	+);
	96	+
	97	+export async function fetchBannedWords(
	98	+ query: BannedWordQuery
	99	+): Promise<{ items: BannedWord[]; totalCount: number }> {
	100	+ const all = await fetchAllBannedWords(query.keyword);
	101	+ const start = (query.page - 1) * query.pageSize;
	102	+
	103	+ return {
	104	+ items: all.slice(start, start + query.pageSize),
	105	+ totalCount: all.length,
	106	+ };
	107	+}
	108	+
	109	+export type CreateBannedWordResult =
	110	+ \| { status: 'success' }
	111	+ \| { status: 'duplicate' };
	112	+
	113	+export async function createBannedWord(
	114	+ word: string
	115	+): Promise<CreateBannedWordResult> {
	116	+ const accessToken = await getSessionAccessToken();
	117	+
	118	+ const result = await backendFetch<unknown>(BEN_WORD_PATH, {
	119	+ method: 'POST',
	120	+ form: { benWordNm: word },
	121	+ accessToken: accessToken ?? undefined,
	122	+ cache: 'no-store',
	123	+ canHaveNullData: true,
	124	+ canHaveEmptyBody: true,
	125	+ });
	126	+
	127	+ if (!result.ok) {
	128	+ // 중복은 정상 흐름이라 예외로 올리지 않는다 — 백엔드가 "이미 등록된 단어 입니다"로 답한다.
	129	+ if (result.message.includes('이미 등록된')) {
	130	+ return { status: 'duplicate' };
	131	+ }
	132	+ throw new BackendRequestError(result);
	133	+ }
	134	+
	135	+ return { status: 'success' };
	136	+}
	137	+
	138	+export async function deleteBannedWord(id: number): Promise<void> {
	139	+ const accessToken = await getSessionAccessToken();
	140	+
	141	+ const result = await backendFetch<unknown>(`${BEN_WORD_PATH}/${id}`, {
	142	+ method: 'DELETE',
	143	+ query: { benWordSn: id },
	144	+ accessToken: accessToken ?? undefined,
	145	+ cache: 'no-store',
	146	+ canHaveNullData: true,
	147	+ canHaveEmptyBody: true,
	148	+ });
	149	+
	150	+ if (!result.ok) {
	151	+ throw new BackendRequestError(result);
	152	+ }
	153	+}
	154	+
	155	+export async function uploadBannedWordExcel(
	156	+ file: File
	157	+): Promise<ExcelUploadResult> {
	158	+ const accessToken = await getSessionAccessToken();
	159	+
	160	+ const multipart = new FormData();
	161	+ multipart.set('file', file);
	162	+
	163	+ const result = await backendFetch<unknown>(`${BEN_WORD_PATH}/excel`, {
	164	+ method: 'POST',
	165	+ multipart,
	166	+ accessToken: accessToken ?? undefined,
	167	+ cache: 'no-store',
	168	+ canHaveNullData: true,
	169	+ });
	170	+
	171	+ const data = result.ok ? result.data : null;
	172	+ const errors =
	173	+ isRecord(data) && Array.isArray(data.errors)
	174	+ ? data.errors.filter((entry): entry is string => typeof entry === 'string')
	175	+ : [];
	176	+
	177	+ if (!result.ok) {
	178	+ // 검증 실패는 fail(300) + data.errors로 온다. 통신 오류와 구분해 화면에 그대로 보여준다.
	179	+ if (errors.length > 0) {
	180	+ return { successCount: 0, errors };
	181	+ }
	182	+ throw new BackendRequestError(result);
	183	+ }
	184	+
	185	+ return {
	186	+ successCount:
	187	+ isRecord(data) && Number.isInteger(Number(data.successCount))
	188	+ ? Number(data.successCount)
	189	+ : 0,
	190	+ errors,
	191	+ };
	192	+}

76cb06e

fa3bd2d

lib/data/repositories/sidebar-menu-repository.ts

--- lib/data/repositories/sidebar-menu-repository.ts

+++ lib/data/repositories/sidebar-menu-repository.ts


           id: 'system',
           label: '시스템관리',
           icon: 'wrench',
-          children: [{ id: 'codes', label: '코드관리', href: '/system/codes' }],
+          children: [
+            { id: 'codes', label: '코드관리', href: '/system/codes' },
+            { id: 'menus', label: '메뉴관리', href: '/system/menus' },
+            { id: 'banned-words', label: '금칙어관리', href: '/system/banned-words' },
+          ],
         },
       ],
     },

fa3bd2d

lib/data/repositories/system-menu-repository.ts (added)

+++ lib/data/repositories/system-menu-repository.ts

...	...	@@ -0,0 +1,171 @@
	1	+import 'server-only';
	2	+import { cache } from 'react';
	3	+import { getSessionAccessToken } from '@/lib/auth/dal';
	4	+import { BackendRequestError, backendFetch } from '@/lib/http/backend-fetch';
	5	+import { buildFileImageUrl } from '@/lib/data/repositories/file-repository';
	6	+import type { SystemMenu } from '@/lib/domain/system-menu';
	7	+import type { SystemMenuValues } from '@/lib/domain/system-menu-form';
	8	+
	9	+/**
	10	+ * 시스템 메뉴 Repository — `TB_SYS_MENU`.
	11	+ *
	12	+ * ```
	13	+ * GET /api/v1/mngr/menu/pagination 목록(페이징). 트리라 한 번에 다 받는다
	14	+ * POST /api/v1/mngr/menu 어노테이션 없음 → form. upMenuId의 부모가 있어야 한다
	15	+ * PUT /api/v1/mngr/menu/{menuId} @RequestBody(JSON)
	16	+ * DELETE /api/v1/mngr/menu/{menuId} soft delete(DEL_YN)
	17	+ * ```
	18	+ *
	19	+ * ⚠️ 백엔드 결함(보고함, 미수정)
	20	+ * 1. `DELETE`의 인자에 `@PathVariable`이 없어 경로 값이 바인딩되지 않는다. 경로와 쿼리에 같은
	21	+ * 값을 함께 실어 보낸다 — 어노테이션이 붙어도 그대로 동작한다.
	22	+ * 2. `GET /{menuId}`는 경로가 `{menuId}`인데 인자가 `@PathVariable String userId`이고 본문도 빈
	23	+ * VO로 조회한다. 목록에 모든 필드가 있어 이 API는 쓰지 않는다.
	24	+ * 3. 새창여부에 해당하는 컬럼이 없다. 화면에는 시안대로 두되 값을 보내지 않는다(사용자 확정).
	25	+ */
	26	+
	27	+const MENU_PATH = '/api/v1/mngr/menu';
	28	+
	29	+// TODO(백엔드): 전체 조회 모드가 없어 큰 페이지 하나로 받는다. 메뉴가 이보다 많아지면 잘린다.
	30	+const FETCH_LIMIT = 1000;
	31	+
	32	+function isRecord(value: unknown): value is Record<string, unknown> {
	33	+ return value !== null && typeof value === 'object';
	34	+}
	35	+
	36	+function readString(source: Record<string, unknown>, key: string): string \| null {
	37	+ const value = source[key];
	38	+ return typeof value === 'string' && value.length > 0 ? value : null;
	39	+}
	40	+
	41	+function parseYesNo(value: unknown): boolean {
	42	+ return value === 'Y';
	43	+}
	44	+
	45	+function toSystemMenu(raw: unknown): SystemMenu[] {
	46	+ if (!isRecord(raw)) {
	47	+ return [];
	48	+ }
	49	+
	50	+ const id = readString(raw, 'menuId');
	51	+ if (!id) {
	52	+ return [];
	53	+ }
	54	+
	55	+ return [
	56	+ {
	57	+ id,
	58	+ parentId: readString(raw, 'upMenuId'),
	59	+ name: readString(raw, 'menuName') ?? '',
	60	+ idPath: readString(raw, 'menuIdPath'),
	61	+ url: readString(raw, 'menuUrl'),
	62	+ roleId: readString(raw, 'roleId'),
	63	+ roleName: readString(raw, 'roleNm'),
	64	+ sortOrder: Number.isInteger(Number(raw.sortOrdr)) ? Number(raw.sortOrdr) : 0,
	65	+ isActive: parseYesNo(raw.useYn),
	66	+ isTopActive: parseYesNo(raw.topYn),
	67	+ isDefault: parseYesNo(raw.defaultYn),
	68	+ description: readString(raw, 'menuExplan'),
	69	+ largeIconId: readString(raw, 'atchFileId'),
	70	+ largeIconName: readString(raw, 'fileNm'),
	71	+ // 미리보기 주소는 서버에서 만든다 — 주소 조립기가 server-only라 화면이 부를 수 없다.
	72	+ largeIconUrl: buildFileImageUrl(readString(raw, 'atchFileId')),
	73	+ smallIconId: readString(raw, 'smallAtchFileId'),
	74	+ smallIconName: readString(raw, 'smallFileNm'),
	75	+ smallIconUrl: buildFileImageUrl(readString(raw, 'smallAtchFileId')),
	76	+ },
	77	+ ];
	78	+}
	79	+
	80	+export const fetchSystemMenus = cache(async (): Promise<SystemMenu[]> => {
	81	+ const accessToken = await getSessionAccessToken();
	82	+
	83	+ const result = await backendFetch<unknown>(`${MENU_PATH}/pagination`, {
	84	+ method: 'GET',
	85	+ query: { pageIndex: 1, recordCountPerPage: FETCH_LIMIT },
	86	+ accessToken: accessToken ?? undefined,
	87	+ cache: 'no-store',
	88	+ });
	89	+
	90	+ if (!result.ok) {
	91	+ throw new BackendRequestError(result);
	92	+ }
	93	+
	94	+ const data = result.data;
	95	+ if (!isRecord(data) \|\| !Array.isArray(data.list)) {
	96	+ throw new Error('메뉴 목록 응답의 형식이 올바르지 않습니다.');
	97	+ }
	98	+
	99	+ return data.list.flatMap(toSystemMenu);
	100	+});
	101	+
	102	+/** 새창여부는 보내지 않는다 — 저장할 컬럼이 없다(파일 상단 ⚠️ 3). */
	103	+function toWriteParams(values: SystemMenuValues) {
	104	+ return {
	105	+ menuName: values.name,
	106	+ sortOrdr: values.sortOrder,
	107	+ roleId: values.roleId,
	108	+ topYn: values.isTopActive ? 'Y' : 'N',
	109	+ menuUrl: values.url,
	110	+ menuExplan: values.description,
	111	+ // 빈 문자열을 그대로 보낸다 — UPDATE가 null만 건너뛰므로 이래야 아이콘을 지울 수 있다.
	112	+ atchFileId: values.largeIconId,
	113	+ smallAtchFileId: values.smallIconId,
	114	+ useYn: values.isActive ? 'Y' : 'N',
	115	+ };
	116	+}
	117	+
	118	+export async function createSystemMenu(values: SystemMenuValues): Promise<void> {
	119	+ const accessToken = await getSessionAccessToken();
	120	+
	121	+ const result = await backendFetch<unknown>(MENU_PATH, {
	122	+ method: 'POST',
	123	+ form: {
	124	+ ...toWriteParams(values),
	125	+ upMenuId: values.parentId,
	126	+ menuIdPath: values.parentIdPath \|\| undefined,
	127	+ },
	128	+ accessToken: accessToken ?? undefined,
	129	+ cache: 'no-store',
	130	+ canHaveNullData: true,
	131	+ canHaveEmptyBody: true,
	132	+ });
	133	+
	134	+ if (!result.ok) {
	135	+ throw new BackendRequestError(result);
	136	+ }
	137	+}
	138	+
	139	+export async function updateSystemMenu(values: SystemMenuValues): Promise<void> {
	140	+ const accessToken = await getSessionAccessToken();
	141	+
	142	+ const result = await backendFetch<unknown>(`${MENU_PATH}/${values.id}`, {
	143	+ method: 'PUT',
	144	+ body: toWriteParams(values),
	145	+ accessToken: accessToken ?? undefined,
	146	+ cache: 'no-store',
	147	+ canHaveNullData: true,
	148	+ canHaveEmptyBody: true,
	149	+ });
	150	+
	151	+ if (!result.ok) {
	152	+ throw new BackendRequestError(result);
	153	+ }
	154	+}
	155	+
	156	+export async function deleteSystemMenu(menuId: string): Promise<void> {
	157	+ const accessToken = await getSessionAccessToken();
	158	+
	159	+ const result = await backendFetch<unknown>(`${MENU_PATH}/${menuId}`, {
	160	+ method: 'DELETE',
	161	+ query: { menuId },
	162	+ accessToken: accessToken ?? undefined,
	163	+ cache: 'no-store',
	164	+ canHaveNullData: true,
	165	+ canHaveEmptyBody: true,
	166	+ });
	167	+
	168	+ if (!result.ok) {
	169	+ throw new BackendRequestError(result);
	170	+ }
	171	+}

fa3bd2d

lib/domain/banned-word-form.ts (added)

+++ lib/domain/banned-word-form.ts

...	...	@@ -0,0 +1,41 @@
	1	+export const WORD_MAX_LENGTH = 100;
	2	+
	3	+export type BannedWordFormErrors = Partial<Record<'word', string>>;
	4	+
	5	+export type BannedWordFormState =
	6	+ \| { status: 'idle' }
	7	+ \| { status: 'error'; message?: string; errors?: BannedWordFormErrors }
	8	+ \| { status: 'success' };
	9	+
	10	+export const INITIAL_BANNED_WORD_FORM_STATE: BannedWordFormState = {
	11	+ status: 'idle',
	12	+};
	13	+
	14	+/** 기획 SYS_WRD_002 ② — 중복은 백엔드가 판정하고 이 문구로 알린다. */
	15	+export const DUPLICATE_WORD_MESSAGE = '중복된 키워드입니다.';
	16	+export const REQUIRED_MESSAGE = '필수입력사항을 입력하세요.';
	17	+
	18	+type ValidationResult =
	19	+ \| { ok: true; value: string }
	20	+ \| { ok: false; errors: BannedWordFormErrors };
	21	+
	22	+export function validateBannedWord(raw: string): ValidationResult {
	23	+ const value = raw.trim();
	24	+
	25	+ if (!value) {
	26	+ return { ok: false, errors: { word: REQUIRED_MESSAGE } };
	27	+ }
	28	+ if (value.length > WORD_MAX_LENGTH) {
	29	+ return {
	30	+ ok: false,
	31	+ errors: { word: `키워드는 ${WORD_MAX_LENGTH}자 이내로 입력해 주세요.` },
	32	+ };
	33	+ }
	34	+
	35	+ return { ok: true, value };
	36	+}
	37	+
	38	+export type ExcelUploadResult = {
	39	+ successCount: number;
	40	+ errors: string[];
	41	+};

fa3bd2d

lib/domain/banned-word-query.ts (added)

+++ lib/domain/banned-word-query.ts

...	...	@@ -0,0 +1,66 @@
	1	+export const BANNED_WORDS_PATH = '/system/banned-words';
	2	+export const BANNED_WORD_NEW_PATH = `${BANNED_WORDS_PATH}/new`;
	3	+/** 엑셀 업로드 양식 다운로드 — 파일 응답이라 라우트 핸들러가 받는다. */
	4	+export const BANNED_WORD_EXCEL_TEMPLATE_PATH = `${BANNED_WORDS_PATH}/excel-template`;
	5	+
	6	+export const BANNED_WORD_PAGE_SIZE_OPTIONS = [10, 30, 50] as const;
	7	+export type BannedWordPageSize =
	8	+ (typeof BANNED_WORD_PAGE_SIZE_OPTIONS)[number];
	9	+
	10	+export const DEFAULT_BANNED_WORD_PAGE_SIZE: BannedWordPageSize = 10;
	11	+const DEFAULT_PAGE = 1;
	12	+const MAX_KEYWORD_LENGTH = 100;
	13	+
	14	+export type BannedWordQuery = {
	15	+ keyword: string;
	16	+ page: number;
	17	+ pageSize: BannedWordPageSize;
	18	+};
	19	+
	20	+type RawSearchParams = Record<string, string \| string[] \| undefined>;
	21	+
	22	+function readParam(params: RawSearchParams, key: string): string \| undefined {
	23	+ const value = params[key];
	24	+ return Array.isArray(value) ? value[0] : value;
	25	+}
	26	+
	27	+function isBannedWordPageSize(value: number): value is BannedWordPageSize {
	28	+ return (BANNED_WORD_PAGE_SIZE_OPTIONS as readonly number[]).includes(value);
	29	+}
	30	+
	31	+export function parseBannedWordQuery(
	32	+ searchParams: RawSearchParams
	33	+): BannedWordQuery {
	34	+ const keywordRaw = readParam(searchParams, 'keyword');
	35	+ const pageRaw = Number(readParam(searchParams, 'page'));
	36	+ const pageSizeRaw = Number(readParam(searchParams, 'pageSize'));
	37	+
	38	+ return {
	39	+ keyword: (keywordRaw ?? '').trim().slice(0, MAX_KEYWORD_LENGTH),
	40	+ page: Number.isInteger(pageRaw) && pageRaw > 0 ? pageRaw : DEFAULT_PAGE,
	41	+ pageSize: isBannedWordPageSize(pageSizeRaw)
	42	+ ? pageSizeRaw
	43	+ : DEFAULT_BANNED_WORD_PAGE_SIZE,
	44	+ };
	45	+}
	46	+
	47	+export function buildBannedWordHref(
	48	+ query: BannedWordQuery,
	49	+ overrides: Partial<BannedWordQuery> = {}
	50	+): string {
	51	+ const merged = { ...query, ...overrides };
	52	+ const params = new URLSearchParams();
	53	+
	54	+ if (merged.keyword) {
	55	+ params.set('keyword', merged.keyword);
	56	+ }
	57	+ if (merged.pageSize !== DEFAULT_BANNED_WORD_PAGE_SIZE) {
	58	+ params.set('pageSize', String(merged.pageSize));
	59	+ }
	60	+ if (merged.page !== DEFAULT_PAGE) {
	61	+ params.set('page', String(merged.page));
	62	+ }
	63	+
	64	+ const queryString = params.toString();
	65	+ return queryString ? `${BANNED_WORDS_PATH}?${queryString}` : BANNED_WORDS_PATH;
	66	+}

fa3bd2d

lib/domain/banned-word.ts (added)

+++ lib/domain/banned-word.ts

...	...	@@ -0,0 +1,15 @@
	1	+export interface BannedWord {
	2	+ id: number;
	3	+ word: string;
	4	+ createdAt: string \| null;
	5	+}
	6	+
	7	+export const EMPTY_FIELD_PLACEHOLDER = '-';
	8	+
	9	+export function formatOptionalValue(
	10	+ value: string \| number \| null \| undefined
	11	+): string {
	12	+ return value === null \|\| value === undefined \|\| value === ''
	13	+ ? EMPTY_FIELD_PLACEHOLDER
	14	+ : String(value);
	15	+}

fa3bd2d

lib/domain/system-menu-form.ts (added)

+++ lib/domain/system-menu-form.ts

...	...	@@ -0,0 +1,106 @@
	1	+export const NAME_MAX_LENGTH = 100;
	2	+export const URL_MAX_LENGTH = 300;
	3	+export const DESCRIPTION_MAX_LENGTH = 300;
	4	+export const SORT_ORDER_MAX = 9999;
	5	+
	6	+export interface SystemMenuValues {
	7	+ id: string;
	8	+ parentId: string;
	9	+ parentIdPath: string;
	10	+ name: string;
	11	+ sortOrder: number;
	12	+ roleId: string;
	13	+ isTopActive: boolean;
	14	+ url: string;
	15	+ description: string;
	16	+ largeIconId: string;
	17	+ smallIconId: string;
	18	+ isActive: boolean;
	19	+}
	20	+
	21	+export type SystemMenuFormErrors = Partial<
	22	+ Record<
	23	+ 'name' \| 'sortOrder' \| 'roleId' \| 'url' \| 'description' \| 'largeIconId' \| 'smallIconId',
	24	+ string
	25	+ >
	26	+>;
	27	+
	28	+export type SystemMenuFormState =
	29	+ \| { status: 'idle' }
	30	+ \| { status: 'error'; message?: string; errors?: SystemMenuFormErrors }
	31	+ \| { status: 'success' };
	32	+
	33	+export const INITIAL_SYSTEM_MENU_FORM_STATE: SystemMenuFormState = {
	34	+ status: 'idle',
	35	+};
	36	+
	37	+/** 기획 SYS_MNU_002_p ④ — 미입력 시 이 문구를 띄운다. */
	38	+export const REQUIRED_MESSAGE = '필수입력 사항을 입력하세요.';
	39	+
	40	+type ValidationResult =
	41	+ \| { ok: true; values: SystemMenuValues }
	42	+ \| { ok: false; errors: SystemMenuFormErrors };
	43	+
	44	+function validateText(
	45	+ raw: string,
	46	+ max: number,
	47	+ label: string
	48	+): { value: string; error?: string } {
	49	+ const value = raw.trim();
	50	+
	51	+ if (!value) {
	52	+ return { value, error: REQUIRED_MESSAGE };
	53	+ }
	54	+ if (value.length > max) {
	55	+ return { value, error: `${label}은 ${max}자 이내로 입력해 주세요.` };
	56	+ }
	57	+ return { value };
	58	+}
	59	+
	60	+export function validateSystemMenu(values: SystemMenuValues): ValidationResult {
	61	+ const errors: SystemMenuFormErrors = {};
	62	+
	63	+ const name = validateText(values.name, NAME_MAX_LENGTH, '메뉴명');
	64	+ if (name.error) {
	65	+ errors.name = name.error;
	66	+ }
	67	+
	68	+ const url = validateText(values.url, URL_MAX_LENGTH, '메뉴링크');
	69	+ if (url.error) {
	70	+ errors.url = url.error;
	71	+ }
	72	+
	73	+ const description = validateText(
	74	+ values.description,
	75	+ DESCRIPTION_MAX_LENGTH,
	76	+ '메뉴설명'
	77	+ );
	78	+ if (description.error) {
	79	+ errors.description = description.error;
	80	+ }
	81	+
	82	+ if (!values.roleId.trim()) {
	83	+ errors.roleId = REQUIRED_MESSAGE;
	84	+ }
	85	+
	86	+ if (!Number.isInteger(values.sortOrder) \|\| values.sortOrder < 1) {
	87	+ errors.sortOrder = '메뉴순번은 1 이상의 숫자로 입력해 주세요.';
	88	+ } else if (values.sortOrder > SORT_ORDER_MAX) {
	89	+ errors.sortOrder = `메뉴순번은 ${SORT_ORDER_MAX} 이하로 입력해 주세요.`;
	90	+ }
	91	+
	92	+ if (Object.keys(errors).length > 0) {
	93	+ return { ok: false, errors };
	94	+ }
	95	+
	96	+ return {
	97	+ ok: true,
	98	+ values: {
	99	+ ...values,
	100	+ name: name.value,
	101	+ url: url.value,
	102	+ description: description.value,
	103	+ roleId: values.roleId.trim(),
	104	+ },
	105	+ };
	106	+}

fa3bd2d

lib/domain/system-menu.ts (added)

+++ lib/domain/system-menu.ts

...	...	@@ -0,0 +1,132 @@
	1	+export interface SystemMenu {
	2	+ id: string;
	3	+ parentId: string \| null;
	4	+ name: string;
	5	+ idPath: string \| null;
	6	+ url: string \| null;
	7	+ roleId: string \| null;
	8	+ roleName: string \| null;
	9	+ sortOrder: number;
	10	+ isActive: boolean;
	11	+ isTopActive: boolean;
	12	+ isDefault: boolean;
	13	+ description: string \| null;
	14	+ largeIconId: string \| null;
	15	+ largeIconName: string \| null;
	16	+ largeIconUrl: string \| null;
	17	+ smallIconId: string \| null;
	18	+ smallIconName: string \| null;
	19	+ smallIconUrl: string \| null;
	20	+}
	21	+
	22	+export interface SystemMenuNode extends SystemMenu {
	23	+ depth: number;
	24	+ children: SystemMenuNode[];
	25	+}
	26	+
	27	+export const EMPTY_FIELD_PLACEHOLDER = '-';
	28	+
	29	+export function formatOptionalValue(
	30	+ value: string \| number \| null \| undefined
	31	+): string {
	32	+ return value === null \|\| value === undefined \|\| value === ''
	33	+ ? EMPTY_FIELD_PLACEHOLDER
	34	+ : String(value);
	35	+}
	36	+
	37	+export function formatActiveLabel(isActive: boolean): string {
	38	+ return isActive ? '활성' : '비활성';
	39	+}
	40	+
	41	+/**
	42	+ * 평면 목록을 트리로 세운다. 부모가 목록에 없는 항목(권한 때문에 잘려 온 가지 등)은 뿌리로
	43	+ * 올려 화면에서 사라지지 않게 한다.
	44	+ */
	45	+export function buildMenuTree(items: SystemMenu[]): SystemMenuNode[] {
	46	+ const byId = new Map<string, SystemMenuNode>();
	47	+ for (const item of items) {
	48	+ byId.set(item.id, { ...item, depth: 0, children: [] });
	49	+ }
	50	+
	51	+ const roots: SystemMenuNode[] = [];
	52	+ for (const node of byId.values()) {
	53	+ const parent = node.parentId ? byId.get(node.parentId) : undefined;
	54	+ if (parent && parent !== node) {
	55	+ parent.children.push(node);
	56	+ } else {
	57	+ roots.push(node);
	58	+ }
	59	+ }
	60	+
	61	+ function order(nodes: SystemMenuNode[], depth: number): SystemMenuNode[] {
	62	+ nodes.sort((a, b) => a.sortOrder - b.sortOrder \|\| a.id.localeCompare(b.id));
	63	+ for (const node of nodes) {
	64	+ node.depth = depth;
	65	+ order(node.children, depth + 1);
	66	+ }
	67	+ return nodes;
	68	+ }
	69	+
	70	+ return order(roots, 0);
	71	+}
	72	+
	73	+/** 펼쳐진 가지만 위에서부터 한 줄씩 늘어놓는다. */
	74	+export function flattenOpenNodes(
	75	+ nodes: SystemMenuNode[],
	76	+ isOpen: (id: string) => boolean
	77	+): SystemMenuNode[] {
	78	+ const rows: SystemMenuNode[] = [];
	79	+
	80	+ function walk(list: SystemMenuNode[]) {
	81	+ for (const node of list) {
	82	+ rows.push(node);
	83	+ if (node.children.length > 0 && isOpen(node.id)) {
	84	+ walk(node.children);
	85	+ }
	86	+ }
	87	+ }
	88	+
	89	+ walk(nodes);
	90	+ return rows;
	91	+}
	92	+
	93	+export function collectNodeIds(nodes: SystemMenuNode[]): string[] {
	94	+ const ids: string[] = [];
	95	+
	96	+ function walk(list: SystemMenuNode[]) {
	97	+ for (const node of list) {
	98	+ if (node.children.length > 0) {
	99	+ ids.push(node.id);
	100	+ walk(node.children);
	101	+ }
	102	+ }
	103	+ }
	104	+
	105	+ walk(nodes);
	106	+ return ids;
	107	+}
	108	+
	109	+/**
	110	+ * 메뉴권한 셀렉트의 선택지 — 역할 목록 API가 없어 목록 응답에 실제로 쓰인 역할만 모은다
	111	+ * (사용자 확정 사항).
	112	+ */
	113	+export function collectRoleOptions(
	114	+ items: SystemMenu[]
	115	+): { value: string; label: string }[] {
	116	+ const byId = new Map<string, string>();
	117	+
	118	+ for (const item of items) {
	119	+ if (item.roleId && !byId.has(item.roleId)) {
	120	+ byId.set(item.roleId, item.roleName ?? item.roleId);
	121	+ }
	122	+ }
	123	+
	124	+ return [...byId.entries()]
	125	+ .map(([value, label]) => ({ value, label }))
	126	+ .sort((a, b) => a.label.localeCompare(b.label, 'ko-KR'));
	127	+}
	128	+
	129	+/** 수정·추가 팝업의 상위메뉴명 표시 — 기획의 `[3] 고객센터` 형식. */
	130	+export function formatParentLabel(parent: SystemMenu \| null): string {
	131	+ return parent ? `[${parent.id}] ${parent.name}` : '';
	132	+}

Delete comment