[Design 6] A Preferred Visit Date Is Not an Appointment Confirmation
Patient A wants to book the first visit in a package product. The customer channel shows August 20, morning as selected and the request as submitted. The screen may look finished, but the clinic still has several questions to answer.
- Can the purchase proceed under the current
AppointmentPlanrevision? - Are the required practitioner, equipment, room, and capacity available at that time?
- Does clinic policy allow the customer request to hold resources immediately?
- If the clinic proposes different terms, has Patient A consented to that change?
The appointment service therefore does not confirm an appointment from the customer’s selected value alone.
A preferred visit date is scheduling intent. An appointment confirmation combines a concrete proposal, resource allocation, clinic approval, and customer consent to that exact proposal.
Without this distinction, the customer’s “request submitted,” the counselor’s “under review,” and the clinic calendar’s “resources held” collapse into the same appointment complete state. A rejected change can then erase an existing appointment, or a schedule without the required equipment can appear confirmed.
Patient A’s request first becomes a scheduling proposal
Section titled “Patient A’s request first becomes a scheduling proposal”Patient A does not submit an arbitrary appointment row. The request contains an AppointmentPlan built from the purchase-time product BOM, a preferred visit window, and a reference to evidence issued by the external consent service. Patient identity, clinic scope, policy, and actual resources are read again from authenticated boundaries and server-side stores.
The appointment service validates these conditions before accepting the request.
| Validation | Question | On failure |
|---|---|---|
| Plan revision | Is the plan still valid and owned by this patient and clinic? | Reject the request instead of attaching it to another plan |
| Product definition hash | Does it match the product definition fixed at purchase time? | Do not silently reinterpret the purchase with the latest product |
| Per-request processing limit | Are item count, dependency count, and search horizon within the accepted range? | Reject the whole request and identify the exceeded limit with an error code |
| Applied policy record | Which clinic policy produced this proposal? | Record the policy used for the proposal so a later policy change remains distinguishable |
| Consent evidence | Is the evidence bound to this patient, plan, schedule, and terms? | Reject mismatched evidence without storing the original personal data |
Even after validation, the result is PROPOSED or HELD, depending on clinic policy. The appointment is not confirmed yet.
PROPOSED, HELD, and CONFIRMED describe different guarantees
Section titled “PROPOSED, HELD, and CONFIRMED describe different guarantees”These states are not decorative steps for a progress indicator. Each represents a different business guarantee.
| State | What is already guaranteed | What remains |
|---|---|---|
PROPOSED | A versioned proposal containing a concrete schedule, items, and applied policy | Resource allocation, required approval, and appointment confirmation |
HELD | A proposal with resources held for a limited time | Approval, consent, and confirmation before the hold expires |
CONFIRMED | An appointment confirmation binding a concrete proposal, consent evidence for that proposal, and resource allocation | Actual attendance and completion of care |
HELD is not a weaker alias for CONFIRMED. Resources may be held temporarily, but the hold can expire when an approval or consent condition is not met. Nor is PROPOSED a casual note. It is a fixed proposal version that records time, items, candidate resources, applied policy, and a proposal hash so the service can later prove what the customer approved.
Appointment confirmation is also a different axis from check-in, treatment progress, and completion. CONFIRMED means that the patient and clinic agreed to a schedule; it does not mean care was completed. Clinical services own actual start, completion, and partial-completion information.
Approving the same terms and changing the terms are different operations
Section titled “Approving the same terms and changing the terms are different operations”If the clinic approves Patient A’s requested time, visit items, and material conditions unchanged, the consent evidence bound to the original request can be used. When policy allows and resource allocation succeeds, the same proposal can move to CONFIRMED.
If the clinic changes a material condition—such as the time of day, practitioner combination, or visit items—the original consent cannot be reused. The appointment service appends a proposal version instead of overwriting the existing one. The terms shown to the customer and the resulting consent evidence bind to the exact proposalId, proposal revision, and proposal hash.
Submit preferred visit date → PROPOSED or HELD → Clinic review ├─ Approve the same terms → validate consent for that proposal → CONFIRMED └─ Change the terms → new proposal revision → customer consent → CONFIRMEDThis model leaves more than an ambiguous statement that “the customer consented to the appointment.” It can reproduce which time, items, and policy terms the customer accepted.
A change proposal does not cancel the existing appointment first
Section titled “A change proposal does not cancel the existing appointment first”Assume Patient A already has a confirmed appointment for next Tuesday morning and wants to move it to Friday afternoon. If the service cancels Tuesday merely to explore Friday, a resource conflict or final customer rejection can destroy the valid Tuesday appointment as well.
A safe appointment change follows this order.
- Keep the existing
confirmedProposalIdand resource allocation. - Append a proposal revision for the new time.
- Validate customer consent evidence for the new proposal.
- Allocate the new resources.
- Replace the confirmed proposal and release the old resources in one transaction.
If the new allocation fails, the customer rejects the proposal, or the proposal expires, the existing confirmation and appointment time remain intact. This is the essential difference between changing a date field and changing a confirmed appointment.
Which service owns each responsibility?
Section titled “Which service owns each responsibility?”Separating preferred schedules from appointment confirmation also requires explicit service boundaries.
| Service | Information it owns | Boundary with the appointment service |
|---|---|---|
| Customer channel and consent service | Preferred visit date, terms shown to the customer, original consent, and issued evidence | Send a verifiable evidence reference without storing the original consent text in the appointment service |
| Appointment service | Proposal revisions, appointment confirmation state, applied policy record, resource-allocation link, and change history | Bind a concrete proposal to consent for that proposal and record state transitions transactionally |
| Clinic operations | Approval authority, available alternatives, and operational policy decisions | Approve the customer request or propose new terms |
| Resource ledger | Actual availability and allocation of practitioners, equipment, rooms, and capacity | Provide the allocation required by HELD and CONFIRMED |
| Clinical and treatment services | Actual start, completion, and partial completion | Publish visit results without deciding scheduling agreement state |
No-show history or VIP policy from customer support and CRM can be an input to this flow. The appointment service does not invent customer tiers or penalties. The policy-owning service determines the basis and scope, while the appointment service applies proposal priority or approval conditions without violating product rules, clinic operating rules, existing confirmed appointment times, or resource allocations. The next article makes that operating-policy boundary concrete for new bookings and waitlist offers.
Current implementation and production activation are not the same claim
Section titled “Current implementation and production activation are not the same claim”The state model and command boundaries described here exist in the current code. They cover customer requests, clinic approval, change proposals, customer acceptance and rejection, direct confirmation, expiration, and cancellation. They also validate consent evidence, applied policy records, and resource allocation together.
An implementation merge does not mean that every clinic has enabled the production write path.
| Evidence label | Scope in this article |
|---|---|
| Current implementation | AppointmentCommitment, AppointmentProposal, request/approve/accept/reject/change commands, consent validation, V10 migrations for H2, PostgreSQL, and MySQL, and tests |
| Approved design | Protect existing appointments, never overwrite a confirmed proposal revision, and preserve applied policy and consent evidence |
| Pending operations | External consent, commerce, and clinical adapters; production WRITE activation; limited-clinic validation and recovery drills |
| Roadmap | Reconfirmation, waitlists, and operating policies such as no-show and VIP priority |
The presence of a CONFIRMED model therefore does not prove that a particular clinic has completed production rollout. The state-transition logic can be ready while the write path remains restricted until external responsibility boundaries and operational validation are complete.
Next in the series
Section titled “Next in the series”This article established the boundary at which one visit time becomes confirmed. The next article makes the operating-policy boundary concrete: who owns booking priority when no-show history, VIP signals, and waitlist offers meet.
Revisit the visual companions
Section titled “Revisit the visual companions”- Appointment plans and capacity
- Product BOM to appointment flow
- Clinic appointment visual companion index
Evidence links
Section titled “Evidence links”- clinic-appointment repository
- Visit commitment and product-version transition design
- Appointment reevaluation after profile changes
- AppointmentCommitment model
- Commitment request contracts
- Commitment application service
- Commitment API guide
Comments
Leave a note or reaction with your GitHub account.