ga-commission-system/docs/05_API_SPEC.md

05_API_SPEC — ga-api (REST API)

모든 Controller / Service 가 동일한 패턴으로 작성된다. 신입이 복붙 후 테이블명/필드명만 바꾸면 새 화면이 완성되도록.

패키지 구조

ga-api/src/main/java/com/ga/api/
├── GaApiApplication.java                       # @SpringBootApplication(scanBasePackages = "com.ga")
├── auth/
│   ├── AuthController.java                     # /api/auth/*
│   └── AuthService.java
├── controller/
│   ├── batch/    BatchTriggerController.java
│   ├── ledger/   LedgerController.java          # 모집/유지/예외 통합
│   ├── org/      OrganizationController.java, AgentController.java
│   ├── product/  CompanyController.java, ProductController.java, ContractController.java
│   ├── receive/  ReceiveController.java
│   ├── rule/     RuleController.java
│   ├── settle/   SettleController.java, PaymentController.java
│   └── system/   UserController.java, RoleController.java
└── service/
    └── (controller 미러 구조 — XxxService.java)

build.gradle:

apply plugin: 'org.springframework.boot'
bootJar { archiveFileName = 'ga-api.jar'; mainClass = 'com.ga.api.GaApiApplication' }
jar.enabled = false
dependencies {
    implementation project(':ga-core')
}

application.yml 은 01_DB_SCHEMA.md 의 yml + server.port: 8080.

---

1. 표준 Controller 패턴

@RestController
@RequestMapping("/api/agents")
@Tag(name = "설계사 관리")
@RequiredArgsConstructor
public class AgentController {

    private final AgentService agentService;

    @GetMapping
    @RequirePermission(menu = "ORG_AGENT", perm = "READ")
    public ApiResponse<PageResponse<AgentResp>> list(AgentSearchParam param) {
        return ApiResponse.ok(agentService.list(param));
    }

    @GetMapping("/{id}")
    @RequirePermission(menu = "ORG_AGENT", perm = "READ")
    public ApiResponse<AgentResp> detail(@PathVariable Long id) {
        return ApiResponse.ok(agentService.detail(id));
    }

    @PostMapping
    @RequirePermission(menu = "ORG_AGENT", perm = "CREATE")
    @DataChangeLog(menu = "ORG_AGENT", table = "agent")
    public ApiResponse<Long> create(@Valid @RequestBody AgentSaveReq req) {
        return ApiResponse.ok(agentService.create(req));
    }

    @PutMapping("/{id}")
    @RequirePermission(menu = "ORG_AGENT", perm = "UPDATE")
    @DataChangeLog(menu = "ORG_AGENT", table = "agent")
    public ApiResponse<Void> update(@PathVariable Long id, @Valid @RequestBody AgentSaveReq req) {
        agentService.update(id, req); return ApiResponse.ok();
    }

    @PatchMapping("/{id}/status")
    @RequirePermission(menu = "ORG_AGENT", perm = "UPDATE")
    @DataChangeLog(menu = "ORG_AGENT", table = "agent")
    public ApiResponse<Void> updateStatus(@PathVariable Long id, @RequestParam String status) {
        agentService.updateStatus(id, status); return ApiResponse.ok();
    }

    @GetMapping("/export")
    @RequirePermission(menu = "ORG_AGENT", perm = "EXPORT")
    public void export(AgentSearchParam p, HttpServletResponse res) {
        agentService.exportExcel(p, res);
    }
}

규칙:

1. 클래스 어노테이션: @RestController @RequestMapping @Tag @RequiredArgsConstructor
2. 메서드 어노테이션: @RequirePermission + (CUD 일 때) @DataChangeLog
3. 응답: ApiResponse<T> / ApiResponse<PageResponse<T>> / ApiResponse<Void>
4. 요청 바디: @Valid @RequestBody XxxSaveReq
5. 검색: XxxSearchParam (쿼리 파라미터로 자동 바인딩)
6. PathVariable: id 는 Long
7. 엑셀 export 는 void + HttpServletResponse 직접 사용

