Feat: Auto-Generate Token Number for Queue-Based Patient Appointments

[md-umair-21]

Previously, in Patient Appointment, there was no field to store a token number for queue-based consultations. When Appointment Based on Check-In was enabled, the system only generated position_in_queue after the Check-In button was pressed.

Because of this, the front desk/receptionist could not issue a token number at the time of booking, which is a common workflow in hospitals and clinics where patients are given a token immediately when the appointment is created.

This PR adds token support for queue-based Patient Appointments.

Changes Introduced:-
1.A new read-only field has been introduced on Patient Appointment:
token_number (Int, non-negative, read-only)
Visible only when appointment_based_on_check_in is enabled (depends_on condition)

Behavior Added:-
1.Token number is auto-generated at booking/save time (not on Check-In)
2.Applies only for queue-based appointments (appointment_based_on_check_in = 1)
3.Scope logic aligns with existing queue scope patterns used for appointment ordering
4.Existing position_in_queue logic remains unchanged

Example Scenario
Receptionist books appointments for a practitioner who uses queue-based consultation.

At booking/taking appointment:
Patient A → Token 1
Patient B → Token 2
Patient C → Token 3

no-docs

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 0ad6fa98-ea3c-4834-9259-d76da24facf9

📥 Commits

Reviewing files that changed from the base of the PR and between 8952c19 and 17ada90.

📒 Files selected for processing (1)

• healthcare/healthcare/doctype/patient_appointment/patient_appointment.py

🚧 Files skipped from review as they are similar to previous changes (1)

• healthcare/healthcare/doctype/patient_appointment/patient_appointment.py

---

Walkthrough

A new read-only, non-negative integer field token_number was added to Patient Appointment and is visible when appointment_based_on_check_in is enabled. A set_token_number() method assigns sequential token numbers per matching appointment filters (date plus practitioner/time or service unit/department). Per-appointment locking helpers (_get_token_lock_name, _acquire_token_lock, _release_token_lock) were added and set_token_number() is called during validation.

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding auto-generation of token numbers for queue-based patient appointments, which is the primary focus of the entire changeset.
Description check	✅ Passed	The description is directly related to the changeset, explaining the problem statement, solution, and specific changes introduced including the new token_number field and auto-generation behavior.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 71fb52a3-1a23-4db8-bfa0-887c34bccfdc

📥 Commits

Reviewing files that changed from the base of the PR and between 4f276a5 and e19f9ee.

📒 Files selected for processing (2)

• healthcare/healthcare/doctype/patient_appointment/patient_appointment.json
• healthcare/healthcare/doctype/patient_appointment/patient_appointment.py

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@healthcare/healthcare/doctype/patient_appointment/patient_appointment.py`:
- Around line 478-489: The MySQL GET_LOCK is being released too early (in
validate), causing races; update the locking strategy used by
_acquire_token_lock/_release_token_lock and the token assignment path so the
lock remains until commit: either (A) stop using session GET_LOCK in validate
and instead obtain row-level locks by performing the MAX(token_number) query
with SELECT ... FOR UPDATE inside the same DB transaction that creates the
appointment (adjust the token-generation function that calls
_acquire_token_lock), or (B) if you keep GET_LOCK, record the lock_name on the
document instance when calling _acquire_token_lock and defer calling
_release_token_lock until after commit (e.g., release in an
on_update/on_update_after_commit hook), ensuring the lock is held for the whole
transaction; reference _acquire_token_lock and _release_token_lock and the
token-assignment codepath when applying the change.
- Around line 465-476: The lock name generated by _get_token_lock_name includes
appointment_time unconditionally but set_token_number only scopes by
appointment_time for Practitioner appointments, causing mismatched lock scopes
and possible duplicate tokens; modify _get_token_lock_name to build the scope
key conditionally: include appointment_time only when appointment_for ==
"Practitioner" (or otherwise when set_token_number will filter by time), so the
lock scope exactly matches the query scope used in set_token_number; also
replace SHA1 with a non-cryptographic deterministic short hash (e.g.,
zlib.adler32 or hashlib.md5) to avoid static-analysis SHA1 warnings while
preserving a stable lock name.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 17905419-e498-4837-be64-3b9e13bce72e

📥 Commits

Reviewing files that changed from the base of the PR and between e19f9ee and 8952c19.

📒 Files selected for processing (1)

• healthcare/healthcare/doctype/patient_appointment/patient_appointment.py

[md-umair-21]

Hi @Sajinsr
Could you please check this PR when you are free and let me know if there are any changes to be made.