fix(etl): refresh amount validation on current develop

[seonghobae]

Purpose

Preserve monetary data integrity at the synchronous ETL boundary. Invalid or unsupported AMOUNT inputs fail closed instead of being converted into the legitimate value 0.00; one invalid amount rejects the complete batch before any processed_data target write.

Exact current identity

• protected/live base: develop@d6c6665163eabe1b5eca80556c6963bafd6b2625;
• branch: repair/amount-integrity-feaea5d;
• exact current head: 3e58774a7517a7a359b6e7327b4c851d8e00c14e;
• current head descends from the prior current-base candidate dcd671488d6a72e886dd557816c18ed303668751 without rewriting history;
• current diff remains the bounded amount-validation source, tests, operator documentation, and changelog slice;
• Draft: true while fresh exact-head checks run.

No predecessor-head check, review, or approval transfers to the current source head.

Implemented boundary

• AMOUNT accepts numeric JSON values and numeric strings only;
• malformed, blank, excessive-precision, extreme-scale, null, boolean, object, and array values fail as INVALID_RECORD;
• genuine numeric and string zero inputs remain accepted and deterministically become 0.00;
• all records are transformed before target persistence, so one invalid amount causes zero processed_data writes for the whole batch;
• BigDecimal, bounded precision/scale, HALF_UP, scale 2, and toPlainString() remain the deterministic representation contract;
• no source value, payload, database diagnostic, or credential is added to ordinary logging;
• historical reconciliation guidance records that previously manufactured zeroes cannot be distinguished from genuine zeroes without independent source-system evidence.

Review remediation

The current source already addresses the CodeRabbit JSON-type finding with focused null, object, array, boolean, numeric, numeric-string, and genuine-zero tests. The latest documentation follow-up also resolves the remaining JDBC-order finding without changing replay semantics:

• direct batches validate before any target-table write;
• idempotent requests may acquire the transaction-scoped request lock and read the replay ledger before validating a new payload;
• invalid input still creates no processed_data target write and no successful idempotency replay record;
• operator documentation and its contract test now distinguish target-data writes from idempotency control-plane JDBC access.

Both current review threads are resolved. A fresh exact-head independent review is still required.

Current verification state

Fresh exact-current-head CI, Dependency Review, CycloneDX SBOM, SAST Semgrep, and Security Scan were triggered by the review remediation. Pending or predecessor-head results are not accepted as passing.

Keep Draft until the unchanged exact head has terminal-success applicable checks, non-vacuous owned-production coverage, zero valid unresolved findings, and qualifying independent formal review where live governance requires it. Stale predecessor PR #310 remains historical until exact unique-work preservation and supersession are revalidated.

[coderabbitai]

📝 Walkthrough

Walkthrough

AMOUNT 형식 오류와 허용 범위 위반을 INVALID_RECORD로 거부하도록 변경했습니다. 오류가 있는 배치는 JDBC 호출 전에 전체 실패합니다. 테스트, 런북, 변경 로그가 새 계약을 반영합니다.

Changes

ETL 금액 무결성

