세콤 지문인식기 연동 설치 가이드

세콤(S-One) 지문인식 출입통제 시스템을 hereby 플랫폼 근태 관리와 연동하는 설치 가이드입니다.

플랫폼 버전: v1.0.0 대상: 시스템 관리자, IT 담당자

연동 개요

연동 흐름:

세콤 단말기가 지문/카드 인식 이벤트를 세콤 매니저로 전송
세콤 매니저가 ODBC 연결을 통해 secom_events 테이블에 실시간 삽입
hereby 백그라운드 잡이 pending 이벤트를 읽어 근태 레코드 생성/업데이트

동기화 지연: 일반적으로 1~2분

사전 요구사항

항목	요구사항
OS	Windows 10/11 또는 Windows Server 2019+
세콤 매니저	Secom Manager (근태·식당) — Secom Link 기능 지원 버전
PostgreSQL ODBC 드라이버	psqlodbc 17.00.0007 (32비트)
네트워크	세콤 PC → hereby DB 서버 TCP/5432 개방
DB 서버	PostgreSQL 16 (hereby 플랫폼 기본 구성)

Step 1: DB 계정 및 IP 권한 설정

세콤 매니저는 전용 PostgreSQL 계정(hereby_secom)을 통해서만 DB에 접근합니다. 이 계정은 secom_events 테이블에 INSERT만 허용되며, 허가된 IP에서만 연결 가능합니다.

1-1. 마이그레이션 실행 (역할 생성)

마이그레이션이 hereby_secom PostgreSQL 역할을 생성합니다:

bash

make db-migrate

적용 확인:

bash

pnpm --filter @hereby/database typeorm migration:show -d src/config/data-source.ts
# [X] AddSecomDbRole1773401000000  ← 체크되어 있어야 합니다

1-2. 클라이언트별 계정 프로비저닝

프로비저닝 스크립트로 비밀번호 설정과 IP 허용 설정을 한 번에 처리합니다:

bash

make provision-secom \
  CLIENT=CLINIC01 \
  PASSWORD='Secom@2024!' \
  SECOM_IP=192.168.1.50/32

파라미터	설명
`CLIENT`	클라이언트 코드 (식별용, 예: CLINIC01)
`PASSWORD`	`hereby_secom` 계정 비밀번호
`SECOM_IP`	세콤 PC의 IP 주소 (CIDR 표기, 예: `192.168.1.50/32`)
`PG_HBA`	(선택) `pg_hba.conf` 경로 — 지정 시 자동 추가
`DRY_RUN=true`	(선택) 실제 실행 없이 적용 내용만 출력

1-3. pg_hba.conf 설정

스크립트가 다음 형식의 pg_hba.conf 항목을 출력합니다:

# Secom fingerprint integration — client: CLINIC01
hostssl  hereby_platform  hereby_secom  192.168.1.50/32  scram-sha-256

Docker 환경에서 적용하는 방법:

bash

# postgres 컨테이너 접속
docker exec -it hereby-postgres bash

# pg_hba.conf에 항목 추가
echo "# Secom fingerprint — client: CLINIC01" >> /var/lib/postgresql/data/pg_hba.conf
echo "hostssl  hereby_platform  hereby_secom  192.168.1.50/32  scram-sha-256" \
  >> /var/lib/postgresql/data/pg_hba.conf

# 설정 리로드
psql -U hereby_admin -d hereby_platform -c "SELECT pg_reload_conf();"

1-4. 권한 검증

bash

# secom 계정으로 INSERT 테스트
PGPASSWORD='Secom@2024!' psql \
  -h localhost -p 5432 \
  -U hereby_secom -d hereby_platform \
  -c "INSERT INTO hereby.secom_events (
        id, event_datetime, terminal_id, employee_number,
        organization_id, "createdAt", "updatedAt"
      ) VALUES (
        gen_random_uuid(), now(), 'TEST-01', '99999',
        '<조직-UUID>', now(), now()
      );"
# INSERT 0 1 이 출력되면 정상

# SELECT 시도 — 반드시 실패해야 합니다
PGPASSWORD='Secom@2024!' psql \
  -h localhost -p 5432 \
  -U hereby_secom -d hereby_platform \
  -c "SELECT * FROM hereby.secom_events LIMIT 1;"
# ERROR: permission denied for table secom_events  ← 정상

계정 보안 원칙

