Designing an Audit Trail for Attendance Edits Without Overwriting Source Events

인사책 — Thu, 15 Oct 2026 02:25:19 +0000

An attendance correction looks like a simple update:

UPDATE attendance_records
SET clock_out_at = '2026-10-15T18:04:00+09:00'
WHERE id = 8412;

That query fixes the current row, but it also destroys the answer to several questions: What was recorded first? Who requested the correction? What evidence supported it? Who approved it? Which value was used for payroll before the change?

For systems that affect pay, deleting that context is a design problem. A safer model treats the original clock event as immutable and records corrections as a separate, reviewable trail.

Start with two different kinds of truth

Attendance software usually contains at least two truths:

Observed truth: the raw event produced by a device, browser, QR scan, or administrator import.
Operational truth: the approved interpretation used for schedules, overtime, and payroll.

Those values can disagree without either being useless. A raw 18:47 clock-out may be genuine, while an approved 18:00 work end may reflect an employee who forgot to clock out after changing clothes. The system should preserve both facts instead of rewriting one into the other.

In Korean workplaces, teams often search for these tools as 출퇴근기록기 (clock-in recorder) or 근태관리기 (attendance management tool). Whatever label the product uses, the important architectural question is the same: does a correction replace evidence, or does it add a decision to the evidence?

Model source events as append-only data

A source event should identify where it came from and when the server received it. Device time alone is not enough because a phone clock can be wrong or an offline client may synchronize later.

CREATE TABLE attendance_events (
  id                BIGSERIAL PRIMARY KEY,
  employee_id       BIGINT NOT NULL,
  event_type        TEXT NOT NULL CHECK (event_type IN ('clock_in', 'clock_out')),
  occurred_at       TIMESTAMPTZ NOT NULL,
  received_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
  source_type       TEXT NOT NULL,
  source_reference  TEXT,
  payload_hash      TEXT NOT NULL,
  created_at        TIMESTAMPTZ NOT NULL DEFAULT now()
);

The application role that inserts these rows should not have permission to update or delete them. Retention and privacy rules may eventually require controlled deletion, but that should be a separate administrative process rather than an ordinary edit endpoint.

Put corrections in their own workflow

A correction request is not another clock event. It is a proposal to interpret one or more source events differently.

CREATE TABLE attendance_corrections (
  id                  BIGSERIAL PRIMARY KEY,
  employee_id         BIGINT NOT NULL,
  work_date           DATE NOT NULL,
  requested_clock_in  TIMESTAMPTZ,
  requested_clock_out TIMESTAMPTZ,
  reason_code         TEXT NOT NULL,
  reason_detail       TEXT,
  requested_by        BIGINT NOT NULL,
  requested_at        TIMESTAMPTZ NOT NULL DEFAULT now(),
  status              TEXT NOT NULL CHECK (status IN ('pending', 'approved', 'rejected', 'cancelled')),
  decided_by          BIGINT,
  decided_at          TIMESTAMPTZ,
  decision_note       TEXT
);

The correction should reference the affected source events through a join table. This matters when one workday has duplicate scans, a missing clock-out, or a shift that crosses midnight.

Build the effective record instead of mutating it

Read models can combine raw events with the latest approved correction. The calculation can live in a database view, a materialized projection, or an application service.

effective attendance
  = original source events
  + latest approved correction
  + policy version used for interpretation

Keeping the policy version is important. A record calculated under a 30-minute break rule should not silently change when the company later adopts a 45-minute rule.

For a practical example of the employee-facing recording flow, this attendance record management guide is useful context. The implementation detail to preserve is the boundary between captured events and later administrative decisions.

Make state transitions explicit

Do not let clients set any status they want. Define legal transitions in one domain function:

type Status = "pending" | "approved" | "rejected" | "cancelled";

const allowed: Record<Status, Status[]> = {
  pending: ["approved", "rejected", "cancelled"],
  approved: [],
  rejected: [],
  cancelled: [],
};

export function canTransition(from: Status, to: Status): boolean {
  return allowed[from].includes(to);
}

If an approved correction is wrong, create a new correction that supersedes it. Reopening and editing the old decision makes the audit trail ambiguous.

Protect the workflow from concurrency bugs

Two managers can open the same pending request and approve different values. Use optimistic locking or a conditional update:

UPDATE attendance_corrections
SET status = 'approved',
    decided_by = $1,
    decided_at = now()
WHERE id = $2
  AND status = 'pending';

The update must affect exactly one row. A zero-row result means the request was already handled and the client should refresh instead of pretending the approval succeeded.

For payroll export, store a snapshot identifier or cutoff time. Otherwise, an approval that arrives during export can create a file that cannot be reproduced later.

Log business meaning, not just HTTP requests

An infrastructure log saying PATCH /attendance/8412 200 is not enough. Emit a domain event with the decision context:

