refs #722: externalize backoffice customer configuration

docs/design/722-configurable-data-catalog/README.md

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