# HMM RDS PostgreSQL 가상 선사 실적 데이터

- Redmine: #729
- 적용 브랜치: `hmm-backoffice`
- 원격 원장: AWS RDS for PostgreSQL
- 대상 스키마: `hmm_demo`
- 기준월 범위: 2025-02-01 ~ 2026-07-01

## 1. 배경

HMM 데모는 Oracle ADB의 직원·조직·권한 데이터와 AWS RDS PostgreSQL의 선사 실적을
federation으로 결합한다. 사용자는 ADB에서 발급한 토큰으로 식별하고, 팀원은 자신에게
배정된 선사만, 팀장은 팀원에게 배정된 선사 전체를 조회하는 흐름을 보여준다.

이번 단계에서는 federation 연결 전에 RDS에 재현 가능한 가상 선사 실적 원장을 만든다.
실제 회사나 실제 재무 실적처럼 오인되지 않도록 모든 선사명과 수치는 데모 전용으로
생성한다.

## 2. 시스템별 책임

| 시스템 | 보관 정보 | 접근 제어 책임 |
|---|---|---|
| RDS PostgreSQL | 선사 기본정보, 선사별 월간 KPI | 전용 스키마와 조회 전용 역할 |
| Oracle ADB | 직원, 팀, 담당 선사 배정, 사용자 토큰 | VPD와 사용자 세션 context |
| Select AI/MCP | 자연어 질문, 보안 View 조회 | ADB에서 허용한 View만 사용 |

직원 사번이나 팀 정보는 RDS에 복제하지 않는다. RDS 데이터에는 선사 코드만 두고, 직원과
선사의 배정 관계는 후속 ADB 단계에서 `HMM_CARRIER_ASSIGNMENTS`로 관리한다.

## 3. 데이터 모델

### 3.1 `hmm_demo.carriers`

가상 선사 기준정보다.

| 컬럼 | 형식 | 설명 |
|---|---|---|
| `carrier_code` | `varchar(10)` | 가상 선사 식별 코드, PK |
| `carrier_name` | `varchar(120)` | 가상 선사명, UNIQUE |
| `country_code` | `char(2)` | ISO 형식의 데모 국가 코드 |
| `alliance_name` | `varchar(80)` | 가상 협력 네트워크 |
| `service_region` | `varchar(40)` | 주력 운항 권역 |
| `performance_tier` | `varchar(10)` | `CORE`, `GROWTH`, `WATCH` |
| `active` | `boolean` | 사용 여부 |
| `created_at` | `timestamptz` | 최초 생성 시각 |

### 3.2 `hmm_demo.carrier_monthly_performance`

선사별 월간 실적 fact다. 한 선사·한 기준월에 한 행만 허용한다.

| 컬럼 | 형식 | 설명 |
|---|---|---|
| `carrier_code` | `varchar(10)` | 선사 코드, FK |
| `performance_month` | `date` | 월의 첫째 날 |
| `contracted_teu` | `integer` | 계약 물동량 |
| `shipped_teu` | `integer` | 실제 운송 물동량 |
| `revenue_usd` | `numeric(16,2)` | 매출 |
| `gross_margin_usd` | `numeric(16,2)` | 매출총이익, 위험 패턴은 음수 허용 |
| `schedule_reliability_pct` | `numeric(5,2)` | 정시 운항률 |
| `vessel_utilization_pct` | `numeric(5,2)` | 선복 활용률 |
| `claim_rate_pct` | `numeric(5,2)` | 클레임 비율 |
| `yoy_growth_pct` | `numeric(7,2)` | 전년 동월 대비 성장률 |
| `risk_level` | `varchar(10)` | `GREEN`, `AMBER`, `RED` |
| `updated_at` | `timestamptz` | 적재 시각 |

PK는 `(carrier_code, performance_month)`다. 퍼센트 값은 0~100, 물동량과 매출은 0 이상을
CHECK 제약으로 보장한다. 월별 조회와 위험 선사 조회에 각각 인덱스를 둔다.

