문서 생성 초안의 PostgreSQL JSONB 저장 관련 #67

krestar · 2026-07-29T11:40:16Z

krestar
Jul 29, 2026
Maintainer

문서 자동 생성을 위한 PostgreSQL JSONB 저장 전략

1. 목적

회사·근로자·계약 등 기존 관계형 데이터를 바탕으로 HWP/HWPX 문서에 필요한 값을 자동 입력하고, 사용자가 누락값을 보완한 뒤 최종 문서를 생성한다.

문서 양식마다 입력 필드와 구조가 달라 가변 데이터를 저장할 방법이 필요하다.

검토한 선택지는 다음과 같다.

별도 NoSQL 데이터베이스 도입
기존 PostgreSQL의 JSONB 활용

최종적으로 별도 NoSQL을 추가하지 않고, 문서별 가변 입력값을 PostgreSQL JSONB에 저장한다.

2. 최종 결정

PostgreSQL을 계속 System of Record로 사용한다.

관계형 데이터는 기존 테이블에 유지하고, 특정 문서에 입력할 값만 JSONB Snapshot으로 저장한다.

관계형 업무 데이터
→ Canonical Document Values 생성
→ PostgreSQL JSONB Draft 저장
→ 사용자 보완·수정
→ AI Document API 호출
→ HWP/HWPX 생성

JSONB는 관계형 데이터를 대체하지 않는다.

다음 정보는 기존 관계형 모델을 유지한다.

회사
근로자
계약
Task
사용자
권한
파일 Metadata

JSONB에는 문서에 입력할 구조화된 값만 저장한다.

3. 구현 범위

필수 범위

PostgreSQL JSONB Draft
고정된 문서 양식
Canonical Field
관계형 데이터 Projection
Draft 생성·조회·수정
양식별 입력 Form
낙관적 잠금
AI Document API 동기 호출
HWP 또는 HWPX 생성
생성 파일 다운로드
기본 Tenant 권한 검증

추가 범위

필수 흐름이 완성된 이후 다음 중 우선순위가 높은 항목을 추가한다.

동일 양식의 다른 출력 형식
두 번째 문서 양식
양식별 체크박스·표 처리
사진·서명 등 Asset 입력

확장 범위

다음 기능은 현재 범위에 포함하지 않는다.

MongoDB 등 별도 NoSQL
런타임 Template 등록
관리자 Template Activation
Template Rollback
복잡한 Version Lifecycle
범용 Dynamic Form
AI Suggestion 상태 관리
비동기 Generation Worker
Outbox 기반 문서 생성
Lease·Fence
JSONB 내부 검색
GIN Index
실제 개인정보 운영

4. 여러 문서 양식 지원

시스템 구조는 여러 문서 양식을 지원한다.

다만 사용자가 실행 중인 시스템에 새 양식을 등록하는 범용 Template Platform은 구현하지 않는다.

지원할 양식은 개발 시점에 확정된 고정 양식으로 관리한다.

현재 사용 가능한 Template Key 예시는 다음과 같다.

identity_guaranty_v129
employment_extension_application_v12_3
immigration_integrated_application_v34
standard_labor_contract_v6

각 양식은 독립적인 template_key를 가진다.

양식별로 HWP와 HWPX의 입력 필드 또는 지원 기능이 실질적으로 다르면 별도 Variant Key로 분리할 수 있다.

standard_labor_contract_v6_hwp
standard_labor_contract_v6_hwpx

동일한 Canonical Values로 두 형식을 모두 생성할 수 있다면 하나의 template_key와 supported_formats를 사용한다.

5. 복수 양식 지원 방식

복수 양식은 다음 구조로 지원한다.

양식별 정적 Contract JSON
+ document_generation_draft 테이블 하나
+ 공통 Draft API
+ 양식별 Frontend Form
+ 양식별 AI Renderer

양식을 추가할 때는 다음 작업을 수행한다.

