ITAM/docker_task_plan.md

# ITAM 도커라이징 작업 태스크 정리

## 1. 문서 목적

이 문서는 ITAM 자산관리 시스템의 도커라이징 작업을 실제 실행 단위로 쪼개서 정리한 태스크 문서다.

이 문서의 목표는 아래와 같다.

1. 내일까지 보여줄 시연 범위를 기준으로 우선순위를 정한다.
2. 시연용 작업과 운영형 전환 작업을 분리한다.
3. 개발 담당자가 바로 실행할 수 있는 체크리스트를 제공한다.

관련 배경과 구조 분석은 [doc_readme.md](c:/Users/user/Desktop/안건%20파일/itam/doc_readme.md) 문서를 기준으로 한다.

현재 구현/검증 상태:

- `Dockerfile.frontend` 생성 완료
- `Dockerfile.backend` 생성 완료
- `docker-compose.yaml` 생성 완료
- `.dockerignore` 생성 완료
- WSL2 Ubuntu에서 `docker compose up --build -d` 검증 완료
- frontend 8080 응답 확인 완료
- backend `/api/assets/master` 응답 확인 완료
- 현재 DB는 external MySQL 기준이며, DB 컨테이너 추가 작업은 다음 단계로 남아 있음

## 2. 이번 작업의 최우선 목표

이번 도커라이징의 1차 목표는 "운영 배포 완료"가 아니라 아래 상태를 재현하는 것이다.

1. frontend 컨테이너가 정상 기동한다.
2. backend 컨테이너가 정상 기동한다.
3. backend가 기존 외부 MySQL 또는 MySQL 컨테이너에 정상 연결된다.
4. 브라우저에서 화면이 열린다.
5. 핵심 API 호출이 정상 동작한다.
6. 업로드 저장 경로가 유지된다.
7. 필요 시 DB까지 함께 포함된 재현 가능한 스택을 제공한다.

## 3. 작업 범위 구분

### 3.1 이번 시연 범위에 포함

- Dockerfile.frontend 초안 작성
- Dockerfile.backend 초안 작성
- docker-compose.yaml 작성
- `.dockerignore` 작성
- MySQL 컨테이너 추가 설계
- 초기 SQL dump 또는 init SQL 적재 방식 정의
- `uploads` 볼륨 처리
- `map_config.json` 영속성 처리 방식 반영
- 컨테이너 기동 및 접속 확인
- 핵심 API 및 화면 확인

### 3.2 이번 시연 범위에서 제외

- DB 전체 마이그레이션 자동화
- nginx 기반 운영 배포 구조
- 단일 이미지 운영 구조 전환
- CI/CD 연계

## 4. 선행 확인 태스크

아래 태스크는 실제 Docker 파일 작성 전에 먼저 확인해야 한다.

### Task 1. 외부 MySQL 접근 가능 여부 확인

- 목적: 컨테이너에서 외부 DB 접속이 가능한지 확인
- 확인 항목:
  - DB_HOST 접근 가능 여부
  - DB_PORT 3306 접속 가능 여부
  - 계정 권한 정상 여부
- 완료 기준:
  - backend 컨테이너 기준 DB 연결 에러가 발생하지 않음

### Task 2. 기준 스키마 상태 확인

- 목적: 현재 앱이 요구하는 테이블 구조가 실제 DB와 맞는지 확인
- 확인 항목:
  - `asset_core`
  - `asset_spec`
  - `asset_location`
  - `asset_remote`
  - `asset_history`
  - `hardware_components_master`
  - `job_spec_standards`
- 완료 기준:
  - `/api/assets/master` 호출 시 쿼리 에러가 발생하지 않음

### Task 3. 파일 영속성 대상 확인

- 목적: 컨테이너 재시작 이후에도 유지되어야 할 파일/폴더 식별
- 대상:
  - `uploads`
  - `map_config.json`
- 완료 기준:
  - 볼륨 설계 대상이 명확하게 문서화됨

### Task 4. DB 기준 데이터 소스 확정

- 목적: MySQL 컨테이너 최초 기동 시 어떤 데이터로 초기화할지 결정
- 선택지:
  - 기존 사내 DB에서 추출한 SQL dump 사용
  - 정리된 스키마 SQL + seed SQL 사용
  - 수동 import 절차 사용
