feat(kyp): add pending KYP endpoint and service logic

Overview

Added a new Pending KYP API endpoint and supporting service logic to identify patients registered to the current camp whose Know Your Patient (KYP) form is either never filled or incomplete.

---

What does this MR do and why?

Volunteers needed a quick way to identify patients who have not completed their KYP forms during the current camp.

This MR introduces a dedicated backend endpoint that:

• Filters only patients registered to the current active camp
• Identifies KYP status as "never filled" or "incomplete"
• Returns only relevant patients for action

This improves operational efficiency and avoids manual tracking.

---

Changes Made

• Added kyp_routes.py — new route file with GET /kyp/pending endpoint
• Added kyp_service.py — service logic to fetch pending KYP patients
• Updated api.py — registered new router with prefix /kyp
• Updated patient_service.py — fixed created_at to store datetime.now(timezone.utc)

---

Technical Details

• get_pending_kyp():

  • Fetches patients registered to the current active camp
  • Orders by CampVisit.created_at ASC (FIFO)

• KYP validation:

  • Checks only:
    • work_profile
    • life_style
  • Excludes:
    • allergies
    • chronic_history

• Helper functions:

  • _is_missing() → recursive check for null/empty/NA
  • _has_missing_value() → detects missing fields

• Status logic:

  • Both sections missing → "never filled"
  • Any field missing → "incomplete"
  • Fully filled → excluded

---

Type of Change

• 🐛 Bug fix
• ✨ New feature
• 💥 Breaking change
• 📝 Documentation update
• ♻️ Refactor
• ⚡ Performance improvement
• 🧪 Test update
• 🔧 Configuration change
• 🚨 Security fix
• 🗑️ Deprecation

---

Related Issues / References

N/A

---

Screenshots or Screen Recordings

• Swagger /docs showing GET /api/v1/kyp/pending
• Successful API response

---

How to Validate Locally

1. Pull this branch
2. Install dependencies
3. Run backend server
4. Open http://localhost:8000/docs
5. Authorize with volunteer/admin/coordinator token
6. Call GET /api/v1/kyp/pending

Expected Behavior

• Returns patients:
  • Registered to current camp
  • With status "never filled" or "incomplete"
• Fully completed KYP → not returned

---

Testing Done

• Unit tests added/updated
• API endpoint tests passing

Test Cases Covered:

Scenario	Expected Result	Status
KYP never filled	Shows "never filled"	✅
KYP partially filled	Shows "incomplete"	✅
KYP fully filled	Not shown	✅
Not in current camp	Not shown	✅
Completed in previous camp	Not shown	✅
Volunteer access	200 OK	✅
Admin access	200 OK	✅

---

Code Quality Checklist

Code Standards

• Follows conventions
• No debug code
• No unused imports
• DRY followed
• Proper type hints

Python & FastAPI

• Single responsibility
• Async used correctly
• Dependency injection used
• Pydantic models used
• Optimized queries
• Error handling done

API Design

• RESTful
• Correct status codes
• Input validation
• Auth + RBAC enforced
• Docs updated

Database

• No schema changes
• ORM used
• Data integrity maintained

Security

• No sensitive logs
• SQL injection safe
• Secure token handling

Error Handling

• Graceful handling
• Proper logging
• Standard responses

---

Documentation

• README updated
• .env.example updated
• API docs updated
• CHANGELOG

---

Known Limitations / Technical Debt

• Records with created_at = null may break FIFO ordering
• DB backfill needed for old data
• allergies and chronic_history not validated

---

Additional Notes

• No existing functionality changed
• Only new endpoint + logic added
• Used by frontend via /api/v1/kyp/pending

---

MR Acceptance Checklist

Quality & Correctness

• Works correctly
• No regressions
• Edge cases handled

Maintainability

• Clean and readable
• Well-structured
• Follows patterns

Acceptance Review

• Reviewed by teammate
• Reviewed by product owner

---