Server에 양식 Contract JSON 추가
Server Projection Mapping 추가
Frontend에 양식 전용 Form 추가
AI에 HWP/HWPX Renderer Mapping 추가
해당 조합의 통합 테스트 추가

양식마다 새로운 Draft 테이블이나 API를 만들지 않는다.

6. Canonical Document Values

Server Domain Field, HWP 내부 Field, HWPX Label을 동일한 Key로 사용하지 않는다.

문서 Draft에는 Server와 AI가 공통으로 사용하는 Canonical Field를 저장한다.

예:

Server Domain Field:
employmentContract.monthlyWage

Canonical Field:
contract.monthly_wage

HWP Internal Field:
monthly_wage

HWPX Target:
월 통상임금 셀

데이터 흐름:

Server Domain Data
→ Canonical Document Values
→ AI Renderer
→ HWP/HWPX 내부 Mapping

JSONB에는 다음을 저장하지 않는다.

HWP 내부 Field 위치
HWPX 셀 좌표
문서에 표시되는 한국어 Label
Renderer 전용 Mapping 정보

예시:

{
  "employer": {
    "company_name": "주식회사 한빛정밀",
    "representative_name": "김민수"
  },
  "worker": {
    "legal_name": "NGUYEN VAN AN",
    "nationality": "베트남"
  },
  "contract": {
    "start_date": "2026-08-01",
    "end_date": "2027-07-31",
    "monthly_wage": 3000000,
    "accommodation_provided": true
  }
}

7. 양식 Contract 관리

양식 Contract는 데이터베이스 테이블이 아니라 Git으로 관리되는 정적 JSON 파일로 둔다.

예상 위치:

src/main/resources/document-contracts/
├─ identity_guaranty_v129_schema_1.json
├─ employment_extension_application_v12_3_schema_1.json
├─ immigration_integrated_application_v34_schema_1.json
└─ standard_labor_contract_v6_schema_1.json

예시:

{
  "template_key": "standard_labor_contract_v6",
  "schema_version": "1",
  "display_name": "표준근로계약서",
  "supported_formats": [
    "hwp",
    "hwpx"
  ],
  "fields": {
    "employer.company_name": {
      "type": "string",
      "editable": true,
      "required": true,
      "max_length": 200
    },
    "worker.legal_name": {
      "type": "string",
      "editable": false,
      "required": true,
      "max_length": 120
    },
    "contract.monthly_wage": {
      "type": "integer",
      "editable": true,
      "required": true,
      "minimum": 0
    },
    "contract.accommodation_provided": {
      "type": "boolean",
      "editable": true,
      "required": false
    }
  }
}

Contract는 다음 정보만 포함한다.

Template Key
Schema Version
표시 이름
지원 출력 형식
허용 Field
기본 타입
수정 가능 여부
필수 여부
간단한 길이·범위 제한
필요한 경우 Format별 Capability

범용 JSON Schema 전체를 구현하지 않는다.

8. Contract Version 관리

배포된 Contract 파일은 불변으로 취급한다.

배포된 Schema Version의 내용을 수정하지 않는다.
Schema가 변경되면 새로운 Version 파일을 추가한다.
기존 Draft가 참조하는 Contract 파일은 삭제하지 않는다.

예:

standard_labor_contract_v6_schema_1.json
standard_labor_contract_v6_schema_2.json

Draft에는 생성 당시의 다음 값을 저장한다.

template_key
schema_version

현재 운영에서는 최신 Version 하나만 사용하더라도, 과거 Draft를 해석할 수 있도록 기존 Contract 파일을 보존한다.

Template Activation, Rollback, Digest 조합과 별도 Lifecycle 테이블은 만들지 않는다.

9. Server와 AI의 책임

Server

Server는 다음을 담당한다.

사용자·회사 권한 검증
Task와 근로자 조회
관계형 데이터 Projection
Contract 로딩
JSONB Draft 저장
허용 Field와 기본 타입 검증
읽기 전용 Field 보호
낙관적 잠금
AI Document API 호출

