dyolink/.cursor/skills/treatment-workspace/SKILL.md

name, description

name	description
dyolink-treatment-workspace	Treatment tab workspace — appointments strip, preview vs form, history, load flow, draft autosave, type-first entry, connected teeth, lab dispatch. Use when changing treatment UX, preview/history, or lab dispatch in TreatmentWorkspace.

Treatment workspace

Main orchestrator: frontend/src/components/ui/treatment/TreatmentWorkspace.tsx

Thin route: app/[locale]/(dashboard)/treatment/page.tsx (supports ?appointmentId=).

Layout (top → bottom)

1. Day strip — AppointmentsStrip.tsx renders DayStripItem[] (appointment | unscheduled) via DayStripCard. Header uses ScheduleDayPicker compact: date is centered in a 3-col grid; no “Schedule date” label; Today sits on the navigator (CalendarDaySelect when the label row is hidden). Timed appointments keep treatment-type pastel banners. Unscheduled cards use the same banner from the first detail’s type only (unscheduledStripColorCode; live draft for the open card; draftHydratingRef must be set before strip/appointment pick so overlay does not paint the previous card’s type). Empty first line → chip theming even if later lines are typed. Trash inherits banner ink on typed cards. Strip trash only when areUnscheduledDetailsStripDeletable (no type/teeth/notes/attachments, including []). Workspace fetches GET /appointments and GET /treatments/day. Patient search (PatientSearchCombobox) sits in the page header (workspace-wide). New treatment is one shared Button at the top of the left rail, with the selected-patient card under it: it opens NewTreatmentPatientPicker (Walk-in always first, then a matching full-width card for the current named patient with name + mobile/email or hint, then search). Creating happens only after an explicit patient choice — never from the selected appointment card. New treatment seeds one blank detail so the type field is ready; a persisted empty plan hydrates as [] until Add (noDetails copy — not the type-first overlay). Last-line chip delete confirms the plan will be empty until Add.

2. Treatment preview — TreatmentPreviewCard.tsx (history browse only; omitted for the live draft)

3. Treatment history — PastTreatmentsPanel.tsx (past saved plans for patient; client-side filters in treatmentHistoryFilters.ts)

4. Editor — detail chips + Add (TreatmentDetailsEditor); type-first form with chart + notes; lab send sheet under the form when the active type is prosthesis (LabCasesDispatchPanel)

Entry (type-first form / optional lab sheet)

Right-column entry is not a three-step wizard. Type dropdown + TreatmentDetailAttachmentsStrip on one row (same height as Dropdown; paperclip | divider | thumbs grouped image → pdf → other; upload progress in one square; click thumb → preview/remove dialog). Compact FDI chart (same scale as Cases), then full-width auto-growing Notes (rows={1}). Chart is dimmed until a type is chosen. Lab-dependent chips show colored sent/unsent text (not badge pills); sent date stays on the Lab dispatch panel.

Stage	UI	When
Treatment	Type dropdown + TreatmentDetailAttachmentsStrip, FdiToothChart / ProsthesisAssignChart, full-width Notes	Always
Lab	LabCasesDispatchPanel under the form	When active detail type is lab-dependent. Auto-ensures a shipment draft (teeth/arch not required to create the draft). No default lab or prosthesis type on a new detail (including siblings in the same plan). Last 3 sent labs appear as chips under search — pick is explicit. Comments stay on the dispatch panel.

• Prosthesis types are assigned on the chart (ProsthesisAssignChart + ProsthesisJobPopover in prosthesisTree.ts). One restoration slot per tooth (crown / veneer-inlay-onlay-overlay); screw-retained is an implant add-on (stackGroup: implant, paints the crown) and stacks with a restoration. Implant abutments and post & core also stack (post & core stays off when the implant is screw-retained). Complete denture / overdenture / appliances / digital use Upper arch / Lower arch (UA/LA). Partial denture is tooth-level (select FDI teeth, Removable in the tooth picker); after send it is one lab job for all those teeth. Picker leaves are filtered by chartRegion so Removable appears in both tooth and arch pickers. Lab dispatch is on the same screen (no Treatment → Lab stepper).
• Detail chips show type + teeth, not “Detail N”. Lab-dependent chips use colored sent/unsent text (same size as the label); sent date stays on Lab dispatch.
• Detail type may differ from appointment purpose. Purpose seeds the first line of an empty appointment draft (first open, and Add detail when the plan is []). Later Add detail starts with an empty type. Unscheduled / New treatment still seeds a blank first line.
• Lab shipments rail / “Go to dispatch” / load-with-focus scrolls to the dispatch panel (pendingScrollToLabRef + labPanelRef).
• Live draft is not duplicated in the left rail preview; preview is for history browse only.

Tooth selection groups

Helpers: frontend/src/components/treatment/toothSelectionGroups.ts. Persisted as toothSelectionGroups on the detail. Lab dispatch lists connected teeth that share a type as one row (LabCaseToothJobsList); unconnected teeth stay one row per tooth (stacked codes stay together). After send, Cases/Tasks match that: a connected same-type bridge is one pipeline; stacked types on a single tooth union their workflow steps; partial_denture is one task set per sourceKey. LabCaseTask unique key includes tooth (first tooth of a merged bridge).