hereby_secom 계정은 secom_events INSERT 전용입니다. SELECT/UPDATE/DELETE 불가
세콤 PC IP 외의 주소에서는 연결 자체가 거부됩니다 (pg_hba.conf)
비밀번호는 버전 관리에 포함하지 않습니다 (스크립트가 런타임에 설정)
세콤 PC 교체 시: 새 IP로 스크립트 재실행 후 기존 pg_hba 항목 삭제

Step 2: PostgreSQL ODBC 드라이버 설치

1-1. 드라이버 다운로드 및 설치

PostgreSQL ODBC 공식 페이지에서 psqlodbc_17_x86.msi (32비트 버전)를 다운로드합니다
psqlodbc-setup.exe를 실행하여 설치합니다
설치 완료 후 재부팅은 불필요합니다

32비트 버전 필수

세콤 매니저는 32비트 ODBC를 사용합니다. 반드시 32비트(x86) 버전을 설치하세요.

1-2. 시스템 DSN 구성

시작 메뉴 → ODBC 데이터 원본(32비트) 검색 후 실행
INFO
64비트 Windows에서 32비트 ODBC 관리자는 C:\Windows\SysWOW64\odbcad32.exe에 있습니다.
시스템 DSN 탭 → 추가 버튼 클릭
드라이버 목록에서 PostgreSQL Unicode 선택 → 마침
다음 정보를 입력합니다:

항목	값
Data Source	`hereby`
Description	(선택사항) Hereby Platform
Database	`hereby_platform`
Server	`<hereby DB 서버 IP>`
Port	`5432`
User Name	`hereby_admin`
Password	`<DB 비밀번호>`
SSL Mode	`require`

테스트 버튼 클릭 → "연결에 성공하였습니다" 확인
저장 버튼 클릭

SSL 인증서 오류 발생 시

SSL 오류가 발생하면 SSL Mode를 prefer로 변경하거나, AWS RDS CA 인증서를 시스템에 설치하세요.

Step 2: hereby DB 마이그레이션 실행

세콤 이벤트를 저장할 secom_events 테이블을 생성합니다.

bash

# hereby 플랫폼 서버에서 실행
make db-migrate

마이그레이션 확인:

bash

pnpm --filter @hereby/database typeorm migration:show -d src/config/data-source.ts

[X] AddSecomEventTable1773400000000 항목이 체크되어 있어야 합니다.

secom_events 테이블 구조

컬럼	타입	설명
`id`	UUID	기본키
`event_datetime`	TIMESTAMPTZ	지문 인식 시각
`terminal_id`	VARCHAR(100)	단말기 ID
`card_number`	VARCHAR(100)	카드/사원증 번호
`employee_number`	VARCHAR(100)	세콤 사원번호 (hereby 사원번호와 매핑)
`employee_name`	VARCHAR(200)	세콤에 등록된 직원 이름
`raw_event_type`	VARCHAR(50)	세콤 원본 이벤트 코드 (예: "1"=입, "2"=출)
`auth_type`	VARCHAR(50)	인증 방법 (지문, 카드, PIN 등)
`ack_mode`	VARCHAR(50)	세콤 응답 모드
`ack_time`	TIMESTAMPTZ	세콤 응답 시각
`raw_data`	JSONB	원본 전체 페이로드
`event_type`	ENUM	정규화된 방향 (check_in / check_out / unknown)
`status`	ENUM	처리 상태 (pending / processed / error / ignored)
`error_message`	TEXT	오류 시 상세 메시지
`processed_at`	TIMESTAMPTZ	근태 레코드 생성 시각
`organization_id`	UUID	소속 조직
`employee_id`	UUID	매핑된 직원 (처리 후 채워짐)
`attendance_id`	UUID	생성된 근태 레코드 ID
`createdAt`	TIMESTAMPTZ	레코드 생성 시각
`updatedAt`	TIMESTAMPTZ	마지막 수정 시각
`origin`	VARCHAR(32)	기록 출처 — `gateway`(세콤 수집, 기본값) / `system_admin`(System Admin 콘솔이 넣은 임의·테스트 기록) / `api`(조직 API ingest). 게이트웨이 미러 열이 아니라 내부 열이라 puller 는 쓰지 않습니다
`originHistory`	JSONB	System Admin 이 넣거나 고치거나 삭제한 이력(append-only, action created/updated/deleted) — 운영자 id·요청 id·시각·사유·변경 전/후. 게이트웨이 기록은 NULL
`deletedAt`	TIMESTAMP	게이트웨이 미러 열이지만 System Admin 의 「삭제」도 여기에 찍습니다(소프트 삭제, status=ignored). 처리기·재계산은 `deletedAt IS NULL` 만 봅니다

