Initial commit

docs/issues/issue_dashboard_and_modal_optimization.md

@@ -0,0 +1,45 @@
+# [Issue] 소프트웨어 자산 관리 체계 개편 및 클라우드(Cloud) 서비스 관리 신설
+
+## 1. 개요
+기존의 단일 소프트웨어(SW) 분류 체계를 비즈니스 모델에 맞춰 **구독형, 영구형, 클라우드형**으로 삼원화하고, 특히 비용 변동이 잦은 클라우드 서비스를 독립적으로 관리할 수 있는 전용 시스템을 신설함.
+
+---
+
+## 2. 주요 작업 내용
+
+### 📂 소프트웨어 관리 프레임워크 재구조화
+- **분류 체계 개편**: 소프트웨어를 아래 세 가지 유형으로 재정의하여 관리 효율성을 높임.
+  1. **구독형 (Subscription)**: 연/월 정액제로 운영되는 SW
+  2. **영구형 (Perpetual)**: 구매 후 영구 소유하는 SW (유지보수 중심 관리)
+  3. **클라우드형 (Cloud)**: 플랫폼 기반 종량제(AWS, Azure 등) 서비스
+- **내비게이션 통합**: 상단 탭을 유형별로 분리하여 각 자산 특성에 맞는 리스트 뷰를 제공함.
+
+### ☁️ 클라우드(Cloud) 서비스 관리 페이지 신설
+- **전용 리스트 뷰 (`CloudListView.ts`)**: 
+  - 플랫폼명, 담당 부서, 프로젝트(사용용도), 결제 수단, 결제일 등 클라우드 특화 항목 중심의 테이블 구성함.
+  - **결제수단별 필터링 기능** (법인카드, 인보이스) 및 통합 검색 기능을 추가함.
+- **클라우드 전문 모달 (`CloudModal.ts`)**:
+  - 클라우드 요금 및 결제 정보 입력을 위한 2분할 레이아웃 배치함.
+  - **업데이트 이력(History Logs)** 시스템을 도입하여 매월 변동되는 비용을 히스토리 형식으로 기록/추적 가능하게 함.
+
+### 📊 대시보드(Dashboard) 리팩토링 및 고도화
+- **카드 레이아웃 최적화**: 사용율, 만료 예정, 클라우드 현황(전월/당월 비교) 정보를 2열 그리드로 정돈함.
+- **데이터 시각화**: 
+  - **클라우드 결제 규모 추이**: 최근 4개월간의 비용 변동을 꺾은선 그래프로 구현함.
+  - **실시간 데이터 연동**: 자산 업데이트 이력(Logs)에 기록된 비용이 대시보드 차트에 실시간 합산 반영되도록 로그 분석 엔진을 구축함.
+- **상세 팝업 연동**: 대시보드 요약 카드를 클릭하면 해당하는 자산의 상세 목록이 뜨는 모달 연동 기능을 추가함.
+
+### 🪟 UX 및 데이터 정합성 강화
+- **수정 저장 워크플로우 (Edit-to-Save)**: 실수로 인한 데이터 변경을 막기 위해 모든 상세 모달에 '조회 모드'를 기본으로 하고, [수정] 버튼 클릭 시에만 입력이 활성화되도록 제어함.
+- **금액 자동 포맷팅**: 콤마 표시 오류를 해결하고 천 단위 포맷팅을 표준화함.
+- **결제 임박 알림**: 각 서비스의 결제일을 계산하여 14일 이내 결제가 필요한 항목을 대시보드에서 즉시 파악할 수 있게 함.
+
+---
+
+## 3. 향후 과제
+- 클라우드 플랫폼 간 비용 비교 통계 기능 확장 검토
+- 결제 수단(법인카드) 만료일에 기초한 알림 서비스 추가 검토
+
+---
+**작업자**: Antigravity (AI Assistant)
+**상태**: 완료 (2026-04-17)

docs/issues/issue_sw_modal_refactor.md

