Code Convention

코드 컨벤션

이 문서는 한국기술교육대학교 오픈소스포털의 프로젝트 단위 코드 작성 기준입니다.

적용 범위

• src/ 이하 모든 신규/수정 코드
• 기존 코드와 충돌 시: 기존 동작 보존 > 점진적 컨벤션 정렬

1) 기본 원칙

• 읽기 쉬운 코드가 우선입니다.
• 중복보다 공용화가 우선이지만, 과한 추상화는 피합니다.
• 변경은 작고 명확하게 나눕니다.
• 동작 변경이 있으면 문서(Wiki + docs)를 함께 갱신합니다.

2) TypeScript / 정적 분석 규칙

• tsconfig.json 기준 strict: true를 유지합니다.
• export 되는 함수/타입은 반환/인터페이스를 명시합니다.
• any는 불가피한 경우만 사용하고 근거 주석을 남깁니다.
• 린트 기준은 eslint-config-next/core-web-vitals, eslint-config-next/typescript를 따릅니다.
• 포맷은 .prettierrc.json을 기준으로 자동 정렬합니다.

3) 파일/네이밍 규칙

라우트 파일

• App Router 고정 파일명 사용
  • page.tsx, layout.tsx, route.ts
  • error.tsx, global-error.tsx, not-found.tsx

컴포넌트/훅

• 컴포넌트: PascalCase.tsx
• 훅: useXxx.ts(x)
• 클라이언트 전용 대형 UI: *Client.tsx

API 함수

• 조회: get*
• 생성: create*
• 수정: update*
• 삭제: delete*
• 토글/액션: toggle*, apply*, decide*

4) React / Next.js 작성 규칙

• 기본은 서버 컴포넌트로 작성합니다.
• 브라우저 API/상태/이벤트가 필요할 때만 'use client'를 선언합니다.
• 데이터 패칭은 page.tsx(서버)에서 우선 처리하고, UI 상호작용은 *Client.tsx로 분리합니다.
• 내부 이동은 Link를 우선 사용합니다.
• 보호 라우트는 middleware.ts와 페이지 단 권한 검사를 함께 고려합니다.

5) import 규칙

• 우선순위
  1. 외부 패키지
  2. @/ 절대 경로 import
  3. 상대 경로 import
• 경로 별칭은 @/* -> src/*만 사용합니다.
• 순환 참조가 생기는 구조는 분리합니다.

6) API 계층 규칙

• 호출은 src/lib/api/* 모듈에 작성합니다.
• 서버/공용 호출은 apiClient를 사용합니다.
• 클라이언트 인증 호출은 clientApiClient를 사용합니다.
• 쿼리 문자열은 URLSearchParams로 구성합니다.
• 예외는 ApiException으로 표준화해 처리합니다.

7) 인증/보안 규칙

• 토큰은 HttpOnly 쿠키(kosp_access_token, kosp_refresh_token) 기반으로 관리합니다.
• 인증 관련 변경 시 Authentication, Routing-Map, Troubleshooting 문서를 함께 갱신합니다.
• 민감 정보는 코드 하드코딩 대신 환경 변수 사용을 우선합니다.

8) 스타일링 규칙

• 기본 스타일링은 Tailwind 유틸 클래스를 사용합니다.
• 클래스 병합은 cn() 유틸(src/lib/utils.ts)을 사용합니다.
• 전역 규칙은 src/app/globals.css에만 추가합니다.
• 인라인 스타일은 동적 계산이 불가피한 경우에만 사용합니다.

9) 상태/이벤트 규칙

• 전역 세션 상태는 AuthContext를 기준으로 처리합니다.
• 커스텀 브라우저 이벤트(sessionChanged, tokenRefreshed, serverDown, sse:notification)는 이름을 변경하지 않습니다.
• 타이머/인터벌 값은 상수로 선언하고 의미 있는 이름을 사용합니다.

10) 에러 처리/로깅 규칙

• 사용자 노출 메시지와 개발자 로그를 분리합니다.
• 네트워크/서버 장애는 serverDown 플로우를 유지합니다.
• 로그아웃/토큰 만료 처리에는 중복 방지 로직(signOutOnce)을 사용합니다.
• console.log 디버그 로그는 머지 전 제거를 원칙으로 합니다.

11) 브랜치/커밋/PR 규칙

브랜치

• develop에서 분기
• 권장 prefix: feat/, fix/, docs/, refactor/, chore/

커밋

• 권장 포맷: <type>: <summary>
  • 예: feat: 팀 초대 수락 플로우 개선

PR

• 변경 요약, 이슈 링크, 영향 범위를 명시합니다.
• 동작 변경 시 스크린샷/재현 절차를 포함합니다.
• 문서 영향이 있으면 Wiki + docs/를 같이 갱신합니다.

12) 신규 코드 체크리스트

• 서버/클라이언트 컴포넌트 경계가 명확한가?
• API 모듈 네이밍/호출 규칙을 지켰는가?
• 타입/린트/포맷 규칙을 지켰는가?
• 에러/권한/만료 케이스를 처리했는가?
• 문서(Wiki + docs/)를 동기화했는가?