---

2. 표준 Service 패턴

@Service @RequiredArgsConstructor
public class AgentService {
    private final AgentMapper mapper;
    private final CommonCodeService codeService;
    private final AgentMapstruct mapstruct;
    private final ExcelService excelService;

    public PageResponse<AgentResp> list(AgentSearchParam param) {
        param.startPage();
        return PageResponse.of(mapper.selectList(param));
    }

    public AgentResp detail(Long id) {
        AgentResp r = mapper.selectDetailById(id);
        if (r == null) throw new BizException(ErrorCode.NOT_FOUND);
        return r;
    }

    @Transactional
    public Long create(AgentSaveReq req) {
        if (req.getLicenseNo() != null && mapper.existsByLicenseNo(req.getLicenseNo()) > 0)
            throw new BizException(ErrorCode.DUPLICATE_DATA);
        AgentVO vo = mapstruct.toVO(req);
        vo.setStatus("ACTIVE");
        mapper.insert(vo);
        return vo.getAgentId();
    }

    @Transactional
    public void update(Long id, AgentSaveReq req) {
        AgentVO vo = mapper.selectById(id);
        if (vo == null) throw new BizException(ErrorCode.NOT_FOUND);
        mapstruct.update(vo, req);
        mapper.update(vo);
    }

    @Transactional
    public void updateStatus(Long id, String status) {
        codeService.validateCode("AGENT_STATUS", status);
        mapper.updateStatus(id, status);
    }

    public void exportExcel(AgentSearchParam p, HttpServletResponse res) {
        excelService.exportLargeExcel("설계사목록", AgentExcelVO.class,
                () -> mapper.selectCursorForExcel(p), res);
    }
}

규칙:

1. Service 는 Mapper + 다른 Service 만 의존 (Controller 직접 호출 X)
2. CUD 메서드는 @Transactional
3. 공통코드 검증은 codeService.validateCode(group, code)
4. 중복 검증 → DUPLICATE_DATA, 미존재 → NOT_FOUND
5. 엑셀은 excelService.exportLargeExcel(fileName, ExcelVO.class, cursorSupplier, response)

---

3. API 엔드포인트 목록 (현재 구현된 것)

인증 (AuthController — /api/auth)

• POST /login — {loginId, password} → {accessToken, refreshToken, user} + login_log 적재
• POST /refresh — refresh 토큰으로 access 갱신
• POST /logout — 클라이언트 토큰 폐기 (서버는 로그만)
• GET /me — 현재 사용자 + 역할 + 메뉴 트리

조직 / 설계사

• OrganizationController /api/orgs
  • GET /tree — 트리 (CTE 재귀)
  • GET /{id} / POST / PUT /{id} / DELETE /{id}
• AgentController /api/agents
  • GET (검색+페이징) / GET /{id} / POST / PUT /{id}
  • PATCH /{id}/status / PATCH /{id}/transfer (조직/직급 변경)
  • GET /{id}/history (조직/직급 이력)
  • GET /export (엑셀 다운로드)

보험상품 / 계약

• CompanyController /api/companies — 보험사 5 건 CRUD
• ProductController /api/products — 보험사 × 상품
• ContractController /api/contracts — 검색/CRUD/엑셀, policy_no 중복검증

수수료 규정

• RuleController /api/rules
  • GET /commission-rates, POST, PUT /{id}, DELETE /{id}
  • GET /payout-rules, ... 동일 패턴
  • GET /override-rules, GET /chargeback-rules, GET /exception-codes

데이터 수신 / 매핑

