diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9bdc05c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,241 @@
+# 장헌산업 업무 데이터 조회 시스템
+
+이 저장소는 장헌산업 내부 업무 데이터를 조회하고, 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를 다시 긁지 않아도 커밋 시점 기준의 데이터를 바로 볼 수 있습니다.