System Admin 콘솔의 「지문 기록 관리」가 넣은 기록도 이 표에 들어가고 같은 처리기로 근태가 됩니다. 실제 수집 기록과 구분하려면 origin 으로 거르세요. 자세한 것은 시스템 관리자 도구 › 지문 기록 관리.

Step 3: 세콤 매니저 ERP 설정

3-1. Secom Link 설정 열기

세콤 매니저 실행
파일 → ERP 설정 → Secom Link 클릭

3-2. 연결 설정

항목	값
Provider	`ODBC`
DSN	`hereby`
사용자 ID	`hereby_admin`
비밀번호	`<DB 비밀번호>`

3-3. 쿼리 설정

소스 쿼리 (세콤 DB에서 읽기):

sql

SELECT
  CONVERT(VARCHAR, EventDate, 120) AS event_datetime,
  TerminalID                        AS terminal_id,
  AckMode                           AS ack_mode,
  CONVERT(VARCHAR, AckTime, 120)    AS ack_time,
  CardNo                            AS card_number,
  EmpID                             AS secom_employee_id,
  EmpName                           AS employee_name,
  EmpNo                             AS employee_number,
  EventType                         AS raw_event_type,
  AuthType                          AS auth_type
FROM Alarm
WHERE EventDate >= @StartDate
  AND EventDate <= @EndDate

타겟 쿼리 (hereby DB에 삽입):

sql

INSERT INTO hereby.secom_events (
  id,
  event_datetime,
  terminal_id,
  ack_mode,
  ack_time,
  card_number,
  employee_number,
  employee_name,
  raw_event_type,
  auth_type,
  organization_id,
  "createdAt",
  "updatedAt"
) VALUES (
  gen_random_uuid(),
  @event_datetime,
  @terminal_id,
  @ack_mode,
  @ack_time,
  @card_number,
  @employee_number,
  @employee_name,
  @raw_event_type,
  @auth_type,
  '<조직 UUID>',  -- hereby 관리자 패널에서 확인
  NOW(),
  NOW()
)

조직 UUID 확인 방법

hereby 관리자 패널 → 설정 → 조직 정보에서 UUID를 확인하거나, DB에서 다음 쿼리로 조회합니다:

sql

SELECT id, name FROM hereby.organizations WHERE code = 'CLINIC01';

Step 4: 직원 번호 매핑

세콤의 사원번호가 hereby의 employeeNumber와 일치해야 합니다.

4-1. hereby 사원번호 확인

관리자 패널 → 직원 관리 → 각 직원의 사원번호 컬럼을 확인합니다.

또는 DB에서 직접 확인:

sql

SELECT employee_number, name, email
FROM hereby.employees
WHERE "deletedAt" IS NULL
ORDER BY employee_number;

4-2. 세콤 매니저 직원 매핑

세콤 매니저 → 등록 관리 → 직원 관리
각 직원의 기본 정보 항목에서 Flex 사원번호 필드에 hereby 사원번호를 입력합니다
hereby 사원번호와 정확히 일치하도록 입력합니다

주의

사원번호 매핑이 잘못되면 다른 직원의 근태 기록이 합산될 수 있습니다. 반드시 검증 후 적용하세요.

Step 5: 활성화 및 테스트

5-1. 동기화 테스트

테스트 직원이 지문인식기를 사용합니다
1~2분 후 DB에서 이벤트 수신을 확인합니다:

sql

SELECT
  employee_number,
  employee_name,
  event_datetime,
  raw_event_type,
  event_type,
  status
FROM hereby.secom_events
ORDER BY "createdAt" DESC
LIMIT 10;

status = 'pending' 레코드가 생성되어 있으면 정상입니다
처리 잡이 실행되면 status = 'processed'로 변경되고 근태 레코드가 생성됩니다

5-2. 처리 현황 모니터링

sql

-- 상태별 이벤트 건수
SELECT status, COUNT(*) AS count
FROM hereby.secom_events
WHERE "deletedAt" IS NULL
GROUP BY status;

-- 오류 이벤트 확인
SELECT employee_number, event_datetime, error_message
FROM hereby.secom_events
WHERE status = 'error'
  AND "deletedAt" IS NULL
ORDER BY event_datetime DESC
LIMIT 20;

-- 최근 24시간 처리 현황
SELECT
  DATE_TRUNC('hour', event_datetime) AS hour,
  COUNT(*) FILTER (WHERE status = 'processed') AS processed,
  COUNT(*) FILTER (WHERE status = 'error')     AS errors,
  COUNT(*) FILTER (WHERE status = 'pending')   AS pending
