Initial dashboard organization setup

docs/DEPLOYMENT_GUIDE.md

@@ -0,0 +1,76 @@
+# MH Dashboard Organization 배포 가이드
+
+## 1. "도메인 발급/등록"이란?
+- 도메인은 사용자가 브라우저에 입력하는 주소입니다. 예를 들면 `orgdash.intra.company.local` 같은 형태입니다.
+- 사내망에서는 보통 IT팀이나 인프라 담당자가 이 주소를 실제 Ubuntu 서버 IP와 연결하는 DNS 설정을 등록합니다.
+- 아직 사내 DNS 등록 절차가 없다면, 우선은 `http://10.10.10.15:8080` 같은 IP 주소로 먼저 접속하고 나중에 도메인을 붙여도 됩니다.
+
+## 2. 이 프로젝트의 권장 구성
+- `proxy`: 사내 접속용 단일 진입점 역할을 하는 Nginx 리버스 프록시
+- `frontend`: 화면상 로그인과 허브 화면을 제공하는 정적 프론트엔드
+- `backend`: 구성원 데이터, 이미지 업로드, 스냅샷 생성을 처리하는 FastAPI 서버
+- `db`: 영구 저장을 담당하는 PostgreSQL 데이터베이스
+
+## 3. 왜 이 구조가 지금 프로젝트에 맞는가
+- 기존 조직도 HTML 화면을 그대로 레거시 모듈로 유지할 수 있습니다.
+- 프로필 사진 업로드를 서버에 저장할 수 있습니다.
+- 월말 조직 데이터 스냅샷을 서버에서 생성하고 보관할 수 있습니다.
+- 요청하신 대로 로그인은 우선 화면상으로만 구현해 둘 수 있습니다.
+
+## 4. Ubuntu 서버 준비
+- 사내망 안에 Ubuntu 24.04 서버를 새로 준비합니다.
+- 사내망에서 필요한 포트만 열어둡니다. 보통 `80` 또는 `8080` 정도면 시작할 수 있습니다.
+- Docker Engine과 Docker Compose 플러그인을 설치합니다.
+- 이 저장소를 서버로 복사합니다.
+- `.env.example`을 기준으로 `.env` 파일을 만들고 실제 DB 비밀번호를 넣습니다.
+
+## 4-1. 현재 로컬 PC 기준 WSL 작업 표준
+- 현재 로컬 개발 서버는 `WSL2 + Ubuntu-24.04` 기준으로 구성했습니다.
+- 기본 작업 사용자는 `hyunho` 입니다.
+- 앞으로의 기준 작업 경로는 아래입니다.
+  - `/home/hyunho/projects/mh-dashboard-organization`
+- Windows 폴더는 원본 참고용으로 남아 있을 수 있지만, 실제 실행과 개발 기준은 WSL 내부 경로로 맞추는 것을 권장합니다.
+
+## 4-2. VS Code는 어떤 경로를 열어야 하나
+- VS Code 좌측 아래에 `WSL: Ubuntu-24.04` 가 보이는 상태로 여는 것이 가장 안전합니다.
+- VS Code에서 `Remote-WSL: Reopen Folder in WSL` 기능으로 다시 열 수 있습니다.
+- 다시 열어야 할 권장 경로는 아래입니다.
+  - `/home/hyunho/projects/mh-dashboard-organization`
+- 이렇게 열면 Docker, Python, Linux 경로, 실행 환경이 실제 서버와 가장 비슷하게 맞춰집니다.
+
+## 5. Docker 설치 관련 메모
+- 메신저에 공유된 명령어는 Ubuntu 서버에 Docker를 설치하기 위한 절차입니다.
+- 최종 기준 문서는 Docker 공식 문서를 보는 것을 권장합니다.
+  https://docs.docker.com/engine/install/ubuntu/
+- 회사에서 apt 미러나 보안 기준을 따로 관리한다면, 패키지 소스를 바꾸기 전에 그 정책을 먼저 확인하는 것이 좋습니다.
+
+## 6. 최초 배포 순서
+1. `.env.example`을 `.env`로 복사합니다.
+2. `POSTGRES_PASSWORD` 값을 실제 비밀번호로 수정합니다.
+3. `docker compose build`를 실행합니다.
+4. `docker compose up -d`를 실행합니다.
+5. 브라우저에서 `http://SERVER_IP:8080` 으로 접속합니다.
+
+## 7. 현재 단계의 데이터 및 백업 정책
+- 데이터베이스: PostgreSQL 볼륨 `postgres_data`
+- 업로드 파일: Docker 볼륨 `uploads_data`
+- 월말 스냅샷 파일: Docker 볼륨 `snapshots_data`
+- 백업 주기: 월말 스냅샷 생성 + DB 볼륨 백업
+- 복구 기준: 아직 정해지지 않았으므로, 우선은 수동 복구 절차를 먼저 문서화하고 이후에 기준을 구체화합니다.
+
+## 8. 현재 구조의 한계
+- 로그인은 화면상 동작만 구현되어 있고, 아직 백엔드 보호 기능은 없습니다.
+- 레거시 조직도 화면은 iframe으로 연결만 해둔 상태이며, DB 기반 API와 완전히 연동되지는 않았습니다.
+- 레거시 화면은 CDN 자산을 사용합니다. 사내망이 외부 인터넷 접속을 막는 환경이라면 추후 로컬 자산으로 바꿔야 합니다.
+
+## 9. 다음 구현 권장 순서
+1. 프로필 사진 업로드 UI를 `/api/uploads/profile-photo` 와 연결합니다.
+2. 구성원 데이터를 브라우저 메모리 방식에서 PostgreSQL 기반 API 저장 방식으로 전환합니다.
+3. 사무실 자리배치 좌표 저장 기능을 추가합니다.
+4. 인증 정책이 정해지면 화면상 로그인 대신 실제 로그인으로 교체합니다.
+
+## 10. 현재 로컬 테스트 접속 정보
+- 접속 주소: `http://localhost:8080`
+- 상태 확인 API: `http://localhost:8080/api/health`
+- WSL 내부 실행 경로:
+  - `/home/hyunho/projects/mh-dashboard-organization`

