# 설계서: 환경변수 기반 공통 데이터 카탈로그

## 프로젝트 개요

이 백오피스는 Oracle Database의 권한, 메타데이터, Select AI와 정형 데이터 조회를
운영하기 위한 공통 관리 화면이다. 현재 일부 화면은 특정 스키마와 업무 테이블 목록을
코드에 고정하고 있어, 다른 프로젝트에 재사용하려면 Java와 MyBatis를 함께 수정해야 한다.

## 목표

1. DB 접속은 기존 `BACKOFFICE_*_DB_*` 환경변수 체계를 유지한다.
2. 메타데이터와 정형 데이터 조회 대상은 `BACKOFFICE_CATALOG_OWNER`와
   `BACKOFFICE_CATALOG_OBJECTS`에서 선언한다.
3. 테이블과 뷰를 공통 `DataCatalogObject` 인터페이스로 표현한다.
4. 서비스와 MyBatis는 검증된 카탈로그 객체에서 전달받은 owner, object name, object type만
   사용한다. HTTP 요청값을 SQL 식별자로 쓰지 않는다.
5. 카탈로그 환경변수가 비어 있거나 잘못되면 기동 시 실패한다. 다른 고객의 객체를 기본값으로
   참조하지 않는다.

## 설정 계약

```bash
export BACKOFFICE_CATALOG_OWNER="APP_OWNER"
export BACKOFFICE_CATALOG_OBJECTS='[
  {"key":"sales","tableName":"SALES_TXN","objectType":"TABLE",
   "businessName":"판매 거래","description":"판매 거래 정보"},
  {"key":"daily-sales","tableName":"VW_DAILY_SALES","objectType":"VIEW",
   "businessName":"일별 판매","description":"일별 판매 집계 뷰"}
]'
```

- `key`: 화면 URL과 선택값에 사용하는 영문 키. 소문자, 숫자, `-`만 허용한다.
- `tableName`: Oracle 단순 식별자. 대문자, 숫자, `_`, `$`, `#`만 허용한다.
- `objectType`: `TABLE` 또는 `VIEW`.
- `businessName`, `description`: 화면 표시용 텍스트.

잘못된 JSON, 중복 key/name, 빈 목록, 허용되지 않은 식별자는 기동 시 명확히 실패한다.

## 구조

```text
환경변수
  → CatalogProperties
  → DataCatalog
  → StructuredDataService / SchemaMetadataService
  → MyBatis Mapper
  → Oracle dictionary / 허용 객체
```

`DataCatalog`은 허용 객체를 해석하는 단일 진입점이다. 미리보기 SQL은 객체 이름을
카탈로그에서만 받아 조합하며, 목록 밖 이름은 SQL에 들어갈 수 없다.

## 보안 SQL 번들

보안 SQL 화면은 `BACKOFFICE_SECURITY_SQL_SCRIPTS` JSON 배열에 선언한 번들만 표시한다.
각 항목은 `scriptId`, `category`, `fileName`, `title`, `description`을 가진다.
`fileName`은 패키지의 `sql/adb/` 하위 상대 경로만 허용하며, 요청값으로 경로를 만들지 않는다.
기존 고객 전용 SQL은 `sql/adb/legacy/<customer>/`에 보존하고, 다른 환경에는 해당 목록을
선언하지 않는다.

## MyBatis 처리

- table/view comment와 column comment 조회는 `owner`, `objectName`을 바인드한다.
- annotation 조회는 Oracle dictionary 제약에 맞춰 `objectName`, `objectType`을 함께
  바인드한다.
- 주석 DDL은 `COMMENT ON TABLE` 문법으로 테이블 또는 뷰에 적용한다.
- annotation DDL은 `TABLE`에만 허용한다. 뷰는 comment 편집만 제공한다.

## 완료 기준

- 환경변수로 테이블과 뷰를 섞은 카탈로그를 선언할 수 있다.
- metadata와 preview가 선언된 owner/object만 조회한다.
- 뷰의 comment/column comment는 조회·수정 가능하고, annotation 편집은 차단된다.
- 설정 파싱과 허용 목록 검증을 자동 테스트한다.

## 비범위

- Select AI profile 내부 object list를 자동으로 생성·변경하지 않는다.
