TK-FB-Project/_archive/룰.md

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

## 1. 프로젝트 개요

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

## 2. 기술 스택 및 개발 환경

### 2.1. 개발 환경 (Docker 기반)

**🐳 현재 Docker Compose로 개발 중**

```bash
# 컨테이너 상태 확인
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**을 사용합니다.
- 성공 응답:
    ```json
    {
      "status": "success",
      "data": { ... }
    }
    ```
- 실패 응답:
    ```json
    {
      "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 실행

```bash
# 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. 요청/응답 예시

**필터 데이터 조회:**
```http
GET /api/daily-work-reports-analysis/filters
Authorization: Bearer {jwt_token}
```

**응답:**
```json
{
  "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"
    }
  }
}
```

**기간별 분석:**
```http
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)

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