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

> "저장 타입(테이블 타입 관리)" 과 "표시 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 생성:
   ```sql
   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 자동 생성. |
