Initial commit: IT센터 출입자관리시스템 (ACS)
방문자 사전신청·승인, 입·출입 체크인/아웃, QR 배지, 재실현황, 블랙리스트, 대시보드 통계, 방문 리포트(엑셀)까지 7단계 전 기능 구현. - backend: Spring Boot 3.4.5 / Java 21 (JDK 26 빌드), 세션 인증, JPA, H2/PostgreSQL, POI, ZXing, Flyway - frontend: React 19 / Vite 6 / TypeScript - infra: Docker Compose (db·app·web nginx), Flyway V1__init, Python 사용자 시드 - docs: 워크플로우 / 시퀀스 다이어그램(Mermaid) / 이슈·유의사항 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
unknown
163
docs/workflow-sequence.md
Normal file
163
docs/workflow-sequence.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# 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 볼륨 영속)]
|
||||
```
|
||||
Reference in New Issue
Block a user