sam-kd/bid/README.md

# 현설 참여 관리 시스템 개발문서

## 📋 개요
현설 참여 관리 시스템은 건설 현장의 현설 정보를 관리하는 웹 애플리케이션입니다. 현설 참여 업체, 현장 정보, 입찰 정보 등을 체계적으로 관리할 수 있습니다.

## 🏗️ 시스템 아키텍처

### 기술 스택
- **Backend**: PHP 7.3
- **Database**: MariaDB 10.1.13
- **Frontend**: HTML5, CSS3, JavaScript
- **UI Framework**: Bootstrap 5.3
- **JavaScript Library**: jQuery, DataTables, SweetAlert2, Toastify
- **호스팅**: 카페24 웹호스팅

### 데이터베이스 구조
- **테이블명**: `bid`
- **문자셋**: UTF-8 Unicode (utf8)
- **연결**: Localhost via UNIX socket

## 📁 파일 구조

```
bid/
├── list.php              # 메인 목록 페이지
├── fetch_modal.php       # 모달 폼 데이터 처리
├── process.php           # CRUD 작업 처리
├── _row.php             # 데이터베이스 행 변수 처리
├── _request.php         # POST 데이터 처리
├── statistics.php       # 통계 페이지
├── dl_ex_deliveryfee.php # 엑셀 다운로드
└── css/
    └── style.css        # 커스텀 스타일시트
```

## 🔧 주요 파일 설명

### 1. list.php (메인 목록 페이지)
**역할**: 현설 정보 목록을 표시하고 관리하는 메인 페이지

**주요 기능**:
- 현설 정보 목록 조회 (날짜 범위, 검색 기능)
- Bootstrap 모달을 통한 등록/수정/삭제
- DataTables를 이용한 테이블 관리 (페이징, 정렬, 검색)
- 동적 행 추가/삭제 (현설 참여업체 및 아이템 관리)
- JSON 데이터 처리 (수량 데이터와 참여업체 데이터)

**핵심 코드 구조**:
```php
// 세션 및 권한 확인
if (!isset($_SESSION["level"]) || $_SESSION["level"] > 5) {
    header("Location:" . $WebSite . "login/login_form.php");
    exit;
}

// 날짜 범위 기본값 설정
if ($fromdate === "" || $fromdate === null || $todate === "" || $todate === null) {
    $fromdate = date("Y-01-01"); // 현재 년도의 1월 1일
    $todate = $currentDate; // 현재 날짜
}

// SQL 쿼리 (날짜 범위 필터링)
$sql = "SELECT * FROM ".$DB.".".$tablename." 
        WHERE is_deleted IS NULL 
        AND registedate BETWEEN :fromdate AND :todate";
```

### 2. fetch_modal.php (모달 폼 처리)
**역할**: Bootstrap 모달에 표시될 폼 데이터를 처리

**주요 기능**:
- 신규 등록, 수정, 복사 모드별 폼 생성
- 기존 데이터 로드 및 폼 초기화
- 현설 참여업체 및 아이템 테이블 동적 생성

**모드별 처리**:
- `insert`: 신규 등록 (기본값: 현재 날짜)
- `modify`: 기존 데이터 수정
- `copy`: 기존 데이터 복사 (num 초기화)

### 3. process.php (CRUD 처리)
**역할**: 데이터베이스 CRUD 작업을 처리하는 API

**주요 기능**:
- INSERT: 신규 데이터 등록
- UPDATE: 기존 데이터 수정
- DELETE: 데이터 삭제 (soft delete)
- JSON 데이터 처리 (quantityJson, participantJson)
- 트랜잭션 처리 및 오류 관리

**데이터 처리**:
```php
// 검색 태그 생성
$searchtag = $registedate . ' ' . $receiver . ' ' . $receiver_tel . ' ' . 
             $address . ' ' . $siteDate . ' ' . $siteAttendance . ' ' . 
             $siteStatus . ' ' . $quantityJson . ' ' . $fee . ' ' . 
             $siteresult . ' ' . $workplacename . ' ' . $estimatedbyPerson . ' ' . $memo;

// 업데이트 로그
$update_log = date("Y-m-d H:i:s") . " - " . $_SESSION["name"] . " " . ($update_log ?? '') . "
";
```

### 4. _row.php (데이터 변수 처리)
**역할**: 데이터베이스에서 가져온 행 데이터를 PHP 변수로 변환

**처리되는 필드**:
- 기본 정보: num, registedate, receiver, receiver_tel, address
- 현설 정보: siteDate, siteAttendance, siteStatus, workplacename
- 입찰 정보: fee, siteresult, bidDate
- JSON 데이터: quantityJson, participantJson
- 기타: memo, update_log, totalitem

### 5. _request.php (POST 데이터 처리)
**역할**: POST로 전송된 폼 데이터를 PHP 변수로 변환

## 🎯 주요 기능

### 1. 현설 정보 관리
- **등록일**: 현설 정보 등록 날짜
- **시공사**: 시공사 정보 및 코드
- **현장명**: 현장 이름
- **주소**: 현장 주소
- **담당자**: 시공사 담당자 및 연락처

