TK-FB-Project/룰.md

생산팀 내부 포털 개발 및 유지보수 규칙

1. 프로젝트 개요

본 문서는 (주)테크니컬코리아 생산팀 내부 포털의 원활한 개발 및 유지보수를 위한 규칙을 정의합니다. 모든 개발자는 본 규칙을 숙지하고 준수해야 합니다.

2. 기술 스택

2.1. 백엔드 (api.hyungi.net)

• 런타임: Node.js
• 프레임워크: Express.js
• 데이터베이스: MariaDB (MySQL)
• 인증: JWT (JSON Web Token)
• 프로세스 매니저: PM2
• 컨테이너: Docker

2.2. 프론트엔드 (web-ui)

• 언어: HTML, CSS, JavaScript (ES6+ Modules)
• 라이브러리: 별도 프레임워크 없이 순수 JS/HTML/CSS 사용

3. 코딩 컨벤션

3.1. 네이밍 컨벤션

• JavaScript (백엔드/프론트엔드):
  • 변수/함수: camelCase (예: calculateTotal)
  • 클래스: PascalCase (예: UserReport)
  • 상수: UPPER_SNAKE_CASE (예: MAX_RETRIES)
• 파일:
  • kebab-case (예: daily-work-report.js)
• CSS:
  • kebab-case (예: .main-container)
• 데이터베이스:
  • 테이블/컬럼: snake_case (예: user_accounts, created_at)

3.2. 코드 포맷팅

• 들여쓰기: 스페이스 2칸
• 세미콜론: 문장 끝에 항상 사용
• ** Prettier 와 같은 코드 포맷터를 사용하여 일관성을 유지하는 것을 강력히 권장합니다.

3.3. 주석

• 복잡한 로직이나 설명이 필요한 부분에 간결하고 명확한 주석을 작성합니다.
• JSDoc 형식을 사용하여 함수/메서드의 목적, 파라미터, 반환 값을 설명하는 것을 권장합니다.

3.4. 파일 길이 가이드라인

• 가독성과 유지보수성을 높이기 위해 파일이 단일 책임을 갖도록 관리하는 것을 목표로 합니다.
• 파일의 길이가 750줄을 초과하기 시작하면, 해당 파일이 너무 많은 역할을 하고 있을 수 있다는 신호로 간주합니다.
• 이 경우, 파일을 역할(라우팅, 컨트롤러, 서비스, 모델 등)에 따라 분리하는 리팩토링을 적극적으로 권장합니다.

3.5. 구조도 문서화

• 하나의 기능이 여러 파일(예: 컨트롤러, 서비스, 모델)로 분리되는 복잡한 구조를 가질 경우, 코드만으로 데이터 흐름이나 파일 간의 상호작용을 파악하기 어려울 수 있습니다.
• 이 경우, 기능의 메인 폴더나 관련 문서(README.md 등)에 간단한 구조도나 설명을 추가하여 다른 개발자들이 구조를 쉽게 이해할 수 있도록 돕는 것을 권장합니다.
• 간단한 텍스트 설명이나 Mermaid.js와 같은 도구를 사용한 다이어그램으로 구조를 명시합니다.

4. API 개발 가이드

4.1. 엔드포인트

• RESTful API 원칙을 따릅니다.
• 리소스는 복수형 명사 사용 (예: /users, /reports)
• 동사보다는 명사를 사용 (예: POST /users (O), POST /createUser (X))

4.2. 요청/응답

• 데이터 형식은 JSON을 사용합니다.
• 성공 응답:

  {
    "status": "success",
    "data": { ... }
  }
  

• 실패 응답:

  {
    "status": "error",
    "message": "에러 메시지"
  }
  

4.3. HTTP 상태 코드

• 200 OK: 요청 성공
• 201 Created: 리소스 생성 성공
• 400 Bad Request: 클라이언트 요청 오류
• 401 Unauthorized: 인증 실패
• 403 Forbidden: 인가(권한) 실패
• 404 Not Found: 리소스 없음
• 500 Internal Server Error: 서버 내부 오류

4.4. 성능 및 자원 관리

• 최소한의 데이터 조회: API는 반드시 필요한 데이터만 조회하고 반환해야 합니다. SELECT * 사용을 지양하고, 실제 클라이언트에서 사용하는 컬럼만 명시적으로 조회합니다.
• 효율적인 쿼리 작성: 복잡한 JOIN이나 비효율적인 WHERE 조건으로 인해 데이터베이스에 과도한 부하를 주는 쿼리가 없는지 항상 확인합니다.
• 코드 리뷰: 새로운 API를 개발하거나 기존 API를 수정할 때, 동료 개발자는 기능의 정확성뿐만 아니라 성능 측면(쿼리 효율, 불필요한 로직 등)도 함께 검토해야 합니다. 성능 저하가 의심되는 코드는 즉시 개선하는 것을 원칙으로 합니다.

5. 데이터베이스 관리

• 테이블/컬럼 네이밍: snake_case 사용
• 스키마 변경:
  • 반드시 migrations 디렉토리에 마이그레이션 스크립트(*.sql)를 작성하여 변경 이력을 관리합니다.
  • 직접 DB에 ALTER TABLE 등을 실행하지 않습니다.

6. Git 관리

6.1. 커밋 메시지 규칙

• 형식: 타입: 제목
• 타입:
  • feat: 새로운 기능 추가
  • fix: 버그 수정
  • docs: 문서 수정
  • style: 코드 스타일 변경 (포맷팅, 세미콜론 등)
  • refactor: 코드 리팩토링
  • test: 테스트 코드 추가/수정
  • chore: 빌드, 패키지 매니저 등 설정 변경
• 예시: feat: 일일 업무 보고서 조회 API 추가

6.2. 브랜치 전략

• main: 최종 배포 버전 브랜치
• develop: 개발 브랜치
• feature/기능명: 기능 개발 브랜치 (예: feature/login-jwt)
• hotfix/이슈번호: 긴급 버그 수정 브랜치

7. 배포

• 환경: development (개발), production (운영)
• 배포 절차:
  1. feature 브랜치 -> develop 브랜치로 Pull Request (PR)
  2. develop 브랜치에서 충분한 테스트
  3. develop 브랜치 -> main 브랜치로 PR
  4. main 브랜치에 머지되면 Docker 이미지를 빌드하여 배포

---

본 규칙은 프로젝트 진행 상황에 따라 지속적으로 개선될 수 있습니다.