acs/docs/workflow-sequence.md

# ACS 워크플로우 — 시퀀스/상태 다이어그램 (Mermaid)

> 대상: IT센터 출입자관리시스템 · 작성일 2026-07-03
> GitHub·VS Code·mermaid.live 등에서 렌더링됨. 서술형 문서는 [workflow.md](workflow.md) 참조.

---

## 1. 방문 신청 상태 머신

```mermaid
stateDiagram-v2
    [*] --> DRAFT: 신청 초안
    DRAFT --> PENDING: 제출
    PENDING --> APPROVED: 승인 (qrToken 발급)
    PENDING --> REJECTED: 반려
    PENDING --> CANCELLED: 취소
    APPROVED --> CANCELLED: 취소
    APPROVED --> EXPIRED: 방문 종료일 경과 후 체크인 시도
    APPROVED --> [*]: 출입 완료
    REJECTED --> [*]
    CANCELLED --> [*]
    EXPIRED --> [*]
```

---

## 2. 전체 흐름 (신청 → 승인 → 발송 → 입·출입)

```mermaid
sequenceDiagram
    autonumber
    actor Host as HOST/담당자
    actor Admin as ADMIN
    participant API as ACS 백엔드
    participant SMS as PassNotifier(SMS)
    actor Visitor as 방문자
    actor Sec as SECURITY/게이트
    participant GW as AccessControlGateway

    Host->>API: ① 방문 사전신청 (POST /api/visit-requests)
    note right of API: 상태 = PENDING (개별 or 엑셀 업로드)

    Admin->>API: ② 승인함 조회 (GET /api/visit-requests/pending)
    Admin->>API: ③ 승인 (POST /api/approvals/{id}/approve)
    note right of API: 상태 = APPROVED, qrToken(UUID) 발급, Approval 기록
    API->>SMS: ④ 출입증(QR PNG) 발송 요청
    note right of SMS: 발송 실패는 catch&log — 승인은 롤백 안 함
    SMS-->>Visitor: 출입증 링크 문자 (ACS_PUBLIC_BASE_URL/pass/:token)

    Visitor->>API: ⑤ 공개 출입증 열람 (GET /pass/:token, 비로그인)
    API-->>Visitor: QR / 방문정보 표시

    Visitor->>Sec: ⑥ 방문일 현장 도착
    Sec->>API: ⑦ 체크인 (POST /api/access/check-in, QR/이름)
    note right of API: 상태·일자·블랙리스트·중복·재입장 검증 (아래 §3)
    API->>GW: openGate(gateId)
    GW-->>API: accepted
    API-->>Sec: 입장 처리 (AccessEvent IN 기록)

    Sec->>API: ⑧ 재실현황 (GET /api/access/inside)
    API-->>Sec: 재실 방문자 목록

    Visitor->>Sec: ⑨ 퇴장
    Sec->>API: ⑩ 체크아웃 (POST /api/access/check-out)
    API-->>Sec: 퇴장 처리 (AccessEvent OUT 기록)

    Admin->>API: ⑪ 대시보드 통계 (GET /api/stats/summary)
    Sec->>API: ⑫ 방문 리포트 (GET /api/reports/visits.xlsx)
    API-->>Sec: 엑셀(POI) 다운로드
```

---

## 3. 체크인 검증 로직 (AccessService.checkIn)

```mermaid
sequenceDiagram
    autonumber
    actor Sec as SECURITY / 키오스크
    participant AS as AccessService
    participant BL as BlacklistService
    participant AE as AccessEventRepo
    participant GW as AccessControlGateway

    Sec->>AS: check-in (qrToken 또는 visitRequestId)
    AS->>AS: 방문신청 resolve

    alt 상태 ≠ APPROVED
        AS-->>Sec: 400 승인되지 않은 방문
    else 방문 종료일 경과
        AS->>AS: 상태 = EXPIRED
        AS-->>Sec: 400 신청일 경과 — 재신청 필요
    else 방문 시작일 이전
        AS-->>Sec: 400 아직 방문일 아님
    else
        AS->>BL: blockReason(name, contact)
        alt 블랙리스트 매칭
            BL-->>AS: 사유
            AS-->>Sec: 403 차단된 방문자
        else 통과
            AS->>AE: isInside? / hasExitedToday?
            alt 이미 재실 중
                AS-->>Sec: 409 중복 입장
            else 금일 퇴장 완료
                AS-->>Sec: 400 재입장 불가
            else 정상
                AS->>AE: AccessEvent(IN) 저장
                AS->>GW: openGate(gateId)
                GW-->>AS: accepted
                AS-->>Sec: 입장 처리 완료
            end
        end
    end
```

---

## 4. 시스템 컴포넌트 개요

```mermaid
flowchart LR
    subgraph FE[프론트엔드 React/Vite]
        L[로그인] --> DB1[대시보드]
        VR[방문신청] --> AQ[승인함 ADMIN]
        AC[출입콘솔] --> KIOSK[키오스크 공개]
        RPT[리포트] & BLK[블랙리스트 ADMIN]
        PP[공개 출입증 /pass/:token]
    end

    subgraph BE[백엔드 Spring Boot]
        CTRL[Controllers] --> SVC[Services]
        SVC --> REPO[(JPA Repositories)]
        SVC --> QR[QrService ZXing]
        SVC --> NOTI[PassNotifier SMS]
        SVC --> GWY[AccessControlGateway Mock/실장비]
        SVC --> POI[Report/Excel POI]
    end

    subgraph DATA[저장소]
        DBH[(H2 dev)]
        DBP[(PostgreSQL prod + Flyway)]
    end

    FE -->|/api 세션 인증| CTRL
    REPO --> DBH
    REPO --> DBP
    NOTI -->|hanbank| MSG[사내 메시지 API]
    PP -.공개 링크.-> FE
```

---

## 5. 배포 파이프라인 (운영, Docker)

```mermaid
flowchart LR
    ENV[.env 설정] --> BUILD[docker compose build]
    BUILD --> UP[compose up -d: db + app + web]
    UP --> FW[app 기동 시 Flyway V1__init 적용]
    FW --> SEED[compose run seed: 사용자 적재]
    SEED --> READY[서비스 준비: nginx :80 → /api → app :8080]
    READY --> DBV[(db_data 볼륨 영속)]
```