zioinfo-mail/docs/site_user_management.md

# [Specification] 사이트·사용자 등록관리

> 대상 기관(사이트) 및 담당자 연락처 정보를 등록·조회·수정하는 기능 명세.  
> 기관 단위 SLA, 계약 정보, 담당자 이메일·전화번호를 통합 관리한다.

---

## 1. 기관(사이트) 관리

### 1.1. 데이터 모델

| 필드 | 타입 | 설명 |
|------|------|------|
| `inst_id` | VARCHAR(20) | 기관 코드 (PK, 예: MOF, MOIS) |
| `inst_name` | VARCHAR(100) | 기관명 |
| `address` | VARCHAR(300) | 기관 주소 |
| `region` | VARCHAR(50) | 지역 (서울/세종/부산 등) |
| `contract_start` | DATE | 유지보수 계약 시작일 |
| `contract_end` | DATE | 유지보수 계약 종료일 |
| `sla_hours` | INT | SLA 응답 시간 (기본 4시간) |
| `pm_contact` | VARCHAR(50) | 담당 PM 사번 |
| `phone` | VARCHAR(20) | 기관 대표 연락처 |
| `note` | TEXT | 특이사항·메모 |
| `is_active` | CHAR(1) | Y: 활성 / N: 비활성 |

### 1.2. API 엔드포인트

| 메서드 | URL | 권한 | 설명 |
|--------|-----|------|------|
| `GET` | `/api/institutions` | ADMIN, PM | 전체 기관 목록 조회 |
| `GET` | `/api/institutions/{inst_code}` | ADMIN, PM, ENGINEER | 기관 상세 조회 |
| `POST` | `/api/institutions` | ADMIN | 기관 신규 등록 |
| `PATCH` | `/api/institutions/{inst_code}` | ADMIN, PM | 기관 정보 수정 |
| `DELETE` | `/api/institutions/{inst_code}` | ADMIN | 기관 비활성화 |

### 1.3. 응답 스키마 (InstitutionOut)

```python
class InstitutionOut(BaseModel):
    inst_code:      str
    inst_name:      str
    address:        str | None
    region:         str | None
    contract_start: date | None
    contract_end:   date | None
    sla_hours:      int
    pm_contact:     str | None
    phone:          str | None
    note:           str | None
    is_active:      str
    server_count:   int  # 연결된 서버 수 (조인)
    contact_count:  int  # 등록된 담당자 수 (조인)
    created_at:     datetime
    updated_at:     datetime
```

---

## 2. 기관 담당자 관리

### 2.1. 데이터 모델

| 필드 | 타입 | 설명 |
|------|------|------|
| `contact_id` | BIGINT | PK |
| `inst_id` | VARCHAR(20) | FK → TB_INST_META |
| `contact_name` | VARCHAR(50) | 담당자 이름 |
| `dept` | VARCHAR(100) | 부서명 |
| `position` | VARCHAR(50) | 직책/직급 |
| `role` | VARCHAR(30) | MANAGER / ENGINEER / PM / SECURITY / HELPDESK |
| `email` | VARCHAR(100) | 이메일 주소 |
| `phone` | VARCHAR(20) | 직통 전화 |
| `mobile` | VARCHAR(20) | 휴대폰 번호 |
| `is_primary` | CHAR(1) | Y: 주 담당자 |
| `is_active` | CHAR(1) | Y: 재직중 |

### 2.2. API 엔드포인트

| 메서드 | URL | 권한 | 설명 |
|--------|-----|------|------|
| `GET` | `/api/institutions/{inst_code}/contacts` | ADMIN, PM, ENGINEER | 기관 담당자 목록 |
| `POST` | `/api/institutions/{inst_code}/contacts` | ADMIN, PM | 담당자 추가 |
| `PATCH` | `/api/institutions/{inst_code}/contacts/{id}` | ADMIN, PM | 담당자 수정 |
| `DELETE` | `/api/institutions/{inst_code}/contacts/{id}` | ADMIN | 담당자 삭제(비활성) |

### 2.3. 담당자 역할 정의

| role | 설명 |
|------|------|
| `MANAGER` | 기관 총괄 담당자 (SLA 관련 주 연락처) |
| `ENGINEER` | 현장 엔지니어 (기술 담당) |
| `PM` | 프로젝트 매니저 |
| `SECURITY` | 정보보안 담당자 |
| `HELPDESK` | 헬프데스크 / 1차 접수 담당자 |