docs/WSL_WORKSPACE_GUIDE.md

@@ -0,0 +1,34 @@
+# WSL 작업 기준 가이드
+
+## 1. 왜 WSL 기준으로 작업하나
+- 현재 이 프로젝트는 Ubuntu 24.04 기반 Docker 환경에서 실행되고 있습니다.
+- Windows 폴더에서 바로 작업하면 실행 경로와 편집 경로가 달라질 수 있습니다.
+- 그래서 앞으로는 `WSL Ubuntu 내부 경로`를 기준 작업공간으로 사용하는 것을 권장합니다.
+
+## 2. 기준 작업 경로
+- 사용자: `hyunho`
+- 프로젝트 경로: `/home/hyunho/projects/mh-dashboard-organization`
+
+## 3. VS Code에서 여는 방법
+1. VS Code 명령 팔레트를 엽니다.
+2. `Remote-WSL: Reopen Folder in WSL` 를 실행합니다.
+3. 아래 경로를 엽니다.
+   - `/home/hyunho/projects/mh-dashboard-organization`
+4. 좌측 아래 상태 표시줄에 `WSL: Ubuntu-24.04` 가 보이면 정상입니다.
+
+## 4. 앞으로의 작업 규칙
+- 코드 수정은 가능하면 WSL 경로 기준으로 진행합니다.
+- Docker 실행, Python 실행, 배포 테스트도 WSL 안에서 진행합니다.
+- Windows 경로는 참고용 또는 백업용으로만 보고, 실행 기준으로 사용하지 않는 것이 좋습니다.
+
+## 5. 자주 쓰는 명령
+```bash
+cd /home/hyunho/projects/mh-dashboard-organization
+docker compose ps
+docker compose logs backend
+docker compose up -d
+```
+
+## 6. 현재 확인 가능한 주소
+- 메인 화면: `http://localhost:8080`
+- API 상태 확인: `http://localhost:8080/api/health`