73e5eff7bd
- CODING_GUIDE에 새 페이지 구조 및 네이밍 규칙 추가 - 상세한 개편 과정 문서 작성 (2026-01-20-page-restructure.md) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
179 lines
5.8 KiB
Markdown
179 lines
5.8 KiB
Markdown
# 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 실행
|
|
```bash
|
|
./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 등은 컴포넌트로 관리
|
|
|
|
### 이모지 사용 금지
|
|
❌ **금지**:
|
|
```html
|
|
<!-- 나쁜 예 -->
|
|
<button>📊 대시보드</button>
|
|
<h1>🔧 작업 관리</h1>
|
|
```
|
|
|
|
✅ **권장**:
|
|
```html
|
|
<!-- 좋은 예 - 아이콘 라이브러리 사용 또는 심플한 텍스트 -->
|
|
<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).
|
|
- **응답 포맷**:
|
|
```json
|
|
{ "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)
|
|
|
|
### 실행
|
|
```bash
|
|
npm test # 전체 실행
|
|
npm run test:watch # 변경 감지
|
|
npm run test:coverage # 커버리지 측정
|
|
```
|
|
|
|
### 작성 패턴 (Service 예시)
|
|
```javascript
|
|
// 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/*`(기능)
|