TK-FB-Project/룰.md

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

1. 프로젝트 개요

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

2. 기술 스택 및 개발 환경

2.1. 개발 환경 (Docker 기반)

🐳 현재 Docker Compose로 개발 중

# 컨테이너 상태 확인
docker ps

# 주요 컨테이너들:
- api_hyungi_dev     (포트: 20005) - 백엔드 API 서버
- web_hyungi_dev     (포트: 20000) - 프론트엔드 웹 서버  
- db_hyungi_dev      (포트: 20306) - MariaDB 데이터베이스
- pma_hyungi_dev     (포트: 20080) - phpMyAdmin

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

• 런타임: Node.js
• 프레임워크: Express.js
• 데이터베이스: MariaDB (MySQL)
• 인증: JWT (JSON Web Token)
• 프로세스 매니저: PM2
• 컨테이너: Docker
• 포트: 20005 (API 서버)
• API Base URL: http://localhost:20005

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

• 언어: HTML, CSS, JavaScript (ES6+ Modules)
• 라이브러리: 별도 프레임워크 없이 순수 JS/HTML/CSS 사용
• 웹서버: Nginx
• 포트: 20000 (웹 서버)
• Web UI URL: http://localhost:20000

2.4. 데이터베이스 관리

• MariaDB: localhost:20306
  • 사용자명: hyungi
  • 비밀번호: tycdoq-Kawcug-8wesfa
  • 데이터베이스: hyungi_dev
• phpMyAdmin: http://localhost:20080
• 시스템 계정: 동일한 계정 정보 사용

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. FastAPI 브릿지 아키텍처 (2025.07 도입)

7.1. 개요

웹서비스 확장성과 성능 향상을 위해 FastAPI 브릿지를 도입합니다. DS923+ 환경에서 최적의 성능을 발휘하도록 설계되었습니다.

7.2. 아키텍처

브라우저 → FastAPI (포트 8000) → Express.js API (포트 3005)
         ↓
    정적 파일 서빙
    API 게이트웨이
    캐싱 (Redis)
    AI/ML 처리

7.3. 기술 스택 (추가)

7.3.1. FastAPI 브릿지

• 런타임: Python 3.11+
• 프레임워크: FastAPI
• 비동기: asyncio, aiohttp
• 캐싱: Redis
• 문서화: Swagger/OpenAPI 자동 생성

7.4. 개발 단계

Phase 1: 기본 프록시 (2-3주)

• FastAPI 기본 설정
• Express.js API 프록시
• 헬스체크 및 모니터링

Phase 2: 정적 파일 이관 (1주)

• 웹 UI 정적 파일 서빙
• 단일 포트 통합 (8000)

Phase 3: 캐싱 계층 (1-2주)

• Redis 캐싱 구현
• 성능 최적화

Phase 4: 확장 기능 (지속적)

• 데이터 분석 API
• AI/ML 기능
• 외부 시스템 연동

7.5. 성능 목표 (DS923+ 기준)

• 동시 사용자: 200명 이상
• 응답 시간: 50-150ms
• 파일 처리: 대용량 지원
• 가용성: 99.9% 이상

8. Docker 환경 구성

8.1. 컨테이너 구성

현재 시스템은 Docker로 완전히 컨테이너화되어 있으며, 다음과 같은 서비스들로 구성됩니다:

8.1.1. 개발 환경 (현재 실행 중)

서비스	컨테이너명	포트	설명
웹 서버	web_hyungi_dev	20000	Nginx 기반 프론트엔드
API 서버	api_hyungi_dev	20005	Node.js Express.js 백엔드
데이터베이스	db_hyungi_dev	20306	MariaDB 10.9
DB 관리	pma_hyungi_dev	20080	phpMyAdmin

8.1.2. 서비스 접속 방법

• 메인 웹사이트: http://localhost:20000
• API 엔드포인트: http://localhost:20005
• 데이터베이스 관리: http://localhost:20080 (phpMyAdmin)
• 데이터베이스 직접 접속: localhost:20306

8.1.3. Docker Compose 실행

# api.hyungi.net 디렉토리에서 실행
cd api.hyungi.net
docker-compose up -d

# 상태 확인
docker ps | grep hyungi

# 로그 확인
docker logs api_hyungi_dev
docker logs web_hyungi_dev

8.1.4. 환경 변수

시스템 설정은 api.hyungi.net/.env 파일에서 관리됩니다:

• 데이터베이스 연결 정보
• API 포트 설정
• JWT 시크릿 키
• 기타 환경별 설정

8.1.5. 기본 계정 정보

웹 포털 관리자 계정:

• 사용자명: hyungi
• 비밀번호: tycdoq-Kawcug-8wesfa
• 권한: admin
• 용도: 시스템 관리 및 개발/테스트

주의사항:

• 이 계정은 개발 및 관리 목적으로만 사용
• 운영 환경에서는 별도의 보안 계정 사용 권장
• 비밀번호 변경 시 본 문서도 함께 업데이트

8.2. 배포

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

9. API 구조 및 엔드포인트

9.1. 작업보고서 분석 API

9.1.1. 개요

• 목적: 데일리 워크 레포트 데이터의 종합 분석 및 시각화
• 권한: Admin 등급 이상 (admin, system)
• 베이스 URL: /api/daily-work-reports-analysis

9.1.2. 엔드포인트 목록

메서드	엔드포인트	설명	권한
GET	/filters	분석용 필터 데이터 조회	Admin+
GET	/period	기간별 종합 분석	Admin+
GET	/project	프로젝트별 상세 분석	Admin+
GET	/worker	작업자별 상세 분석	Admin+

9.1.3. 요청/응답 예시

필터 데이터 조회:

GET /api/daily-work-reports-analysis/filters
Authorization: Bearer {jwt_token}

응답:

{
  "success": true,
  "data": {
    "projects": [
      {"project_id": 1, "project_name": "프로젝트A"}
    ],
    "workers": [
      {"worker_id": 1, "worker_name": "홍길동"}
    ],
    "workTypes": [
      {"work_type_id": 1, "work_type_name": "설계"}
    ],
    "dateRange": {
      "min_date": "2025-01-01",
      "max_date": "2025-12-31"
    }
  }
}

기간별 분석:

GET /api/daily-work-reports-analysis/period?start_date=2025-08-01&end_date=2025-08-31&project_id=1
Authorization: Bearer {jwt_token}

9.1.4. 보안 정책

• 인증: JWT 토큰 필수
• 권한: admin 또는 system 권한 필요
• 접근 제어: 프론트엔드에서 권한 체크 후 페이지 접근 허용
• 오류 응답: 권한 부족 시 403 Forbidden 반환

9.1.5. 프론트엔드 연동

• 페이지: /pages/analysis/work-report-analytics.html
• 네비게이션: Admin 섹션에 ADMIN 배지와 함께 표시
• 권한 체크: 페이지 로드 시 localStorage의 사용자 권한 확인

9.2. API 네이밍 규칙

9.2.1. 라우트 네이밍

• kebab-case 사용 (예: daily-work-reports-analysis)
• 복수형 명사 사용 (예: reports, users)
• RESTful 원칙 준수

9.2.2. 파일 네이밍

• 컨트롤러: {resource}Controller.js (camelCase)
• 라우트: {resource}Routes.js (camelCase)
• 모델: {resource}Model.js (camelCase)

---

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