- 완료 기준:
  - `docker/mysql/init` 기준 적재 전략 또는 수동 복원 절차가 확정됨

## 5. 시연용 도커라이징 태스크

### Task 5. 프런트 Dockerfile 작성

- 목적: Vite 개발 서버를 컨테이너에서 구동
- 작업 내용:
  - Node 20 계열 이미지 사용
  - `package*.json` 복사 후 `npm install`
  - 8080 포트 노출
  - `npm run dev -- --host 0.0.0.0` 실행
- 산출물:
  - `Dockerfile.frontend`
- 완료 기준:
  - 컨테이너에서 8080 포트가 정상 listen 상태가 됨

### Task 6. 백엔드 Dockerfile 작성

- 목적: Express API 서버를 컨테이너에서 구동
- 작업 내용:
  - Node 20 계열 이미지 사용
  - `package*.json` 복사 후 `npm install`
  - 3000 포트 노출
  - `npm run server` 실행
- 산출물:
  - `Dockerfile.backend`
- 완료 기준:
  - 컨테이너에서 3000 포트가 정상 listen 상태가 됨

### Task 7. MySQL Docker 구성 추가

- 목적: DB까지 포함한 재현 가능한 스택 구성
- 작업 내용:
  - `mysql:8.0` 서비스 정의
  - `MYSQL_DATABASE`, `MYSQL_USER`, `MYSQL_PASSWORD` 설정
  - utf8mb4 문자셋 옵션 반영
  - MySQL 데이터 volume 연결
  - 초기 SQL 적재용 `docker/mysql/init` 디렉터리 설계
- 산출물:
  - `docker-compose.yaml` 내 `db` 서비스 또는 별도 DB compose 확장안
- 완료 기준:
  - MySQL 컨테이너가 정상 기동하고 3306 포트에서 응답 가능

### Task 8. backend DB 연결 전환

- 목적: backend가 external MySQL 대신 DB 컨테이너를 바라보도록 변경
- 작업 내용:
  - `DB_HOST`를 `db`로 전환
  - 필요 시 `.env.docker` 또는 compose 내부 환경변수 사용
  - backend `depends_on`에 db 추가
- 산출물:
  - DB 컨테이너용 backend 환경 정의
- 완료 기준:
  - backend 로그에서 DB 연결 성공 확인

### Task 9. docker-compose.yaml 확장

- 목적: frontend/backend를 함께 기동
- 작업 내용:
  - frontend 서비스 정의
  - backend 서비스 정의
  - db 서비스 정의
  - 포트 매핑 추가
  - `.env` 또는 docker 전용 환경변수 연결
  - MySQL 데이터 볼륨 연결
  - `uploads` 볼륨 연결
  - `map_config.json` 처리 방식 반영
- 산출물:
  - `docker-compose.yaml`
- 완료 기준:
  - `docker compose up --build` 한 번으로 세 서비스가 모두 올라옴

### Task 10. `.dockerignore` 작성

- 목적: 불필요한 빌드 컨텍스트 제외
- 제외 권장 항목:
  - `node_modules`
  - `dist`
  - `build`
  - `.git`
  - `uploads`
  - `*.xlsx`
- 산출물:
  - `.dockerignore`
- 완료 기준:
  - 이미지 빌드 컨텍스트가 과도하게 커지지 않음

## 6. 시연 검증 태스크

### Task 11. WSL 컨테이너 기동 검증

- 실행 명령:

```bash
powershell -ExecutionPolicy Bypass -File .\start_docker_wsl.ps1
```

- 확인 항목:
  - frontend 로그 에러 여부
  - backend 로그 에러 여부
  - db 로그 에러 여부
  - backend와 db 연결 성공 여부
- 완료 기준:
  - 세 컨테이너 모두 종료 없이 유지됨

### Task 12. 웹 접속 검증

- 확인 항목:
  - `http://localhost:8080` 접속 가능 여부
  - 첫 화면 로딩 여부
  - 콘솔 에러 여부
- 완료 기준:
  - 브라우저에서 초기 화면이 정상 표시됨

### Task 13. API 검증

- 확인 항목:
  - `http://localhost:3000/api/assets/master`
  - 프런트에서 `/api/assets/master` 호출 정상 여부