@@ -0,0 +1,33 @@
+# [이슈] S/W 자산 관리 고도화 및 이력 추적 기능 구현
+
+## 1. 개요
+소프트웨어 자산의 라이프사이클을 체계적으로 관리하기 위해 상세 정보 모달을 개편하고, 갱신(업데이트) 이력을 추적할 수 있는 기능을 구현하였습니다. 또한, 사용자의 가독성을 위해 상태를 나타내는 자동 뱃지를 도입하고 날짜 입력 편의성을 개선하였습니다.
+
+## 2. 작업 상세 내용
+
+### A. S/W 목록(Table) 개선
+- **상태 자동 계산 시스템 도입**:
+    - 구독 S/W: 만료일 기준 **[사용중] / [만료]** 자동 표시.
+    - 영구 S/W: 유지보수 대상 여부에 따라 **[유효] / [없음]** 표시.
+- **UI 뱃지 적용**: 테이블 좌측에 상태 뱃지를 추가하여 시각적 인지도를 높임.
+
+### B. 상세 정보 모달 개편 (`SWModal.ts`)
+- **2단 분할 레이아웃 적용**: 좌측(기본 정보), 우측(업데이트 타임라인)으로 UI 재설계.
+- **날짜 입력 필드 개선**: 
+    - '구매일' 필드에 캘린더 피커(Calendar Picker) 적용.
+    - '구독 기간' 필드를 **시작일**과 **종료일**로 분리하여 각각 캘린더 적용.
+    - 직접 입력("yyyy-mm-dd") 형식도 동시 지원.
+
+### C. 계약 업데이트(갱신) 관리 기능
+- **[업데이트 추가]** 버튼 및 전용 서브 팝업 구현.
+- 갱신 시 발생하는 비용, 기간 연장, 메모를 기록하여 타임라인(Log)에 누적.
+- 업데이트 반영 시 메인 자산 정보의 구독 기한 및 누적 금액이 자동으로 최신화되도록 연동.
+
+## 3. 관련 파일
+- `src/views/SW_Table.ts`: 테이블 상태 로직 및 뱃지 렌더링.
+- `src/components/Modal/SWModal.ts`: 모달 UI 및 날짜 처리, 업데이트 로직.
+- `src/styles/modal.css`: 분할 레이아웃 및 타임라인 스타일.
+
+## 4. 확인 사항
+- 엑셀 업로드/다운로드 시 기존 '구독일' 문자열 형식과의 호환성 유지 확인.
+- 브라우저 테스트를 통한 캘린더 작동 및 테이블 상태 연동 확인 완료.

docs/itam_cicd_setup.md

