feat: 1200%룰 이연 분급 도래월 지급(PayInstallmentStep) + 코드베이스 신입교육 주석

PayInstallmentStep(Step 4.5): 1200%룰로 이연된 분급(installment_plan SCHEDULED)을
도래월(settle_month=정산월)에 recruit_ledger로 편입해 실제 지급. 이전엔 이연만 되고
도래월 지급 절차가 없어 차액이 영구 미지급되던 갭을 메움.
- BatchConfig job flow에 step4b(calcRecruit→payInstallment→calcMaintain) 등록
- InstallmentPlanMapper.resetPaidToScheduledByMonth(+XML)로 재실행 멱등
  (진입 시 PAID→SCHEDULED 역산, Step4 deleteBySettleMonth가 원장 정리)
- RecruitLedgerMapper insert에 reconcile_status 컬럼, SettlementContext.installmentPaidCount
- 단위테스트 3건(정상지급/멱등/계약미존재) GREEN

신입교육 주석: 컨트롤러/서비스/공통/프론트 전반에 도메인·코드 설명 주석 추가
(동작 변경 없음 — 빌드/테스트/타입체크 전부 GREEN으로 무회귀 확인).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

ga-core/src/main/java/com/ga/core/mapper/installment/InstallmentPlanMapper.java

@@ -23,6 +23,9 @@ public interface InstallmentPlanMapper {
     /** 정산월의 SCHEDULED 분급 계획 조회 (배치 지급 처리용) */
     List<InstallmentPlanVO> selectScheduledByMonth(@Param("settleMonth") String settleMonth);
 
+    /** 정산월의 PAID 분급 계획을 SCHEDULED로 되돌림 (배치 재실행 멱등용) */
+    int resetPaidToScheduledByMonth(@Param("settleMonth") String settleMonth);
+
     int insert(InstallmentPlanVO vo);
 
     /** 7년치 분급 계획 일괄 생성 */

ga-core/src/main/resources/mapper/installment/InstallmentPlanMapper.xml

@@ -185,6 +185,13 @@
         WHERE plan_id = #{planId}
     </update>
 
+    <!-- 정산월의 PAID 분급을 SCHEDULED로 역산 (배치 재실행 멱등용) -->
+    <update id="resetPaidToScheduledByMonth">
+        UPDATE installment_plan
+        SET status = 'SCHEDULED', paid_amount = 0, paid_at = NULL, payment_id = NULL, updated_at = NOW()
+        WHERE settle_month = #{settleMonth} AND status = 'PAID'
+    </update>
+
     <!-- 계약 삭제 시 연관 분급 계획 일괄 삭제 -->
     <delete id="deleteByContract">
         DELETE FROM installment_plan WHERE contract_id = #{contractId}

ga-core/src/main/resources/mapper/ledger/RecruitLedgerMapper.xml

@@ -88,13 +88,13 @@
     <insert id="batchInsert">
         INSERT INTO recruit_ledger (contract_id, agent_id, policy_no, company_code, product_code,
             insurance_type, commission_year, premium, pay_method, company_rate, company_amount,
-            payout_rate, agent_amount, tax_amount, settle_month, status, version, created_at)
+            payout_rate, agent_amount, tax_amount, reconcile_status, settle_month, status, version, created_at)
         VALUES
         <foreach collection="list" item="r" separator=",">
             (#{r.contractId}, #{r.agentId}, #{r.policyNo}, #{r.companyCode}, #{r.productCode},
              #{r.insuranceType}, #{r.commissionYear}, #{r.premium}, #{r.payMethod},
              #{r.companyRate}, #{r.companyAmount}, #{r.payoutRate}, #{r.agentAmount}, #{r.taxAmount},
-             #{r.settleMonth}, COALESCE(#{r.status},'CALCULATED'), 1, NOW())
+             COALESCE(#{r.reconcileStatus},'PENDING'), #{r.settleMonth}, COALESCE(#{r.status},'CALCULATED'), 1, NOW())
         </foreach>
     </insert>