# 🏷️ Git 운영 및 통합 업데이트 관리 규칙

이 문서는 Smart IMS 플랫폼의 **Git 운영 정책**, **태그 작성 규칙**, 그리고 **운영 서버 수동 업데이트 방법**을 설명합니다.

---

## 1. 태그 메시지 작성 규칙 (Changelog 자동 생성)

플랫폼의 업데이트 엔진은 태그 메시지의 **머리말(Prefix)**과 **리스트 기호(`-`, `*`)**를 분석하여 관리 페이지의 업데이트 히스토리를 생성합니다.

### 📋 메시지 구조
```text
[TYPE] 업데이트 제목 (한 줄 요약)
- 상세 변경 내용 1
- 상세 변경 내용 2
* 상세 변경 내용 3
```

### 🏷️ 업데이트 타입 (TYPE) 정의
| 키워드 | 업데이트 유형 | 시각적 표시 | 비고 |
|:--- |:--- |:--- |:--- |
| `[URGENT]` | **긴급/보안** | 빨간색 배너 | 최우선 업데이트 권장 |
| `[HOTFIX]` | **긴급 수정** | 빨간색 배너 | 버그 즉시 수정 건 |
| `[FEATURE]` | **기능 추가** | 남색(Indigo) | 새로운 기능 도입 |
| `[FIX]` | **일반 수정** | 회색(Slate) | 일반적인 버그 수정 |
| `[PATCH]` | **패치/보정** | 회색(Slate) | 마이너 품질 개선 |

---

## 2. 개발 및 배포 절차 (개발 PC)

개발 작업 및 태그 생성은 아래 경로에서 진행합니다.
*   **작업 경로**: `d:\antigravity\smartims` (윈도우 개발 환경 기반)

### STEP 1: 코드 변경 사항 커밋 및 푸시
```powershell
# [위치: d:\antigravity\smartims (루트)]
git add .
git commit -m "릴리즈 준비: v0.3.5 패치"
git push origin main
```

### STEP 2: 어노테이티드 태그(Annotated Tag) 생성
```powershell
# [위치: d:\antigravity\smartims (루트)]
git tag -a v0.3.5 -m "[PATCH] 시스템 안정화 패치
- 원격 태그 동기화 로직 강화
- API 캐시 방지 타임스탬프 도입"
```

### STEP 3: 원격 저장소에 태그 푸시
```powershell
# [위치: d:\antigravity\smartims (루트)]
git push origin v0.3.5
```

---

## 3. 운영 서버 수동 업데이트 방법 (Production Server)

웹 UI 업데이트가 실패하거나 SSH를 통해 직접 서버에서 제어해야 할 경우 사용합니다.
*   **서비스 경로**: `/volume1/web/smartims` (리눅스 운영 환경 기반)

### STEP 1: 원격 정보 확인 및 체크아웃
```bash
# [위치: /volume1/web/smartims (루트)]

# 1. 원격 저장소의 최신 태그 목록 확인 (무엇이 최신인지 먼저 확인)
git ls-remote --tags origin

# 2. 태그 정보 강제 업데이트 (원격 저장소와 완벽 동기화)
git fetch origin +refs/tags/*:refs/tags/* --force --prune --prune-tags

# 3. 대상 버전으로 강제 체크아웃
git checkout -f v0.3.5
```

### STEP 2: 프론트엔드 빌드 및 의존성 업데이트
```bash
# [위치: /volume1/web/smartims (루트)]
npm install
npm run build
```

### STEP 3: 백엔드 반영 및 서비스 재시작
```bash
# [위치: /volume1/web/smartims/server]
cd server
npm install
pm2 reload smartims-api
```

---

## 4. 유용한 Git 명령어 레퍼런스

*   **태그 목록 확인**: `git tag -l` (모든 환경의 루트 폴더)
*   **최신 태그 정보 확인**: `git describe --tags --abbrev=0`
*   **원격 태그 강제 덮어쓰기 (메시지 수정 시)**:
    ```powershell
    # [위치: 개발 PC 루트]
    git tag -a v0.3.5 -f -m "수정된 메시지..."
    git push origin v0.3.5 -f
    ```

---

## 5. 데이터 백업 및 유지관리 절차 (시놀로지 운영 서버 기준)

자동 업데이트는 데이터를 안전하게 유지하지만, 서버 이전이나 예기치 못한 환경 변화에 대비하여 다음 절차에 따라 주기적으로 백업하는 것을 권장합니다.

### ✅ 자동 업데이트 시 데이터 안전성
*   **파일 안전**: 시스템 관리 메뉴를 통한 **[자동 업데이트]** 실행 시, `server/uploads` 폴더는 Git 추적 제외 대상이므로 **삭제되거나 초기화되지 않고 그대로 유지**됩니다.
*   **DB 안전**: 업데이트 시 기존 데이터베이스의 테이블 구조만 업데이트(Migration)하며, 이미 등록된 자산 데이터는 보존됩니다.

### 📦 수동 백업 절차 (Step-by-Step)
운영 서버(시놀로지) SSH 터미널에서 아래 순서대로 실행하여 백업 파일을 생성합니다.

#### 1단계: 업로드 이미지 백업
자산 이미지 및 매뉴얼 파일이 저장된 폴더를 압축합니다.
```bash
# [위치: /volume1/web/smartims]
# uploads 폴더를 backup_images_오늘날짜.tar.gz로 압축
tar -czvf backup_images_$(date +%Y%m%d).tar.gz server/uploads/
```

#### 2단계: 데이터베이스(DB) 백업
시스템의 모든 텍스트 데이터(자산 정보, 계정, 로그 등)를 추출합니다.
```bash
# [위치: /volume1/web/smartims]
# .env에 설정된 정보를 바탕으로 DB 전체를 백업
# (비밀번호 입력 프롬프트가 뜨면 DB 비밀번호 입력)
/usr/local/mariadb10/bin/mysqldump -u root -p smartims > backup_db_$(date +%Y%m%d).sql
```

#### 3단계: 백업 파일 안전 보관
생성된 `backup_images_*.tar.gz`와 `backup_db_*.sql` 파일을 시놀로지 File Station을 통해 외부 저장소나 PC로 내려받아 보관하십시오.

---

## 💡 최종 주의사항
1.  **실행 위치 확인**: 특히 `pm2` 명령어나 `server` 관련 설정은 반드시 `server` 폴더 내에서 실행하거나 경로를 정확히 지정해야 합니다.
2.  **경로 이동 주의**: `cd server`를 통해 폴더를 이동하여 작업을 마친 후에는 반드시 `cd ..`를 통해 다시 루트 폴더로 복귀하여 다음 작업에 혼선이 없도록 합니다.
3.  **권한 관리**: 운영 서버에서는 반드시 서비스 실행 권한을 가진 계정으로 명령어를 실행해야 `PM2` 프로세스 관리에 문제가 생기지 않습니다.
4.  **수동 설치 주의**: `git clone`을 새로 받아 설치할 때는 기존 `uploads` 폴더가 포함되어 있지 않으므로 반드시 위 1단계에서 만든 백업본을 복구해야 합니다.