{
  "event": "attendance_correction_approved",
  "correction_id": 392,
  "employee_id": 117,
  "work_date": "2026-10-15",
  "previous_effective_clock_out": "2026-10-15T18:47:12+09:00",
  "new_effective_clock_out": "2026-10-15T18:00:00+09:00",
  "reason_code": "forgot_to_clock_out",
  "decided_by": 42,
  "policy_version": "attendance-policy-2026-09"
}

Avoid copying free-form notes, precise location data, or device identifiers into every analytics system. The audit store can retain necessary evidence with stricter access controls, while downstream events carry only the fields needed for operations.

Test invariants, not only endpoints

The most valuable tests assert properties that must remain true across refactors:

A source event cannot be updated through the normal application role.
A pending correction can be decided only once.
A rejected correction never changes the effective attendance record.
An approved correction does not erase the referenced source events.
Payroll export can be reproduced from a recorded cutoff and policy version.
A manager cannot approve a correction outside the manager's authorized team.

Property-based tests are particularly useful around overnight shifts, duplicate events, daylight-saving transitions, and late offline synchronization.

A small implementation checklist

Before shipping an attendance correction feature, verify that the system can answer these questions without reading application logs by hand:

What did the employee or device originally submit?
When did the server receive it?
What replacement value was requested, and why?
Who approved or rejected the request?
Which policy version produced the payable result?
Which version was included in a specific payroll export?

If any answer disappears after an edit, the design is still overwriting history.

The goal is not to implement event sourcing everywhere. It is to preserve the few boundaries that matter: observations remain observations, decisions remain decisions, and payroll results remain reproducible. That separation makes corrections easier to explain, safer to authorize, and much less painful to debug.

근태 데이터에서 월말 오류를 줄이는 4가지 검증 규칙

인사책 — Wed, 16 Sep 2026 07:00:56 +0000

근태 관리는 단순히 출근과 퇴근 시간을 저장하는 기능으로 끝나지 않습니다. 월말에 확인해야 할 것은 누가 몇 시간을 일했는가뿐 아니라, 수정이 왜 발생했는지와 어떤 기준으로 확정됐는지입니다. 이 글은 근태 데이터를 다루는 개발·운영 팀이 오류를 줄이기 위해 적용할 수 있는 검증 규칙을 정리한 메모입니다.

1. 원본 이벤트와 수정 요청을 덮어쓰지 않습니다

출근 기록을 수정할 때 기존 시간을 바로 바꾸면, 나중에 오류의 원인을 되짚기 어렵습니다. 원본 이벤트와 수정 이벤트를 별도로 남기고, 어떤 기록이 현재 유효한지 상태값으로 판단하는 편이 안전합니다.

수정 요청에는 요청 사유, 요청 시각, 승인자, 승인 결과를 별도 필드로 둡니다. 이렇게 하면 시간값 하나를 고치는 일이 아니라, 검토 가능한 변경 이력을 만드는 일이 됩니다.

2. 예외를 정상 흐름과 분리합니다

지각, 외근, 교육, 누락, 휴가처럼 근태에 영향을 주는 예외는 정상 출퇴근 이벤트와 같은 방식으로 처리하면 집계가 흔들립니다. 예외 유형과 증빙 여부, 승인 상태를 분리하면 월말에 확인할 대상이 훨씬 선명해집니다.

예를 들어 missing_check_in, remote_work, leave, manual_correction처럼 상태를 구분하고, 자동 집계 전에 미승인 예외만 모아 검토하는 방식이 좋습니다.

3. 주 단위 집계를 월말보다 먼저 확인합니다

월말에 한 번에 오류를 찾으면 수정 범위가 커집니다. 주 단위로 근무시간, 휴게시간, 연장근로 가능성을 확인하면 데이터 문제와 운영 문제를 일찍 분리할 수 있습니다. 한국의 근무시간 한도와 월말 점검 항목은 인사책의 주 52시간 근무시간 계산 가이드처럼 제도 기준과 기록 검증 절차를 함께 보는 것이 실무적입니다.

4. 확정 결과에는 승인 근거를 남깁니다

집계가 끝났다고 해서 데이터가 설명 가능한 상태가 되는 것은 아닙니다. 담당자가 왜 이 시간이 확정됐는가를 질문받았을 때 원본 이벤트, 수정 요청, 승인 이력을 순서대로 확인할 수 있어야 합니다.

이 규칙은 규모가 작은 팀에서도 유용합니다. 처음부터 복잡한 시스템을 만들기보다, 변경을 덮어쓰지 않고 예외를 분리하며 주 단위 검토를 반복하는 것만으로도 월말 확인 비용을 줄일 수 있습니다.

실제 운영 흐름에 맞춰 출퇴근 기록과 예외 처리 기준을 정리하려는 팀은 인사책 출퇴근 기록 관리 안내에서 기본 기능과 적용 방식을 확인할 수 있습니다.

기록의 정확성은 더 많은 입력 화면보다, 나중에 설명할 수 있는 검증 흐름에서 나옵니다.

DEV Community: 인사책