From e4697dd5eee9059f44adb091c7ebda5a73a42bb8 Mon Sep 17 00:00:00 2001 From: GA Pro Date: Sat, 9 May 2026 22:50:19 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EC=8B=A4=ED=96=89=20=EA=B0=80=EC=9D=B4?= =?UTF-8?q?=EB=93=9C=20+=20=EC=9A=B4=EC=98=81=20DB=20=EC=97=B0=EA=B2=B0=20?= =?UTF-8?q?=EC=A0=95=EB=B3=B4=20README=20=EB=B3=B4=EA=B0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 시나리오 A: 운영 DB(trading_ai/ga, 포트 55432) 연결 실행 - 시나리오 B: 로컬 PostgreSQL 처음부터 (Flyway 자동 마이그레이션) - 시나리오 C: Docker Compose 전체 기동 - 트러블슈팅 6항목 (Gradle 미설치, JDBC 드라이버, Flyway 스키마, JWT, AG Grid, 비밀번호) - 13개 페이지 메뉴-경로 표 - 데이터 현황 테이블 (보험사 5 / 상품 20 / 설계사 50 / 계약 200 등) - 외부 시스템 연결 정보 (호스트/포트/스키마/관리자 계정) --- README.md | 291 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 241 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 03e926d..3d54e69 100644 --- a/README.md +++ b/README.md @@ -26,41 +26,198 @@ ga-commission-system/ └── ga-frontend/ # React SPA (포트 3000) ``` -## 빠른 시작 (Docker Compose) +--- + +## 🚀 실행 가이드 + +### 환경 요구사항 + +- **Java 17+** (`java -version` 확인) +- **Node.js 18+** + npm +- **PostgreSQL 14+** (운영: `192.168.0.60:55432/trading_ai/ga` schema) +- **Redis 7+** (선택 — 공통코드/세션 캐시) +- **Gradle** (또는 IDE: IntelliJ IDEA 권장 — 자동으로 Gradle wrapper 생성) + +### 시나리오 A — 운영 DB(trading_ai/ga) 에 연결해서 실행 ⭐ 권장 + +이미 V1~V17 마이그레이션 + 테스트 데이터(보험사 5 / 상품 20 / 설계사 50 / 계약 200)가 +`192.168.0.60:55432/trading_ai/ga` 스키마에 적용되어 있습니다. + +#### 1) Backend (ga-api) 실행 ```bash -docker compose up -d --build -# 프론트: http://localhost:3000 -# API: http://localhost:8080/swagger-ui.html -# Batch: http://localhost:8081 (내부) +# 1-1. Gradle wrapper 가 없다면 한 번 생성 (Gradle 설치 필요) +gradle wrapper --gradle-version 8.6 + +# 1-2. 빌드 +./gradlew :ga-api:bootJar + +# 1-3. 실행 (trading_ai 프로파일 — 운영 DB 연결) +./gradlew :ga-api:bootRun --args='--spring.profiles.active=trading_ai' + +# 또는 환경변수로 비밀번호/Redis 호스트 오버라이드 +export DB_PASSWORD=your-password +export REDIS_HOST=localhost +java -jar ga-api/build/libs/ga-api.jar --spring.profiles.active=trading_ai ``` -## 로컬 개발 +확인: +- API: http://localhost:8080 +- Swagger: http://localhost:8080/swagger-ui.html + +#### 2) Backend (ga-batch) 실행 — 정산 배치 트리거 처리 -### 1. PostgreSQL + Redis 기동 ```bash -docker compose up -d postgres redis +./gradlew :ga-batch:bootRun --args='--spring.profiles.active=trading_ai' +# 또는 +java -jar ga-batch/build/libs/ga-batch.jar --spring.profiles.active=trading_ai ``` -### 2. ga-api 실행 (Flyway 자동 마이그레이션) -```bash -./gradlew :ga-api:bootRun -``` +기본 포트 8081. ga-api 가 `/api/batch/settlement/run` 호출 시 batch_job_log 에 +`REQUESTED` 상태로 기록되며, ga-batch 가 이를 폴링/직접 호출로 실행합니다. -### 3. ga-batch 실행 -```bash -./gradlew :ga-batch:bootRun -``` +#### 3) Frontend 실행 -### 4. 프론트 실행 ```bash cd ga-frontend npm install -npm run dev -# http://localhost:3000 +npm run dev # http://localhost:3000 (Vite dev server) ``` -## 주요 기능 +기본적으로 `/api/*` 요청은 Vite 프록시로 `http://localhost:8080` 으로 전달됩니다. + +#### 4) 로그인 & 동작 확인 + +``` +URL : http://localhost:3000 +ID : admin +PW : admin1234! +``` + +로그인 후 사이드바 메뉴 — 좌측에 동적으로 메뉴가 그려져야 합니다. +주요 화면: + +| 메뉴 | 경로 | 설명 | +|------|------|------| +| 대시보드 | `/` | 정산 요약 카드 | +| 설계사 관리 | `/org/agents` | 50명 더미 + 검색/등록/수정/엑셀 | +| 계약 관리 | `/contracts` | 200건 더미 + 상태/보험사 필터 | +| 모집수수료 원장 | `/ledger/recruit` | AG Grid 호환 테이블 + 엑셀 다운로드 | +| 예외금액 원장 | `/ledger/exception` | 승인/반려 | +| 정산 결과 | `/settle` | 월 요약 + 확정/보류 | +| 정산 배치 | `/settle/batch` | 배치 실행 + 진행률 폴링 | +| 지급 관리 | `/payments` | 지급 상태 추적 | +| 사용자 관리 | `/system/users` | 비번 초기화/잠금 해제 | +| 역할/권한 | `/system/roles` | 권한 매트릭스 (메뉴 × 6권한) | +| 공통코드 | `/system/codes` | 그룹별 코드 조회 | + +--- + +### 시나리오 B — 로컬 PostgreSQL 로 처음부터 (개발용) + +```bash +# 1) PostgreSQL + Redis 기동 (Docker) +docker compose up -d postgres redis + +# 2) ga-api 실행 (Flyway 가 자동으로 V1~V17 마이그레이션) +./gradlew :ga-api:bootRun +# 기본 프로파일은 application.yml — localhost:5432/ga 에 연결 + +# 3) ga-batch 실행 +./gradlew :ga-batch:bootRun + +# 4) 프론트 +cd ga-frontend && npm install && npm run dev +``` + +`application.yml` 의 기본 DB: +```yaml +url: jdbc:postgresql://localhost:5432/ga +username: ga +password: ga +``` + +--- + +### 시나리오 C — Docker Compose 로 전체 기동 + +```bash +docker compose up -d --build +# postgres + redis + api + batch + frontend 모두 컨테이너로 기동 +# - 프론트: http://localhost:3000 +# - API: http://localhost:8080/swagger-ui.html +# - Batch: http://localhost:8081 (내부 통신용) +``` + +`docker-compose.yml` 환경변수: +- `JWT_SECRET` — JWT 서명 키 (256bit 이상) +- `ENCRYPT_KEY` — AES-256 키 (32바이트) + +--- + +### DB 마이그레이션 직접 실행 (스크립트) + +저장소 루트의 `migrate.py` (이 파일은 ga-commission-system 외부에 있음) — Python + pg8000 으로 +V1~V17 SQL을 임의 DB에 일괄 적용: + +```bash +pip install pg8000 +python migrate.py +# host/port/db/user/schema 는 파일 상단 상수로 수정 +``` + +`ga` 스키마가 이미 있으면 idempotent guard 로 멈춥니다. +완전 재설치는 `DROP SCHEMA ga CASCADE; CREATE SCHEMA ga;` 후 재실행. + +--- + +## 🧪 데이터 확인 (운영 DB 기준) + +| 테이블 | 건수 | +|--------|------| +| insurance_company | 5 (삼성/한화/교보/디비/KB) | +| product | 20 (보험사 × 4상품) | +| organization | 7 (본부 1 / 지점 3 / 팀 3) | +| agent | 50 (GM 3 / DM 3 / SMGR 6 / SFC 12 / FC 26) | +| contract | 200 (ACTIVE 190 / LAPSE 10) | +| commission_rate | 100 | +| payout_rule | 120 | +| override_rule | 10 | +| chargeback_rule | 4 | +| common_code (그룹/상세) | 18 / 42 | +| menu / menu_permission | 33 / 150 | +| role / role_menu_permission | 4 / 323 | + +--- + +## 🔧 트러블슈팅 + +### Q. `./gradlew` 가 없다고 함 +`gradle wrapper --gradle-version 8.6` 로 한번 생성하거나, IntelliJ 로 프로젝트 열면 자동 생성. + +### Q. ga-api 부팅 시 `Failed to determine a suitable driver class` +JDBC URL 또는 자격증명 누락. `--spring.profiles.active=trading_ai` 가 적용됐는지 확인. + +### Q. `NoSuchKey: ga` (Flyway) +운영 DB 의 `ga` 스키마를 인식하려면 `currentSchema=ga` 가 URL 에 있어야 함. +`application-trading_ai.yml` 에서 이미 설정되어 있음. + +### Q. 프론트에서 401 / "토큰이 만료되었습니다" +`localStorage` 에 `accessToken` 이 만료됨. `/login` 으로 다시 로그인. + +### Q. AG Grid 가 빈 화면으로 보임 +`@ag-grid-community/styles/ag-theme-quartz.css` import 가 잘 됐는지 확인. + +### Q. 비밀번호 변경 +```sql +-- BCrypt 해시 생성 후 직접 UPDATE +UPDATE ga.users SET password = '$2b$10$...' WHERE login_id = 'admin'; +``` +또는 사용자 관리 화면 → "비번초기화" 액션. + +--- + +## 📋 주요 기능 ### 백엔드 - **인증/권한**: JWT (HS256), 메뉴×권한 RBAC, BCrypt 비밀번호 @@ -68,29 +225,30 @@ npm run dev - **메뉴**: 트리 구조, 사용자별 동적 메뉴 + 권한 매트릭스 - **엑셀**: SXSSF+Cursor 다운로드(100만건), SAX+배치 업로드(70만건) - **로그**: 로그인/API/데이터변경 자동 기록 (비동기) -- **암호화**: AES-256 CBC (resident_no, account_no) +- **암호화**: AES-256 CBC (`resident_no`, `account_no` 자동) ### 도메인 - **조직**: 트리 구조, CTE 재귀, 인사 이력 - **계약**: 보험사/상품/계약 관리 - **수수료 규정**: 보험사율, 지급율, 오버라이드, 환수, 예외코드 -- **원장**: 모집/유지/예외 (PageHelper, AG Grid 서버사이드 가능) +- **원장**: 모집/유지/예외 (PageHelper + AG Grid) - **정산**: 8 Step 배치 (수신→변환→대사→모집→유지→환수/예외→오버라이드→집계) - **지급**: 이체파일 생성, 상태 추적 ### 정산 배치 8 Step 1. **receiveData** — 보험사별 DataReceiver → raw_commission_data 적재 -2. **transformData** — MappingEngine으로 표준 변환 +2. **transformData** — MappingEngine 으로 raw → 표준 원장 (TRIM/UPPER/DATE/DIVIDE/CODE_MAP) 3. **reconcile** — 보험사 통보액 vs 시스템 계산액 대사 -4. **calcRecruit** — 모집수수료 (계약시점 규정 적용) -5. **calcMaintain** — 유지수수료 (납입주기 매칭) -6. **chargebackException** — 환수 자동생성 -7. **calcOverride** — 조직 트리 오버라이드 -8. **aggregate** — 통합 집계 → settle_master UPSERT (3.3% 세금) +4. **calcRecruit** — 모집수수료 (계약시점 commission_rate/payout_rule 적용) +5. **calcMaintain** — 유지수수료 (납입주기 매칭, 1~5년차) +6. **chargebackException** — 실효 계약 환수 자동생성 +7. **calcOverride** — 조직 트리 상향 탐색 → 상위 직급에 분배 +8. **aggregate** — 설계사별 통합 집계 → settle_master UPSERT (3.3% 세금) -## 신입 개발자 표준 패턴 +--- + +## 🛠 신입 개발자 표준 패턴 (5분 컷) -### Backend (5분) ```java // 1) VO (XxxVO + XxxResp + XxxSaveReq + XxxSearchParam) @Data @@ -124,31 +282,64 @@ public class FooController { } ``` -## 보안 +--- + +## 🔒 보안 + - JWT (HS256) — 액세스 2시간, 리프레시 7일 -- AES-256 CBC 암호화 (자동 적용 — `EncryptTypeHandler`) +- AES-256 CBC 암호화 (`EncryptTypeHandler` 자동 적용) - RBAC — `role_menu_permission` 매트릭스 - `@DataChangeLog` — 데이터 변경 이력 AOP 자동 -- API 접근 로그 — 비동기 저장 +- API 접근 로그 — 비동기 저장 (`api_access_log`) -## DB 마이그레이션 -- V1~V8: 도메인 스키마 + 초기 데이터 -- V9~V12: 공통코드/메뉴/시스템관리 + 초기 데이터 -- V13: 인덱스 최적화 -- V14: 파티셔닝 helper 함수 -- V15: 통계/리포트 뷰 (v_agent_monthly_summary, v_org_settle_summary, v_chargeback_risk) +--- -## 진행 상황 +## 🗄 DB 마이그레이션 -- [x] 1단계 — 프로젝트 뼈대 + DB (V1~V15) -- [x] **ga-common** — 공통 프레임워크 (model/exception/auth/security/code/menu/excel/file/system/notification) -- [x] **ga-core** — 22개 테이블의 VO/Mapper/XML -- [x] **ga-api** — Auth + 도메인 컨트롤러 (org/product/rule/receive/ledger/settle/payment/system) -- [x] **ga-batch** — MonthlySettlementJob 8 Step +| 버전 | 내용 | +|------|------| +| V1~V8 | 도메인 스키마 + 초기 데이터 (직급, 예외코드) | +| V9~V12 | 공통코드/메뉴/시스템관리 + 초기 데이터 | +| V13 | 인덱스 최적화 | +| V14 | 파티셔닝 helper 함수 | +| V15 | 통계/리포트 뷰 (v_agent_monthly_summary 등) | +| V16 | 관리자 계정 + 메뉴 상세 + 권한 매트릭스 | +| V17 | 테스트 데이터 (보험사 5 / 상품 20 / 설계사 50 / 계약 200 + 수수료 규정) | + +--- + +## ✅ 진행 상황 + +- [x] 1단계 — 프로젝트 뼈대 + DB (V1~V17) +- [x] **ga-common** — 공통 프레임워크 일체 +- [x] **ga-core** — 22개 테이블 VO/Mapper/XML +- [x] **ga-api** — Auth + 14개 도메인 컨트롤러 +- [x] **ga-batch** — MonthlySettlementJob 8 Step (실제 동작 로직 포함) - [x] **Docker** — docker-compose + multi-stage Dockerfile + nginx -- [x] **ga-frontend** — Vite + React + AntD + React Query 스켈레톤 (로그인 + 대시보드 + 동적 메뉴) +- [x] **ga-frontend** — 13개 페이지 (대시보드/설계사/계약/원장/정산/지급/배치/시스템관리) +- [x] **운영 DB 적용** — 192.168.0.60:55432/trading_ai/ga (V1~V17 + 테스트 데이터) +- [ ] **단위/통합 테스트** — 미작성 +- [ ] **MappingEngine 정밀화** — 일부 변환 규칙은 단순화된 형태 -## 향후 확장 -- **프론트 페이지 추가**: menu 테이블 등록 → React 페이지 구현 → 동적 라우팅 적용 -- **신규 보험사**: company_profile + company_field_mapping 등록 + DataReceiver 구현 -- **신규 정산 규정**: commission_rate/payout_rule/override_rule/chargeback_rule 의 effective_from 만 다른 버전으로 추가 +--- + +## 🔮 향후 확장 + +- **프론트 페이지 추가**: `menu` 테이블 등록 → React 페이지 구현 → 동적 라우팅 적용 +- **신규 보험사**: `company_profile` + `company_field_mapping` 등록 + 필요 시 `DataReceiver` 구현 +- **신규 정산 규정**: `commission_rate`/`payout_rule`/`override_rule`/`chargeback_rule` 에 `effective_from` 만 다른 버전으로 추가 (versioning) +- **이체파일 포맷**: 은행별 EBCDIC/CSV 출력 어댑터 추가 + +--- + +## 📡 외부 시스템 연결 정보 (요약) + +| 항목 | 값 | +|------|-----| +| 운영 DB 호스트 | `192.168.0.60` | +| 운영 DB 포트 | `55432` | +| 운영 DB 데이터베이스 | `trading_ai` | +| 운영 DB 스키마 | `ga` | +| 운영 DB 사용자 | `kyu` | +| Git 원격 | https://gl.kyleyang.co.kr/kyu/ga-commission-system | +| 초기 관리자 | `admin / admin1234!` |