AI Document Service

AI Document Service는 다음을 담당한다.

Canonical Values 수신
Template Key 확인
HWP/HWPX 내부 Mapping
체크박스·표 처리
문서 생성
Renderer 오류 반환
생성 파일 반환

AI는 Server의 PostgreSQL에 직접 접근하지 않는다.

Frontend

Frontend는 다음을 담당한다.

지원 양식 선택
양식 전용 Form 표시
읽기 전용·수정 가능 Field 구분
Draft 조회·저장
Version 충돌 안내
문서 생성 요청
생성 파일 다운로드

범용 Dynamic Form은 구현하지 않는다.

10. 데이터 모델

신규 테이블은 document_generation_draft 하나만 추가한다.

document_generation_draft

draft_id UUID PK
company_id UUID NOT NULL
task_id UUID NOT NULL

template_key VARCHAR NOT NULL
schema_version VARCHAR NOT NULL

values_json JSONB NOT NULL

created_by UUID NOT NULL
updated_by UUID NOT NULL

version BIGINT NOT NULL

created_at TIMESTAMPTZ NOT NULL
updated_at TIMESTAMPTZ NOT NULL

`template_key`

사용한 문서 양식을 식별한다.

정적 Contract JSON의 template_key와 일치해야 한다.

`schema_version`

Draft 생성 당시 사용한 Contract Version이다.

`values_json`

문서에 입력할 전체 Canonical Values Snapshot이다.

`version`

JPA @Version 낙관적 잠금에 사용한다.

하나의 Task에서 같은 양식을 여러 번 작성할 수 있으므로 다음 Unique Constraint는 만들지 않는다.

UNIQUE(company_id, task_id, template_key)

11. 기존 Draft와 분리

기존 document_request_draft는 근로자에게 제출을 요청할 문서 종류, 언어와 안내 메시지를 저장한다.

새 document_generation_draft는 HWP/HWPX 양식에 실제로 입력할 값을 저장한다.

document_request_draft
→ 어떤 문서를 제출하도록 요청할지 관리

document_generation_draft
→ 특정 문서에 어떤 값을 입력할지 관리

목적과 생명주기가 다르므로 별도 Aggregate로 유지한다.

12. Draft 생성 API

POST /api/v1/document-generation-drafts

요청:

{
  "task_id": "uuid",
  "template_key": "standard_labor_contract_v6"
}

처리 순서:

1. 사용자·회사 권한 검증
2. Task와 관계형 데이터 조회
3. Template Contract 로딩
4. Contract에 정의된 Canonical Field만 Projection
5. Draft 저장
6. 생성된 Draft 반환

Projection은 Contract Allow-list를 기준으로 명시적으로 수행한다.

Contract에 정의된 Field만 관계형 데이터에서 Projection한다.
예상하지 못한 Projection Field는 조용히 제거하지 않는다.
개발·테스트 단계에서 계약 오류로 처리한다.

응답 예:

{
  "draft_id": "uuid",
  "task_id": "uuid",
  "template_key": "standard_labor_contract_v6",
  "schema_version": "1",
  "version": 0,
  "values": {
    "employer": {
      "company_name": "주식회사 한빛정밀"
    },
    "worker": {
      "legal_name": "NGUYEN VAN AN"
    },
    "contract": {
      "monthly_wage": 3000000
    }
  },
  "missing_fields": [
    "contract.start_date",
    "contract.end_date"
  ]
}

Idempotency-Key와 Request Fingerprint는 구현하지 않는다.

Frontend는 요청 진행 중 생성 버튼을 비활성화해 중복 클릭을 줄인다.

13. Draft 조회 API

GET /api/v1/document-generation-drafts/{draftId}

Server는 다음을 확인한다.

Draft 존재
사용자의 회사와 Draft의 회사 일치
Task 접근 권한
해당 Template Contract Version 존재

응답에는 다음을 포함한다.