### 3.3 `hmm_demo.carrier_performance_latest_v`

가장 최근 기준월의 선사명과 KPI를 한 번에 조회하는 View다. 후속 federation 점검과
백오피스 미리보기에서 사용한다.

## 4. 가상 데이터

8개 가상 선사와 18개월 실적 144행을 만든다.

| 코드 | 가상 선사 | 의도한 데모 패턴 |
|---|---|---|
| `C001` | Bluewave Maritime | 높은 정시율과 지속 성장 |
| `C002` | Pacific Star Lines | 안정적 실적 |
| `C003` | Korea Ocean Link | 정시율과 클레임률 회복 |
| `C004` | Nordic Seaways | 계절성 변동 |
| `C005` | Orient Bridge Shipping | 점진적 물동량·마진 하락 |
| `C006` | Atlantic Merchant Line | 정시율 저하와 클레임 증가 |
| `C007` | Global Horizon Cargo | 빠른 성장 |
| `C008` | Southern Cross Marine | 지속적인 고위험 패턴 |

모든 수치는 프로파일 상수와 월 순번으로 계산한다. 난수를 사용하지 않으므로 어느 환경에서
다시 실행해도 같은 결과가 만들어진다.

## 5. 재실행과 변경 규칙

- `CREATE SCHEMA/TABLE IF NOT EXISTS`를 사용한다.
- 기준정보와 실적은 PK 기준 `ON CONFLICT DO UPDATE`로 현행화한다.
- 스크립트가 소유하지 않은 행은 삭제하지 않는다.
- 전체 실행은 하나의 transaction으로 처리한다.
- 오류가 발생하면 `ON_ERROR_STOP`과 transaction rollback으로 부분 적재를 방지한다.
- 비밀번호, endpoint, CA 파일 경로는 SQL에 넣지 않는다.

## 6. 보안

- `hmm_federation_reader`는 `NOLOGIN` 그룹 역할로 만든다.
- 해당 역할에는 `hmm_demo`의 `USAGE`와 테이블/View `SELECT`만 부여한다.
- ADB database link용 LOGIN 역할과 비밀번호는 federation 단계에서 별도로 생성하고
  `hmm_federation_reader` 역할만 상속시킨다.
- DDL/DML 권한과 `public` 스키마 변경 권한은 federation 역할에 부여하지 않는다.
- RDS 연결은 AWS global CA bundle과 `sslmode=verify-full`로 검증한다.

## 7. 적재 순서

1. RDS TLS와 현재 계정의 CREATE 권한을 확인한다.
2. `database/source/postgres_hmm_carrier_performance.sql`을 실행한다.
3. `database/source/postgres_hmm_carrier_performance_verify.sql`을 실행한다.
4. 재실행 후에도 동일한 선사 8개와 실적 144행인지 확인한다.
5. 후속 작업에서 ADB credential과 PostgreSQL database link를 만든다.

## 8. 검증 기준

- 선사 수: `8`
- 월간 실적: `144`
- 선사별 월 수: 모두 `18`
- 기간: `2025-02-01` ~ `2026-07-01`
- 최신월 위험 분포에 `GREEN`, `AMBER`, `RED`가 모두 존재
- `C001`의 최신 매출이 최초 매출보다 증가
- `C005`, `C006`, `C008`의 최신 매출이 최초 매출보다 감소
- 존재하지 않는 선사 코드, 잘못된 퍼센트, 월 첫째 날이 아닌 날짜 입력 거부
- `hmm_federation_reader`에 `SELECT`만 부여
- TLS 1.2 이상으로 실제 조회 성공

## 9. 제외 범위

- ADB의 `HMM_CARRIER_ASSIGNMENTS` 생성과 직원별 배정
- ADB PostgreSQL database link 생성
- ADB 보안 View와 VPD 정책
- Select AI profile 및 MCP tool 변경
- 실제 선사명이나 실제 경영 실적 적재

이 항목들은 RDS 가상 원장이 검증된 뒤 별도 단계로 진행한다.
