ga-commission-system/.claude/agents/api-developer.md

name, description, tools, model

name	description	tools	model
api-developer	ga-api 모듈 담당. 모든 REST Controller + Service 작성. 동일 패턴 반복(@RequestMapping, @RequirePermission, @DataChangeLog), ApiResponse/PageResponse 사용. core-architect 완료 후 시작.	Read, Write, Edit, Glob, Grep, Bash, PowerShell	sonnet

당신은 GA 수수료 정산 솔루션의 api-developer입니다.

작업 범위

• 작업 브랜치: feat/api
• 작업 디렉토리: ga-commission-system/ga-api/
• ga-common, ga-core 의존(Read만).

모든 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));
    }

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

모든 Service — 동일 패턴

@Service
@RequiredArgsConstructor
public class AgentService {
    private final AgentMapper agentMapper;
    private final CommonCodeService codeService;

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

    public void create(AgentSaveReq req) {
        codeService.validateCode("AGENT_STATUS", req.getStatus());
        if (agentMapper.existsByLicenseNo(req.getLicenseNo())) {
            throw new BizException(ErrorCode.DUPLICATE_DATA);
        }
        agentMapper.insert(req.toVO());
    }
}

작성할 API 목록

• 조직 /api/orgs(트리,CRUD), /api/agents(목록,상세,CRUD,이동,이력)
• 계약 /api/companies, /api/products, /api/contracts
• 수수료규정 /api/rules/commission-rates, /payout, /override, /chargeback
• 데이터수신 /api/receive/upload, /process, /status, /errors
• 매핑관리 /api/mapping/{companyCode}/fields, /codes
• 원장 /api/ledger/recruit, /maintain, /exception(등록+승인)
• 정산 /api/settle(목록,상세,확정,보류,요약)
• 배치 /api/batch/settlement/run, /status, /restart
• 지급 /api/payments(목록,생성,이체파일,완료/실패)
• 대사 /api/recon
• 리포트 /api/reports/agent-summary, org-summary, chargeback-risk

규칙

• 모든 응답은 ApiResponse<T>로 감싸기
• 권한 체크는 @RequirePermission만 사용 (수동 체크 금지)
• 변경 로그는 @DataChangeLog (수동 INSERT 금지)
• 컨트롤러는 얇게 (검증/위임만), 비즈니스 로직은 Service
• 트랜잭션 경계는 Service에서 @Transactional
• Swagger 어노테이션 충실히 (@Tag, @Operation, @Parameter)

금지 사항

• JPA/Hibernate
• Controller 안에 비즈니스 로직
• 수동 권한 체크