Visit Call — 아파트 입주민 주차 관리 서비스

flowchart LR
    App["입주민 앱 1.x<br/>Flutter"]
    Office["관리사무소 브라우저"]
    subgraph Backend["1.x 백엔드 · Windows PC, PM2"]
        Main["메인 서버<br/>Express · Sequelize"]
        DB[("MySQL<br/>테이블 20개")]
        Poll["폴링 서버<br/>Express · mssql"]
        Admin["관리자 웹<br/>Next.js 14 + 월 이월 스케줄러"]
    end
    Vendor[("업체 주차관제 DB<br/>MSSQL")]
    LPR["차단기 LPR"]
    FCM["Firebase<br/>Cloud Messaging"]

    App -- "HTTP /api · JWT" --> Main
    Main --> DB
    Main -- "HTTP 등록 · 삭제" --> Poll
    Poll -- "WebSocket 입출차 이벤트<br/>+ HTTP 콜백 재시도" --> Main
    Poll -- "Change Tracking 1초 폴링<br/>등록 테이블 쓰기" --> Vendor
    LPR --> Vendor
    Main -- "입차 · 세대원 알림" --> FCM --> App
    Office --> Admin
    Admin -- "SQL 직접 읽기·쓰기" --> DB
    Admin -- "SQL 직접 읽기" --> Vendor

flowchart LR
    subgraph Phone["입주민 휴대폰"]
        App["Visit Call 앱 2.0<br/>Flutter · iOS / Android"]
    end

    subgraph Firebase["Firebase"]
        RC["Remote Config<br/>단지 목록"]
        FCM["Cloud Messaging<br/>푸시"]
    end

    subgraph SiteA["노원 단지 · 1.x 유지"]
        L1["1.x 메인 서버 + 폴링 서버"]
        VA[("업체 주차관제 DB")]
    end

    subgraph SiteB["부천 단지 · 2.0 단지 서버 (Docker Compose)"]
        PX["proxy · Caddy<br/>자동 TLS"]
        SV["통합 서버 · Fastify"]
        DB[("PostgreSQL")]
        AD["관리자 웹 · Next.js BFF"]
        VB[("업체 주차관제 DB<br/>단지 내부망")]
    end

    Office["관리사무소 브라우저"]

    App -- "단지 목록" --> RC
    App -- "레거시 /api" --> L1
    App -- "HTTPS /api" --> PX
    PX --> SV
    Office -- "HTTPS" --> PX --> AD
    AD -- "/v1/admin · 관리자 토큰" --> SV
    SV --> DB
    SV -- "변경 추적 · 방문 등록" --> VB
    L1 <--> VA
    SV -- "입차 · 세대원 알림" --> FCM
    L1 --> FCM
    FCM -- "푸시" --> App

flowchart LR
    subgraph Server["server · Fastify 5 (단일 프로세스)"]
        Legacy["legacy<br/>앱 호환 /api/*"]
        AdminApi["admin API<br/>/v1/admin/*"]
        Domain["도메인<br/>예약 · 세대 · 세션 · 주차시간"]
        Connector["parking-connector<br/>방문 등록 반영"]
        Sync["parking-sync<br/>변경 추적 폴러 · 이벤트 소비자"]
        Scheduler["scheduler<br/>단지 시간대 배치"]
        Notifier["notifier<br/>FCM"]
    end
    DB[("PostgreSQL 18")]
    Vendor[("업체 주차관제 DB")]
    Legacy --> Domain
    AdminApi --> Domain
    Domain --> DB
    Domain --> Connector
    Scheduler --> Connector
    Connector -- "등록 테이블 쓰기" --> Vendor
    Sync -- "Change Tracking 읽기" --> Vendor
    Sync --> DB
    Sync --> Notifier

flowchart TD
    Boot["main.dart<br/>dotenv → Firebase → 백그라운드 푸시 핸들러<br/>→ DI → 단지 복원 → 푸시 초기화 → runApp"] --> Splash["스플래시 (최소 1초)"]
    Splash --> Q1{"선택한 단지가 있나?"}
    Q1 -- "없음" --> Site["① 단지 선택"] --> Login
    Q1 -- "있음" --> Restore["SessionController.restore()"]
    Restore -- "signedIn" --> Role{"역할"}
    Restore -- "noSession · expired" --> Login["② 로그인"]
    Restore -- "failed (네트워크 등)" --> Retry["다시 시도 / 로그인 화면으로<br/>로그인 정보는 지우지 않는다"]
    Login --> Role
    Role -- "reserve" --> Pending["승인 대기"]
    Role -- "head · member" --> Home["홈 · ④ 방문 차량 예약"]