Chart hit-testing (FdiToothChart.tsx): the hit target is the unrotated full cell (pointerdown + keyboard). Do not bind both pointerdown and click (double-toggle looks like a miss). Visual glyph is pointer-events-none; tilt lives on the outer wrapper; scale/hover is nested inside so inline transform does not kill scale. Horizontal inset (~22%) leaves a dead zone between teeth; FDI numbers are also clickable (ToothNumber).

• Plain click: add/remove single; deselecting a tooth in a bridge removes it and splits/shrinks remaining sides (never a 1-tooth connected group).
• Neighbor circles: when two arch-adjacent teeth are both selected, an empty circle appears between them (not per-tooth). Click empty → connect; click filled → disconnect (teeth stay selected). Transitive A–B + B–C = one bridge.
• Shift+click: inclusive same-arch range → all selected as singles (empty circles); overlapping existing bridges are absorbed as singles too. Midline neighbors (11–21, 41–31) allowed.
• Prosthesis assign chart: Shift = range then assign to the span; Ctrl/Cmd or drag copies the last type-set. Click a selected tooth opens the picker; click drops a tooth only from an in-progress Shift range that still has no jobs. Arch products open from the Upper/Lower arch labels and store UA/LA (not 16 FDI teeth). Partial denture is assigned from selected teeth (not the arch labels). pruneToothProsthesisForGroups must keep those sentinels.
• Prevent browser selection artifacts (select-none, Shift preventDefault on mousedown).
• On group change, prune/remap labCase.toothProsthesis via pruneToothProsthesisForGroups.
• Connected UI label: ConnectedSelectionBadge (shared Badge + primary tint) in dispatch + lab case lists.
• Lab case comments: shared LabCaseCommentsPanel — newest-first; sent = justify-start / text-start, received = justify-end / text-end (RTL-safe); require viewerSide: 'LAB' | 'CLINIC'. Used in Cases, Tasks, share focus, and Treatment (DetailLabCaseCommentsSection). Composer: h-9 input + primary send / visibility buttons (white icons; Send mirrored in RTL).

Two layers of state (critical)

| Layer | State | Updated when |

|-------|--------|--------------|

| Preview | previewTreatment; selectedPreviewId !== null = browse mode | History click updates preview only |

| Form | details[], labCaseDrafts[] | Appointment change → draft API; Load into workspace → hydrate. Autosave and strip-switch flush both saveDraft then saveLabCases. Dirty includes the lab-case snapshot (jobs, dest, due date), not only details. Non-prosthesis plans keep empty drafts and do not create lab rows. |

Browse mode: banner + “Load into workspace” / “Back to current draft”. No Open button on preview card.

Lab dispatch attention: LabDispatchAttentionPanel lists lab-dependent unsent details (current draft + user history). “Go to dispatch” / “Load & dispatch”.

History API

GET /treatments/patients/:id/history returns saved treatments for that patient scoped to the logged-in clinician (Treatment.providerUserId or linked Appointment.providerUserId). Owners are not exempt — each user only sees plans they created or own via their appointments.

History filters (client-side only)

PastTreatmentsPanel filters already-fetched history — no extra API params.

• Not shipped to lab — show treatments that have at least one lab-dependent detail (prosthesis via labDependentCodes) with !sentAt.
• Date — filter on treatmentAt matching that local calendar day.
• When not shipped is on, filters already-fetched history only (excludes the active appointment row).
• Previous treatments rail excludes the active appointment; live draft stays in the editor only. Refresh history after lab send.

Helpers: frontend/src/components/treatment/treatmentHistoryFilters.ts.

Lab shipment without teeth

Saved lab-dependent detail with no teeth can autosave but cannot create a lab shipment.

• Inline amber banner in TreatmentDetailsEditor on both Treatment and Lab steps when the active detail qualifies (isLabDependentDetailMissingTeeth). Do not use a separate notice card.
• handleAddLabCase shows toast with labShipmentBlockedBody.
• Dispatch panel only appears when a detail passes isDetailReadyForLabDispatch (persisted + lab-dependent + teeth).

Lab case comments on details

Comments for a shipment live in the Lab dispatch panel (and Cases/Tasks/share), not on Content notes.

• Unsent: deferred composer in DetailLabCaseCommentsSection (posts with Send to lab).
• Sent / in progress: live composer until tasks complete (canPostComments).
• UI: DetailLabCaseCommentsSection → LabCaseCommentsPanel + treatmentsApi comment endpoints (viewerSide="CLINIC").
• Backend includes tasks: { select: { id, status } } on lab cases; mapDetail exposes taskProgress: { completed, total }.

Live lab rail refresh

Inbox Socket.IO notification.created → notifyTabBadgesChanged() → silent refresh of patient lab cases + unread rail. Does not remount the workspace or clear draft/form state. See .cursor/skills/notifications-inbox/SKILL.md.

