wace_rps/docs/table-type-and-screen-design.md

테이블 타입 관리 ↔ 화면관리 설계 방향성

"저장 타입(테이블 타입 관리)" 과 "표시 UI(화면관리)" 를 명확히 분리한다. 한 컬럼이 어떤 데이터인지는 테이블 타입에서 정하고, 그 데이터를 화면에서 어떻게 보여줄지는 화면관리에서 정한다.

---

1. 핵심 원칙

레이어	무엇을 결정하나	누가 정의하나
테이블 타입 관리	저장 단위(타입), 컬럼 코멘트, PK/NN/IDX/UQ, 참조 대상	개발/관리자
화면관리	입력 UI 컴포넌트(text/textarea/달력/체크박스/라디오/셀렉트…), 화면별 라벨, 정렬, 필수 여부, 기본값, 표시 옵션	개발/관리자

저장 타입은 간단하게, 화면 UI 는 풍부하게. 한 저장 타입에 여러 UI 컴포넌트가 매핑된다.

---

2. 테이블 생성 규칙

2.1 코멘트 필수

• 모든 테이블에는 코멘트가 필수. 빈 값이면 저장 차단.
• 모든 컬럼에도 코멘트가 필수 (시스템 자동 생성 컬럼 제외).
• 코멘트는 PostgreSQL COMMENT ON TABLE / COLUMN ... IS '...' 로 DB 에 같이 박아 둔다.
• 화면관리는 이 코멘트를 기본 라벨 로 가져다 쓴다. 화면별로 라벨을 다르게 쓰고 싶으면 화면관리에서 재정의.

2.2 시스템 자동 생성 컬럼 (테이블 생성 시 자동 부여, 사용자 편집 불가)

id            BIGINT PRIMARY KEY              -- 행 식별자
company_code  VARCHAR(40)                     -- 멀티테넌트 회사 코드
writer        VARCHAR(80)                     -- 작성자(사용자 ID)
created_date  TIMESTAMP DEFAULT NOW()         -- 생성 일시
updated_date  TIMESTAMP                       -- 수정 일시 (트리거로 갱신)

• 위 5개 컬럼은 테이블 생성 시 자동 삽입.
• 테이블 타입 관리 UI 에서 🔒 잠금 표시되고, 타입/PK/NN/IDX/UQ/코멘트 모두 수정 불가.
• 화면관리에서 이 컬럼들을 화면에 표시할지 여부는 화면 작성자가 결정.

2.3 사용자 정의 컬럼

• 위 메타 컬럼을 제외한 나머지는 모두 사람이 직접 정의.
• 컬럼명, 코멘트(=기본 라벨), 타입, PK/NN/IDX/UQ 를 사람이 입력.

---

3. 컬럼 타입 (저장 단위)

테이블 타입 관리에서 선택 가능한 저장 타입은 다음 8개로 제한한다.

그룹	타입	코드값	설명	DB 표현 (PostgreSQL)
기본	텍스트	text	일반 문자열	VARCHAR(N) 또는 TEXT
	숫자	number	정수·소수	NUMERIC / INTEGER
	날짜	date	날짜/시간	TIMESTAMP 또는 DATE
참조	코드	code	공통코드(comm_code) 자식 코드 참조	VARCHAR FK to comm_code.code_id
	테이블 참조	entity	다른 테이블의 행 참조	BIGINT FK to <target>.id
자동	채번	numbering	시퀀스 기반 자동 채번	VARCHAR (예: INSP-2026-0001)
첨부	파일	file	파일 업로드	VARCHAR (파일 메타 OBJID)
	이미지	image	이미지 업로드	VARCHAR (파일 메타 OBJID)

제외된 타입과 그 이유

제외된 타입	이유	화면관리에서 어떻게 다루나
카테고리	공통코드(code) 와 동작이 동일 — 중복 개념	code 타입으로 통합
체크박스 / 라디오 / 셀렉트	표시 UI 변형. 저장 타입과는 무관	code 또는 entity 타입 컬럼에 대해 화면관리에서 컴포넌트 선택
여러 줄 (textarea)	표시 UI 변형. 저장은 동일하게 text	text 타입 컬럼에 대해 화면관리에서 text input vs textarea 선택

---

4. 화면관리 매핑

저장 타입별로 화면관리에서 선택 가능한 UI 컴포넌트는 다음과 같다.

4.1 text (텍스트)

• 단일 행 입력 (<input type="text">)
• 여러 줄 입력 (<textarea>)
• 자동 완성 (특정 컬럼 값 목록을 가져와 제안)
• 마스킹 입력 (전화번호, 사업자번호 등)

4.2 number (숫자)

• 숫자 입력 (<input type="number">)
• 금액 입력 (천단위 콤마, 단위 접미사)
• 퍼센트 입력 (0~100 슬라이더 또는 입력)
• 스피너 (+/- 버튼)

4.3 date (날짜)

• 달력 picker (단일 날짜)
• 날짜 범위 picker (from ~ to)
• 시간 포함 picker (datetime-local)
• 연/월 picker (정밀도가 낮은 경우)

4.4 code (공통코드)

화면관리에서 가장 풍부한 컴포넌트 선택지가 열리는 타입.

