Skip to content

fix: refactor(book-no, seeding, patient-flow, family): unify book_no lifecycle, stabilize seeding, and align family APIs

Surya Manoj Pentakota requested to merge book_no_and_family into develop

Title (semantic)

refactor(book-no, seeding, patient-flow, family): unify book_no lifecycle, stabilize seeding, and align family APIs

Description

This merge request is a cumulative refactor across patient creation, book number lifecycle, seeding, role protection, and family APIs.

Primary goal: make book_no handling deterministic and production-aligned, while also aligning family endpoints with book_no-driven flows and stricter relationship modeling.

This merge request has two major changes:

  1. Auto Book Number Generate:

  1. refactoring book-no by adding book no to user table so all users have book_no as a primary identifier (for now did not removed the book_no in patients table to disturb the current implementation and will have refactor the complete implementation to use book numbers from user table

  2. added patient role to all users as default and created patient records for these new users.

  3. service for auto generating book no to fill the gaps btw the current sequence of book numbers and maintaining book number geneartion in sequence.

  1. Family Tracking:

    1)added routes for family tracking so that we can create families using the book_no and assign the family roles like Head, spouse, child, parent.

Key Changes

1️⃣ Patient Creation Logic Refactor (patient_service.py)

  • Simplified create_patient() flow.
  • Uses generate_book_no() when book_no is not provided.
  • Calls remove_book_no() only when book_no was auto-generated.
  • Removed duplicate user creation logic.
  • Fixed patient.book_no vs generated book_no_to_use inconsistencies.
  • Standardized patient role assignment.
  • Improved transactional ordering (flush -> commit -> cleanup).

Impact: Prevents duplicate users, fixes wrong book_no assignment, and preserves gap-table correctness.

2️⃣ Gap-Aware Seeding (Production-Accurate Book No Flow)

Introduced/updated:

  • SeedUserFactory
  • reset_book_no_state()
  • create_patient_profiles_for_users()

Improvements:

  • Seeded users now follow the same book_no lifecycle as production.
  • book_no_gaps is consumed correctly during seeding.
  • book_no_seq resets on --clear.
  • Patient profiles are consistently mapped to users.book_no.
  • Removed inconsistent seed-time book_no generation shortcuts.

Impact: Seeded DB behavior now mirrors production behavior.

3️⃣ Database Reset Stability

reset_book_no_state() now:

  • Clears book_no_gaps
  • Resets book_no_seq
  • Prevents post-reseed sequence drift

Impact: Avoids duplicate book numbers and gap/sequence corruption.

4️⃣ Role Protection Hardening

Added test coverage for patient role enforcement:

  • test_remove_role_rejects_patient_role_removal

Behavior now:

  • Removing patient role is explicitly rejected (HTTP 400).
  • Service layer is not invoked for this invalid operation.

Impact: Prevents invalid state (patient records without patient role).

5️⃣ Family Module Alignment (Book No Driven)

Family endpoints were refactored to match current book_no-first architecture:

  • Removed duplicated route segment (/family/family/... -> /family/...).
  • Fixed route shadowing so /family/my-families is matched correctly.
  • Replaced user_id-driven member operations with book_no where needed.

Updated behavior:

  • POST /api/v1/family/
    • Query: book_no, family_role
    • Can create family with role directly (head not mandatory at creation).
  • POST /api/v1/family/members
    • Query: family_id, book_no, family_role
  • PUT /api/v1/family/{family_id}/user/{book_no}
    • Query: family_role
  • DELETE /api/v1/family/{family_id}/user
    • Query: book_no

Also enforced cross-family membership checks and family existence checks in service layer.

6️⃣ Family Role Model Simplification

Family relationship options were narrowed across schema + dropdowns + service validation to:

  • head
  • spouse
  • child
  • parent

Removed deprecated/extra variants (son, daughter, parents, grandparent, grandparents).

Why This Refactor Was Needed

Previously:

  • Book number generation/consumption paths were inconsistent.
  • Seeding bypassed production lifecycle assumptions.
  • Patient/user/profile alignment could drift.
  • Family routes mixed user_id and book_no patterns inconsistently.
  • Route structure had duplication and path conflicts.
  • Family role taxonomy was broader than required product behavior.

This refactor makes book_no and family flows deterministic, gap-safe, and operationally consistent.

Backward Compatibility

  • Non-family APIs remain backward-compatible.
  • Family API contracts were tightened/updated (path/query parameter shape changes), so consumers of old family endpoints must adjust.
  • No new DB-breaking schema migration introduced for family-role API updates (migration chain remains stable).

Testing

  • Added/updated tests for patient-role protection.
  • Verified seed flow with --clear.
  • Verified patient creation with:
    • provided book_no
    • auto-generated book_no
    • existing user reuse
  • Verified route matching for:
    • /family/my-families
    • /family/{family_id}
    • updated member update/remove endpoints

Result

  • Deterministic book_no lifecycle
  • Production-aligned seeding
  • Stronger data integrity
  • Cleaner service logic
  • Family APIs aligned to book_no-first usage
  • Reduced technical debt

Related Issue(s)

Closes #49 (closed)

Edited by Lakshy Yarlagadda

Merge request reports