---

## 3. ITSM 사용자 (내부 운영자) 관리

> GUARDiA ITSM 로그인 계정 관리. 기관 담당자와 별도 관리.

### 3.1. 사용자 역할 (RBAC)

| 역할 | 설명 | 주요 기능 |
|------|------|-----------|
| `ADMIN` | 시스템 관리자 | 전체 설정, 사용자 관리, 모든 기관 접근 |
| `PM` | PM / 팀장 | SR 승인, 전체 현황 조회, 타임테이블 관리 |
| `ENGINEER` | SM 엔지니어 | 담당 SR 처리, 쉘 스크립트 실행, 타임테이블 입력 |
| `CUSTOMER` | 기관 담당자 | 자기 기관 SR 등록 및 현황 조회만 허용 |

### 3.2. API 엔드포인트

| 메서드 | URL | 권한 | 설명 |
|--------|-----|------|------|
| `GET` | `/api/users` | ADMIN | 전체 사용자 목록 |
| `GET` | `/api/users/me` | 전체 | 내 프로필 조회 |
| `POST` | `/api/users/register` | ADMIN | 신규 계정 생성 |
| `PATCH` | `/api/users/{id}` | ADMIN | 사용자 정보 수정 |
| `POST` | `/api/users/{id}/deactivate` | ADMIN | 계정 비활성화 |
| `POST` | `/api/auth/login` | - | 로그인 (JWT 발급) |
| `POST` | `/api/auth/logout` | 전체 | 로그아웃 |

### 3.3. 사용자 추가 필드

```python
class User(Base):
    # 기존 필드 외 추가
    email:      str          # 이메일 (알림 발송용)
    phone:      str | None   # 휴대폰 (SMS 알림용)
    dept:       str | None   # 부서명
    position:   str | None   # 직책
    inst_code:  str | None   # 소속 기관 코드 (CUSTOMER 역할용)
```

---

## 4. 프론트엔드 화면 구성

### 4.1. 기관 관리 화면 (`view-institutions`)

```
┌─────────────────────────────────────────────────────────┐
│ 🏢 기관(사이트) 관리               [+ 기관 등록]        │
├─────────────────────────────────────────────────────────┤
│ [검색: 기관명]  [지역 필터▼]  [계약만료 임박▼]           │
├──────┬───────────┬──────┬───────────┬──────┬────────────┤
│ 코드 │ 기관명    │ 지역 │ 계약 만료  │ 서버 │ SLA        │
├──────┼───────────┼──────┼───────────┼──────┼────────────┤
│ MOF  │ 기획재정부 │ 세종 │ 2025-12-31│  8대 │ 4h         │
│ MOIS │ 행정안전부 │ 서울 │ 2026-03-31│ 12대 │ 2h ⚠       │  ← SLA 단시간 경고
│ MSS  │ 중소벤처부 │ 세종 │ 2025-11-30│  5대 │ 4h 🔴      │  ← 만료 임박
└──────┴───────────┴──────┴───────────┴──────┴────────────┘
```

### 4.2. 기관 상세 / 담당자 탭

```
┌─ 기관 상세: 기획재정부 (MOF) ──────────────────────────┐
│ [기본정보] [담당자] [서버] [SR이력] [타임테이블]         │
├─────────────────────────────────────────────────────────┤
│ 담당자 탭                              [+ 담당자 추가]   │
│ ┌──────────┬────┬────────────┬──────────────────┬──────┐ │
│ │ 이름     │역할│ 이메일     │ 연락처           │ 주담 │ │
│ ├──────────┼────┼────────────┼──────────────────┼──────┤ │
│ │ 김○○    │PM  │ k@mof.go.kr│ 010-xxxx-xxxx   │ ★   │ │
│ │ 이○○    │ENG │ l@mof.go.kr│ 02-xxxx-xxxx    │      │ │
│ └──────────┴────┴────────────┴──────────────────┴──────┘ │
└─────────────────────────────────────────────────────────┘
```

---

## 5. 알림 연동

- 계약 만료 **30일/7일/1일 전** → 담당 PM 이메일 발송 (Celery Beat 스케줄)
- SSL 인증서 만료 **60일/30일/7일 전** → ITSM 알림 + 메신저 채널 경고
- SLA 초과 위험 SR → 기관 담당자 이메일/SMS 통보 (연락처 DB 기반)