79 lines
3.5 KiB
Markdown
79 lines
3.5 KiB
Markdown
# 설계서: 환경변수 기반 공통 데이터 카탈로그
|
|
|
|
## 프로젝트 개요
|
|
|
|
이 백오피스는 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를 자동으로 생성·변경하지 않는다.
|