- 완료 기준:
  - 200 응답 또는 정상 데이터 응답 확인

### Task 14. DB 초기 데이터 검증

- 확인 항목:
  - MySQL 컨테이너 내부에 목표 DB가 생성되었는지
  - 기준 테이블이 존재하는지
  - 샘플 데이터 또는 실데이터가 적재되었는지
- 완료 기준:
  - backend가 기대하는 최소 테이블과 데이터가 실제로 조회됨

### Task 15. 업로드/파일 저장 검증

- 확인 항목:
  - `/api/upload` 호출 정상 여부
  - 업로드 파일이 `uploads`에 실제 저장되는지
  - `map_config.json` 수정 내용이 유지되는지
- 완료 기준:
  - 컨테이너 재시작 후에도 저장 데이터가 유지됨

## 7. 시연 후 후속 태스크

### Task 16. 운영형 프런트 배포 구조 전환

- 목표: Vite dev server 대신 정적 빌드 기반 구조로 전환
- 후보:
  - nginx 정적 서빙
  - Express 정적 서빙

### Task 17. DB 초기화/마이그레이션 전략 통합

- 목표: 기준 스키마와 실행 순서를 단일 정책으로 통일
- 필요 작업:
  - 기준 스키마 선정
  - 초기화 스크립트 확정
  - 마이그레이션 순서 정의

### Task 18. `.env.example` 및 배포 환경 분리

- 목표: 민감정보를 저장소에서 분리하고 배포별 설정 체계화

### Task 19. 운영 볼륨 및 백업 전략 정리

- 목표: 업로드 파일과 설정 파일, MySQL 데이터의 장기 보존 정책 정리

### Task 20. DB 백업/복원 절차 문서화

- 목표: 컨테이너 DB를 기준으로 dump/restore 절차를 문서화

## 8. 우선순위 정리

### P0: 내일까지 반드시 필요한 작업

1. Task 1. 외부 MySQL 접근 가능 여부 확인
2. Task 2. 기준 스키마 상태 확인
3. Task 4. DB 기준 데이터 소스 확정
4. Task 7. MySQL Docker 구성 추가
5. Task 8. backend DB 연결 전환
6. Task 9. docker-compose.yaml 확장
7. Task 11. WSL 컨테이너 기동 검증
8. Task 12. 웹 접속 검증
9. Task 13. API 검증
10. Task 14. DB 초기 데이터 검증

### P1: 시연 안정화를 위해 권장되는 작업

1. Task 3. 파일 영속성 대상 확인
2. Task 10. `.dockerignore` 작성
3. Task 15. 업로드/파일 저장 검증

### P2: 시연 이후 진행할 작업

1. Task 16. 운영형 프런트 배포 구조 전환
2. Task 17. DB 초기화/마이그레이션 전략 통합
3. Task 18. `.env.example` 및 배포 환경 분리
4. Task 19. 운영 볼륨 및 백업 전략 정리
5. Task 20. DB 백업/복원 절차 문서화

## 9. 개발자용 최종 작업 순서 제안

개발 담당자에게는 아래 순서로 진행하라고 전달하면 된다.

1. 외부 DB 연결 가능 여부부터 확인
2. 현재 DB 스키마가 앱 요구사항과 맞는지 확인
3. DB 기준 dump 또는 init SQL 확보
4. MySQL 컨테이너 구성 추가
5. backend의 DB 연결 대상을 `db`로 전환
6. WSL에서 `docker compose config` 확인
7. WSL에서 컨테이너 기동 테스트
8. 웹 접속 및 API 확인
9. 업로드 및 파일 영속성 확인
10. 시연 완료 후 운영형 구조로 분리 작업 진행

## 10. 완료 판단 기준

이번 도커라이징 1차 작업은 아래 조건을 만족하면 완료로 본다.

1. `docker compose up --build`로 프런트, 백엔드, DB가 모두 기동한다.
2. 브라우저에서 8080 화면이 열린다.
3. `/api/assets/master`가 정상 응답한다.
4. backend가 DB 컨테이너와 정상 연결된다.
5. DB 초기 테이블과 데이터가 기대 상태로 적재된다.
6. `uploads`, `map_config.json`, MySQL 데이터가 재시작 후에도 유지된다.

이 문서는 실제 구현 작업의 체크리스트로 사용한다.