Draft ID
Task ID
Template Key
Schema Version
현재 Values
Version
무조건 필수인 누락 Field
생성·수정 시각

14. Draft 수정 API

PUT /api/v1/document-generation-drafts/{draftId}

요청:

{
  "expected_version": 2,
  "values": {
    "employer": {
      "company_name": "한빛정밀 제2사업장"
    },
    "worker": {
      "legal_name": "NGUYEN VAN AN"
    },
    "contract": {
      "start_date": "2026-08-01",
      "end_date": "2027-07-31",
      "monthly_wage": 3200000
    }
  }
}

Client는 전체 Draft Snapshot을 전송한다.

읽기 전용 Field도 반드시 포함해야 한다.

읽기 전용 Field 규칙

현재 Draft에 존재하는 읽기 전용 Field는 요청에도 존재해야 한다.
읽기 전용 Field가 누락되면 요청을 거부한다.
기존 저장값과 다른 값이 전달되면 요청을 거부한다.
Server가 요청마다 관계형 원본을 다시 Projection하지 않는다.

처리 순서:

1. Draft와 권한 조회
2. expected_version 확인
3. 전체 Snapshot 구조 검증
4. 읽기 전용 Field 존재 여부 확인
5. 읽기 전용 Field의 기존 값 유지 확인
6. 수정 가능 Field 타입·범위 검증
7. values_json 전체 교체
8. Version 증가
9. 최신 Draft 반환

오류 예:

DOCUMENT_FIELD_REQUIRED_IN_SNAPSHOT
DOCUMENT_FIELD_NOT_EDITABLE
DOCUMENT_FIELD_NOT_ALLOWED
DOCUMENT_FIELD_TYPE_MISMATCH
DOCUMENT_DRAFT_VERSION_CONFLICT

필수값이 누락돼도 Draft 저장은 허용한다.

15. 낙관적 잠금

Draft에는 JPA @Version을 사용한다.

사용자 A가 Version 2 조회
사용자 B가 Version 2를 Version 3으로 저장
사용자 A가 Version 2로 저장
→ 409 DOCUMENT_DRAFT_VERSION_CONFLICT

자동 Merge는 구현하지 않는다.

Frontend는 충돌 시 다음과 같이 안내한다.

다른 사용자가 문서를 수정했습니다.
최신 내용을 확인한 뒤 다시 저장해 주세요.

낙관적 잠금은 별도 분산 인프라 없이 전체 문서가 묵시적으로 덮어써지는 문제를 방지하므로 유지한다.

16. 입력 검증

Server 검증 범위는 다음으로 제한한다.

존재하는 Template Key
존재하는 Schema Version
허용된 Canonical Field
String
Integer
Number
Boolean
문자열 최대 길이
숫자 최소·최대
사용자 수정 가능 여부
Payload 최대 크기
Tenant와 Task 권한

지원하지 않는 검증:

범용 JSON Schema Keyword
복잡한 조건부 Required
Field 간 계산식
범용 Object Array Schema
HWP/HWPX 렌더링 가능성

missing_fields는 무조건 필수인 Field만 계산한다.

missing_fields가 비어 있음
≠ 최종 문서 생성 성공 보장

조건부 Field와 실제 Renderer 제약은 문서 생성 단계에서 AI Document Service가 확인한다.

17. Object와 Array 지원 범위

JSONB에는 중첩 Object를 저장할 수 있다.

범용 Object Array 검증 시스템은 구현하지 않는다.

중첩 Object
→ 지원

Scalar Array
→ 필요한 양식에 한해 지원 가능

Object Array
→ 범용 지원하지 않음

특정 문서에 Object Array가 반드시 필요하다면 해당 배열 한 종류만 양식 전용 검증 코드로 처리한다.

양식에 실제 배열 요구가 없다면 Array 관련 구현과 완료 기준을 추가하지 않는다.

18. 문서 생성 API

POST /api/v1/document-generation-drafts/{draftId}/generate

요청:

