File name
Commit message
Commit date
File name
Commit message
Commit date
File name
Commit message
Commit date
import 'server-only';
import { getSessionAccessToken } from '@/lib/auth/dal';
import { getApiBaseUrl } from '@/lib/env';
import { BackendRequestError, backendFetch } from '@/lib/http/backend-fetch';
import type { DecorationItem, DecorationItemType } from '@/lib/domain/decoration-item';
import type { DecorationItemEditableValues } from '@/lib/domain/decoration-item-form';
import type {
DecorationItemQuery,
DecorationItemSearchField,
} from '@/lib/domain/decoration-item-query';
/**
* 꾸미기 아이템 Repository — 이 도메인을 백엔드에서 "어떻게 읽고 쓰는지"만 안다(엔드포인트·
* 파라미터·응답 매핑). 통신 규약은 `lib/http/backend-fetch.ts`가, 토큰 보관·검증은 `lib/auth`가
* 소유하므로 여기에 들어오지 않는다.
*
* ```
* GET /api/v1/mngr/item/pagination 목록 (ROLE_ADMIN)
* GET /api/v1/mngr/item/{itemSn} 단건
* POST /api/v1/mngr/item 등록
* PUT /api/v1/mngr/item/{itemSn} 수정
* DELETE /api/v1/mngr/item/{itemSn} 삭제
* POST /api/v1/common/file/upload/{moduleId} 이미지 업로드(multipart)
* ```
*
* 아래는 백엔드 저장소(edupay-backend, develop)의 실제 구현을 읽고 확인한 것이다 —
* MngrItemApiController / MngrItemServiceImpl / MngrItemMapper.xml / FileCommonApiController.
*
* - **쓰기 API는 JSON이 아니라 form 인코딩이다.** 컨트롤러가 `@RequestBody`가 아닌
* `@ParameterObject`로 받으므로 JSON을 보내면 전 필드가 null인 채 저장된다(오류도 나지 않는다).
* - **목록은 `searchItemType`이 필수다** — SQL의 WHERE에 `AND a.ITEM_TYPE = #{searchItemType}`이
* 무조건 붙는다. 값이 없으면 아무것도 조회되지 않는다.
* - **검색은 아이템명(`searchCondition="1"`)만 구현돼 있다.** 아이템ID 검색 분기는 없어, 그
* 값을 보내면 조건 없이 전체가 반환된다(사용자 지시로 화면 선택지는 유지하고 백엔드에 추가 요청).
* - **정렬은 고정이다** — `ROW_NUMBER() OVER (ORDER BY SORT_ORDR DESC)`를 다시 역순으로 정렬해
* 결과적으로 정렬순서 오름차순이며(시안 ADM_ITM_101과 일치) 정렬 파라미터는 없다.
* - **응답의 `totalCount`는 전체 건수가 아니라 그 페이지의 행 수다**(학생·관리자 목록과 동일한
* `PaginationUtil` 결함). 그대로 믿으면 페이지가 가득 찰 때마다 다음 페이지에 도달할 수 없어
* 하한값으로 보정한다.
*
* 캐시: 조회는 `no-store` — 개인화 데이터는 아니지만 관리 화면이라 신선도가 우선이고 검색 조건이
* 매 요청 달라진다. 쓰기는 캐시 대상이 아니며 호출부(Server Action)가 `revalidatePath`로 목록을
* 재검증한다.
*/
const DECORATION_ITEM_PATH = '/api/v1/mngr/item';
const FILE_UPLOAD_PATH = '/api/v1/common/file/upload';
const FILE_IMAGE_PATH = '/api/v1/common/file/image';
/** 파일 업로드 경로 변수 — 아이템 이미지용 모듈 ID(사용자 확정 사항). */
const ITEM_FILE_MODULE_ID = 'MODULE_ITEM';
/** 화면·URL의 유형 값 ↔ 백엔드 `itemType` 코드값(사용자 확정 사항). */
const ITEM_TYPE_CODE: Record<DecorationItemType, string> = {
individual: 'N',
set: 'S',
};
const ITEM_TYPE_BY_CODE: Record<string, DecorationItemType> = {
N: 'individual',
S: 'set',
};
/**
* 화면의 "검색 대상" → 백엔드 `searchCondition` 값.
*
* **백엔드에 구현된 분기는 `"1"`(아이템명) 하나뿐이다.** 아이템ID 검색은 사용자 지시로 화면
* 선택지를 유지한 채 백엔드에 추가를 요청하기로 했고, 그때 쓸 값으로 `"2"`를 예약해 둔다
* (학생 목록이 1=이름·2=아이디·3=휴대전화를 쓰는 관례와 같은 순번). **백엔드가 이 값을 모르는
* 동안에는 검색어가 무시되고 전체 목록이 반환된다.**
*/
const SEARCH_CONDITION_BY_FIELD: Record<DecorationItemSearchField, string> = {
name: '1',
itemId: '2',
};
/** 이름순 정렬이 아니라 "전체 건수를 알기 위해" 한 번에 받아올 최대 행 수(아래 주석 참조). */
const TYPE_TOTAL_COUNT_FETCH_LIMIT = 1_000;
function isRecord(value: unknown): value is Record<string, unknown> {
return value !== null && typeof value === 'object';
}
function readString(source: Record<string, unknown>, key: string): string | null {
const value = source[key];
return typeof value === 'string' && value.length > 0 ? value : null;
}
function readNumber(source: Record<string, unknown>, key: string): number | null {
const value = source[key];
return typeof value === 'number' ? value : null;
}
/** 업로드된 파일 ID로 백엔드 이미지 URL을 만든다 — 이 GET은 인증이 필요 없어 브라우저가 직접 부른다. */
function buildImageUrl(imageFileId: string | null): string | null {
if (!imageFileId) {
return null;
}
const base = getApiBaseUrl().replace(/\/+$/, '');
const url = new URL(`${base}${FILE_IMAGE_PATH}`);
url.searchParams.set('atchFileId', imageFileId);
// 아이템은 파일을 1개만 등록하므로 첨부 순번은 항상 1이다(백엔드도 미지정 시 1로 기본값 처리).
url.searchParams.set('fileSn', '1');
return url.toString();
}
/**
* 백엔드 응답 1건 → 도메인 타입. 식별자·이름 등 목록의 존재 이유인 값이 없으면 예외로 끊는다
* (fail-fast) — 빈 화면을 조용히 보여주는 것보다 계약 위반을 즉시 드러내는 편이 낫다.
*
* `rnum`은 담지 않는다 — 표의 "번호"는 현재 페이지 기준 표시 순번이고 표 컴포넌트가 계산한다.
*/
function toDecorationItem(raw: unknown): DecorationItem {
if (!isRecord(raw)) {
throw new Error('아이템 응답 항목의 형식이 올바르지 않습니다.');
}
const itemSn = readNumber(raw, 'itemSn');
if (itemSn === null) {
throw new Error('아이템 응답에 itemSn이 없습니다.');
}
const imageFileId = readString(raw, 'atchFileId');
return {
itemSn,
// 코드값이 비었거나 모르는 값이면 화면 기본 유형으로 떨어뜨리지 않고 개별로 둔다 —
// 목록은 유형별로 조회하므로 실제로는 요청한 유형의 행만 온다.
itemType: ITEM_TYPE_BY_CODE[readString(raw, 'itemType') ?? ''] ?? 'individual',
name: readString(raw, 'itemNm') ?? '',
categoryCode: readString(raw, 'itemCateCd') ?? '',
categoryName: readString(raw, 'itemCateNm'),
points: readNumber(raw, 'itemAmount') ?? 0,
description: readString(raw, 'itemExplan'),
isActive: readString(raw, 'useYn') === 'Y',
sortOrder: readNumber(raw, 'sortOrdr') ?? 0,
imageFileId,
imageUrl: buildImageUrl(imageFileId),
updatedAt: readString(raw, 'lastMdfcnDt'),
};
}
function buildListParams(
query: DecorationItemQuery,
pageIndex: number,
recordCountPerPage: number
): Record<string, string | number> {
const keyword = query.keyword.trim();
return {
searchItemType: ITEM_TYPE_CODE[query.itemType],
searchCondition: keyword ? SEARCH_CONDITION_BY_FIELD[query.searchField] : '',
searchKeyword: keyword,
// 유효한 페이징 파라미터는 이 둘뿐이다 — 서버가 offset을 직접 계산해 firstIndex·
// recordCountPerPage를 덮어쓰고 나머지(pageUnit·pageSize·lastIndex)는 읽지 않는다.
pageIndex,
recordCountPerPage,
};
}
/** 목록 조회 1회 — 응답 검증까지만 하고 건수 판단은 호출부에 맡긴다. */
async function requestItemList(
query: DecorationItemQuery,
pageIndex: number,
recordCountPerPage: number
): Promise<{ items: DecorationItem[]; reportedTotalCount: number }> {
const accessToken = await getSessionAccessToken();
const result = await backendFetch<unknown>(
`${DECORATION_ITEM_PATH}/pagination`,
{
method: 'GET',
query: buildListParams(query, pageIndex, recordCountPerPage),
accessToken: accessToken ?? undefined,
cache: 'no-store',
}
);
if (!result.ok) {
throw new BackendRequestError(result);
}
const data = result.data;
if (!isRecord(data) || !Array.isArray(data.list)) {
throw new Error('아이템 목록 응답의 형식이 올바르지 않습니다.');
}
return {
items: data.list.map(toDecorationItem),
reportedTotalCount:
typeof data.totalCount === 'number' ? data.totalCount : data.list.length,
};
}
export type DecorationItemPage = {
items: DecorationItem[];
/** 검색어까지 적용한 결과 건수. `isTotalCountExact`가 false면 "적어도 이만큼"이라는 하한값이다. */
totalCount: number;
isTotalCountExact: boolean;
/**
* 검색어와 무관하게 현재 유형(개별/셋트) 전체 등록 건수 — 등록/수정 팝업의
* "정렬순서 (총 등록 N개)" 힌트와 신규 등록 기본 정렬순서 계산에 쓴다.
*/
typeTotalCount: number;
};
/**
* 검색·유형·페이징이 적용된 목록을 조회한다.
*
* **`totalCount` 보정**: 백엔드는 count 쿼리 없이 `list.size()`를 총건수로 내려준다
* (`PaginationUtil.execute`). 그대로 쓰면 한 페이지가 가득 찰 때마다 `totalPages`가 1로 계산돼
* 2페이지 이후에 접근할 수 없으므로, 학생 목록과 동일하게 하한값으로 보정한다 — 페이지가 가득
* 차지 않았으면 마지막 페이지이므로 `offset + 행 수`가 확정 총건수이고, 가득 찼으면 하한값만
* 알린다. 백엔드가 진짜 count를 넣으면 `Math.max`가 자동으로 그 값을 채택한다.
*
* **`typeTotalCount`는 별도 조회다** — 검색 결과가 아니라 그 유형에 실제로 존재하는 전체 개수여야
* 하는데(정렬순서 힌트·기본값의 근거) 백엔드가 총건수를 주지 않으므로, 검색어를 뺀 조건으로 큰
* 상한을 걸어 한 번 더 조회해 길이를 센다. 백엔드에 count가 생기면 이 왕복을 없앨 수 있다.
*/
export async function fetchDecorationItems(
query: DecorationItemQuery
): Promise<DecorationItemPage> {
const { items, reportedTotalCount } = await requestItemList(
query,
query.page,
query.pageSize
);
const offset = (query.page - 1) * query.pageSize;
const confirmedCount = offset + items.length;
const reachedLastPage = items.length < query.pageSize;
const typeTotal = await requestItemList(
{ ...query, keyword: '' },
1,
TYPE_TOTAL_COUNT_FETCH_LIMIT
);
return {
items,
totalCount: Math.max(reportedTotalCount, confirmedCount),
isTotalCountExact: reachedLastPage || reportedTotalCount > confirmedCount,
typeTotalCount: typeTotal.items.length,
};
}
/*
* ─── 쓰기 경로 ────────────────────────────────────────────────────────────────
* 컨트롤러가 `@ParameterObject`로 받으므로 전부 form 인코딩으로 보낸다(파일 상단 주석 참조).
*/
/** 등록·수정이 공유하는 전송 필드. */
function buildWriteForm(
values: DecorationItemEditableValues
): Record<string, string | number | undefined> {
return {
itemNm: values.name,
itemCateCd: values.categoryCode,
itemAmount: values.points,
itemExplan: values.description,
useYn: values.isActive ? 'Y' : 'N',
sortOrdr: values.sortOrder,
itemType: ITEM_TYPE_CODE[values.itemType],
// 썸네일은 백엔드가 자동생성하도록 바뀔 예정이라 지금은 atchFileId만 보낸다(사용자 확정 사항).
atchFileId: values.imageFileId,
};
}
async function sendWrite(
path: string,
method: 'POST' | 'PUT',
values: DecorationItemEditableValues
): Promise<void> {
const accessToken = await getSessionAccessToken();
const result = await backendFetch<null>(path, {
method,
form: buildWriteForm(values),
accessToken: accessToken ?? undefined,
cache: 'no-store',
// 등록·수정 성공 응답은 `ApiResponseVO.success(null)` — data가 정상적으로 null이다.
canHaveNullData: true,
});
if (!result.ok) {
throw new BackendRequestError(result);
}
}
export async function createDecorationItem(
values: DecorationItemEditableValues
): Promise<void> {
await sendWrite(DECORATION_ITEM_PATH, 'POST', values);
}
/**
* 수정.
*
* ⚠️ **백엔드 결함**: 컨트롤러의 update가 요청 VO에서 `itemType`을 빌더에 담지 않는데 UPDATE 문은
* `ITEM_TYPE = #{itemType}`을 쓴다 — 그래서 수정하면 ITEM_TYPE이 null이 되고, 목록은
* `ITEM_TYPE = searchItemType`으로 필터하므로 그 아이템이 개별·셋트 양쪽 탭에서 사라진다.
* 우리가 `itemType`을 보내도 컨트롤러가 버리므로 프론트에서 우회할 수 없다(사용자 지시로 그대로
* 연동하고 이슈로 보고한다). `lastMdfcnDt`도 컨트롤러가 채우지 않아 수정일시가 null이 된다.
*/
export async function updateDecorationItem(
itemSn: number,
values: DecorationItemEditableValues
): Promise<void> {
await sendWrite(`${DECORATION_ITEM_PATH}/${itemSn}`, 'PUT', values);
}
export async function deleteDecorationItem(itemSn: number): Promise<void> {
const accessToken = await getSessionAccessToken();
const result = await backendFetch<null>(`${DECORATION_ITEM_PATH}/${itemSn}`, {
method: 'DELETE',
accessToken: accessToken ?? undefined,
cache: 'no-store',
canHaveNullData: true,
});
if (!result.ok) {
throw new BackendRequestError(result);
}
}
/**
* 이미지 업로드 — 성공 시 `atchFileId` 문자열을 돌려준다.
*
* 브라우저가 백엔드에 직접 올리지 않는다(토큰이 서버에만 있다) — Server Action이 받은 File을
* 그대로 백엔드로 중계한다.
*/
export async function uploadDecorationItemImage(file: File): Promise<string> {
const accessToken = await getSessionAccessToken();
const multipart = new FormData();
multipart.set('file', file);
const result = await backendFetch<string>(
`${FILE_UPLOAD_PATH}/${ITEM_FILE_MODULE_ID}`,
{
method: 'POST',
multipart,
accessToken: accessToken ?? undefined,
cache: 'no-store',
}
);
if (!result.ok) {
throw new BackendRequestError(result);
}
if (typeof result.data !== 'string' || !result.data) {
throw new Error('이미지 업로드 응답에 파일 ID가 없습니다.');
}
return result.data;
}