Files

Hyungi Ahn 05843da1c4 refactor(db,frontend): Improve queries and modularize frontend

- Replaced SELECT* queries in 8 models with explicit columns.
- Began modularizing work-report-calendar.js by creating CalendarAPI.js, CalendarState.js, and CalendarView.js.
- Refactored manage-project.js to use global API helpers.
- Fixed API container crash by adding missing volume mounts to docker-compose.yml.
- Added new migration for missing columns in the projects table.
- Documented current DB schema and deployment notes.

2025-12-19 12:42:24 +09:00

3.2 KiB

Raw Blame History

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 활용 권장.

📡 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)

중요도

Service Layer ⭐ (최우선: 비즈니스 로직 검증)
Controller Layer (요청 처리 검증)
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/*(기능)

3.2 KiB Raw Blame History