{
  "output_format": "hwp"
}

처리 순서:

1. 짧은 Transaction에서 Draft·권한·Template 조회
2. 필수값과 지원 Format 검증
3. AI 요청에 필요한 값을 DTO로 복사
4. Transaction 종료
5. AI Document API 동기 호출
6. 생성 파일 반환

외부 AI 호출을 기다리는 동안 DB Transaction을 유지하지 않는다.

잘못된 구조:

DB Transaction 시작
→ AI API 호출 대기
→ 파일 생성
→ Transaction 종료

AI HTTP Client에는 다음 Timeout을 설정한다.

Connection Timeout
Response 또는 Read Timeout
전체 문서 생성 제한시간

AI 요청 예:

{
  "template_id": "standard_labor_contract_v6",
  "format": "hwp",
  "values": {
    "employer": {
      "company_name": "주식회사 한빛정밀"
    },
    "worker": {
      "legal_name": "NGUYEN VAN AN"
    },
    "contract": {
      "monthly_wage": 3200000
    }
  }
}

다음 문제가 실제로 확인될 때만 비동기 Generation을 검토한다.

HTTP Timeout 빈발
다수 동시 요청
실패 재시도 필요
서버 재시작 후 작업 복구 필요

19. HWP와 HWPX 지원

각 양식과 출력 Format 조합을 독립적으로 검증한다.

예:

표준근로계약서
├─ HWP
└─ HWPX

통합신청서
├─ HWP
└─ HWPX

양식 Contract의 supported_formats에 지원 여부를 기록한다.

HWP와 HWPX의 필드 구조가 다르면 별도 Template Key를 사용한다.

같은 Canonical Values 사용
→ 하나의 template_key + supported_formats

필요 Field 또는 기능이 다름
→ 별도 template_key

Format별 Capability가 필요하면 Contract에 간단히 기록한다.

{
  "capabilities": {
    "hwp": {
      "photo": true,
      "signature": true
    },
    "hwpx": {
      "photo": false,
      "signature": false
    }
  }
}

별도 Renderer Manifest나 Capability Revision 시스템은 만들지 않는다.

20. 직접 편집된 HWP/HWPX

생성된 HWP/HWPX는 JSONB Draft에서 만들어진 파생 산출물이다.

사용자가 생성 파일을 직접 열어 수정할 수는 있지만, 해당 변경을 JSONB Draft로 역동기화하지 않는다.

JSONB Draft
→ 문서 생성
→ 사용자가 파일 직접 수정
→ 최종 산출물로 취급
→ JSONB에는 반영하지 않음

수정된 파일을 재업로드해 값을 역추출하는 기능은 구현하지 않는다.

21. 개인정보

현재는 가상 데이터를 사용한다.

사용 가능한 예:

가상 회사명
가상 근로자명
가상 주소
가상 계약 조건
테스트 전화번호

사용하지 않는 정보:

실제 외국인등록번호
실제 여권번호
실제 계좌번호
실제 서명
실제 신분증 사진

실제 개인정보를 적용할 때는 별도로 다음을 결정해야 한다.

암호화
접근 권한
AI 전달 범위
보존기간
삭제 정책
생성 문서 보호

22. JSONB Index

현재는 JSONB 내부 Field 검색을 지원하지 않는다.

Draft는 다음 관계형 컬럼으로 조회한다.

draft_id
company_id
task_id
template_key
schema_version
created_at
updated_at

GIN Index는 추가하지 않는다.

실제 JSON 내부 검색 요구가 생긴 뒤 Query와 PostgreSQL 실행계획을 기준으로 추가한다.

23. 테스트

Contract 테스트

실제 Template Key 로딩
Template Key와 파일 이름 일치
Schema Version 로딩
배포된 Version 파일 불변 보존
허용 Field
수정 가능 여부
지원 Format

Draft 테스트