### 2. 현설 참여 정보
- **현설일**: 현설 진행 날짜
- **참여자**: 현설 참여 업체 및 담당자
- **진행상태**: 현설 진행 상태
- **산출자**: 산출 담당자

### 3. 입찰 정보
- **입찰금액**: 입찰 금액 (콤마 포맷팅)
- **입찰일**: 입찰 날짜
- **입찰결과**: 낙찰/탈락/유찰
- **총개소**: 총 아이템 개수

### 4. 아이템 관리
- **동적 행 추가/삭제**: 아이템 테이블의 행을 동적으로 관리
- **수량 자동 계산**: 아이템 수량의 합계 자동 계산
- **JSON 저장**: 아이템 정보를 JSON 형태로 데이터베이스 저장

### 5. 검색 및 필터링
- **날짜 범위 검색**: 등록일 기준 날짜 범위 검색
- **키워드 검색**: searchtag 필드를 통한 통합 검색
- **빠른 날짜 선택**: 전체, 전년도, 당월, 오늘 등 빠른 선택 버튼

## 🔄 데이터 흐름

### 1. 목록 조회
```
사용자 요청 → list.php → 데이터베이스 쿼리 → 결과 표시
```

### 2. 데이터 등록/수정
```
모달 열기 → fetch_modal.php → 폼 표시 → 사용자 입력 → 
process.php → 데이터베이스 저장 → 목록 새로고침
```

### 3. 데이터 삭제
```
삭제 버튼 클릭 → SweetAlert2 확인 → process.php → 
soft delete 처리 → 목록 새로고침
```

## 🎨 UI/UX 특징

### 1. 반응형 디자인
- Bootstrap 5.3 기반 반응형 레이아웃
- 모바일 친화적 인터페이스

### 2. 사용자 경험
- **Toastify**: 작업 완료 알림
- **SweetAlert2**: 확인/경고 다이얼로그
- **DataTables**: 고급 테이블 기능 (페이징, 정렬, 검색)
- **자동 높이 조절**: textarea 자동 크기 조절

### 3. 접근성
- 키보드 네비게이션 지원
- 시각적 피드백 제공
- 직관적인 아이콘 사용

## 🔒 보안 및 권한

### 1. 세션 관리
- 로그인 세션 확인
- 권한 레벨 검증 (level > 5 접근 제한)

### 2. 데이터 검증
- SQL Injection 방지 (PDO prepared statements)
- XSS 방지 (htmlspecialchars 사용)
- CSRF 방지 (세션 기반 인증)

### 3. 오류 처리
- PDO 예외 처리
- 트랜잭션 롤백
- 사용자 친화적 오류 메시지

## 📊 성능 최적화

### 1. 데이터베이스 최적화
- 인덱스 활용 (registedate, searchtag)
- prepared statements 사용
- 트랜잭션 처리

### 2. 프론트엔드 최적화
- AJAX를 통한 비동기 처리
- DataTables 서버 사이드 처리
- 이미지 및 CSS 최적화

### 3. 캐싱
- 브라우저 캐싱 활용
- 세션 데이터 재사용

## 🐛 알려진 이슈 및 제한사항

### 1. PHP 7.3 호환성
- null coalescing operator (??) 사용
- array destructuring 미지원

### 2. 데이터베이스 제한사항
- MariaDB 10.1.13 버전 제한
- UTF-8 문자셋 사용

### 3. 브라우저 호환성
- IE 11 이하 미지원
- 모던 브라우저 권장

## 🔧 개발 환경 설정

### 1. 필수 요구사항
- PHP 7.3 이상
- MariaDB 10.1.13 이상
- 웹 서버 (Apache/Nginx)

### 2. 의존성 파일
- `/session.php`: 세션 관리
- `/load_header.php`: CDN 및 라이브러리 로드
- `/lib/mydb.php`: 데이터베이스 연결
- `/myheader1.php`: 헤더 템플릿

### 3. 설정 파일
- 데이터베이스 연결 정보 (`mydb.php`)
- 세션 설정 (`session.php`)
- CDN 설정 (`load_header.php`)

## 📝 업데이트 로그

### 버전 관리
- 모든 데이터 변경사항은 `update_log` 필드에 기록
- 사용자명과 타임스탬프 포함
- HTML 엔티티로 줄바꿈 처리

### 로그 형식
```
YYYY-MM-DD HH:MM:SS - 사용자명 기존로그내용
```

## 🤝 기여 가이드라인

### 1. 코드 스타일
- PSR-4 네이밍 컨벤션 준수
- 들여쓰기: 4칸 스페이스
- UTF-8 인코딩 사용

### 2. 보안 가이드라인
- 모든 사용자 입력 검증
- SQL Injection 방지
- XSS 방지

### 3. 테스트
- 기능별 테스트 수행
- 크로스 브라우저 테스트
- 모바일 반응형 테스트

---

**개발자**: 5130.co.kr 개발팀  
**최종 업데이트**: 2024년  
**버전**: 1.0