Highest Feature: TPT (TB Preventive Treatment) Follow-up
Scope of this ticket
Build the following backend APIs to support the TPT Follow-up dynamic form:
- Dynamic Form / Master Data API – returns field config + dropdown options for rendering the TPT form (Regimen Type, TPT Outcome, Place of Death, etc.)
- TPT Follow-up Save API – persists a single follow-up visit record against a beneficiary's ongoing TPT treatment
- TPT Recommended List API – returns beneficiaries with status "Recommended for TPT" for the landing screen line list
- TPT Follow-up History API – returns the visit history for a given beneficiary's TPT treatment
1. Master Data / Dynamic Form Config API
Endpoint (proposed): flw-api/tpt/formConfig
Should return static dropdown options used by the client to render the form:
| Field | Options |
|---|---|
| Regimen Type | 6H, 3RH, 3HP, 6Lfx, 4R, 1HP |
| Adherence to Medicines | Regular, Irregular |
| TPT Outcome | Cured, Failed, Lost to Follow-up (LFU), Death |
| Place of Death | Home, Subcenter, PHC, CHC, District Hospital, Medical College Hospital, Private Hospital, Other Place |
2. TPT Follow-up Save API
Endpoint (proposed): flw-api/tpt/followUp/save
| Sr. No | Parameter | Type | Mandatory | Validation / Logic |
|---|---|---|---|---|
| 1 | beneficiaryId | Long | Yes | Must reference an existing beneficiary recommended for TPT |
| 2 | regimenType | String | Yes | One of: 6H, 3RH, 3HP, 6Lfx, 4R, 1HP |
| 3 | treatmentStartDate | Date | Yes | >= TB Identification/Diagnosis visit date; <= today |
| 4 | expectedTreatmentCompletionDate | Date (server calculated) | Auto | Derived from treatmentStartDate + regimenType: 6H → +1 month 3RH, 3HP → +3 months 1HP, 4R → +6 months 6Lfx → +4 months |
| 5 | followUpDate | Date | Yes (per visit) | >= treatmentStartDate; > last follow-up date; <= today; max 1 follow-up per calendar month |
| 6 | monthlyFollowUpDone | Integer (Month-1 to Month-6, server calculated) | Auto | Incremented based on sequential monthly follow-ups |
| 7 | adherenceToMedicines | String | Yes | Regular / Irregular |
| 8 | anyDiscomfort | Boolean | Yes | true / false |
| 9 | treatmentCompleted | Boolean | Yes | true / false |
| 10 | actualTreatmentCompletionDate | Date | Conditional | Enabled/required only if treatmentCompleted = true; must be > last follow-up date |
| 11 | tptOutcome | String | Conditional | Cured / Failed / Lost to Follow-up (LFU) / Death – required when treatmentCompleted = true |
| 12 | dateOfDeath | Date | Conditional | Mandatory only if tptOutcome = Death; <= today; >= treatmentStartDate or > last follow-up date |
| 13 | placeOfDeath | String | Conditional | Mandatory only if tptOutcome = Death; one of the listed place options |
| 14 | reasonForDeath | String (server set) | Auto | Fixed value "Tuberculosis"; set only if tptOutcome = Death |
| 15 | reason | String | Conditional | Mandatory only if treatmentCompleted = false (reason for non-completion) |
Business logic on save:
- If tptOutcome = "Death": update the Beneficiary record – set beneficiaryStatus = "Death", along with dateOfDeath, placeOfDeath, reasonForDeath = "Tuberculosis" – and sync this update to AMRIT.
- Once TPT treatment is marked complete, move the beneficiary back to the TB screening list while retaining the full TPT treatment history (do not delete/overwrite prior visit records).
- Each save call appends a new follow-up visit record; it should not overwrite previous visits.
3. TPT Recommended List API
Endpoint (proposed): flw-api/tpt/recommendedList
Returns beneficiaries flagged "Recommended for TPT" (household contacts of a confirmed DS-TB/DR-TB case) for the landing screen line list.
4. TPT Follow-up Visit History API
Endpoint (proposed): flw-api/tpt/followUp/history
Parameter: beneficiaryId
Returns all past follow-up visit records for that beneficiary's TPT treatment, in chronological order, to render the "TPT Follow up visit history" table.
Acceptance Criteria
- Master/config API returns correct dropdown options for Regimen Type, Adherence, TPT Outcome, and Place of Death.
- Save API accepts and persists all fields listed above with correct validations.
- expectedTreatmentCompletionDate is correctly auto-calculated server-side based on regimenType and treatmentStartDate.
- Follow-up date validations (monthly cadence, not before treatment start, not after today, not before last follow-up) are enforced.
- Conditional fields (actualTreatmentCompletionDate, tptOutcome, dateOfDeath, placeOfDeath, reason) are only accepted/required per their trigger conditions.
- On tptOutcome = "Death", Beneficiary record is updated (status, date of death, place of death, reason for death) and synced to AMRIT.
- On treatment completion, beneficiary moves back to TB screening list; TPT visit history is preserved and retrievable via history API.
- Recommended list API correctly returns household contacts of confirmed DS-TB/DR-TB cases.
- Existing TB Screening APIs/functionality remain unaffected.
- API documentation updated accordingly.
- blocks
-
FLW-1159
Create Tuberculosis Preventive Treatement (TPT) Module
-
- Closed
-