지원 양식별 Draft 생성
관계형 데이터 Projection
예상하지 못한 Projection Field 차단
JSONB 저장·조회
전체 Snapshot PUT
읽기 전용 Field 누락 차단
읽기 전용 Field 변경 차단
필수값 누락 상태 저장
잘못된 타입 차단
Unknown Field 차단
낙관적 잠금 충돌
Tenant 접근 차단

문서 생성 테스트

Draft 조회 Transaction과 AI 호출 분리
HWP 생성
HWPX 생성
지원하지 않는 Format 차단
필수값 누락 차단
AI API Timeout
AI API 오류 응답
정상 파일 다운로드
직접 편집된 파일의 JSONB 비동기화

PostgreSQL 통합 테스트

실제 JSONB Column
JPA JSONB Mapping
Flyway Migration
중첩 Object 저장
@Version
Tenant-aware FK

24. 인수 기준

필수 완료

대표 양식 하나에 대해 다음 수직 흐름이 동작해야 한다.

관계형 데이터 조회
→ Canonical Projection
→ JSONB Draft 생성
→ 사용자 수정
→ Draft 저장
→ HWP 생성
→ 파일 다운로드

추가 완료

다음 중 하나 이상을 추가한다.

동일 양식의 HWPX
두 번째 양식의 HWP
사진·서명 등 추가 Capability

확장 완료

복수 양식의 HWP/HWPX 조합
추가 양식별 Form
추가 Renderer Mapping

시스템 구조는 복수 양식을 지원하지만, 모든 양식·포맷 조합의 완성을 필수 인수 조건으로 두지 않는다.

25. 완료 기준

26. 최종 결론

문서별 입력 구조가 달라도 핵심 업무 데이터가 PostgreSQL에 존재하므로, 별도 NoSQL을 도입하지 않는다.

최종 구조는 다음과 같다.

Version별 정적 Contract JSON
+ document_generation_draft 테이블 하나
+ Canonical Document Values
+ 공통 Draft API
+ 양식별 Frontend Form
+ 양식별 AI Renderer

여러 문서 양식 지원은 유지한다.

다만 다음과 같은 Template 운영 플랫폼 기능은 구현하지 않는다.

런타임 Template 등록
복잡한 Lifecycle
관리자 Activation
자동 Rollback
범용 Dynamic Form
분산 Generation Worker

우선 대표 양식 하나의 전체 수직 흐름을 완성하고, 같은 구조를 재사용해 HWPX와 추가 양식을 순차적으로 확장한다.

Navigation Menu

Uh oh!

문서 생성 초안의 PostgreSQL JSONB 저장 관련 #67

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Uh oh!

문서 생성 초안의 PostgreSQL JSONB 저장 관련 #67

Uh oh!

krestar Jul 29, 2026 Maintainer

문서 자동 생성을 위한 PostgreSQL JSONB 저장 전략

1. 목적

2. 최종 결정

3. 구현 범위

필수 범위

추가 범위

확장 범위

4. 여러 문서 양식 지원

5. 복수 양식 지원 방식

6. Canonical Document Values

7. 양식 Contract 관리

8. Contract Version 관리

9. Server와 AI의 책임

Server

AI Document Service

Frontend

10. 데이터 모델

template_key

schema_version

values_json

version

11. 기존 Draft와 분리

12. Draft 생성 API

13. Draft 조회 API

14. Draft 수정 API

읽기 전용 Field 규칙

15. 낙관적 잠금

16. 입력 검증

17. Object와 Array 지원 범위

18. 문서 생성 API

19. HWP와 HWPX 지원

20. 직접 편집된 HWP/HWPX

21. 개인정보

22. JSONB Index

23. 테스트

Contract 테스트

Draft 테스트

문서 생성 테스트

PostgreSQL 통합 테스트

24. 인수 기준

필수 완료

추가 완료

확장 완료

25. 완료 기준

26. 최종 결론

Replies: 0 comments

krestar
Jul 29, 2026
Maintainer

`template_key`

`schema_version`

`values_json`

`version`