Layer / File(s)	Summary
금액 검증 및 배치 차단 etl-service/src/main/java/com/xtrmetl/etl/service/EtlService.java, etl-service/src/test/java/com/xtrmetl/etl/service/*	formatAmount가 잘못된 형식, 과도한 정밀도, 극단적 스케일, 지수 형식의 금액을 INVALID_RECORD로 거부합니다. 오류가 있는 배치는 JDBC 쓰기 없이 실패합니다. 유효한 금액은 기존처럼 소수점 둘째 자리로 반올림합니다.
금액 무결성 문서 및 계약 검증 docs/etl/bounded-atomic-batches.md, CHANGELOG.md, etl-service/src/test/java/com/xtrmetl/etl/documentation/EtlBatchDocsAlignmentTest.java	런북과 변경 로그가 잘못된 금액의 사전 거부, 배치 전체 실패, 실제 0.00과의 구분, 모니터링 및 제한된 진단 기록 지침을 설명합니다. 문서 정합성 테스트가 해당 내용을 검증합니다.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Mergeability Score: 🟠 High · up to bfbf1

The change adds AMOUNT validation, but null, object, and array values can still bypass the check and be stored, creating a concrete data-integrity risk; merge should wait until this validation path is corrected. The idempotent-request documentation also needs to clarify whether validation must occur before its first database call.

Possibly related issues

• ContextualWisdomLab/mightyETL#198: EtlService.formatAmount의 fail-closed 검증과 관련 테스트 및 문서 변경을 다룹니다.

Suggested labels: manual-merge

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 ETL 금액 검증 변경을 명확히 나타내며, 변경사항의 주요 목적과 일치합니다.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch repair/amount-integrity-feaea5d

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

etl-service/src/test/java/com/xtrmetl/etl/service/EtlServiceAmountIntegrityTest.java (1)

32-48: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

실제 0 값의 회귀 경로를 추가하세요.

현재 parameterized test는 모두 거부해야 하는 입력만 검증합니다. 런북과 변경 로그는 잘못된 입력과 실제 0 값의 구분을 계약으로 선언합니다. amount:"0"이 AMOUNT:0.00으로 저장되고 JDBC가 한 번 호출되는지 추가로 검증하세요.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@etl-service/src/test/java/com/xtrmetl/etl/service/EtlServiceAmountIntegrityTest.java`
around lines 32 - 48, Extend the amount integrity tests around
rejectsInvalidOrUnsupportedAmountsBeforeJdbc with a separate valid-zero case for
amount "0". Verify processing succeeds, the persisted AMOUNT is 0.00, and
jdbcTemplate is invoked exactly once, while keeping zero excluded from the
rejection inputs.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/etl/bounded-atomic-batches.md`:
- Around line 47-48: 문서의 “첫 JDBC 호출 전” 계약이 적용되는 경로를 명시하세요. 현재
processDataIdempotently는 prepareBatch 전에 requestLock.tryLock 및
findStoredIdempotencyRecord를 호출하므로, 계약을 processData에만 제한한다면 문서에 그 범위를 분명히 적고, 멱등
요청에도 적용하려면 ledger 조회 전에 배치 검증을 수행하도록 processDataIdempotently 흐름을 변경한 뒤 잘못된
AMOUNT가 target write를 차단하는 테스트를 추가하세요.

In `@etl-service/src/main/java/com/xtrmetl/etl/service/EtlService.java`:
- Around line 403-415: Update the AMOUNT handling in transformValue to validate
the JSON node type before null or container values are returned, accepting only
numeric nodes and numeric strings and rejecting null, objects, arrays, and other
types with invalidRecord(). Add tests covering each rejected JSON type and valid
numeric inputs.

---

Nitpick comments:
In
`@etl-service/src/test/java/com/xtrmetl/etl/service/EtlServiceAmountIntegrityTest.java`:
- Around line 32-48: Extend the amount integrity tests around
rejectsInvalidOrUnsupportedAmountsBeforeJdbc with a separate valid-zero case for
amount "0". Verify processing succeeds, the persisted AMOUNT is 0.00, and
jdbcTemplate is invoked exactly once, while keeping zero excluded from the
rejection inputs.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c74b4d6a-dd5a-450c-9e91-66f131762054

📥 Commits

Reviewing files that changed from the base of the PR and between feaea5d and bfbf116.

📒 Files selected for processing (7)

• CHANGELOG.md
• docs/etl/bounded-atomic-batches.md
• etl-service/src/main/java/com/xtrmetl/etl/service/EtlService.java
• etl-service/src/test/java/com/xtrmetl/etl/documentation/EtlBatchDocsAlignmentTest.java
• etl-service/src/test/java/com/xtrmetl/etl/service/EtlServiceAmountIntegrityTest.java
• etl-service/src/test/java/com/xtrmetl/etl/service/EtlServiceBatchSafetyTest.java
• etl-service/src/test/java/com/xtrmetl/etl/service/EtlServiceTest.java

[seonghobae]

@coderabbitai review

[coderabbitai]

Rate Limit Exceeded

@seonghobae have exceeded the limit for the number of chat messages per hour. Please wait 31 minutes and 46 seconds before sending another message.