sequenceDiagram
    autonumber
    participant H as 세대주 앱
    participant M as 세대원 앱
    participant S as 서버
    participant DB as PostgreSQL
    participant F as FCM

    Note over H,DB: 세대주 가입
    H->>S: POST /api/auth/hosts/verify (이름 + 휴대폰)
    S->>DB: 세대 명부 조회, 정확히 1세대만 통과
    S->>DB: 가입 티켓 발급 (10분, 요청 IP)
    S-->>H: host_id, address
    H->>S: POST /api/auth/register (아이디, 비밀번호, hostId, 약관 동의)
    S->>DB: 티켓 소진 + 세대주 계정 + 약관 동의 기록
    S-->>H: 200 (1.x는 201이라 앱이 실패로 표시하던 문제를 앱·서버 양쪽에서 해결)

    Note over M,F: 세대원 가입과 승인
    M->>S: POST /api/auth/register-member
    S-->>M: 201, 역할 reserve
    S->>F: family_member_joined
    F-->>H: 세대원 가입 요청 알림
    H->>S: POST /api/hosts/{hostId}/members/{accountKey}/approve
    S->>F: member_approved (1.x는 버그로 발송되지 않음)
    F-->>M: 승인 알림, 다시 로그인하면 홈

sequenceDiagram
    autonumber
    actor U as 입주민 앱
    participant S as 통합 서버
    participant DB as PostgreSQL
    participant V as 업체 주차관제 DB

    U->>S: POST /api/car/validate (Bearer)
    S->>DB: 등록 티켓 발급 (30분)
    S-->>U: isValid = true
    U->>S: POST /api/visitor/register-vehicle (토큰 없음)
    S->>DB: 티켓 소진 + reservations INSERT<br/>유일 (site_id, plate, visit_date_from)
    alt 방문일이 단지 시간대로 오늘
        S->>V: 그 차량의 유효 예약 전체를 등록 테이블 1행으로 합쳐 반영
        alt 입주민·정기 차량 행이 이미 있음
            S->>DB: 예약 삭제
            S-->>U: 409 RESIDENT_CAR
        else 반영 성공
            S->>DB: 반영 상태 registered
            S-->>U: success
        end
    else 미래 날짜
        S-->>U: success (반영 대기)
        Note over S,V: 단지 시간 00:03 배치가 반영하고, 실패분은 5분마다 재시도
    end

sequenceDiagram
    autonumber
    participant L as 차단기 LPR
    participant V as 업체 DB
    participant P as 폴링 서버
    participant M as 메인 서버
    participant F as FCM
    participant App as 앱

    L->>V: 입차 이력 행 기록
    loop 1초마다
        P->>V: 변경 추적 버전 확인, 늘었으면 변경 행 조회
    end
    P->>V: 방문 차량이면 이력 행에 등록 구분 표시
    P-->>M: WebSocket 입차 이벤트 (HTTP 콜백은 최대 3회 재시도)
    M->>M: 1분 중복 제거, 차량번호와 예약 기간으로 매칭
    M->>F: 매칭된 세대의 계정에 입차 알림
    F-->>App: plteNo, enterTime

sequenceDiagram
    autonumber
    participant L as 차단기 LPR
    participant V as 업체 DB
    participant P as 폴러 (단지별 1워커)
    participant DB as PostgreSQL
    participant C as 이벤트 소비자
    participant F as FCM

    L->>V: 입차 이력 행 기록
    loop 단지마다 루프 하나
        P->>V: 마지막 버전 이후 변경 조회<br/>스냅샷 격리, 최소 유효 버전 검사, 자기 쓰기 제외
        P->>DB: parking_events INSERT (dedupe_key) + ct_cursors 전진<br/>(한 트랜잭션)
    end
    C->>DB: 새 이벤트 조회
    C->>DB: (site_id, 차량번호, 단지 날짜)로 예약 매칭<br/>입차 게이트·기록 비활성화 기간 확인
    C->>DB: parking_sessions INSERT
    C->>F: 세대 계정(세대주·세대원)에 입차 푸시
    L->>V: 출차 이력 행 기록
    C->>DB: 업체 입차 ID(+차량번호)로 열린 세션을 찾아 exit_at 기록<br/>이중 게이트 중복 출차·미래 시각은 무시

sequenceDiagram
    participant A as 예약 확인 탭
    participant B as 사용기록 탭
    participant C as ApiClient
    participant S as SessionController
    participant SV as 서버

    par 동시 요청
        A->>C: GET /api/visitor/history/{hostId}
    and
        B->>C: GET /api/parking-time/current/{hostId}
    end
    C->>SV: 두 요청 (만료된 토큰)
    SV-->>C: 401, 401
    C->>S: refreshToken() 진행 중이면 같은 Future를 기다린다
    S->>SV: POST /api/auth/relogin (1번만)
    SV-->>S: 새 토큰
    C->>SV: 두 요청을 각각 1번씩 재시도
    SV-->>C: 200, 200
    opt 갱신이 거절되면
        S-->>A: sessionExpired, 앱 루트가 로그인 화면으로 보낸다
    end

