hyungi/TK-FB-Project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 문서 구조 정리 및 페이지 검토 보고서 작성

Browse Source 
- docs/README.md 전면 개편 (문서 인덱스, 구조 설명)
- 31개 페이지 종합 검토 보고서 작성
- 이모지 사용, 사이드바 불일치, 인라인 스타일 등 문제점 식별

주요 발견:
- 이모지 300개+ 사용 (CODING_GUIDE 위반)
- 27/31 페이지에서 이모지 사용
- admin/ 6개 페이지 사이드바 HTML 직접 작성 (중복)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Hyungi Ahn
2026-02-02 14:42:00 +09:00
parent 5f1791443a
commit 09b3cf8e65
2 changed files with 392 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

250
docs/README.md
View File

@@ -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 |
---
## 📧 문의

207
개발 log/2026-02-02-page-review-report.md Normal file
View File

@@ -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개)
**주요 사용 위치:**
- 페이지 제목 (`<title>`)
- 버튼 아이콘 (`<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개+)
- **구조적 문제**: 사이드바 불일치, 인라인 스타일
단계적으로 리팩토링을 진행하여 코드 품질과 유지보수성을 향상시킬 것을 권장합니다.