diff --git a/docs/README.md b/docs/README.md index 121ead2..7abfa82 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,88 +1,208 @@ -# TK-FB-Project 개발 문서 +# TK-FB-Project 문서 가이드 -## 📚 문서 구조 +> **최종 업데이트**: 2026-02-02 +> **버전**: 2.0.0 -이 디렉토리는 TK-FB-Project의 개발 및 유지보수를 위한 종합 문서 저장소입니다. +이 문서는 TK-FB-Project의 모든 개발 문서를 안내합니다. -### 디렉토리 구조 +--- + +## 📚 문서 구조 개요 ``` -docs/ -├── README.md # 이 파일 - 문서 인덱스 -├── architecture/ # 아키텍처 관련 문서 -│ ├── OVERVIEW.md # 시스템 아키텍처 개요 -│ ├── DATABASE.md # 데이터베이스 스키마 및 설계 -│ └── API_DESIGN.md # API 설계 원칙 -├── refactoring/ # 리팩토링 관련 문서 -│ ├── PLAN.md # 리팩토링 계획 및 로드맵 -│ ├── LOG.md # 리팩토링 작업 로그 -│ └── ANALYSIS.md # 코드 분석 리포트 -├── guides/ # 개발 가이드 -│ ├── SETUP.md # 개발 환경 설정 -│ ├── CODING_STYLE.md # 코딩 스타일 가이드 -│ ├── GIT_WORKFLOW.md # Git 워크플로우 -│ ├── SECURITY.md # 보안 가이드라인 -│ └── TROUBLESHOOTING.md # 문제 해결 가이드 -└── api/ # API 문서 - ├── ENDPOINTS.md # API 엔드포인트 목록 - ├── AUTHENTICATION.md # 인증 및 권한 - └── EXAMPLES.md # API 사용 예제 +TK-FB-Project/ +├── CODING_GUIDE.md # [메인] 통합 개발 가이드 (필독) +├── DEV_LOG.md # [메인] 개발 진행 현황 +├── CHECKLIST.md # 프로젝트 체크리스트 +│ +├── docs/ # 상세 문서 +│ ├── README.md # (이 파일) 문서 인덱스 +│ ├── standards/ # 표준 문서 +│ ├── guides/ # 개발 가이드 +│ ├── features/ # 기능별 문서 +│ └── architecture/ # 아키텍처 문서 +│ +├── 개발 log/ # 일별 개발 로그 (2025-12 ~ ) +├── 개발로그/ # 일별 개발 로그 (2026-01) +│ # ⚠️ 두 폴더 통합 예정 +│ +└── _archive/ # 레거시 문서 (참고용) ``` -## 📖 주요 문서 +--- -### 시작하기 -- [개발 환경 설정](guides/SETUP.md) - 프로젝트 설정 및 실행 방법 -- [시스템 아키텍처](architecture/OVERVIEW.md) - 전체 시스템 구조 이해 -- [코딩 스타일 가이드](guides/CODING_STYLE.md) - 코드 작성 규칙 +## 🎯 필독 문서 (Quick Start) -### 개발 -- [API 문서](api/ENDPOINTS.md) - REST API 엔드포인트 레퍼런스 -- [데이터베이스 스키마](architecture/DATABASE.md) - DB 구조 및 관계 -- [문제 해결](guides/TROUBLESHOOTING.md) - 자주 발생하는 문제 해결법 +| 순서 | 문서 | 설명 | 대상 | +|:---:|------|------|------| +| 1 | [CODING_GUIDE.md](../CODING_GUIDE.md) | 프로젝트 실행, 코딩 규칙, API 개발 | 모든 개발자 | +| 2 | [DEV_LOG.md](../DEV_LOG.md) | 최근 개발 현황 및 변경사항 | 모든 개발자 | +| 3 | [guides/SETUP.md](guides/SETUP.md) | 개발 환경 상세 설정 | 신규 개발자 | -### 리팩토링 -- [리팩토링 계획](refactoring/PLAN.md) - 개선 로드맵 -- [리팩토링 로그](refactoring/LOG.md) - 변경 이력 -- [코드 분석](refactoring/ANALYSIS.md) - 현재 코드베이스 분석 +--- + +## 📁 문서 분류 + +### 1. 표준 문서 (Standards) + +프로젝트 전반에 적용되는 규칙과 표준입니다. + +| 문서 | 설명 | 상태 | +|------|------|:----:| +| [DOCUMENTATION_STANDARD.md](DOCUMENTATION_STANDARD.md) | 문서 작성 표준 | ✅ 현행 | +| [ADMIN_PAGE_STANDARD.md](ADMIN_PAGE_STANDARD.md) | 관리 페이지 개발 표준 | ✅ 현행 | +| [guides/CODING_STYLE.md](guides/CODING_STYLE.md) | JavaScript/HTML/CSS 코딩 스타일 | ✅ 현행 | + +### 2. 개발 가이드 (Guides) + +특정 기능이나 작업에 대한 상세 가이드입니다. + +| 문서 | 설명 | 상태 | +|------|------|:----:| +| [guides/SETUP.md](guides/SETUP.md) | 개발 환경 설정 | ✅ 현행 | +| [guides/work-report-time-input-guide.md](guides/work-report-time-input-guide.md) | 작업보고서 시간 입력 UX | ✅ 현행 | +| [TBM_DEPLOYMENT_GUIDE.md](TBM_DEPLOYMENT_GUIDE.md) | TBM 시스템 배포/사용 가이드 | ✅ 현행 | + +### 3. 아키텍처 문서 (Architecture) + +시스템 구조와 설계에 대한 문서입니다. + +| 문서 | 설명 | 상태 | +|------|------|:----:| +| [architecture/OVERVIEW.md](architecture/OVERVIEW.md) | 시스템 아키텍처 개요 | ⚠️ 업데이트 필요 | +| [_archive/DATABASE_SCHEMA.md](../_archive/DATABASE_SCHEMA.md) | 데이터베이스 스키마 | 📦 아카이브 | + +### 4. 개발 로그 (Development Logs) + +일별/주제별 개발 진행 기록입니다. + +#### 📅 최근 로그 (2026년) + +| 날짜 | 제목 | 주요 내용 | +|------|------|----------| +| 01-28 | [설비 관리 시스템](../개발%20log/2026-01-28-equipment-management-system.md) | 설비 CRUD, 작업장 연동 | +| 01-27 | [시간 입력 UX 개선](../개발%20log/2026-01-27-time-input-ux-improvement.md) | 터치 최적화 시간 선택 | +| 01-20 | [UI 표준화 Phase 1](../개발%20log/2026-01-20-ui-standardization-phase1.md) | 디자인 시스템, 템플릿 | +| 01-20 | [페이지 구조 재설계](../개발%20log/2026-01-20-page-restructure.md) | 폴더 구조 변경 | +| 01-19 | [작업자-계정 연동](../개발로그/2026-01-19_작업자_계정연동_기능.md) | 계정 통합 기능 | + +#### 📅 이전 로그 (2025년) + +| 날짜 | 제목 | 주요 내용 | +|------|------|----------| +| 12-09 | [초기 개발](../개발%20log/2025-12-09.md) | 프로젝트 초기 설정 | + +### 5. 아카이브 (Archive) + +더 이상 사용하지 않거나 참고용 문서입니다. + +| 문서 | 설명 | 비고 | +|------|------|------| +| [_archive/README.md](../_archive/README.md) | 레거시 시작 가이드 | CODING_GUIDE.md로 대체 | +| [_archive/TESTING_GUIDE.md](../_archive/TESTING_GUIDE.md) | 테스트 작성 가이드 | Jest 테스트 참고용 | +| [_archive/룰.md](../_archive/룰.md) | 초기 개발 규칙 | CODING_GUIDE.md로 대체 | +| [_archive/DELETED_PAGES.md](../_archive/DELETED_PAGES.md) | 삭제된 페이지 기록 | 히스토리 참고 | +| [_archive/DELETED_TABLES.md](../_archive/DELETED_TABLES.md) | 삭제된 테이블 기록 | 히스토리 참고 | + +--- + +## 📋 문서 중복 안내 + +일부 내용이 여러 문서에 중복되어 있습니다. **Primary Source**를 참고하세요. + +| 주제 | Primary Source | Secondary (요약) | +|------|----------------|------------------| +| 개발 환경 설정 | [guides/SETUP.md](guides/SETUP.md) | CODING_GUIDE.md 실행 가이드 섹션 | +| 코딩 컨벤션 | [guides/CODING_STYLE.md](guides/CODING_STYLE.md) | CODING_GUIDE.md 코딩 컨벤션 섹션 | +| 페이지 구조 | [CODING_GUIDE.md](../CODING_GUIDE.md) | - | +| DB 스키마 | CHECKLIST.md | _archive/DATABASE_SCHEMA.md | + +--- + +## 🌐 웹 UI 페이지 구조 + +### 페이지 현황 (31개) + +``` +web-ui/pages/ +├── dashboard.html # 메인 대시보드 +│ +├── work/ # 작업 관리 (4개) +│ ├── tbm.html # TBM 관리 +│ ├── report-create.html # 작업보고서 작성 +│ ├── report-view.html # 작업보고서 조회 +│ └── analysis.html # 작업 분석 +│ +├── safety/ # 안전 관리 (7개) +│ ├── management.html # 안전 관리 +│ ├── training-conduct.html # 안전교육 진행 +│ ├── checklist-manage.html # 체크리스트 관리 +│ ├── issue-report.html # 이슈 신고 +│ ├── issue-list.html # 이슈 목록 +│ ├── issue-detail.html # 이슈 상세 +│ └── visit-request.html # 출입 신청 +│ +├── attendance/ # 근태 관리 (8개) +│ ├── daily.html # 일일 출퇴근 +│ ├── monthly.html # 월간 근태 +│ ├── vacation-request.html # 휴가 신청 +│ ├── vacation-approval.html # 휴가 승인 +│ ├── vacation-input.html # 휴가 직접 입력 +│ ├── vacation-management.html # 휴가 관리 +│ ├── vacation-allocation.html # 휴가 발생 입력 +│ └── annual-overview.html # 연간 휴가 현황 +│ +├── admin/ # 시스템 관리 (9개) +│ ├── accounts.html # 계정 관리 +│ ├── page-access.html # 권한 관리 +│ ├── workers.html # 작업자 관리 +│ ├── projects.html # 프로젝트 관리 +│ ├── tasks.html # 작업 관리 +│ ├── workplaces.html # 작업장 관리 +│ ├── equipments.html # 설비 관리 +│ ├── codes.html # 코드 관리 +│ └── attendance-report.html # 출퇴근-보고서 대조 +│ +└── profile/ # 개인 설정 (2개) + ├── info.html # 내 정보 + └── password.html # 비밀번호 변경 +``` + +--- ## 🔄 문서 업데이트 규칙 -1. **리팩토링 시**: 변경 사항을 `refactoring/LOG.md`에 기록 -2. **API 변경 시**: `api/ENDPOINTS.md` 업데이트 -3. **아키텍처 변경 시**: 관련 다이어그램 및 문서 갱신 -4. **새로운 기능 추가 시**: 해당 가이드 문서 작성 +### 언제 업데이트하나요? -## 📝 문서 작성 가이드 +| 상황 | 업데이트 대상 | +|------|--------------| +| 새 기능 추가 | DEV_LOG.md + 해당 기능 문서 | +| 버그 수정 | DEV_LOG.md | +| 코딩 규칙 변경 | CODING_GUIDE.md + guides/CODING_STYLE.md | +| 페이지 추가/삭제 | CODING_GUIDE.md 페이지 구조 섹션 | +| DB 스키마 변경 | CHECKLIST.md | -### 문서 작성 원칙 -- **명확성**: 기술 용어는 쉽게 설명 -- **최신성**: 코드 변경 시 즉시 업데이트 -- **완결성**: 독립적으로 이해 가능하도록 작성 -- **예제 포함**: 코드 예제와 스크린샷 활용 +### 개발 로그 작성 규칙 -### 마크다운 스타일 ```markdown -# H1: 문서 제목 (한 문서에 한 개만) -## H2: 주요 섹션 -### H3: 하위 섹션 +# YYYY-MM-DD 개발 로그 -- 리스트 사용 -- 코드 블록 활용 -- 테이블로 정보 정리 +## 개요 +- 간단한 작업 요약 + +## 변경 사항 +### 1. [기능명] +- 변경 내용 상세 +- 관련 파일: `path/to/file.js` + +## 테스트 +- [ ] 테스트 항목 + +## 다음 작업 +- 후속 작업 목록 ``` -## 🔗 외부 리소스 - -- [프로젝트 README](../README.md) -- [데이터베이스 스키마](../DATABASE_SCHEMA.md) -- [MySQL 호환성 노트](../MYSQL_COMPATIBILITY_NOTES.md) - -## 📅 문서 이력 - -| 날짜 | 버전 | 변경 내용 | 작성자 | -|------|------|----------|--------| -| 2025-12-11 | 1.0 | 문서 구조 초기 생성 | Claude Code | +--- ## 📧 문의 diff --git a/개발 log/2026-02-02-page-review-report.md b/개발 log/2026-02-02-page-review-report.md new file mode 100644 index 0000000..455189a --- /dev/null +++ b/개발 log/2026-02-02-page-review-report.md @@ -0,0 +1,207 @@ +# 2026-02-02 전체 페이지 검토 보고서 + +## 개요 + +31개 HTML 페이지에 대한 종합 검토를 실시했습니다. + +**검토 항목:** +1. 사이드바 스크립트 포함 여부 +2. 경로 오류 +3. 이모지 사용 (CODING_GUIDE 위반) +4. 하드코딩된 링크 오류 +5. 코드 품질 이슈 + +--- + +## 종합 결과 + +| 카테고리 | 페이지 수 | 사이드바 | 이모지 위반 | 인라인 스타일 | 경로 오류 | +|----------|:--------:|:--------:|:-----------:|:------------:|:---------:| +| work/ | 4 | 0/4 | 4/4 | 4/4 | 0/4 | +| safety/ | 7 | 0/7 | 3/7 | 5/7 | 0/7 | +| attendance/ | 8 | 0/8 | 8/8 | 6/8 | 0/8 | +| admin/ | 9 | 6/9 (직접작성) | 9/9 | 7/9 | 0/9 | +| profile/ | 2 | 0/2 | 2/2 | 1/2 | 1/2 | +| dashboard | 1 | 1/1 | 1/1 | 1/1 | 0/1 | +| **합계** | **31** | **7/31** | **27/31** | **24/31** | **1/31** | + +--- + +## 카테고리별 상세 + +### 1. work/ (4개) + +| 파일 | 사이드바 | 이모지 | 인라인 스타일 | 비고 | +|------|:-------:|:------:|:------------:|------| +| tbm.html | navbar만 | 21개 | 92개 | 가장 심각 | +| report-create.html | navbar만 | 5개 | 29개 | 중간 | +| report-view.html | navbar만 | 8개 | 6개 | 양호 | +| analysis.html | navbar만 | 65개 | 23개 | 이모지 최다 | + +**총 이모지: 99개** (콘솔 로그 포함) + +### 2. safety/ (7개) + +| 파일 | 사이드바 | 이모지 | 인라인 스타일 | 비고 | +|------|:-------:|:------:|:------------:|------| +| management.html | navbar만 | 0개 | 다수 | 양호 | +| training-conduct.html | navbar만 | 1개 | 다수 | 양호 | +| checklist-manage.html | navbar만 | 8개 | 다수 | CSS 하드코딩 | +| issue-report.html | navbar만 | 0개 | 적음 | 우수 | +| issue-list.html | navbar만 | 0개 | 적음 | 우수 | +| issue-detail.html | navbar만 | 0개 | 적음 | 우수 | +| visit-request.html | navbar만 | 2개 | 다수 | 양호 | + +**총 이모지: 11개** + +### 3. attendance/ (8개) + +| 파일 | 사이드바 | 이모지 | 인라인 스타일 | 비고 | +|------|:-------:|:------:|:------------:|------| +| daily.html | navbar만 | 5개 | 다수 | - | +| monthly.html | navbar만 | 2개 | 다수 | - | +| vacation-request.html | navbar만 | 3개 | 다수 | - | +| vacation-approval.html | navbar만 | 2개 | 다수 | - | +| vacation-input.html | navbar만 | 3개 | 다수 | - | +| vacation-management.html | navbar만 | 3개 | 다수 | - | +| vacation-allocation.html | navbar만 | 2개 | 적음 | CSS 분리됨 | +| annual-overview.html | navbar만 | 2개 | 적음 | CSS 분리됨 | + +**총 이모지: 22개** + +### 4. admin/ (9개) + +| 파일 | 사이드바 | 이모지 | 인라인 스타일 | 비고 | +|------|:-------:|:------:|:------------:|------| +| accounts.html | 없음 | 9개 | 다수 | - | +| page-access.html | 없음 | 5개 | 다수 | - | +| workers.html | HTML 직접 | 26개 | 중간 | 사이드바 중복 | +| projects.html | HTML 직접 | 20개 | 중간 | 사이드바 중복 | +| tasks.html | HTML 직접 | 20개 | 중간 | 사이드바 중복 | +| workplaces.html | HTML 직접 | 22개 | 다수 | Canvas 복잡 | +| equipments.html | HTML 직접 | 12개 | 중간 | - | +| codes.html | HTML 직접 | 23개 | 중간 | 탭 시스템 | +| attendance-report.html | 없음 | 6개 | 심각 | 인라인 JS 포함 | + +**총 이모지: 143개** + +### 5. profile/ (2개) + +| 파일 | 사이드바 | 이모지 | 인라인 스타일 | 비고 | +|------|:-------:|:------:|:------------:|------| +| info.html | navbar만 | 9개 | 적음 | 링크 오류 1개 | +| password.html | navbar만 | 12개 | 적음 | - | + +**총 이모지: 21개** +**링크 오류**: info.html에서 `/pages/profile/change-password.html` → `password.html`로 수정 필요 + +### 6. dashboard.html + +| 파일 | 사이드바 | 이모지 | 인라인 스타일 | 비고 | +|------|:-------:|:------:|:------------:|------| +| dashboard.html | ✅ 있음 | 3개 | 다수 | 범례/모달 인라인 | + +--- + +## 주요 문제점 + +### 1. 이모지 사용 (CODING_GUIDE 위반) 🔴 + +**CODING_GUIDE 규정:** +> "모던하고 깔끔한 디자인: 이모지 사용 지양, 아이콘 또는 심플한 텍스트 사용" + +**현황:** +- 31개 페이지 중 27개에서 이모지 사용 +- 총 이모지 사용: 약 300개 이상 +- 가장 심각: `analysis.html` (65개), `workers.html` (26개), `codes.html` (23개) + +**주요 사용 위치:** +- 페이지 제목 (``) +- 버튼 아이콘 (`<span class="btn-icon">`) +- 섹션 헤더 +- 콘솔 로그 (analysis.html) + +### 2. 사이드바 불일치 🟡 + +**현황:** +- dashboard.html만 `load-sidebar.js` 사용 +- admin/ 6개 페이지는 사이드바 HTML 직접 포함 (중복 코드) +- 나머지 페이지는 사이드바 없음 (navbar만) + +**문제점:** +- 일관성 부족 +- 코드 중복 (admin/ 페이지들) +- 유지보수 어려움 + +### 3. 인라인 스타일 과다 사용 🟡 + +**심각한 파일:** +- `tbm.html`: 92개 +- `attendance-report.html`: style 블록 + 인라인 JS +- `workplaces.html`: 200줄 이상 +- `dashboard.html`: 모달/범례 전체가 인라인 + +**문제점:** +- CSS 변수 미사용 (CODING_GUIDE 위반) +- 스타일 재사용 불가 +- 유지보수 어려움 + +### 4. 하드코딩된 색상값 🟢 + +일부 페이지에서 CSS 변수 대신 하드코딩된 색상 사용: +- `#3b82f6`, `#2563eb`, `#e5e7eb` 등 +- CODING_GUIDE: `var(--primary-500)` 등 CSS 변수 사용 권장 + +--- + +## 권장 조치사항 + +### 🔴 높은 우선순위 + +1. **이모지 제거 작업** + - 모든 페이지의 이모지를 텍스트 또는 CSS 아이콘으로 교체 + - 예시: `📊` → "통계" 또는 CSS `::before` 아이콘 + +2. **사이드바 통일** + - 모든 페이지에 `load-sidebar.js` 적용 + - admin/ 페이지의 직접 작성된 사이드바 제거 + +3. **링크 오류 수정** + - `profile/info.html`: `change-password.html` → `password.html` + +### 🟡 중간 우선순위 + +4. **인라인 스타일 분리** + - 각 페이지별 CSS 파일 생성 또는 공통 CSS 확장 + - `tbm.html`, `attendance-report.html` 우선 + +5. **하드코딩 색상 → CSS 변수** + - checklist-manage.html 등 + +### 🟢 낮은 우선순위 + +6. **콘솔 로그 이모지 제거** (analysis.html) +7. **코드 중복 제거** (Axios 설정 등) + +--- + +## 작업 계획 + +| 단계 | 작업 | 예상 파일 수 | +|:---:|------|:-----------:| +| 1 | 이모지 제거 - 버튼/제목 | 27개 | +| 2 | 사이드바 통일 | 30개 | +| 3 | 인라인 스타일 분리 | 10개 (심각한 것만) | +| 4 | CSS 변수 적용 | 5개 | + +--- + +## 결론 + +현재 코드베이스는 기능적으로는 잘 작동하지만, CODING_GUIDE 준수율이 낮습니다. + +- **CODING_GUIDE 준수율**: 약 40% +- **가장 시급한 문제**: 이모지 사용 (300개+) +- **구조적 문제**: 사이드바 불일치, 인라인 스타일 + +단계적으로 리팩토링을 진행하여 코드 품질과 유지보수성을 향상시킬 것을 권장합니다.