JH/README.md

# 장헌산업 업무 데이터 조회 시스템

이 저장소는 장헌산업 내부 업무 데이터를 조회하고, ERP 정보와 매칭해서 웹 화면으로 보여주는 사내용 도구입니다.

주요 목적은 아래 2가지입니다.

- `8091` 페이지: 사람별/프로젝트별 근무 데이터 조회
- `8092` 페이지: 시공 코드, 계약정보, 공사개요, 연계코드 조회


## 구성 개요

이 프로젝트는 Python 기반의 간단한 웹 서버와 SQLite DB(`matching.db`)를 사용합니다.

- 웹 서버: `mysql_preview_server.py`
- 공용 DB: `matching.db`
- 메인 대시보드 화면: `index.html`
- 사람별 근무 화면: `people-unified.html`
- 시공 코드 조회 화면: `project-codes.html`

같은 저장소 안에서 여러 HTML 화면을 제공하지만, 데이터는 공통으로 `matching.db`를 사용합니다.


## 페이지 설명

### `8091` 메인/근무 데이터 페이지

`8091` 포트는 근무 데이터와 집계 화면용입니다.

포함 내용:

- 프로젝트별 투입시간 집계
- 사람별 근무내역 조회
- 월별/기간별 프로젝트 투입 현황
- 사업관리 작업일보 기반 추가 공수 데이터 조회

관련 화면:

- `index.html`: 메인 대시보드
- `people-unified.html`: 사람별 / 프로젝트별 근무내역
- `detail-view.html`, `detail-view-project.html`: 상세 보기


### `8092` 시공 코드 조회 페이지

`8092` 포트는 ERP 시공 코드 전용 조회 화면입니다.

포함 내용:

- 시공코드 목록
- 계약정보
- 공사개요
- 교량 매칭 정보
- 공사시행계획서 기반 교량제원
- 연계코드 표시

연계코드는 아래 형식으로 표시됩니다.

- `영업/설계 약칭(코드번호)`가 아니라
- 현재는 `약칭(코드번호) · 약칭(코드번호)` 형식

예시:

- `새만금~전주간 고속도로 건설고사(제4공구) [8차](25-교영-09)`
- `새만금~전주간 고속도로 건설고사(제4공구) [8차](25-설계-05)`

관련 화면:

- `project-codes.html`


## 데이터 소스

이 시스템은 여러 데이터 소스를 함께 사용합니다.

### 1. SQLite 캐시 DB

- 파일: `matching.db`
- 저장소에 포함되어 있음
- 클론한 사람도 같은 시점의 데이터를 바로 볼 수 있음

주요 저장 내용:

- 직원 정보
- `dailyproject` 근무 데이터
- 프로젝트 약칭
- ERP 시공 코드 캐시
- ERP 계약정보 캐시
- ERP 교량 개요 캐시
- ERP 공사시행계획서 캐시
- 영업/설계/시공 연계코드 캐시


### 2. MySQL 원본 데이터

사내 MySQL에서 근무 데이터를 읽어와 SQLite로 적재합니다.

관련 환경값:

- `MYSQL_HOST`
- `MYSQL_PORT`
- `MYSQL_USER`
- `MYSQL_PASSWORD`
- `MYSQL_DB`


### 3. ERP 데이터

ERP에서 아래 정보를 가져옵니다.

- 프로젝트 약칭
- 시공 코드 목록
- 계약정보
- 공사관리 / 공사개요
- 공사시행계획서
- 영업/설계/시공 연계코드

관련 기본 URL:

- `http://erp.jangheon.co.kr/projt_mng`


## DB 관련 중요 사항

이 저장소는 **코드만이 아니라 `matching.db`도 함께 관리**합니다.

이유:

- 클론한 사람이 바로 같은 데이터를 볼 수 있어야 함
- 내부 페이지가 DB 캐시를 전제로 동작함
- ERP/MySQL 접속 없이도 기본 조회가 가능해야 함

즉, 이 저장소에서는 `matching.db`도 실제 배포/공유 자산입니다.

다만 아래 파일은 운영 중 자동 생성될 수 있습니다.

- `matching.db-wal`
- `matching.db-shm`
- `matching.db.bak-*`

이 파일들은 보조 파일/백업 파일이며, 기본 공유 대상은 `matching.db`입니다.


## 연계코드 저장 방식

시공코드 페이지의 연계코드는 DB에도 저장됩니다.

관련 테이블:

- `project_alias`
- `erp_project_alias_cache`
- `erp_linked_code_cache`

예를 들어 시공코드 하나에 대해 아래 정보를 저장합니다.

- 시공코드
- 사업코드
- 연관 영업코드
- 연관 영업 약칭
- 연관 설계코드
- 연관 설계 약칭

그래서 나중에 아래와 같은 질문에 바로 답할 수 있습니다.

- “이 시공코드의 연관 영업코드는 뭐야?”
- “이 설계코드 약칭이 뭐야?”


## 실행 방법

### 로컬 실행

Python 서버 실행:

```bash
python3 mysql_preview_server.py
```

기본 포트:

- `8091`: 메인/근무 데이터
- `8092`: 시공 코드 조회


### Docker 실행

이미지/컨테이너는 `docker-compose.yml`과 `Dockerfile`로 실행할 수 있습니다.

관련 문서:

- `DEPLOY_DOCKER.md`


## 주요 파일 설명

- `mysql_preview_server.py`: 현재 실제 기능 대부분이 들어있는 메인 서버
- `app.py`: 이전/보조 서버 코드
- `index.html`: 8091 메인 대시보드
- `people-unified.html`: 사람별/프로젝트별 근무 조회
- `project-codes.html`: 8092 시공 코드 전용 화면
- `matching.db`: 공용 SQLite 데이터베이스
- `docker-compose.yml`: Docker 배포 설정
- `DEPLOY_DOCKER.md`: Docker 배포 방법


## 사용 흐름

### 근무 데이터 흐름

1. MySQL 원본 데이터를 읽음
2. SQLite `matching.db`에 적재
3. `8091` 페이지에서 집계/상세 조회


### 시공 코드 데이터 흐름

1. ERP에서 시공코드 목록 조회
2. ERP 계약정보 / 공사개요 / 공사시행계획서 조회
3. 영업/설계/시공 연계코드와 약칭 매칭
4. SQLite `matching.db`에 캐시 저장
5. `8092` 페이지에서 빠르게 조회


## 운영 시 주의사항

- `matching.db`는 실제 운영 데이터가 들어 있으므로 함부로 초기화하면 안 됩니다.
- ERP 재조회 버튼을 누르면 캐시가 갱신될 수 있습니다.
- 운영 중에는 DB 파일이 변경될 수 있어 `matching.db-wal`, `matching.db-shm`가 생길 수 있습니다.
- 다른 사람이 같은 결과를 보려면 저장소의 `matching.db`도 함께 최신 상태여야 합니다.


## 권장 공유 방식

다른 사람이 이 저장소를 받아서 바로 확인하려면:

1. 저장소를 클론
2. `matching.db`가 포함되어 있는지 확인
3. 서버 실행
4. `8091`, `8092` 페이지 접속

이렇게 하면 ERP를 다시 긁지 않아도 커밋 시점 기준의 데이터를 바로 볼 수 있습니다.