# 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 대상은 오류를 반환한다.