Merge pull request #1342 from Moadong/develop-fe

[release] FE

Author: seongwon030

.github/workflows/frontend-ci.yml

@@ -35,4 +35,6 @@ jobs:
         run: npm run lint
 
       - name: Build
+        env:
+          SKIP_DYNAMIC_SITEMAP: 'true'
         run: npm run build

.gitignore

@@ -8,4 +8,5 @@
 CLAUDE.md
 .claude
 
-dailyNote/
+dailyNote/
+

AGENTS.md

@@ -0,0 +1,153 @@
+# AGENTS.md
+
+## 목적
+
+이 문서는 코딩 에이전트가 `moadong` 저장소에 들어왔을 때 바로 작업을 시작할 수 있도록 프로젝트 구조, 실행 방법, 코드 작성 규칙, 검증 방식, 협업 규칙을 전달하기 위한 가이드다.
+
+## 프로젝트 구조
+
+- 루트는 `frontend/`와 `backend/`로 나뉜다.
+- 프론트엔드는 React + TypeScript + Vite 기반이다.
+- 백엔드는 Spring Boot + Gradle 기반이다.
+
+### 프론트엔드 주요 경로
+
+- `frontend/src/pages/`
+  - 라우트 단위 페이지
+- `frontend/src/components/`
+  - 공통 UI 컴포넌트
+- `frontend/src/hooks/`
+  - 재사용 훅
+- `frontend/src/hooks/Queries/`
+  - 서버 상태 조회 및 변경 훅
+- `frontend/src/apis/`
+  - API 호출 함수
+- `frontend/src/store/`
+  - 클라이언트 상태
+- `frontend/src/styles/`
+  - 전역 스타일 및 테마
+
+### 백엔드 주요 경로
+
+- `backend/src/main/java/moadong/`
+  - 도메인별 패키지 루트
+- `backend/src/main/java/moadong/global/`
+  - 공통 설정, 예외, 유틸
+- `backend/src/main/java/moadong/club/`
+  - 동아리 관련 도메인
+- `backend/src/main/java/moadong/user/`
+  - 사용자 관련 도메인
+
+## 개발 환경
+
+### 프론트엔드
+
+- 작업 경로: `/Users/seokyoung-won/Desktop/moadong/frontend`
+- Node 버전: `frontend/.nvmrc` 기준
+- 현재 확인된 버전: `22.12.0`
+- 번들러: Vite
+- 설정 파일: `frontend/config/vite.config.ts`
+
+### 백엔드
+
+- 작업 경로: `/Users/seokyoung-won/Desktop/moadong/backend`
+- Java 버전: 17
+- 빌드 도구: Gradle
+
+## 빌드 및 테스트 명령어
+
+### 프론트엔드
+
+```bash
+nvm use
+npm install
+npm run dev
+npm run build
+npm run test
+npm run typecheck
+```
+
+### 백엔드
+
+```bash
+./gradlew bootRun
+./gradlew test
+./gradlew unitTest
+./gradlew integrationTest
+```
+
+## 작업 원칙
+
+- 기존 구조와 패턴을 먼저 따르고, 필요가 명확할 때만 새 패턴을 추가한다.
+- 변경 범위는 가능한 한 작게 유지한다.
+- 기능 변경과 대규모 리팩터링을 한 번에 섞지 않는다.
+- 학생용 흐름과 관리자용 흐름에 공통으로 영향을 주는 수정은 양쪽 화면을 함께 의식한다.
+- API 계약을 바꾸는 수정은 프론트와 백엔드 영향 범위를 같이 확인한다.
+
+## 코드 스타일 규칙
+
+### 프론트엔드
+
+- 먼저 기존 페이지와 인접한 파일의 코드 스타일을 따른다.
+- 데이터 패칭은 `frontend/src/hooks/Queries/`의 기존 패턴을 우선 재사용한다.
+- API 호출은 `frontend/src/apis/`에 두고, 페이지나 컴포넌트 안에 직접 분산시키지 않는다.
+- 공통 UI가 필요하면 `frontend/src/components/`에서 재사용 가능한지 먼저 확인한다.
+- 타입이 필요하면 기존 타입 선언 위치와 네이밍 규칙을 따른다.
+
+### 백엔드
+
+- 도메인 패키지 구성을 유지한다.
+- controller, service, repository, dto 또는 payload 역할을 섞지 않는다.
+- 예외 처리와 검증은 기존 프로젝트 방식과 일관되게 맞춘다.
+- 파일 업로드, 알림, 실시간 이벤트처럼 부작용이 있는 로직은 연관 기능까지 같이 확인한다.
+
+## 검증 기준
+
+- 수정 후에는 가능한 한 가장 좁은 범위의 검증부터 실행한다.
+- 프론트 UI 수정이면 관련 페이지와 훅, 테스트 가능 여부를 먼저 확인한다.
+- 공통 상태나 공통 컴포넌트 변경이면 영향 받는 페이지를 넓게 살핀다.
+- 백엔드 수정이면 관련 테스트 태스크가 있는지 먼저 확인한 뒤 필요한 범위만 실행한다.
+- 실행하지 못한 테스트가 있으면 결과 보고 시 명시한다.
+
+## 소규모 보안 주의사항
+
+- 비밀키, 토큰, 계정 정보, 민감 설정값을 코드나 문서에 직접 남기지 않는다.
+- `.env`나 로컬 설정 파일을 새로 만들거나 수정할 때는 커밋 대상인지 반드시 확인한다.
+- 사용자 입력은 신뢰하지 않고 검증 로직을 유지한다.
+- 로그에 개인정보나 민감한 식별자를 과도하게 남기지 않는다.
+- 인증, 파일 업로드, 외부 스토리지, 푸시, 메일 관련 변경은 영향 범위를 명확히 확인한다.
+
+## 커밋 규칙
+
+- 한글로 작성한다.
+- 한 커밋은 하나의 목적을 가지도록 유지한다.
+- 커밋 메시지는 짧고 명확하게 작성한다.
+- 가능하면 변경 이유가 드러나는 동사를 사용한다.
+
+예시:
+
+```text
+feat: 관리자 지원자 상태 변경 UI 추가
+fix: 모집 종료일 검증 오류 수정
+refactor: 지원서 조회 훅 분리
+test: 지원 폼 유효성 검사 케이스 추가
+```
+
+## PR 작성 규칙
+
+- 제목만 보고도 변경 목적을 이해할 수 있게 작성한다.
+- 본문에는 최소한 다음 내용을 포함한다.
+  - 변경 내용
+  - 변경 이유
+  - 검증 방법
+  - 영향 범위
+- UI 변경이면 가능하면 스크린샷 또는 화면 설명을 첨부한다.
+- 학생용 화면 변경인지 관리자용 화면 변경인지 드러나게 적는다.
+
+## 신규 멤버를 위한 메모
+
+- 먼저 `README.md`를 읽고 서비스 맥락을 파악한다.
+- 프론트엔드는 `frontend/package.json`, `frontend/src/pages/`, `frontend/src/hooks/Queries/`를 먼저 보면 구조 파악이 빠르다.
+- 백엔드는 `backend/build.gradle`과 주요 도메인 패키지를 먼저 보면 된다.
+- 처음 수정할 때는 넓은 리팩터링보다 작은 기능 단위로 진입하는 편이 안전하다.
+- 운영 데이터나 배포 방식은 문서가 없으면 추측하지 말고 팀의 기존 절차를 확인한다.

