refs #734: add validated annotation PL/SQL API

docs/design/734-sgmp-annotation-api/README.md

@@ -0,0 +1,42 @@
+# SGMP annotation 관리 API (#734)
+
+> 상태: Approved
+> 구현: `sql/adb/76_sgmp_annotation_api.sql`
+> 목적: 백오피스와 운영 스크립트가 동일한 검증 규칙으로 테이블/뷰 annotation을 추가·수정하도록 한다.
+
+## 입력 계약
+
+`SGMP_SET_ANNOTATION`은 스키마, 대상 종류(`TABLE` 또는 `COLUMN`), 테이블/뷰 이름, 선택적 컬럼 이름, annotation 값, 선택적 annotation 이름을 받는다. annotation 이름 기본값은 `AI_GUIDANCE`이며, 이름을 명시하면 그 이름을 사용한다.
+
+컬럼 이름은 `COLUMN` 대상에서만 필수다. 값은 4,000자 이내이며 빈 값은 허용하지 않는다. 객체와 컬럼은 `ALL_OBJECTS`/`ALL_TAB_COLUMNS`에서 확인하고 식별자는 `DBMS_ASSERT`로 제한한다.
+
+## 동작
+
+1. 대상 객체가 TABLE 또는 VIEW인지 확인한다.
+2. VIEW의 COLUMN 대상은 Oracle에서 변경할 수 없으므로 명확한 오류로 거부한다.
+3. `ALL_ANNOTATIONS_USAGE`에서 동일 annotation의 존재 여부를 확인한다.
+4. 기존 값이 있으면 DROP 후 ADD, 없으면 ADD만 수행한다.
+5. 수행 결과(`ADDED` 또는 `REPLACED`)와 정규화된 대상을 반환한다.
+
+DDL은 Oracle의 implicit commit 특성이 있으므로 호출자는 별도 트랜잭션으로 간주하지 않는다. 이 함수는 게임명·prefix·특정 테이블 정책을 하드코딩하지 않으며, 입력 객체의 존재와 Oracle 문법만 검증한다.
+
+## 호출 예
+
+```sql
+SELECT SGMP_SET_ANNOTATION(
+  'SGMP_POC', 'TABLE', 'CZN_COMN_USER_MST', NULL,
+  'AU는 최신 BASE_DT에서 AU_FLAG=1이고 EXPT_USER_YN=N인 활성 사용자 수다.',
+  'AI_GUIDANCE'
+) FROM dual;
+
+SELECT SGMP_SET_ANNOTATION(
+  'SGMP_POC', 'COLUMN', 'CZN_COMN_USER_MST', 'AU_FLAG',
+  'AU 집계용 활성 사용자 플래그(1=활성).', 'BUSINESS_DEFINITION'
+) FROM dual;
+```
+
+## 테스트 기준
+
+- TABLE 신규 annotation은 `ADDED`를 반환한다.
+- 같은 이름을 다시 호출하면 기존 값을 교체하고 `REPLACED`를 반환한다.
+- 존재하지 않는 객체/컬럼, 잘못된 대상 종류, VIEW의 COLUMN 대상은 오류를 반환한다.