Appointments default selection

On today: in-progress slot first, else nearest start time to now. Other days: first appointment. Re-runs every 60s on today unless selectionLocked. Frontend filters appointments to providerUserId === userId.

Today checkbox (ScheduleDayPicker, including compact on the Treatment strip and Appointments page headers): unchecked when selectedDay is not today (e.g. after loading a historical treatment). Checking Today calls onSelectDay(today) which unlocks selection (selectionLocked = false) and resets browse/historical context; appointments reload and auto-select nearest to now.

Lab org search (dispatch)

LinkedOrganizationSearchCombobox in LabCasesDispatchPanel — search-only results (no dropdown). Chips under the search are the last 3 labs this clinic sent a case to (rememberRecentLab after successful send). They are shortcuts, not defaults: a new detail’s lab stays empty until the user chooses (types stay on the chart). Switching details clears the search box. No match + org tab access → Invite a lab navigates to /organizations?action=invite-lab. No org access → show permission message; dispatch stops.

Pattern mirrors PatientSearchCombobox in appointments.

Scroll

Use scrollWithinMainScrollContainer() (not raw scrollIntoView) when jumping to lab dispatch panel — dashboard <main> is the scroll container; document scroll conflicts with .app-web-bg { overflow: hidden }.

Use shared Checkbox (not native <input type="checkbox">) to avoid focus-driven scroll jumps.

Backend APIs

| Endpoint | Purpose |

|----------|---------|

| GET /appointments?from&to | Timed strip cards |

| GET /treatments/day?from&to | Standalone (unscheduled) strip cards |

| POST /treatments | Create standalone { patientId?, walkIn?, treatmentAt } |

| DELETE /treatments/:id | Empty standalone only (appointmentId null, no detail rows). UI may PUT { details: [] } first when the strip looks blank but autosave has not finished. |

| GET /treatments/patients/:patientId/history | History (patient + org; filtered by provider) |

| GET /treatments/appointments/:id/draft | Load form on appointment select |

| GET/PUT /treatments/:treatmentId/draft | Load/save when there is no appointment |

| PUT .../lab-cases | Autosave (600ms debounce) — appointment or treatment id |

Walk-in uses one sentinel Patient per clinic (isWalkIn, hidden from Patients/search/booking). Display via i18n, never the stored name. Patient search: same workspace patient with a live visit → no-op; else open today’s strip visit if any; else load latest history into the editor; no history and no strip visit → do not auto-create. Detach the previous visit, keep the searched patient, and show an inline editor empty state (noTreatmentFoundTitle / noTreatmentFoundBody) that points to New treatment in the rail (Walk-in, current named patient card, or search).

Draft writes for appointments require provider match (ensureAppointmentProvider). Standalone requires treatment.providerUserId === actor.

Edit gating

canEditTreatmentForDay = canEdit && hasLiveContext && !isViewingPastDay && workspaceMode === 'live'

hasLiveContext is a selected live appointment or standalone treatment. Past day or historical workspace mode freezes the treatment form + most lab-dispatch fields.

Per-detail sent lock

isDetailLocked = linked lab case has sentAt. Locked details: type, comment, teeth, attachments are read-only (UI + draft save skips updates/deletes; attachment upload returns TREATMENT_DETAIL_SENT).

Add / remove details

• Add detail stays enabled whenever canEditTreatmentForDay — even if sibling details are already sent.
• Remove detail: trash icon on each detail chip in chrome (TreatmentDetailsEditor showChrome), including the last remaining line. Disabled when !canEdit, day/workspace disabled, detail sent (isDetailLocked), or uploadBusy. Confirm via confirmRemoveDetail. Drop linked unsent lab drafts with the detail. Empty details persist as [] (SaveTreatmentDraftDto has no @ArrayMinSize; areDetailsPersistable is details.every(isDetailTypeSelected) so [] saves). Unscheduled strip-card trash uses areUnscheduledDetailsStripDeletable (blank lines), then PUT { details: [] } and DELETE /treatments/:id (backend still refuses when any detail row remains — TREATMENT_HAS_DETAILS). Do not put a delete control in the type/notes fields.

Sent lab shipment fields (vs detail)

After send, destination / prosthesis / shipment attachments are frozen. Due date stays editable until all lab tasks complete (UI still respects day/mode disabled). Comments stay editable until tasks complete and intentionally ignore the day/mode gate.

Full map helpers: treatmentDetailRules.ts, LabCasesDispatchPanel.tsx.

• @IsOptional() email: use @Transform empty string → undefined before @IsEmail (see patients DTO).

• Form validation → inline errors; transient feedback → global useToast() via ToastProvider.

When changing history scope

Filter in backend listPatientHistory / lab-case lists on patient + org + provider scope (common/treatment-provider-scope.ts). History is per selected patient and per clinician, not per day or all org plans.

UI filters (not shipped, date) are client-side only — do not add API params unless product explicitly requires server-side filtering.