코드 품질 자동 체인 마지막 단계. ga-api에 5a 산출물 적용 + 잔여 Controller
Mapper 직접 주입 제거.
MapStruct 적용 (수동 매핑 제거):
- ContractService.create/update — ContractMapStruct.toVO/updateVO
- LedgerService — ExceptionLedgerMapStruct.toVO
- UserService.create/update — UserMapStruct.toVO/updateVO
AgentOrgHistoryResp 적용:
- AgentService.history() 반환 List<AgentOrgHistoryVO> → List<AgentOrgHistoryResp>
- AgentMapper.selectHistoryResp(agentId) 사용
- AgentController history 시그니처 동반 변경 — 감사 필드 누설 + FK ID 노출 문제 해소
잔여 Controller Mapper 직접 주입 제거:
- AgentController/LedgerController — AgentService.exportCursor /
LedgerService.exportRecruitCursor/exportMaintainCursor 위임
- PaymentService 신설 — PaymentController에서 Mapper/TransferFileService
직접 주입 제거, PageHelper.startPage Service로 이전
- UploadTemplateService 신설 — 3개 Mapper(template/column/history) Service로 이전
PageHelper 위치 통일:
- grep -rn "startPage" controller/ → 결과 없음 (모두 Service로 이전)
남은 예외:
- BatchTriggerController.BatchJobLogMapper — 배치 트리거 특수 패턴이라 보류
- PaymentStatus Enum — 도메인 단계에서 처리 예정
리뷰에서 P0로 지적된 동시성/롱 트랜잭션 이슈 일괄 해소.
LookupCache (P0 데이터 정합성):
- 싱글톤 인스턴스 필드 캐시 제거 → preload()가 새 Map 반환, 호출자 보유
- TransformEngine.transform/applyTransform/applyLookup/applyCodeMap 시그니처에
lookupData 파라미터 추가하여 명시적 전달
- 스레드 간 공유 상태 자체가 없어져 동기화 불필요
UploadService (P0 가용성):
- 신규 UploadTxHelper로 saveHistory/insertBatch/updateHistory를 REQUIRES_NEW로 분리
- UploadService에서 @Transactional 완전 제거 — 파일 파싱은 트랜잭션 밖
- 청크(1000행) 단위 커밋 → 커넥션 점유 시간 감소
TransferFileService (P0 정합성):
- 파일 생성을 트랜잭션 밖으로 분리
- markPaymentsSent() 별도 @Transactional로 payment UPDATE만 처리
- 파일 저장 실패 시 payment 상태 미변경으로 재시도 안전성 확보
조회 메서드 readOnly=true 일괄 적용 (Hibernate dirty check 비활성화 / 읽기 복제본 라우팅 준비):
- AgentService, ContractService, LedgerService, SettleService,
OrganizationService, UserService 조회 메서드 전체
엑셀 컬럼 매핑이 더 직관적이도록:
Backend:
- TargetFieldMetaService 신규: 9개 target_table 의 사용 가능 필드 메타데이터
(recruit_ledger 15 / maintain_ledger 11 / contract 10 / agent 10 /
commission_rate 7 / payout_rule 7 / chargeback_rule 6 / exception_ledger 6 /
payment 6) — field/label/type/required
- UploadService.extractHeaders(file, headerRow, sheetIndex, previewRows):
StreamingReader 로 첫 행 헤더 + N행 미리보기 추출, A/B/C 컬럼 라벨 생성
- UploadController 에 3개 엔드포인트 추가:
· POST /api/upload-templates/excel-headers (multipart) → ExcelHeaderResp
· GET /api/upload-templates/target-fields/{targetTable}
· GET /api/upload-templates/target-tables
Frontend:
- api/uploadTemplate.ts: extractHeaders / targetFields / targetTables 함수 추가
+ ExcelHeaderResp / TargetFieldMeta 타입
- ColumnEditor 보강:
1) "샘플 엑셀로 자동 채우기" 버튼 — 사용자가 샘플 파일 올리면 헤더 추출 후
sourceColumn(A,B,C) + sourceHeader(헤더명) 자동 채움 (기존 매핑 있으면
Modal.confirm 으로 덮어쓰기 확인)
2) 대상 필드 Input → Select (target_table 별 메타 옵션) — showSearch +
선택 시 targetType 자동 설정 (필드 메타의 type 으로)
3) 헤더에 target_table tag 표시 (→ recruit_ledger)
4) 자동 채우기 후 첫 5행 샘플 데이터 테이블이 매핑 편집기 위에 표시됨
검증: tsc -b 통과, ga-api 재기동 후 /target-fields 200 (15필드 응답)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
헤더 깨짐 수정 (MainLayout):
- logo 를 div 박스 대신 단순 img(/vite.svg) 로 (ProLayout 기본 슬롯 호환)
- avatarProps.render 의 chevron 제거 → ProLayout 기본 dom 만 Dropdown 트리거
- token.header 의 잘못된 키(colorBgRightActionsItemHover) 제거,
heightLayoutHeader 56 으로 통일
- actionsRender 의 정산월 영역을 Space + 라벨 조합으로 정리
등록/수정 모달 (DrawerForm / ModalForm):
- AgentList: DrawerForm (680px) — 설계사명 / 사번 / 소속(Select) / 직급 /
전화 / 이메일 / 주민번호(암호화) / 은행 / 계좌(암호화) / 입사일,
수정 시 detail API 자동 fetch + initialValues 주입,
액션 컬럼: 수정/퇴사 (Modal.confirm)
- ContractList: ModalForm (680px) — 증권번호 / 설계사(Select) / 상품(Select) /
계약자 / 피보험자 / 보험료 / 납입주기 / 계약일 / 효력발생일
toolBarRender 등록 버튼 추가
- ExceptionLedger: ModalForm (620px) — 설계사 / 정산월 / 예외코드 /
금액 / 증권번호 / 보험사 / 내용
toolBarRender 등록 버튼 추가, 예외코드 옵션은 ruleApi 에서 동적 로드
api/contract.ts: ContractSaveReq + create/update 추가
검증: tsc -b 통과 / dev 서버 HMR 정상 반영
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- 09_UI_DESIGN.md 신규: Ant Design 테마 토큰, 글로벌 CSS 변수,
레이아웃 규격(Header 48px / Sider 220px), 페이지 표준 3종(목록/상세/대시보드),
공통 컴포넌트 스타일(CodeBadge/MoneyText/SearchForm/DataTable/DataGrid),
등록·수정 폼 규칙(Drawer), 화면별 와이어프레임 6종, 신입 체크리스트
- 00_PROMPTS.md: 프롬프트 3 frontend-developer 가 09_UI_DESIGN.md 도 함께 참조
- 06_FRONTEND_SPEC.md: 상단에 디자인 시스템 참조 추가
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
00_PROMPTS.md — Claude Code 실행 프롬프트 1~6
01_DB_SCHEMA.md — V1~V17 Flyway 스키마 + 프로젝트 뼈대
02_COMMON_SPEC.md — ga-common 공통 프레임워크 (모델/예외/MyBatis/AOP/엑셀/공통컴포넌트)
03_CORE_SPEC.md — ga-core VO 설계 원칙 + Mapper 패턴
04_BATCH_SPEC.md — ga-batch 정산 8 Step + DataReceiver/MappingEngine
05_API_SPEC.md — ga-api Controller/Service 표준 패턴 + 엔드포인트 목록
06_FRONTEND_SPEC.md — ga-frontend 13개 화면 + 공통 컴포넌트 사용법
07_INFRA_SPEC.md — Docker/Nginx + README + DEVELOPER_GUIDE
08_DBA_SPEC.md — V13~V15 인덱스/파티셔닝/뷰
실제 구현된 ga-commission-system 기준으로 작성. 코드는 변경 없음.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
mybatis-spring-boot-starter 가 BaseTypeHandler<String> 빈을 자동 등록하면서
모든 String 컬럼에 적용해버리는 문제 해결. @Component 를 제거하고
EncryptTypeHandlerInitializer (@Configuration) 에서 EncryptUtil 만 정적 주입.
사용처는 mapper XML 에서 컬럼별 typeHandler 속성으로 명시(기존과 동일).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- 시나리오 A: 운영 DB(trading_ai/ga, 포트 55432) 연결 실행
- 시나리오 B: 로컬 PostgreSQL 처음부터 (Flyway 자동 마이그레이션)
- 시나리오 C: Docker Compose 전체 기동
- 트러블슈팅 6항목 (Gradle 미설치, JDBC 드라이버, Flyway 스키마, JWT, AG Grid, 비밀번호)
- 13개 페이지 메뉴-경로 표
- 데이터 현황 테이블 (보험사 5 / 상품 20 / 설계사 50 / 계약 200 등)
- 외부 시스템 연결 정보 (호스트/포트/스키마/관리자 계정)
Backend:
- MappingEngine: company_field_mapping 기반 동적 변환 구현
- raw_content(JSON) → 표준 원장 (TRIM/UPPER/LOWER/DATE/DIVIDE/MULTIPLY/CODE_MAP)
- policy_no 로 contract 매칭 → contract_id/agent_id 자동
- 실패 시 parse_error_log 자동 적재
- Recruit/Maintain Mapper.sumByAgentMonth 추가
- OrganizationMapper.selectAncestorIds (CTE 재귀 상향) 추가
- CalcOverrideStep 실제 동작:
* lower agent 의 모집+유지 합계를 base 로 사용
* 자기 조직 → 상위 조직 순으로 to_grade 직급 ACTIVE 설계사 탐색
* (lowerOrgId, toGrade) 캐싱
Frontend (주요 화면):
- 공통 컴포넌트:
* CodeSelect (공통코드 드롭다운, React Query 캐시)
* CodeBadge (상태 색상 자동 매핑)
* MoneyText (천단위 콤마, 음수 빨강, 부호 옵션)
* PermissionButton (권한 없으면 미렌더)
* SearchForm (조건 배열 → 자동 폼)
* ExcelExportButton (blob 다운로드)
* PageContainer
- 훅: useCommonCodes, usePermission (메뉴별 boolean)
- API 모듈: agent, contract, ledger, settle, code
- 페이지: AgentList, ContractList, RecruitLedger, SettleList
* SettleList: 월 요약 카드 + 확정/보류 액션 + 권한 체크
- 라우터: /org/agents, /contracts, /ledger/recruit, /settle
V16 fix:
- PAYMENT 메뉴는 V12 에서 level1 directory 로 생성됨 → V16 에서 PAGE 로 UPDATE 후 권한 매트릭스 적용 (자식으로 또 만들면 unique 충돌)
Bugs:
- MyBatisConfig: @MapperScan basePackages corrected to scan all com.ga.* by @Mapper annotation (was missing common.code/menu/system/file/notification)
- CalcRecruitStep: endDate was first day of month (only contracts on day 1 were picked); now full month range via DateUtil.getMonthRange
- EncryptTypeHandler: removed @MappedTypes(String.class) to prevent encrypting all String columns; now requires explicit per-column typeHandler
- mybatis-config.xml: removed redundant javaType for JsonTypeHandler (uses @MappedTypes)
V16 admin initial data:
- Child menus (24): ORG_TREE, ORG_AGENT, CONTRACT_LIST, COMPANY, PRODUCT,
RULE_*, RECEIVE_*, LEDGER_*, SETTLE_LIST, BATCH_RUN, PAYMENT, SYSTEM_*
- Permissions for each PAGE menu × {READ,CREATE,UPDATE,DELETE,APPROVE,EXPORT}
- SUPER_ADMIN: full grants
- ADMIN: all except SYSTEM
- MANAGER: READ/CREATE/UPDATE/EXPORT except SYSTEM
- AGENT: READ on LEDGER_*, SETTLE_LIST
- admin user (login_id=admin, pw=admin1234!) mapped to SUPER_ADMIN
GA Pro