feat(letters): add urgency + days_remaining to GET /api/letters (KLAR-T3) - #23
Open
aircode610 wants to merge 5 commits into
Open
aircode610 wants to merge 5 commits into
aircode610 wants to merge 5 commits into
Conversation
added 5 commits
September 10, 2026 19:50
…s_remaining (KLAR-T3)
…ency util (KLAR-T3)
…(KLAR-T3 review 1) Blocking issue 1: compute_days_remaining and compute_urgency each called date.today() independently, so a midnight rollover between the two calls could yield a contradictory pair (e.g. days_remaining=8, urgency=red). Added urgency_for_deadline(deadline_date) which snapshots date.today() once and derives both values from that single snapshot; list_letters now uses it instead of calling the two functions separately. compute_urgency/ compute_days_remaining are kept as-is for existing single-value callers. Blocking issue 2: no test asserted the actual GET /api/letters response shape. Added test_list_letters_response_includes_days_remaining_and_urgency, which calls the list_letters handler directly (Session(engine) + real User/ Letter rows with varying deadlines, same pattern as test_scanned_pdf_graceful.py's _call_post_letter) and asserts each returned LetterListItem carries both days_remaining and urgency with correct values across all three colors plus the no-deadline case. Also added a regression test simulating a mid-computation clock rollover to pin the atomicity guarantee.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds two computed fields (
days_remainingandurgency) to the GET/api/lettersresponse to help users quickly assess deadline criticality at a glance.Changes
1. Shared Urgency Utilities (
backend/services/urgency.py)compute_days_remaining(deadline_date: str | None) -> int | None: Returns days until deadline, or None if no deadlinecompute_urgency(days_remaining: int | None) -> str: Maps days to urgency level2. Schema Update (
backend/schemas/letters.py)days_remaining: int | Noneandurgency: strtoLetterListItemdataclass3. Endpoint Update (
backend/app/routes/letters.py)/api/lettersto compute and include urgency + days_remaining for each letter item4. Test Coverage (
backend/tests/)compute_days_remaining()andcompute_urgency()(4 cases: red, yellow, green, no deadline)Blocking Issues & Fixes
Issue #1: Initial Test Failures
compute_days_remaining()returning wrong calculation(deadline - today).dayscorrectlye3268ae test(urgency): add failing unit tests...Issue #2: Response Structure & Endpoint Integration
ed152b8 fix(letters): atomic days_remaining/urgency + endpoint response test...Verification
✅ Gate check:
npm run testpasses (unit + integration tests)✅ Spec compliance: All 6 acceptance criteria met:
days_remainingandurgencycompileallgate passesRelates to