• 셀렉트박스 (단일 선택, 옵션이 많을 때)
• 체크박스 그룹 (다중 선택)
• 라디오 그룹 (단일 선택, 옵션이 적을 때)
• autocomplete (옵션이 매우 많을 때)
• 트리 셀렉트 (계층형 공통코드일 때 — 대/중/소분류)

4.5 entity (테이블 참조)

• 셀렉트박스 (참조 테이블의 displayName 목록)
• 모달 픽커 (검색·페이지네이션이 필요한 경우)
• autocomplete (옵션이 많을 때)
• 마스터 카드 미리보기 (선택 후 참조 행의 주요 필드를 보여주는 UI)

4.6 numbering (채번)

• 읽기 전용 표시 (저장 시 자동 발번 — 사용자는 입력 불가)
• 화면 표시 형식만 결정 (예: INSP-{YYYY}-{0000})

4.7 file / image (첨부)

• 드래그앤드롭 업로드
• 파일 리스트 + 추가/삭제 버튼
• 이미지 미리보기 + 갤러리
• 다중 업로드 vs 단일 업로드

---

5. 데이터 흐름 (실제 작동 예시)

5.1 새 테이블 만들기

1. 관리자가 테이블 타입 관리 에서 inspection_equipment_mng 생성
2. 테이블 코멘트: "검사 장비의 정보와 교정 주기를 관리하는 테이블" (필수)
3. 시스템이 자동으로 id / company_code / writer / created_date / updated_date 5컬럼 부여 (잠금)
4. 관리자가 사용자 컬럼 추가:
   • equipment_code 타입=text 코멘트="장비 고유 코드(필수)"
   • equipment_name 타입=text 코멘트="장비명"
   • calibration_period 타입=number 코멘트="교정주기 (개월)"
   • last_calibration_date 타입=date 코멘트="최근 교정일"
   • equipment_type 타입=code 코멘트="장비유형" + 코드 카테고리 선택
   • manager_id 타입=entity 코멘트="담당자" + 참조 테이블=user_info
5. 저장 시 DDL 생성:

   CREATE TABLE inspection_equipment_mng (...);
   COMMENT ON TABLE  inspection_equipment_mng IS '검사 장비의 정보와 교정 주기를 관리하는 테이블';
   COMMENT ON COLUMN inspection_equipment_mng.equipment_code IS '장비 고유 코드(필수)';
   ...
   

5.2 화면 만들기

1. 개발자가 화면관리 에서 새 화면 작성, 대상 테이블 = inspection_equipment_mng
2. 시스템이 컬럼 목록 + 각 컬럼의 코멘트(기본 라벨) + 타입을 가져옴
3. 개발자가 각 컬럼별 UI 컴포넌트를 선택:
   • equipment_code (text) → 단일 행 입력, 라벨="장비코드"(코멘트에서 가져온 기본값), 필수=Y
   • equipment_name (text) → 단일 행 입력
   • calibration_period (number) → 숫자 입력, 접미사="개월"
   • last_calibration_date (date) → 달력 picker
   • equipment_type (code) → 라디오 그룹 (옵션이 4~5개라서)
   • manager_id (entity) → autocomplete (사용자 검색)
4. 라벨은 코멘트가 디폴트로 채워지지만, 화면별로 다르게 쓰고 싶으면 화면관리에서 자유롭게 override
5. 필수/읽기전용/기본값 등의 입력 제약도 화면관리에서 화면별로 지정

---

6. UI 정책 (테이블 타입 관리 화면)

6.1 우측 패널 — 컬럼 상세

• 타입: 셀렉트박스 (위 8개 중 1개)
• 타입별 상세:
  • code 선택 시 → 공통코드 카테고리 픽커 + 계층 역할(대분류/중분류/소분류)
  • entity 선택 시 → 참조 테이블 + 조인 컬럼(값)
  • numbering 선택 시 → 채번 규칙 안내(옵션설정 메뉴 안내)
  • 그 외 타입 → 별도 설정 없음
• 코멘트: Textarea (필수)
• 시스템 컬럼이면 위 모든 입력 비활성화 + 잠금 안내 배너

6.2 우측 패널에서 제거된 항목

• 표시 이름 (= 라벨) → 코멘트로 대체. 라벨은 화면관리에서.
• 필수 입력 / 읽기 전용 → 화면관리에서.
• 기본값 / 최대 길이 → 화면관리(또는 DDL 단계) 에서.

6.3 중앙 컬럼 그리드

• 시스템 컬럼은 🔒 자물쇠 아이콘 + 톤다운 + PK/NN/IDX/UQ 토글 비활성화
• 일반 컬럼은 행 클릭으로 우측 패널 열림, PK/NN/IDX/UQ 클릭 토글, hover 시 ⋯ 액션 노출

---

7. 향후 확장 포인트

항목	비고
채번 규칙 관리	옵션설정 > 채번설정 메뉴로 분리. 본 메뉴에서는 채번 규칙 ID 만 선택.
다국어 코멘트	코멘트를 i18n 키 + 다국어 테이블로 분리할지 검토. 현재는 단일 언어.
변경 이력	컬럼 타입/코멘트/제약 변경 이력을 별도 테이블에 적재.
컬럼 의존성 그래프	entity 참조가 많아지면 테이블 간 ERD 자동 생성.