sequenceDiagram
    actor A as 관리자 브라우저
    participant N as 관리자 웹 (Next BFF)
    participant S as 서버 /v1/admin/*
    participant DB as PostgreSQL
    A->>N: 화면 요청 (httpOnly 쿠키)
    N->>S: Bearer 관리자 토큰
    S->>S: 토큰 버전 확인 → 사이트 범위 검사
    S->>DB: 조회 · 변경 + 감사 로그 (변경 시)
    S-->>N: 응답 (공유 zod 스키마로 직렬화)
    N->>N: 같은 스키마로 응답 검증
    N-->>A: 렌더링

erDiagram
    apartments ||--o{ hosts : "세대"
    hosts ||..o{ account : "계정 (FK 없음)"
    hosts ||--o{ visitors : "방문 = 예약 + 입출차"
    visitors ||--o| visitor_parking_syncs : "업체 등록 재시도"
    visitorlinks |o--o{ visitors : "방문 링크"
    hosts ||..o{ visitors_history : "30일 지난 방문 (FK 없음)"
    hosts ||--o{ usage_parkingtime : "월 허용시간"
    hosts ||--o{ usage_parkingtimestats : "월 사용 통계"
    hosts ||--o{ user_agreements : "약관 동의"

    apartments {
        int apartment_id PK
        varchar apartment_name
    }
    hosts {
        int host_id PK
        int apartment_id FK
        varchar address2 "NNN동 NNN호"
        varchar resident_name
        varchar resident_phone
    }
    account {
        int account_KEY PK
        int host_id "FK 없음"
        varchar ID UK "로그인 ID"
        varchar PW "bcrypt"
        varchar role "head / member / reserve"
        varchar fcm_token "1계정 1기기"
        varchar session_token "단일 기기 세션"
    }
    visitors {
        int visitor_id PK
        int host_id FK
        varchar car_number
        date visit_date_from
        date visit_date_to
        datetime entry_time
        datetime exit_time
        varchar parking_entry_id UK "업체 입차 ID"
    }
    visitor_parking_syncs {
        int visitor_id PK, FK
        varchar status "pending / synced / failed"
        int attempt_count
        datetime next_attempt_at
    }
    visitorlinks {
        varchar unique_string UK
        datetime expiration_date
        boolean is_used
    }
    visitors_history {
        int history_id PK
        int host_id
        varchar car_number
        datetime deleted_at
    }
    usage_parkingtime {
        int host_id FK
        decimal monthly_limit_hours
        decimal daily_limit_hours
        varchar month_data
    }
    usage_parkingtimestats {
        int host_id FK
        varchar usage_month "YYYY-MM"
        decimal total_hours
        int total_sessions
    }
    user_agreements {
        int host_id FK
        varchar user_id
        varchar service_terms_version
        varchar privacy_policy_version
    }

erDiagram
    sites ||--o{ hosts : "세대"
    hosts ||--o{ accounts : "세대주 · 세대원"
    sites ||--o{ reservations : "단지"
    hosts ||--o{ reservations : "방문 예약"
    accounts |o--o{ reservations : "예약한 계정"
    reservations |o--o{ parking_sessions : "예약 1 : 세션 N"
    hosts |o--o{ parking_sessions : "세대"
    sites ||--o{ parking_events : "아웃박스"
    sites ||--o{ ct_cursors : "테이블별 커서"
    parking_events }o..o| parking_sessions : "소비자가 매칭"
    hosts ||--o{ parking_time_allocations : "월 허용시간"

    sites {
        bigint id PK
        text code UK "URL 슬러그"
        text name
        text timezone "기본 Asia/Seoul"
        text status "active / inactive"
        jsonb settings "방문 코드, 게이트, 중복 제거, LPR 오차, 동호 형식 등"
        jsonb parking_connector "kind, secretRef만 (비밀값 금지)"
    }
    hosts {
        bigint id PK "앱의 hostId"
        bigint site_id FK
        text dong
        text ho
        text unit_label "NNN동 NNN호"
        text resident_name
        text resident_phone "숫자만"
        text status
    }
    accounts {
        bigint id PK "앱의 accountKey"
        bigint host_id FK
        text login_id UK "대소문자 무시 전역 유일"
        text password_hash "bcrypt"
        text role "head / member / reserve"
        text fcm_token UK "1계정 1기기"
        text session_token "단일 기기 세션"
        timestamptz approved_at
    }
    reservations {
        bigint id PK "앱의 visitor_id"
        bigint site_id FK
        bigint host_id FK
        bigint account_id FK "null 허용"
        text plate "정규화 차량번호"
        date visit_date_from "단지 시간대"
        date visit_date_to
        text projection_status "pending / registered / failed / skipped"
        timestamptz projected_at
    }
    parking_sessions {
        bigint id PK
        bigint site_id FK
        bigint reservation_id FK "예약 삭제 후에도 통계용 보존"
        bigint host_id FK
        text plate
        timestamptz entry_at
        timestamptz exit_at
        text vendor_entry_id "출차 매칭 1순위 키"
        text vendor_entry_time "업체 원문 YYYYMMDDHHMMSS"
    }
    parking_events {
        bigint id PK
        bigint site_id FK
        text kind "enter / exit"
        text plate
        timestamptz occurred_at
        text vendor_entry_id
        text gate_id
        jsonb raw "업체 원본 행"
        text dedupe_key UK "site:table:pk:version"
        text status "new / processed / ignored / failed"
        int attempts
    }
    ct_cursors {
        bigint site_id PK
        text table_name PK "enter / exit"
        bigint last_version "마지막 처리 버전"
        text last_vendor_time
    }
    parking_time_allocations {
        bigint id PK
        bigint site_id FK
        bigint host_id FK
        date month "해당 월 1일, 없는 달은 이전 값"
        numeric monthly_limit_hours
        numeric daily_limit_hours
    }

erDiagram
    hosts ||--o{ signup_tickets : "세대 인증 후 발급"
    hosts ||--o{ registration_tickets : "세대"
    accounts ||--o{ registration_tickets : "차량 검사 후 발급"
    hosts ||--o{ pending_host_updates : "정보 변경 요청"
    accounts |o--o{ user_agreements : "약관 동의 (증빙 보존)"
    sites ||--o{ history_disable_periods : "기록 비활성화"
    sites |o--o{ admin_users : "단지 범위 관리자"
    admin_users |o--o{ audit_logs : "변경 기록"
    admin_users |o--o{ pending_host_updates : "승인 · 거절"

    signup_tickets {
        bigint id PK
        bigint host_id FK
        text ip "같은 IP에서만 소진"
        timestamptz expires_at "10분"
        timestamptz used_at
    }
    registration_tickets {
        bigint id PK
        bigint host_id FK
        bigint account_id FK
        text plate
        timestamptz expires_at "30분"
        timestamptz used_at
    }
    pending_host_updates {
        bigint id PK
        bigint site_id FK
        bigint host_id FK
        text requested_by
        text resident_name
        text resident_phone
        text status "pending / approved / rejected"
        bigint decided_by FK
    }
    user_agreements {
        bigint id PK
        bigint site_id FK
        bigint account_id FK "탈퇴 시 null"
        text login_id "증빙용 보존"
        text service_terms_version
        text privacy_policy_version
    }
    history_disable_periods {
        bigint id PK
        bigint site_id FK
        date start_date
        date end_date
        boolean is_active
    }
    admin_users {
        bigint id PK
        text login_id UK
        text scope "super / site"
        bigint site_id FK "site 범위일 때만"
        int token_version "올리면 기존 토큰 폐기"
    }
    audit_logs {
        bigint id PK
        bigint admin_user_id FK
        text admin_login_id
        bigint site_id FK
        text action "host.create 등"
        jsonb summary "개인정보 제외"
    }

flowchart LR
    subgraph Dev["개발"]
        D1["작업 브랜치"] --> D2["구현 + 테스트 작성"]
        D2 --> D3["flutter analyze<br/>flutter test"]
    end
    subgraph CI["GitHub Actions"]
        C1["push · PR마다<br/>analyze + test"]
    end
    subgraph Release["릴리스"]
        R1["main 병합"] --> R2["빌드 번호 올리기"]
        R2 --> R3["에뮬레이터 · 실기기 확인"]
        R3 --> A1["flutter build appbundle"] --> A2["Google Play<br/>프로덕션 검토 → 출시"]
        R3 --> I1["flutter build ipa"] --> I2["App Store Connect<br/>TestFlight → 심사 → 출시"]
    end
    subgraph Ops["운영"]
        O1["새 단지 추가"] --> O2["Remote Config sites 수정"] --> O3["앱 재배포 없이 반영"]
    end
    D3 --> C1 --> R1

flowchart LR
    Dev["개발 Mac<br/>개발 · 테스트"] -- "git push" --> Git[("GitHub private")]
    Git -- "git pull · 배포 브랜치" --> Site
    subgraph Site["단지 운영 PC · Docker Compose"]
        Migrate["migrate (일회성)"] --> Srv["server"]
        Prx["proxy · Caddy<br/>Let's Encrypt"] --> Srv
        Prx --> Adm["admin"]
        Adm --> Srv
        Srv --> PG[("db")]
    end
    Router["공유기<br/>80 · 443 포워딩, DDNS"] --> Prx
    Srv -- "단지 내부망" --> VDB[("업체 DB")]