frontend/.gitignore

@@ -18,5 +18,8 @@ build-storybook.log
 /storybook-static
 *storybook.log
 coverage/ 
+public/sitemap.xml
 # Sentry Config File
-.env.sentry-build-plugin
+.env.sentry-build-plugin
+
+AGENTS.md

frontend/package.json

@@ -4,10 +4,11 @@
   "main": "index.js",
   "scripts": {
     "dev": "vite --config ./config/vite.config.ts",
-    "build": "tsc --noEmit && vite build --config ./config/vite.config.ts",
+    "generate:sitemap": "node ./scripts/generate-sitemap.mjs",
+    "build": "npm run generate:sitemap && tsc --noEmit && vite build --config ./config/vite.config.ts",
     "preview": "vite preview --config ./config/vite.config.ts",
-    "build:dev": "vite build --config ./config/vite.config.ts",
-    "build:prod": "NODE_ENV=production vite build --config ./config/vite.config.ts",
+    "build:dev": "npm run generate:sitemap && vite build --config ./config/vite.config.ts",
+    "build:prod": "npm run generate:sitemap && NODE_ENV=production vite build --config ./config/vite.config.ts",
     "clean": "rm -rf dist",
     "format": "prettier --write \"**/*.{ts,tsx,js,jsx,css,scss}\"",
     "lint": "eslint --fix",

frontend/public/sitemap.xml

@@ -0,0 +1,172 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const SITE_URL =
+  process.env.SITE_URL ||
+  process.env.VITE_SITE_URL ||
+  'https://www.moadong.com';
+const STATIC_PATHS = [
+  '/',
+  '/introduce',
+  '/club-union',
+  '/festival-introduction',
+];
+const ENV_FILES = [
+  '.env',
+  '.env.local',
+  '.env.production',
+  '.env.production.local',
+];
+const FETCH_TIMEOUT_MS = 10_000;
+const shouldSkipDynamicSitemap = ['1', 'true', 'yes'].includes(
+  (process.env.SKIP_DYNAMIC_SITEMAP || '').toLowerCase(),
+);
+
+const loadEnvFile = async (filePath) => {
+  try {
+    const raw = await readFile(filePath, 'utf8');
+
+    raw.split(/\r?\n/).forEach((line) => {
+      const trimmed = line.trim();
+
+      if (!trimmed || trimmed.startsWith('#')) {
+        return;
+      }
+
+      const separatorIndex = trimmed.indexOf('=');
+      if (separatorIndex === -1) {
+        return;
+      }
+
+      const key = trimmed.slice(0, separatorIndex).trim();
+      if (!key || process.env[key]) {
+        return;
+      }
+
+      let value = trimmed.slice(separatorIndex + 1).trim();
+
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1);
+      }
+
+      process.env[key] = value;
+    });
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+};
+
+const escapeXml = (value) =>
+  value
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+
+const formatLastModified = (date) => {
+  const isoString = date.toISOString();
+  return `${isoString.slice(0, 19)}+00:00`;
+};
+
+const buildUrlEntry = (loc, lastmod) => `  <url>
+    <loc>${escapeXml(loc)}</loc>
+    <lastmod>${lastmod}</lastmod>
+    <changefreq>daily</changefreq>
+    <priority>${loc === `${SITE_URL}/` ? '1.0' : '0.8'}</priority>
+  </url>`;
+
+const getDynamicPaths = async (apiBaseUrl) => {
+  if (shouldSkipDynamicSitemap) {
+    console.warn(
+      '[generate-sitemap] SKIP_DYNAMIC_SITEMAP is enabled. Generating static sitemap only.',
+    );
+    return [];
+  }
+
+  if (!apiBaseUrl) {
+    console.warn(
+      '[generate-sitemap] VITE_API_BASE_URL is not set. Generating static sitemap only.',
+    );
+    return [];
+  }
+
+  try {
+    const searchUrl = new URL('/api/club/search/', apiBaseUrl);
+    searchUrl.search = new URLSearchParams({
+      keyword: '',
+      recruitmentStatus: 'all',
+      category: 'all',
+      division: 'all',
+    }).toString();
+
+    const response = await fetch(searchUrl, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch clubs for sitemap: ${response.status} ${response.statusText}`,
+      );
+    }
+
+    const payload = await response.json();
+    const clubs = Array.isArray(payload?.data?.clubs)
+      ? payload.data.clubs
+      : Array.isArray(payload?.clubs)
+        ? payload.clubs
+        : [];
+
+    return clubs
+      .map((club) => club?.name)
+      .filter((name) => typeof name === 'string' && name.trim().length > 0)
+      .map((name) => `/clubDetail/@${encodeURIComponent(name.trim())}`);
+  } catch (error) {
+    console.warn(
+      '[generate-sitemap] Failed to fetch dynamic club URLs. Falling back to static sitemap only.',
+    );
+    console.warn(`[generate-sitemap] ${error.message}`);
+    return [];
+  }
+};
+
+const main = async () => {
+  const rootDir = process.cwd();
+  await Promise.all(
+    ENV_FILES.map((fileName) => loadEnvFile(path.join(rootDir, fileName))),
+  );
+
+  const apiBaseUrl = process.env.VITE_API_BASE_URL;
+  const dynamicPaths = await getDynamicPaths(apiBaseUrl);
+  const timestamp = formatLastModified(new Date());
+
+  const allPaths = [...STATIC_PATHS, ...dynamicPaths];
+  const uniquePaths = [...new Set(allPaths)];
+
+  const xml = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+    ...uniquePaths.map((routePath) =>
+      buildUrlEntry(new URL(routePath, SITE_URL).toString(), timestamp),
+    ),
+    '</urlset>',
+    '',
+  ].join('\n');
+
+  const outputPath = path.join(rootDir, 'public', 'sitemap.xml');
+  await mkdir(path.dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, xml, 'utf8');
+
+  console.log(
+    `Generated sitemap with ${uniquePaths.length} URLs at ${outputPath}`,
+  );
+};
+
+main().catch((error) => {
+  console.error('[generate-sitemap]', error);
+  process.exit(1);
+});