勤怠端末（Hikvision）
用途: 物理的な勤怠端末（例: Hikvision DS-K1T342/343）を HRM に接続し、アプリ以外の打刻を勤怠表へ自動反映します。
メニュー: システム設定 → 勤怠端末
権限:
| 権限 | 内容 |
|---|---|
| ATTENDANCE_DEVICE_VIEW | 端末一覧・詳細・イベント・同期スケジュールの閲覧 |
| ATTENDANCE_DEVICE_MANAGE | 端末の追加/編集/停止、従業員紐付け、接続確認、同期、スケジュール保存 |
対応端末
Hikvision 端末（DS-K1T342/343 および ISAPI 互換機）に対応。各端末は HRM 上の 支店（オフィス） に紐付けます。
接続方式（2種類）
| UI 表示 | 技術値 | 動作 | 選択目安 |
|---|---|---|---|
| 直接接続 | DIRECT | システムが LAN 上の端末 IP に ISAPI で接続し、勤怠イベントを取得 | 端末とサーバーが同一ネットワーク |
| 端末自動送信 | PUSH | 打刻時に端末が HTTP Listening 経由でサーバーへイベントを送信 | サーバーから直接接続できない、または端末から HTTP 送信可能 |
端末自動送信と ISAPI による追加取得
2つの経路は 独立 しており、両方必須ではありません。
| 経路 | 必須? | 説明 |
|---|---|---|
| HTTP Listening（端末自動送信） | PUSH 端末では必須 | 打刻時に /api/d/e/<token> へイベントを POST |
| ISAPI による追加取得 | 任意 | ログイン情報保存時、サーバーが ISAPI で追加取得 — 直接接続または端末自動送信 |
注意: 端末自動送信を追加したら、ホスト名 / URL / ポート / プロ トコル を端末の HTTP Listening に設定します。URL は バックエンドポート（多くは :3001）を指し、Web UI の :3000 ではありません。
勤怠として扱うイベント
認証成功（major 5 — 入退室管理）かつ端末ユーザー ID があるイベントのみ取り込みます。
| 打刻種別 | イベント minor |
|---|---|
| カード | 38 |
| 顔 | 75 |
| 指紋 | 113 |
その他（ドア開放、認証失敗など）は保存または無視されますが、勤怠表には書き込まれません。
自動同期スケジュール
勤怠端末 画面上部の 自動同期スケジュール:
| 項目 | 既定 | 意味 |
|---|---|---|
| 通常同期間隔 | 5 分 | 勤務時間外の取得間隔 |
| 勤務時間前後の同期間隔 | 1 分 | 出勤/退勤前後の取得間隔 |
| 高速同期の時間帯 | ±30 分 | 短い間隔を適用する前後の時間 |
勤務時間は システム設定 → 勤務時間 から取得（パネル内リンク）。
自動同期の対象:
- 直接接続 端末（常に ISAPI で取得）。
- 端末自動送信 で ISAPI 認証情報を保存した端末（追加取得）。
ISAPI なしの端末自動送信も HTTP Listening で打刻を受信できます。
端末の追加
- システム設定 → 勤怠端末 → 端末を追加。
- 直接接続 または 端末自動送信、名称・IP・支店を入力。
- 直接接続: ISAPI のユーザー名/パスワード。
- 端末自動送信: 作成後に HTTP Listening 設定を端末へコピー。トークンは一度だけ表示 — すぐ保存。
期待結果: 一覧に表示され、イベント受信または同期成功後 オンライン になります。
詳細ダイアログ
| タブ | 内容 |
|---|---|
| 概要 | 接続状態、同期、送信接続確認 / 今すぐ同期 |
| 設定 | 名称・支店、ISAPI 認証情報、トークン再生成（端末自動送信） |
| 従業員紐付け | 端末ユーザー ID → HRM 従業員 |
| 勤怠イベント | 打刻ログ（ページング、処理状態） |
| 照合 | 直接接続のみ — 端末ユーザーとシステム上の紐付けを比較 |
接続確認と同期
| 操作 | 目的 | 勤怠へ書き込み? |
|---|---|---|
| 送信接続確認（端末自動送信） | データ受信 URL、ホスト名、受信イベント、保留イベントの確認 | いいえ — 読み取りのみ |
| 接続確認（直接接続） | ISAPI 接続テスト | いいえ |
| 今すぐ同期 | ISAPI 追加取得（設定時）、取り込み、保留イベントの処理 | はい（本番書き込み有効時） |
結果は行ごと（緑/黄/赤）に表示。必要時は URL をコピーできます。
従業員紐付け
打刻ごとに 端末ユーザー ID（例: 251）が送られます。
- 自動: 従業員コード または HRM 従業員 ID と一致 → イベント処理時に紐付けを作成。
- 手動: 従業員紐付け タブで追加。
未紐付けのイベントは 保存 されますが勤怠表には反映されません。紐付け後は 今すぐ同期 で保留イベントを再処理してください。
イベント処理
イベント受信（HTTP Listening または ISAPI）
→ 保存（sourceEventId による技術的冪等性 + 同一分の業務集約）
→ 従業員紐付けの解決
→ 勤怠表へ書き込み（許可時）
イベント状態（勤怠イベントタブ）
| UI 表示 | 技術値 | 意味 |
|---|---|---|
| 保留 | PENDING | 受信済み、未処理（再試行可） |
| テストモード | SHADOW | 試験処理済み、勤怠表未書き込み（テストモードまたは未紐付け） |
| 処理済み | PROCESSED | 勤怠表へ書き込み成功 |
| 処理失敗 | FAILED | 処理エラー |
| 無視 | IGNORED | 勤怠イベントではない |
重複イベント（2 層）
| 層 | ルール | 目的 |
|---|---|---|
| 技術的冪等性 | 同一 (device_id, source_event_id) | プロバイダ再送 |
| 業務集約 | 同一端末 + 同一端末ユーザー + 同一ベトナム暦の分 | UI/勤怠ノイズ低減 — 1 分あたり 1 件 |
同一分内に複数回（顔・カード・指紋など）打刻しても 1 件 として保持します。詳細は 技術付録。
テストモード（シャドウ）
IT がテストモードを有効にしている間、イベントは保存されても 勤怠表は更新されない 場合があります。勤怠イベント タブにデータがあるのに勤怠表が空 → IT に ATTENDANCE_DEVICE_SHADOW_MODE / ATTENDANCE_DEVICE_WRITE_TO_ATTENDANCE を確認。詳細: 技術付録。
勤怠表への書き込み
本番書き込み有効時:
- その日 最初 の打刻 → 出勤。
- 最後 の打刻 → 退勤。
- アプリ打刻と統合: 最早出勤、最遅退勤。
- 端末の 支店 が勤怠オフィスとして使用 — アプリの GPS/WiFi チェックは 適用されません。
- 同一ベトナム暦の分内の複数打刻（同一ユーザー・同一端末）は UI/勤怠用に 1 件 に集約。詳細: 技術付録。
端末の停止
UI の削除は 停止（ソフト削除） です。稼働一覧から非表示、ingest トークン無効化、イベント履歴は監査のため保持。既に書き込んだ勤怠データは削除されません。
トラブルシューティング
| 現象 | 対処 |
|---|---|
| 端末自動送信: イベントなし | HTTP Listening、正しいバックエンド URL、テスト打刻 |
ホスト名が localhost | IT が PUBLIC_SITE_ORIGIN を設定し、トークン再生成 |
| ISAPI 401 | 設定 タブで認証情報を修正 |
| イベントはあるが勤怠なし | 従業員紐付け、テストモード、今すぐ同期 |
| 顔 OK、カード/指紋 NG | 勤怠イベント タブでイベント種別確認、端末設定、今すぐ同期 |
| 接続確認後も保留イベントあり | 正常 — 今すぐ同期 を使用（確認エラーではない） |
| 直接接続をより速く | 自動同期スケジュール と 勤務時間 を調整 |