295 lines
9.1 KiB
Markdown
295 lines
9.1 KiB
Markdown
# History / As-Of DB Plan
|
|
|
|
## Goal
|
|
|
|
월간 스냅샷 파일을 따로 만드는 대신, DB 자체를 시간축이 있는 구조로 전환한다.
|
|
목표는 다음과 같다.
|
|
|
|
- 조직도와 자리배치도를 수정할 때마다 과거 값이 사라지지 않게 누적 저장
|
|
- 사용자가 특정 날짜 또는 기간을 선택하면 그 시점 기준 상태를 다시 조회
|
|
- 날짜가 원래 없는 데이터도 `유효 시작일`과 `유효 종료일`을 부여해 과거 버전 조회 가능하게 만들기
|
|
|
|
핵심 원칙은 아래 한 줄이다.
|
|
|
|
- 최신 값을 덮어쓰지 않고, `valid_from`, `valid_to` 기반 버전 행을 누적한다
|
|
|
|
## Why This Instead Of Snapshots
|
|
|
|
- 월간 스냅샷 파일은 생성 시점만 남고 중간 변경 추적이 약하다
|
|
- 원하는 날짜 기준으로 바로 조회하기 어렵다
|
|
- 조직도만 따로 파일로 남으면 자리배치도, 권한, 운영 이력을 함께 맞추기 어렵다
|
|
|
|
따라서 이 프로젝트에는 "파일 스냅샷"보다 "시점 조회 가능한 버전 DB"가 더 맞다.
|
|
|
|
## Query Model
|
|
|
|
조회 기준은 `as_of` 또는 `date_from`, `date_to` 이다.
|
|
|
|
- 특정 날짜 조회:
|
|
- `GET /api/members?as_of=2026-03-01`
|
|
- `GET /api/seat-maps/active/layout?as_of=2026-03-01`
|
|
- 기간 비교:
|
|
- `GET /api/history/organization/compare?date_from=2026-03-01&date_to=2026-03-31`
|
|
|
|
공통 조회 조건은 아래다.
|
|
|
|
```sql
|
|
WHERE valid_from <= :as_of
|
|
AND (valid_to IS NULL OR valid_to > :as_of)
|
|
```
|
|
|
|
## Recommended Data Model
|
|
|
|
### 1. Stable Base Tables
|
|
|
|
식별자와 최소 메타만 유지하는 기준 테이블.
|
|
|
|
```sql
|
|
CREATE TABLE members (
|
|
id SERIAL PRIMARY KEY,
|
|
employee_id TEXT,
|
|
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
|
);
|
|
```
|
|
|
|
```sql
|
|
CREATE TABLE seat_assignment_targets (
|
|
member_id INTEGER PRIMARY KEY REFERENCES members(id) ON DELETE CASCADE,
|
|
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
|
);
|
|
```
|
|
|
|
설명:
|
|
- `members` 는 "사람 자체" 식별자 역할
|
|
- 실제 이름, 조직, 직급, 연락처, 좌석 같은 표시 데이터는 버전 테이블로 이동
|
|
|
|
### 2. Member Version Table
|
|
|
|
```sql
|
|
CREATE TABLE member_versions (
|
|
id BIGSERIAL PRIMARY KEY,
|
|
member_id INTEGER NOT NULL REFERENCES members(id) ON DELETE CASCADE,
|
|
name TEXT NOT NULL,
|
|
company TEXT NOT NULL DEFAULT '',
|
|
rank TEXT NOT NULL DEFAULT '',
|
|
role TEXT NOT NULL DEFAULT '',
|
|
department TEXT NOT NULL DEFAULT '',
|
|
grp TEXT NOT NULL DEFAULT '',
|
|
division TEXT NOT NULL DEFAULT '',
|
|
team TEXT NOT NULL DEFAULT '',
|
|
cell TEXT NOT NULL DEFAULT '',
|
|
work_status TEXT NOT NULL DEFAULT '',
|
|
work_time TEXT NOT NULL DEFAULT '',
|
|
phone TEXT NOT NULL DEFAULT '',
|
|
email TEXT NOT NULL DEFAULT '',
|
|
photo_url TEXT NOT NULL DEFAULT '',
|
|
valid_from TIMESTAMPTZ NOT NULL,
|
|
valid_to TIMESTAMPTZ,
|
|
revision_no BIGINT NOT NULL,
|
|
changed_by_user_id BIGINT,
|
|
change_reason TEXT NOT NULL DEFAULT '',
|
|
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
|
);
|
|
|
|
CREATE INDEX member_versions_member_time_idx
|
|
ON member_versions (member_id, valid_from, valid_to);
|
|
```
|
|
|
|
설명:
|
|
- 날짜가 원래 없던 조직도 데이터도 이 테이블에서 과거 버전 관리
|
|
- 어떤 시점에 이름, 조직, 직책, 연락처가 어땠는지 재구성 가능
|
|
|
|
### 3. Seat Assignment Version Table
|
|
|
|
```sql
|
|
CREATE TABLE seat_assignment_versions (
|
|
id BIGSERIAL PRIMARY KEY,
|
|
member_id INTEGER NOT NULL REFERENCES members(id) ON DELETE CASCADE,
|
|
seat_map_id INTEGER REFERENCES seat_maps(id) ON DELETE CASCADE,
|
|
seat_slot_id INTEGER REFERENCES seat_slots(id) ON DELETE CASCADE,
|
|
seat_label TEXT NOT NULL DEFAULT '',
|
|
valid_from TIMESTAMPTZ NOT NULL,
|
|
valid_to TIMESTAMPTZ,
|
|
revision_no BIGINT NOT NULL,
|
|
changed_by_user_id BIGINT,
|
|
change_reason TEXT NOT NULL DEFAULT '',
|
|
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
|
);
|
|
|
|
CREATE INDEX seat_assignment_versions_member_time_idx
|
|
ON seat_assignment_versions (member_id, valid_from, valid_to);
|
|
```
|
|
|
|
설명:
|
|
- 현재 `seat_positions` 가 맡는 "최신 좌석 상태"를 버전형으로 저장
|
|
- 특정 날짜의 자리배치도를 다시 그릴 수 있음
|
|
|
|
### 4. Optional Change Event Table
|
|
|
|
```sql
|
|
CREATE TABLE entity_change_events (
|
|
id BIGSERIAL PRIMARY KEY,
|
|
entity_type TEXT NOT NULL,
|
|
entity_id BIGINT NOT NULL,
|
|
action_type TEXT NOT NULL,
|
|
revision_no BIGINT NOT NULL,
|
|
changed_by_user_id BIGINT,
|
|
changed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
|
change_reason TEXT NOT NULL DEFAULT '',
|
|
patch_json JSONB NOT NULL DEFAULT '{}'::jsonb
|
|
);
|
|
```
|
|
|
|
설명:
|
|
- 버전 테이블은 "그 시점의 전체 값"
|
|
- 이벤트 테이블은 "무엇이 바뀌었는지"
|
|
- 초기에는 없어도 되지만, 추후 비교 UI와 감사로그에 유용
|
|
|
|
### 5. Revision Table
|
|
|
|
```sql
|
|
CREATE TABLE history_revisions (
|
|
id BIGSERIAL PRIMARY KEY,
|
|
scope TEXT NOT NULL DEFAULT 'organization',
|
|
revision_label TEXT NOT NULL,
|
|
created_by_user_id BIGINT,
|
|
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
|
note TEXT NOT NULL DEFAULT ''
|
|
);
|
|
```
|
|
|
|
설명:
|
|
- 버전 묶음을 사람 친화적으로 관리할 때 사용
|
|
- 예: `2026-03-27 1차 조직개편 반영`
|
|
|
|
## How Writes Change
|
|
|
|
현재 구조:
|
|
- `UPDATE members SET ...`
|
|
- `UPSERT seat_positions ...`
|
|
|
|
바꿀 구조:
|
|
1. 현재 유효한 버전 행을 조회
|
|
2. 값이 달라지면 기존 행의 `valid_to` 를 닫음
|
|
3. 새 값을 가진 행을 `valid_from = now()` 로 insert
|
|
4. 필요하면 최신 캐시 테이블도 함께 갱신
|
|
|
|
예시:
|
|
|
|
```sql
|
|
UPDATE member_versions
|
|
SET valid_to = NOW()
|
|
WHERE member_id = :member_id
|
|
AND valid_to IS NULL;
|
|
|
|
INSERT INTO member_versions (
|
|
member_id, name, company, rank, role, department, grp, division, team, cell,
|
|
work_status, work_time, phone, email, photo_url,
|
|
valid_from, valid_to, revision_no, changed_by_user_id, change_reason
|
|
)
|
|
VALUES (
|
|
:member_id, :name, :company, :rank, :role, :department, :grp, :division, :team, :cell,
|
|
:work_status, :work_time, :phone, :email, :photo_url,
|
|
NOW(), NULL, :revision_no, :changed_by_user_id, :change_reason
|
|
);
|
|
```
|
|
|
|
## How Date-Bearing And Date-Less Data Coexist
|
|
|
|
### 날짜가 원래 있는 데이터
|
|
|
|
- `integration_work_logs.work_date`
|
|
- `integration_vouchers.issue_date`
|
|
|
|
이 데이터는 원래 날짜 컬럼이 있으므로 그대로 사용하면 된다.
|
|
|
|
### 날짜가 원래 없는 데이터
|
|
|
|
- 조직도 인원 기본 정보
|
|
- 조직 소속
|
|
- 자리배치 상태
|
|
- 사진 경로
|
|
|
|
이 데이터는 `valid_from`, `valid_to` 를 붙여 시점 조회가 가능하게 만든다.
|
|
|
|
즉, "날짜가 없는 데이터"가 아니라 "유효기간을 부여한 버전 데이터"로 바꾸는 것이다.
|
|
|
|
## API Direction
|
|
|
|
### Common UI Input
|
|
|
|
사용자가 실제 HTML에서 고르는 기준은 헤더의 날짜 제어를 공통 입력으로 쓰는 것이 맞다.
|
|
|
|
권장안:
|
|
- 프로젝트/팀 분석: 기존처럼 `시작일 ~ 종료일`
|
|
- 조직도/자리배치도: 우선 `기준일(as_of)` 1개를 사용
|
|
- 필요하면 조직도 비교 화면에서 `비교 시작일`, `비교 종료일` 확장
|
|
|
|
현재 상태:
|
|
- 헤더 날짜 제어는 `프로젝트별 분석`, `팀/개인별 분석` iframe에 이미 전달되고 있음
|
|
- 조직도/자리배치도는 아직 헤더 날짜를 실제 조회 조건으로 사용하지 않음
|
|
|
|
권장 API:
|
|
|
|
```text
|
|
GET /api/members?as_of=2026-03-27
|
|
GET /api/members/{id}?as_of=2026-03-27
|
|
GET /api/seat-maps/active/layout?as_of=2026-03-27
|
|
GET /api/history/organization/compare?date_from=2026-03-01&date_to=2026-03-31
|
|
```
|
|
|
|
## Migration Strategy
|
|
|
|
### Phase 1. History Tables Add
|
|
|
|
- `member_versions`
|
|
- `seat_assignment_versions`
|
|
- `history_revisions`
|
|
- 필요 시 `entity_change_events`
|
|
|
|
현재 `members`, `seat_positions` 는 그대로 유지
|
|
|
|
### Phase 2. Backfill
|
|
|
|
- 현재 `members` 최신값을 `member_versions(valid_from = NOW(), valid_to = NULL)` 로 적재
|
|
- 현재 `seat_positions` 최신값을 `seat_assignment_versions(valid_from = NOW(), valid_to = NULL)` 로 적재
|
|
- 이 단계에서는 과거 진짜 이력은 없고 "현재 상태를 버전 구조에 싣는 것"이 목표
|
|
|
|
### Phase 3. Dual Write
|
|
|
|
- 조직도 수정 시:
|
|
- 기존 `members` 갱신
|
|
- 동시에 `member_versions` 에 append
|
|
- 자리배치 저장 시:
|
|
- 기존 `seat_positions` 갱신
|
|
- 동시에 `seat_assignment_versions` 에 append
|
|
|
|
### Phase 4. As-Of Read APIs
|
|
|
|
- 조직도 API에 `as_of` 지원
|
|
- 자리배치도 API에 `as_of` 지원
|
|
- 헤더 날짜 제어와 연결
|
|
|
|
### Phase 5. Full History-First Read
|
|
|
|
- 최신 조회도 버전 테이블 기준으로 전환
|
|
- `members`, `seat_positions` 는 캐시 또는 편의 테이블로 축소 가능
|
|
|
|
## Recommended First Scope
|
|
|
|
처음부터 모든 테이블을 이력화하지 말고 아래부터 시작하는 것이 안전하다.
|
|
|
|
1. `members` -> `member_versions`
|
|
2. `seat_positions` -> `seat_assignment_versions`
|
|
3. 조직도/자리배치도 조회 API에 `as_of`
|
|
|
|
이 세 가지가 되면 사용자는 원하는 날짜의 조직 상태와 좌석 상태를 볼 수 있다.
|
|
|
|
## Explicitly Removed From Scope
|
|
|
|
- 월간 스냅샷 파일 생성
|
|
- 스냅샷 다운로드 기능
|
|
- 조직도만 따로 파일로 내보내는 방식
|
|
|
|
이 프로젝트의 방향은 "파일 스냅샷"이 아니라 "시점 조회 가능한 버전 DB"다.
|