• ReceiveController /api/receive
  • POST /upload?companyCode=&dataType= — multipart 업로드 → raw_commission_data 적재
  • POST /process?companyCode=&settleMonth= — MappingEngine 으로 변환 호출
  • GET /status?companyCode=&settleMonth= — 진행 현황
  • GET /errors?companyCode=&resolveStatus= — 에러 목록
  • PATCH /errors/{errorId}/resolve — 에러 해결 처리
  • 매핑 관리: GET /mapping/{companyCode}/fields, POST/PUT/DELETE

원장 (LedgerController /api/ledger — 통합)

• GET /recruit (검색+페이징) / GET /recruit/export (엑셀)
• GET /maintain, GET /exception — 동일 패턴
• POST /exception — 예외금액 등록 (수동)
• PATCH /exception/{id}/approve — 승인 (@RequirePermission perm=APPROVE)
• PATCH /exception/{id}/reject — 반려

정산

• SettleController /api/settle
  • GET (월별 검색) / GET /{id} / GET /summary?settleMonth=
  • PATCH /{id}/confirm (@RequirePermission APPROVE) — @Transactional, version 체크 → RULE_VERSION_CONFLICT 가능
  • PATCH /{id}/hold {reason}
• PaymentController /api/payments
  • GET 검색 / POST 이체 생성 (settle_master.status='CONFIRMED' 인 것만)
  • POST /{id}/transfer-file 이체파일 생성
  • PATCH /{id}/success, PATCH /{id}/fail

배치 트리거 (BatchTriggerController /api/batch)

• POST /settlement/run?settleMonth=&companyCode= — batch_job_log 적재 + ga-batch 트리거
• GET /settlement/status?jobLogId= — 진행 상태
• POST /settlement/restart?jobLogId=&fromStep= — 재실행 (선택 구현)

시스템관리

• UserController /api/system/users
  • GET / POST / PUT /{id} / DELETE /{id}
  • PATCH /{id}/reset-password — 임시 비밀번호 발급 (이메일/알림)
  • PATCH /{id}/unlock — 잠금 해제
  • PUT /{id}/roles — 역할 매핑
• RoleController /api/system/roles
  • 역할 CRUD + GET /{id}/permissions (메뉴 × 권한 매트릭스)
  • PUT /{id}/permissions (전체 매트릭스 갱신)

공통 (ga-common 에 위치하지만 ga-api 가 노출)

• MenuController /api/menus — GET /my, GET /tree, CRUD
• CommonCodeController /api/common/codes — 그룹/상세 CRUD
• FileController /api/files — 업로드/다운로드/목록
• NotificationController /api/notifications — 목록/읽음
• SystemConfigController /api/system/config — 시스템 설정
• SystemLogController /api/system/logs — 로그인/API/변경 이력

---

4. 인증 / 권한 흐름

1. 로그인: POST /api/auth/login → JWT 발급
2. 헤더: 모든 요청에 Authorization: Bearer <token>
3. JwtAuthFilter: SecurityContext 에 LoginUser 주입
4. @RequirePermission: PermissionAspect 가 role_menu_permission 조회 → 없으면 FORBIDDEN
5. @DataChangeLog: 변경 전/후 데이터 비교 후 data_change_log JSONB 비동기 적재
6. ApiLogAspect: 모든 요청 api_access_log 비동기 적재 (민감정보 마스킹)

---

5. 응답 표준

성공

{
  "success": true, "code": "0000", "message": "OK",
  "data": { ... }, "timestamp": "2026-05-10T12:34:56"
}

페이징

{
  "success": true, "code": "0000",
  "data": {
    "list": [...], "pageNum": 1, "pageSize": 20, "total": 123, "pages": 7
  }
}

실패

{
  "success": false, "code": "B009", "message": "중복된 데이터입니다",
  "data": null, "timestamp": "..."
}

---

6. 테스트 (선택)

• MockMvc 기반 Controller 테스트
  • @WebMvcTest(AgentController.class) + @MockBean AgentService
  • 인증/권한 검증 (403 응답)
  • 요청 바디 검증 (@Valid 실패 시 400)
• WireMock 으로 ga-batch 호출 stub