@@ -0,0 +1,226 @@
+# ITAM CI/CD 설정 가이드
+
+## 1. 문서 목적
+
+이 문서는 현재 ITAM 저장소에 구성된 CI/CD 파일을 실제 운영에 연결하기 위해 필요한 기준을 정리한 가이드다.
+
+대상 범위는 아래와 같다.
+
+1. Gitea Actions workflow 역할
+2. Gitea Variables / Secrets 설정값
+3. 운영 서버 배포 디렉토리 기준
+4. 운영 영속 경로 기준
+5. production deploy 실행 전 확인 사항
+
+---
+
+## 2. 현재 CI/CD 구성
+
+현재 `.gitea/workflows`에는 ITAM 관련 workflow만 남겨둔 상태다.
+
+1. `itam_code_check.yml`
+2. `itam_docker_build_check.yml`
+3. `itam_production_deploy.yml`
+
+각 workflow의 역할은 아래와 같다.
+
+1. `itam_code_check.yml`: TypeScript/Vite build와 compose 문법 검증
+2. `itam_docker_build_check.yml`: 운영용 Docker 이미지 빌드 가능 여부 검증
+3. `itam_production_deploy.yml`: 운영 서버에 SSH 접속 후 실제 배포 수행
+
+현재 배포 흐름은 아래와 같다.
+
+```mermaid
+flowchart LR
+  DEV["Developer Push or Manual Run"] --> CODE["ITAM Code Check"]
+  CODE --> BUILD["ITAM Docker Build Check"]
+  BUILD --> DEPLOY["ITAM Production Deploy"]
+  DEPLOY --> HOST["Production Host"]
+  HOST --> APP["docker compose up -d --build"]
+  linkStyle default stroke:#d32f2f,stroke-width:2px;
+```
+
+---
+
+## 3. Gitea Variables / Secrets 기준
+
+`itam_production_deploy.yml`이 정상 동작하려면 아래 값이 필요하다.
+
+### 3.1 Variables
+
+아래 항목은 Gitea repository Variables에 등록한다.
+
+| Key | 설명 | 예시 |
+| --- | --- | --- |
+| `PROD_HOST` | 운영 서버 SSH 접속 호스트 | `10.0.0.25` |
+| `PROD_USER` | 운영 서버 SSH 사용자 | `deploy` |
+| `PROD_DEPLOY_PATH` | 서버에서 저장소를 배포할 경로 | `/opt/itam` |
+| `PROD_BACKUP_ROOT` | 배포 전 백업 저장 경로, 배포 경로 바깥이어야 함 | `/opt/itam-backups` |
+| `PROD_GIT_URL` | 운영 서버에서 pull 가능한 저장소 주소 | `git@gitea.example.com:team/itam.git` |
+| `PROD_DB_HOST` | 외부 MySQL 호스트 | `172.16.8.151` |
+| `PROD_DB_PORT` | 외부 MySQL 포트 | `3306` |
+| `PROD_DB_USER` | 운영 DB 계정 | `itam_admin` |
+| `PROD_DB_NAME` | 운영 DB 이름 | `itam` |
+| `PROD_LOG_LEVEL` | 애플리케이션 로그 레벨 | `info` |
+
+### 3.2 Secrets
+
+아래 항목은 Gitea repository Secrets에 등록한다.
+
+| Key | 설명 |
+| --- | --- |
+| `PROD_SSH_PRIVATE_KEY` | 운영 서버 접속용 개인키 |
+| `PROD_DB_PASS` | 운영 DB 비밀번호 |
+
+### 3.3 운영 원칙
+
+1. `PROD_DB_PASS`는 Variables가 아니라 Secrets에만 둔다.
+2. `PROD_SSH_PRIVATE_KEY`는 배포 전용 계정 키를 사용한다.
+3. `PROD_GIT_URL`은 운영 서버에서 직접 pull 가능한 주소여야 한다.
+4. 운영 서버의 `known_hosts`는 workflow에서 자동 등록되지만, 최초 운영 전 수동 접속 검증도 함께 수행하는 것이 안전하다.
+5. `PROD_BACKUP_ROOT`는 `PROD_DEPLOY_PATH` 내부가 아니라 바깥 경로를 사용해야 한다.
+
+---
+
+## 4. 운영 서버 배포 디렉토리 기준
+
+현재 `itam_production_deploy.yml`은 운영 서버에서 아래 흐름으로 배포를 수행한다.
+
+1. `PROD_DEPLOY_PATH` 디렉토리를 생성한다.
+2. 기존 운영 상태가 있으면 배포 전 백업을 수행한다.
+3. 해당 경로에 저장소를 clone 또는 fetch 한다.
+4. 지정 브랜치로 checkout 한다.
+5. `uploads`, `logs/nginx` 디렉토리를 생성한다.
+6. `.env.deploy`를 서버의 `.env`로 복사한다.
+7. `docker compose -f docker-compose.prod.yaml up -d --build`를 실행한다.
+
+권장 디렉토리 구조는 아래와 같다.
+
+```text
+/opt/itam/
+  .env
+  docker-compose.prod.yaml
+  Dockerfile.frontend.prod
+  Dockerfile.backend.prod
+  map_config.json
+  uploads/
+  logs/
+    nginx/
+  docker/
+    nginx/
+      default.conf
+    frontend/
+      default.conf
+  src/
+  public/
+  img/
+
+/opt/itam-backups/
+  db/
+  files/
+```
+
+현재 구조 기준 배포 관계는 아래와 같다.
+
+```mermaid
+flowchart TB
+  subgraph HOST["Production Host"]
+    REPO["PROD_DEPLOY_PATH"]
+    ENV[".env"]
+    UP["uploads/"]
+    LOGS["logs/nginx/"]
+    MAP["map_config.json"]
+  end
+
+  subgraph CTR["Docker Services"]
+    NGINX["itam-nginx"]
+    FRONT["itam-frontend"]
+    BACK["itam-backend"]
+  end
+
+  DB["External MySQL"]
+
+  REPO --> NGINX
+  ENV --> BACK
+  UP --> BACK
+  MAP --> BACK
+  LOGS --> NGINX
+  REPO --> BAK["PROD_BACKUP_ROOT"]
+  NGINX --> FRONT
+  NGINX --> BACK
+  BACK --> DB
+  linkStyle default stroke:#d32f2f,stroke-width:2px;
+```
+
+---
+
+## 5. 영속 경로 기준
+
+현재 `docker-compose.prod.yaml` 기준으로 운영에서 유지되어야 하는 경로는 아래와 같다.
+
+1. `.env`
+2. `uploads/`
+3. `map_config.json`
+4. `logs/nginx/`
+5. `PROD_BACKUP_ROOT`
+
+각 경로의 의미는 아래와 같다.
+
+1. `.env`: backend 런타임 환경변수
+2. `uploads/`: 업로드 파일 데이터
+3. `map_config.json`: 위치/맵 구성 데이터
+4. `logs/nginx/`: reverse proxy 접근 로그 및 에러 로그
+5. `PROD_BACKUP_ROOT`: 배포 전 DB dump와 운영 파일 아카이브 저장 위치
+
+운영 기준으로 보면 `uploads/`와 `map_config.json`은 애플리케이션 데이터이고, `.env`는 환경 설정이며, `logs/nginx/`는 운영 추적 데이터다.
+
+즉 서버 운영 시 컨테이너만 다시 띄우면 되는 구조가 아니라, 이 경로들이 유지되는 것을 전제로 배포가 성립한다.
+
+---
+
+## 6. 배포 전 체크리스트
+
+`itam_production_deploy.yml` 실행 전 아래 항목을 먼저 확인한다.
+
+1. 운영 서버에 Docker Engine과 `docker compose`가 설치되어 있어야 한다.
+2. 운영 서버의 배포 계정이 Docker 실행 권한을 가져야 한다.
+3. 운영 서버에서 `PROD_GIT_URL`로 직접 `git fetch`가 가능해야 한다.
+4. 외부 MySQL 접속 정보가 실제 운영망 기준으로 열려 있어야 한다.
+5. 운영 서버에 `map_config.json` 초기 파일이 존재해야 한다.
+6. 방화벽 또는 보안 장비에서 80 포트 접근 정책이 정리되어 있어야 한다.
+
+권장 확인 명령 예시는 아래와 같다.
+
+```bash
+docker --version
+docker compose version
+git ls-remote <PROD_GIT_URL>
+test -f map_config.json
+test -d uploads
+```
+
+---
+
+## 7. 현재 구조에서의 해석
+
+현재 ITAM CI/CD는 staging 없이도 운영 배포가 가능한 최소 구조로 정리되어 있다.
+
+이 구조의 장점은 아래와 같다.
+
+1. workflow 수가 적어서 관리가 단순하다.
+2. 운영 배포에 필요한 변수와 시크릿 범위가 명확하다.
+3. staging이 필요해지면 production deploy workflow를 복제해 별도 환경으로 확장하기 쉽다.
+
+즉, 지금 단계에서는 production 기준을 먼저 고정하고, staging은 동일 패턴으로 추후 추가하는 전략이 적절하다.
+
+---
+
+## 8. 다음 권장 작업
+
+현재 문서 기준으로 바로 이어서 할 작업은 아래 순서가 적절하다.
+
+1. `PROD_DEPLOY_PATH` 실제 서버 경로 확정
+2. 운영 서버 배포 계정 생성 및 SSH 키 등록
+3. `map_config.json`, `uploads/` 초기 데이터 준비
+4. production deploy workflow에 smoke check 추가
+5. 로그 로테이션과 백업/복구 절차 문서화