140 lines
6.3 KiB
Markdown
140 lines
6.3 KiB
Markdown
# 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. `sql/source/postgres_hmm_carrier_performance.sql`을 실행한다.
|
|
3. `sql/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 가상 원장이 검증된 뒤 별도 단계로 진행한다.
|