TK-FB-Project/CODING_GUIDE.md

TK-FB-Project 통합 개발 가이드

이 문서는 프로젝트의 실행, 규칙, 테스트, 호환성 등 모든 개발 관련 사항을 통합한 가이드입니다.

---

🏗 프로젝트 개요 및 아키텍처

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

기술 스택

• Backend: Node.js, Express.js (Port: 20005)
• Frontend: Vanilla HTML/CSS/JS (Port: 20000)
• Database: MariaDB (Port: 20306), phpMyAdmin (Port: 20080)
• Infra: Docker Compose (Synology NAS, Mac Mini)
• Bridge: FastAPI (Port: 20010, Python 3.11+) - 2025.07 도입

아키텍처 모식도

브라우저 → FastAPI (8000) → Express (3005) → MariaDB
                         ↓
                   정적 파일 서빙

Note: 현재 개발 환경 포트는 위 기술 스택 섹션 참조

---

🚀 실행 가이드

필수: 환경 변수 설정

.env.example을 .env로 복사하고 설정하세요. 절대 커밋 금지!

Docker 실행

./start.sh        # 간편 실행 (권장)
./stop.sh         # 중지
docker-compose up -d # 수동 실행

---

📏 코딩 컨벤션

네이밍

대상	스타일	예시
JS 변수/함수	camelCase	calculateTotal
JS 클래스	PascalCase	UserReport
파일명	kebab-case	work-report.js
DB 테이블/컬럼	snake_case	user_accounts
API URL	plural, kebab	/api/work-reports

코드 품질

• 파일 분리: 750줄 초과 시 리팩토링 고려 (Controller/Service/Model 분리 필수).
• Early Return: 중첩 조건문 지양.
• 주석: JSDoc 활용 권장.

---

🎨 UI/UX 디자인 가이드

디자인 원칙

• 모던하고 깔끔한 디자인: 이모지 사용 지양, 아이콘 또는 심플한 텍스트 사용
• 일관성: 모든 페이지에서 동일한 디자인 시스템 적용
• 컴포넌트 재사용: navbar, footer 등은 컴포넌트로 관리

이모지 사용 금지

❌ 금지:

<!-- 나쁜 예 -->
<button>📊 대시보드</button>
<h1>🔧 작업 관리</h1>

✅ 권장:

<!-- 좋은 예 - 아이콘 라이브러리 사용 또는 심플한 텍스트 -->
<button class="btn-primary">
  <i class="icon-dashboard"></i>
  대시보드
</button>
<h1>작업 관리</h1>

색상 가이드

• Primary: 하늘색 계열 (#0ea5e9, #38bdf8, #7dd3fc)
• 기본 배경: 흰색/밝은 회색 계열
• 텍스트: #1f2937 (dark gray)
• 보조 텍스트: #6b7280 (medium gray)

컴포넌트 구조

• 네비게이션: web-ui/components/navbar.html 참조
• 일관된 헤더: 모든 페이지에서 <div id="navbar-container"></div> 사용
• CSS 로딩 순서: design-system.css → 페이지별 CSS

페이지 구조 (2026-01-20 개편)

web-ui/pages/
├── dashboard.html              # 메인 대시보드
├── work/                       # 작업 관련 페이지
│   ├── report-create.html      # 작업보고서 작성
│   ├── report-view.html        # 작업보고서 조회
│   └── analysis.html           # 작업 분석
├── admin/                      # 관리자 기능
│   ├── index.html              # 관리 메뉴 허브
│   ├── projects.html           # 프로젝트 관리
│   ├── workers.html            # 작업자 관리
│   ├── codes.html              # 코드 관리
│   └── accounts.html           # 계정 관리
├── profile/                    # 사용자 프로필
│   ├── info.html               # 내 정보
│   └── password.html           # 비밀번호 변경
└── .archived-*/                # 미사용 페이지 보관

네이밍 규칙:

• 메인 페이지: 단일 명사 (dashboard.html)
• 관리 페이지: 복수형 명사 (projects.html, workers.html)
• 기능 페이지: 동사-명사 (report-create.html, report-view.html)
• 폴더명: 단수형, 소문자 (work/, admin/, profile/)

네비게이션 구조:

• 1차: dashboard.html (메인 진입점)
• 2차: admin/index.html (관리 허브)
• 모든 페이지: navbar를 통해 profile, 작업 페이지로 이동 가능

---

📡 API 개발 가이드

• RESTful: 명사형 리소스 사용 (POST /users O, /createUser X).
• 응답 포맷:

  { "success": true, "data": {...}, "message": "..." }
  

• 계층 구조:
  • Controller: 요청/응답 처리, 유효성 검사.
  • Service: 비즈니스 로직, 트랜잭션 관리.
  • Model: DB 쿼리 실행.

MySQL 8.0 호환성 주의사항 (중요)

Synology NAS(MySQL 8.0)의 Strict Mode로 인해 db.execute() 사용 시 Incorrect arguments 에러가 발생할 수 있습니다.

• 해결책: db.query() 사용 권장 (특히 복잡한 JOIN/Subquery).
• 가이드: models/WorkAnalysis.js 등의 getRecentWork 참조.

---

🧪 테스트 가이드 (Jest)

중요도

1. Service Layer ⭐ (최우선: 비즈니스 로직 검증)
2. Controller Layer (요청 처리 검증)
3. Integration (E2E)

실행

npm test                # 전체 실행
npm run test:watch      # 변경 감지
npm run test:coverage   # 커버리지 측정

작성 패턴 (Service 예시)

// Service는 DB Model을 Mocking하여 테스트
const service = require('../service');
jest.mock('../model');

it('should create report', async () => {
    Model.create.mockResolvedValue(123); // Mock DB response
    const result = await service.createReport(...);
    expect(result).toEqual(...);
});

---

📝 Git 관리

• 커밋 메시지: type: subject (예: feat: 작업보고서 API 추가)
• Types: feat, fix, docs, style, refactor, test, chore
• 브랜치: main(배포), develop(통합), feature/*(기능)