FROM hereby.secom_events
WHERE event_datetime >= NOW() - INTERVAL '24 hours'
GROUP BY 1
ORDER BY 1;

운영 참고사항

데이터 처리 기준

상황	처리 방법
20시간 이전 이벤트	자동 처리됨 (단, 수동 확인 권장)
14일 초과 이벤트	hereby 관리자 패널에서 수동 근태 일괄 업로드 필요
중복 이벤트	`ignored` 상태로 처리

세콤 PC 관리

세콤 PC는 항상 켜져 있어야 합니다 (절전 모드 비활성화)
안정적인 인터넷 연결 필수
네트워크 단절 시 세콤 매니저에서 날짜 범위 지정 후 수동 재전송 가능: 파일 → ERP 설정 → Secom Link → 날짜 범위 지정 → 실행

다중 사업장 구성

단일 사업장, 복수 법인: 각 법인별로 별도 organization_id 필요
복수 사업장, 별도 세콤 시스템: 사업장별 세콤 PC와 계정 필요, 동일 secom_events 테이블에 organization_id로 구분하여 삽입

문제 해결

ODBC 연결 실패

[ERROR] Data source name not found

→ 시스템 DSN 이름이 hereby인지 확인 (대소문자 구분) → 32비트 ODBC 관리자에서 설정했는지 확인 (SysWOW64\odbcad32.exe)

SSL 오류

[ERROR] SSL connection required

→ ODBC 설정에서 SSL Mode를 require 또는 prefer로 설정 → DB 서버에서 해당 IP의 SSL 연결이 허용되어 있는지 확인 (pg_hba.conf)

이벤트가 pending 상태로 유지될 때

→ 처리 잡이 실행 중인지 API 서버 로그 확인 → employee_number 매핑이 올바른지 확인:

sql

-- 매핑되지 않은 사원번호 목록
SELECT DISTINCT s.employee_number
FROM hereby.secom_events s
LEFT JOIN hereby.employees e ON e.employee_number = s.employee_number
WHERE e.id IS NULL AND s."deletedAt" IS NULL;

세콤 지문인식기 연동 설치 가이드 ​

연동 개요 ​

사전 요구사항 ​

Step 1: DB 계정 및 IP 권한 설정 ​

1-1. 마이그레이션 실행 (역할 생성) ​

1-2. 클라이언트별 계정 프로비저닝 ​

1-3. pg_hba.conf 설정 ​

1-4. 권한 검증 ​

Step 2: PostgreSQL ODBC 드라이버 설치 ​

1-1. 드라이버 다운로드 및 설치 ​

1-2. 시스템 DSN 구성 ​

Step 2: hereby DB 마이그레이션 실행 ​

secom_events 테이블 구조 ​

Step 3: 세콤 매니저 ERP 설정 ​

3-1. Secom Link 설정 열기 ​

3-2. 연결 설정 ​

3-3. 쿼리 설정 ​

Step 4: 직원 번호 매핑 ​

4-1. hereby 사원번호 확인 ​

4-2. 세콤 매니저 직원 매핑 ​

Step 5: 활성화 및 테스트 ​

5-1. 동기화 테스트 ​

5-2. 처리 현황 모니터링 ​

운영 참고사항 ​

데이터 처리 기준 ​

세콤 PC 관리 ​

다중 사업장 구성 ​

문제 해결 ​

ODBC 연결 실패 ​

SSL 오류 ​

이벤트가 pending 상태로 유지될 때 ​

세콤 지문인식기 연동 설치 가이드

연동 개요

사전 요구사항

Step 1: DB 계정 및 IP 권한 설정

1-1. 마이그레이션 실행 (역할 생성)

1-2. 클라이언트별 계정 프로비저닝

1-3. pg_hba.conf 설정

1-4. 권한 검증

Step 2: PostgreSQL ODBC 드라이버 설치

1-1. 드라이버 다운로드 및 설치

1-2. 시스템 DSN 구성

Step 2: hereby DB 마이그레이션 실행

secom_events 테이블 구조

Step 3: 세콤 매니저 ERP 설정

3-1. Secom Link 설정 열기

3-2. 연결 설정

3-3. 쿼리 설정

Step 4: 직원 번호 매핑

4-1. hereby 사원번호 확인

4-2. 세콤 매니저 직원 매핑

Step 5: 활성화 및 테스트

5-1. 동기화 테스트

5-2. 처리 현황 모니터링

운영 참고사항

데이터 처리 기준

세콤 PC 관리

다중 사업장 구성

문제 해결

ODBC 연결 실패

SSL 오류

이벤트가 pending 상태로 유지될 때