137 lines
5.0 KiB
Markdown
137 lines
5.0 KiB
Markdown
|
|
# 생산팀 내부 포털 개발 및 유지보수 규칙
|
|
|
|
## 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**을 사용합니다.
|
|
- 성공 응답:
|
|
```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`: 서버 내부 오류
|
|
|
|
## 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 이미지를 빌드하여 배포
|
|
|
|
---
|
|
본 규칙은 프로젝트 진행 상황에 따라 지속적으로 개선될 수 있습니다. |