HBSA230_Secom Sync (지문 동기화 소스)
(Hereby) 시스템 관리 > [[HBSA200]] > Secom Sync
| 앱 | System Admin (포트 4100) |
| 부모 화면 | [[HBSA200]] |
| 대상 사용자 | 플랫폼 운영자(OPERATOR) |
| 프로토타입 | TBU |
| 관련 정책 | [[POL_권한(RBAC)]] |
| Status | draft (코드 기반 — 라이브 실사 불가: dev 라우트 AccessDenied 격리, 2026-08-25 확인) |
| Owner | 카나 |
개요
Secom 지문 게이트웨이 데이터를 조직별로 끌어오는 동기화 소스를 관리한다. 소스 생성 시 secom-puller 서비스가 다음 cron tick부터 자동 pull을 시작한다. secom_sync_state는 엔티티 없이 API 내부 raw query로 다뤄지며(design), 콘솔은 fan-out 조회 + 단일-org mutation.
문서 히스토리
| 날짜 | 작성자 | 팀 | 변경 내용 |
|---|---|---|---|
| 2026-08-25 | 카나 | 콸 | 최초 작성 (redesign PR #583 코드 census 기반, 라이브 미실사) |
Data I/O
Client → Server
| 액션 | 콘솔 REST | systemProcedure |
|---|---|---|
| 목록 | GET /api/secom-sync (fan-out) | systemSecomSyncStates |
| 생성 | POST /api/secom-sync | systemCreateSecomSyncState |
| ON/OFF | PUT /api/secom-sync/:sourceKey | systemToggleSecomSyncState |
| 커서 초기화 | POST .../reset-cursor | systemResetSecomSyncCursor |
| 삭제 | DELETE .../:sourceKey | systemDeleteSecomSyncState |
Server → Client
| 변수 | 소스 | 비고 |
|---|---|---|
secomSyncStates[] | systemSecomSyncStates | sourceKey/schemaName/organization/enabled/lastGatewayCreatedAt/lastRunAt/lastPulledCount/totalEvents |
코드 근거: tabs/secom-sync.html, server/routes/secom-sync.ts.
화면 플로우
메인 사양표
| 번호 | 항목/기능명 | 타입 | 사양 및 기능 설명 | 연관/영향 범위 | 비고 |
|---|---|---|---|---|---|
| 00 | 화면 진입 조건 | - | activeTab === 'secom-sync' | - | |
| 01 | 초기 상태 | Output | "Sources: {n}" + "refresh" + "+ Add Source" | - | |
| 10 | 소스 테이블 | List | [List] 컬럼 source key/schema/organization/enabled/last cursor/last run/last pulled/total events/actions | secomSyncStates | source key=orange |
| 11 | ㄴ enabled | Toggle | ON=green/OFF=gray 배지 클릭 → toggleSecomSync(key, !enabled) | systemToggleSecomSyncState | |
| 12 | ㄴ reset | Button | "reset"(yellow) → ask "커서를 초기화하시겠습니까?\n모든 데이터를 처음부터 다시 가져옵니다." → resetSecomCursor() | systemResetSecomSyncCursor | danger tone |
| 13 | ㄴ delete | Button | "delete"(red) → ask "이 소스를 삭제하시겠습니까?" → deleteSecomSync() | systemDeleteSecomSyncState | |
| 10-E | ㄴ Empty | Text | "No sync sources configured. Add one to start pulling Secom fingerprint data." | - | |
| 20 | 값 없음 처리 | - | organization 없으면 "—", lastRunAt 없으면 "never", cursor 없으면 "—" | - | |
| 30 | 에러·실패 | - | 로드 실패 tabError. 중복 sourceKey 409, 없는 키 404 | - |
서브 화면 / 모달 사양표
Add Secom Sync Source 모달
| 번호 | 항목/기능명 | 타입 | 사양 및 기능 설명 | 연관/영향 범위 | 비고 |
|---|---|---|---|---|---|
| 00 | 노출 조건 | - | showSecomSyncForm. 타이틀 "Add Secom Sync Source" | openSecomSyncForm() | |
| 10 | SOURCE KEY | Input Box | "SOURCE KEY *"(placeholder "bestrh") 안내 "고유 식별자 (예: 병원 코드 소문자)" | secomSyncForm.sourceKey | |
| 20 | SCHEMA | Input Box | "GATEWAY SCHEMA NAME *"(placeholder "bestrh_secom") 안내 "Gateway DB의 스키마명 (Secom Manager가 쓰는 스키마)" | schemaName | |
| 30 | ORGANIZATION | Dropdown | "선택..." + 전 조직(name (code)) | organizationId | 필수 |
| 40 | 생성 후 안내 | Info | "생성 후:" · "enabled=true, cursor=1970-01-01 (epoch)로 초기화" · "secom-puller 서비스가 다음 cron tick에서 자동으로 데이터 가져오기 시작" · "Gateway DB 연결 정보는 .env의 GATEWAY_DB_* 환경변수에서 읽음" | - | |
| 50 | 제출 | Button | "Create" → createSecomSync(). 진행 중 "creating...". 에러 red 배너(secomSyncFormError) | systemCreateSecomSyncState |
권한 / 상태 요약
| 시나리오 | 트리거 | 결과 | 비고 |
|---|---|---|---|
case01 [생성] | Create | enabled·epoch cursor로 소스 등록 | audit |
case02 [중복 key] | 기존 sourceKey | 409 | |
case03 [reset] | 확인 | 처음부터 재수집 | 파괴적 |
OQ
- Gateway DB 접속·puller cron 주기 상세 = 콘솔 UI 범위 밖(.env), TBU