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 형식을 사용하여 함수/메서드의 목적, 파라미터, 반환 값을 설명하는 것을 권장합니다.

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: 서버 내부 오류

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 이미지를 빌드하여 배포

---

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