domain/workflow.rs
1//! Workflow events and outcomes for reviewable resort operations.
2//!
3//! # Operator framing
4//!
5//! Use this page to understand how a source fact turns into a staff-visible task,
6//! review reason, draft message, or recommended next action. It matters to
7//! operators because workflow values preserve why something is being suggested,
8//! what evidence supports it, and which human review gate still controls the live
9//! care, labor, payment, or customer-communication step.
10//!
11//! The next step is to follow the type that matches the queue you are explaining:
12//! events identify why work started, task/message modules describe staff-facing
13//! drafts, review values explain why automation stopped, and outcomes record the
14//! evidence trail. The Rust API details below are the generated implementation surface for
15//! implementers; this framing is the business reading guide.
16//!
17//! Workflows connect provider/read-model facts to staff-visible tasks, customer-message drafts, policy
18//! context, and recommended next actions. They preserve evidence and review reasons so AI agents can
19//! reduce manual triage while keeping live care, labor, payment, and customer communications inside
20//! explicit approval boundaries.
21
22use chrono::{DateTime, Utc};
23use nutype::nutype;
24#[allow(unused_imports)]
25use serde::{Deserialize, Serialize};
26use uuid::Uuid;
27
28use crate::{entities, policy};
29
30#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
31/// Stable identifier for a workflow event emitted by an agent, adapter, or staff-facing process.
32pub struct EventId(pub Uuid);
33
34#[nutype(
35 sanitize(trim),
36 validate(not_empty, len_char_max = 500),
37 derive(
38 Debug,
39 Clone,
40 PartialEq,
41 Eq,
42 PartialOrd,
43 Ord,
44 Hash,
45 Serialize,
46 Deserialize
47 )
48)]
49pub struct Summary(String);
50
51/// Risk marker surfaced when a workflow may affect pet safety, labor cost, payment, or customer trust.
52#[nutype(
53 sanitize(trim),
54 validate(not_empty, len_char_max = 160),
55 derive(
56 Debug,
57 Clone,
58 PartialEq,
59 Eq,
60 PartialOrd,
61 Ord,
62 Hash,
63 Serialize,
64 Deserialize
65 )
66)]
67pub struct RiskFlag(String);
68
69/// Evidence note proving what source fact, review, or staff action verified a workflow outcome.
70#[nutype(
71 sanitize(trim),
72 validate(not_empty, len_char_max = 500),
73 derive(
74 Debug,
75 Clone,
76 PartialEq,
77 Eq,
78 PartialOrd,
79 Ord,
80 Hash,
81 Serialize,
82 Deserialize
83 )
84)]
85pub struct VerificationNote(String);
86
87/// Review explanation recorded when automation must stop at a manager, medical, or customer-message gate.
88#[nutype(
89 sanitize(trim),
90 validate(not_empty, len_char_max = 300),
91 derive(
92 Debug,
93 Clone,
94 PartialEq,
95 Eq,
96 PartialOrd,
97 Ord,
98 Hash,
99 Serialize,
100 Deserialize
101 )
102)]
103pub struct ReviewReason(String);
104
105/// External workflow-provider vocabulary retained before promotion into domain tasks or messages.
106pub mod external {
107 use nutype::nutype;
108 #[allow(unused_imports)]
109 use serde::{Deserialize, Serialize};
110
111 /// External workflow provider or system name that supplied a task, message, or status update.
112 #[nutype(
113 sanitize(trim),
114 validate(not_empty, len_char_max = 120),
115 derive(
116 Debug,
117 Clone,
118 PartialEq,
119 Eq,
120 PartialOrd,
121 Ord,
122 Hash,
123 Serialize,
124 Deserialize
125 )
126 )]
127 pub struct Provider(String);
128
129 /// External workflow identifier used to correlate provider tasks and status updates.
130 #[nutype(
131 sanitize(trim),
132 validate(not_empty, len_char_max = 120),
133 derive(
134 Debug,
135 Clone,
136 PartialEq,
137 Eq,
138 PartialOrd,
139 Ord,
140 Hash,
141 Serialize,
142 Deserialize
143 )
144 )]
145 pub struct Id(String);
146}
147
148/// Provider task fields used to create staff work without losing source evidence.
149pub mod task {
150 use nutype::nutype;
151 #[allow(unused_imports)]
152 use serde::{Deserialize, Serialize};
153
154 /// Staff-visible task title summarizing the operational work item.
155 #[nutype(
156 sanitize(trim),
157 validate(not_empty, len_char_max = 160),
158 derive(
159 Debug,
160 Clone,
161 PartialEq,
162 Eq,
163 PartialOrd,
164 Ord,
165 Hash,
166 Serialize,
167 Deserialize
168 )
169 )]
170 pub struct Title(String);
171
172 /// Task or message body text that carries source evidence and review instructions.
173 #[nutype(
174 sanitize(trim),
175 validate(not_empty, len_char_max = 2000),
176 derive(
177 Debug,
178 Clone,
179 PartialEq,
180 Eq,
181 PartialOrd,
182 Ord,
183 Hash,
184 Serialize,
185 Deserialize
186 )
187 )]
188 pub struct Body(String);
189}
190
191/// Provider message fields used before normalization into customer-message workflows.
192pub mod message {
193 use nutype::nutype;
194 #[allow(unused_imports)]
195 use serde::{Deserialize, Serialize};
196
197 #[nutype(
198 sanitize(trim),
199 validate(not_empty, len_char_max = 80),
200 derive(
201 Debug,
202 Clone,
203 PartialEq,
204 Eq,
205 PartialOrd,
206 Ord,
207 Hash,
208 Serialize,
209 Deserialize
210 )
211 )]
212 pub struct Channel(String);
213
214 #[nutype(
215 sanitize(trim),
216 validate(not_empty, len_char_max = 2000),
217 derive(
218 Debug,
219 Clone,
220 PartialEq,
221 Eq,
222 PartialOrd,
223 Ord,
224 Hash,
225 Serialize,
226 Deserialize
227 )
228 )]
229 pub struct Body(String);
230}
231
232/// Provider status-update fields used to reconcile external task or message progress.
233pub mod status_update {
234 use crate::entities;
235 use nutype::nutype;
236 #[allow(unused_imports)]
237 use serde::{Deserialize, Serialize};
238
239 /// Provider-supplied status reason text preserved as review evidence.
240 pub mod reason {
241 use super::*;
242
243 #[nutype(
244 sanitize(trim),
245 validate(not_empty, len_char_max = 500),
246 derive(
247 Debug,
248 Clone,
249 PartialEq,
250 Eq,
251 PartialOrd,
252 Ord,
253 Hash,
254 Serialize,
255 Deserialize
256 )
257 )]
258 pub struct Reason(String);
259 }
260
261 pub use reason::Reason;
262
263 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
264 /// Intended reservation transition requested by a workflow before policy and review checks are applied.
265 pub enum TransitionIntent {
266 /// Request medical review workflow state, command, or review outcome.
267 RequestMedicalReview,
268 /// Apply capacity decision workflow state, command, or review outcome.
269 ApplyCapacityDecision,
270 /// Confirm accepted offer workflow state, command, or review outcome.
271 ConfirmAcceptedOffer,
272 /// Cancel reservation workflow state, command, or review outcome.
273 CancelReservation,
274 /// Reject by policy workflow state, command, or review outcome.
275 RejectByPolicy,
276 /// Complete checkout workflow state, command, or review outcome.
277 CompleteCheckout,
278 }
279
280 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
281 /// Workflow-scoped reservation transition request with target state, reason, and review intent.
282 pub struct Reservation {
283 /// Workflow status value preserved for staff review and audit evidence.
284 pub status: entities::reservation::Status,
285 /// Workflow intent value preserved for staff review and audit evidence.
286 pub intent: TransitionIntent,
287 /// Business reason staff should review before proceeding.
288 pub reason: Reason,
289 }
290
291 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
292 /// Workflow target that a task, event, or recommended action is about.
293 pub enum Target {
294 /// Reservation record participating in the workflow.
295 Reservation(Reservation),
296 }
297}
298
299#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
300/// Workflow event that records what changed, who/what it concerns, and what evidence/risk came with it.
301pub struct Event {
302 /// Workflow event ID value preserved for staff review and audit evidence.
303 pub event_id: EventId,
304 /// Workflow event type value preserved for staff review and audit evidence.
305 pub event_type: EventType,
306 /// Workflow occurred at value preserved for staff review and audit evidence.
307 pub occurred_at: DateTime<Utc>,
308 /// Workflow actor value preserved for staff review and audit evidence.
309 pub actor: entities::ActorRef,
310 /// Workflow location ID value preserved for staff review and audit evidence.
311 pub location_id: entities::LocationId,
312 /// Workflow subject value preserved for staff review and audit evidence.
313 pub subject: Subject,
314 /// Workflow policy context value preserved for staff review and audit evidence.
315 pub policy_context: PolicyContext,
316}
317
318#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
319/// Event category emitted by triage, policy, review, external sync, or source ingestion.
320pub enum EventType {
321 /// Inquiry received workflow state, command, or review outcome.
322 InquiryReceived,
323 /// Customer registered workflow state, command, or review outcome.
324 CustomerRegistered,
325 /// Pet profile created workflow state, command, or review outcome.
326 PetProfileCreated,
327 /// Vaccine document uploaded workflow state, command, or review outcome.
328 VaccineDocumentUploaded,
329 /// Booking requested workflow state, command, or review outcome.
330 BookingRequested,
331 /// Booking triage needed workflow state, command, or review outcome.
332 BookingTriageNeeded,
333 /// Booking confirmation needed workflow state, command, or review outcome.
334 BookingConfirmationNeeded,
335 /// Daily note created workflow state, command, or review outcome.
336 DailyNoteCreated,
337 /// Daily update needed workflow state, command, or review outcome.
338 DailyUpdateNeeded,
339 /// Incident created workflow state, command, or review outcome.
340 IncidentCreated,
341 /// Checkout completed workflow state, command, or review outcome.
342 CheckoutCompleted,
343 /// Review request eligible workflow state, command, or review outcome.
344 ReviewRequestEligible,
345 /// Membership changed workflow state, command, or review outcome.
346 MembershipChanged,
347 /// Loyalty credit available workflow state, command, or review outcome.
348 LoyaltyCreditAvailable,
349}
350
351#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
352/// Subject of a workflow event or recommendation.
353pub enum Subject {
354 /// Customer record participating in the workflow.
355 Customer(entities::CustomerId),
356 /// Pet record participating in the workflow.
357 Pet(entities::PetId),
358 /// Reservation record participating in the workflow.
359 Reservation(entities::reservation::Id),
360 /// External system object referenced from domain history.
361 External {
362 /// Workflow provider value preserved for staff review and audit evidence.
363 provider: external::Provider,
364 /// Workflow id value preserved for staff review and audit evidence.
365 id: external::Id,
366 },
367}
368
369#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
370/// Policy context attached to a workflow so reviewers can see allowed actions and required gates.
371pub struct PolicyContext {
372 /// Workflow allowed actions value preserved for staff review and audit evidence.
373 pub allowed_actions: Vec<AllowedAction>,
374 /// Workflow automation level value preserved for staff review and audit evidence.
375 pub automation_level: policy::automation::Level,
376 /// Workflow required reviews value preserved for staff review and audit evidence.
377 pub required_reviews: Vec<policy::ReviewGate>,
378}
379
380#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
381/// Action an automation policy permits for a workflow outcome.
382pub enum AllowedAction {
383 /// Read entities workflow state, command, or review outcome.
384 ReadEntities,
385 /// Extract structured data workflow state, command, or review outcome.
386 ExtractStructuredData,
387 /// Draft customer message workflow state, command, or review outcome.
388 DraftCustomerMessage,
389 /// Create internal task workflow state, command, or review outcome.
390 CreateInternalTask,
391 /// Suggest reservation status workflow state, command, or review outcome.
392 SuggestReservationStatus,
393 /// Suggest play eligibility workflow state, command, or review outcome.
394 SuggestPlayEligibility,
395 /// Summarize care notes workflow state, command, or review outcome.
396 SummarizeCareNotes,
397 /// Flag risk workflow state, command, or review outcome.
398 FlagRisk,
399}
400
401#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
402/// Workflow result carrying status, summary, recommended action, and verification notes for staff review.
403pub struct Result<T> {
404 /// Workflow status value preserved for staff review and audit evidence.
405 pub status: Status,
406 /// Workflow summary value preserved for staff review and audit evidence.
407 pub summary: Summary,
408 /// Workflow structured output value preserved for staff review and audit evidence.
409 pub structured_output: Option<T>,
410 /// Workflow recommended actions value preserved for staff review and audit evidence.
411 pub recommended_actions: Vec<RecommendedAction>,
412 /// Workflow risk flags value preserved for staff review and audit evidence.
413 pub risk_flags: Vec<RiskFlag>,
414 /// Workflow verification value preserved for staff review and audit evidence.
415 pub verification: Vec<VerificationNote>,
416 /// Workflow human review reason value preserved for staff review and audit evidence.
417 pub human_review_reason: Option<ReviewReason>,
418}
419
420#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
421/// Normalized lifecycle states used to reconcile source-system data with domain workflows.
422pub enum Status {
423 /// Completed workflow state, command, or review outcome.
424 Completed,
425 /// Needs human review workflow state, command, or review outcome.
426 NeedsHumanReview,
427 /// Rejected by policy workflow state, command, or review outcome.
428 RejectedByPolicy,
429 /// Needs more information workflow state, command, or review outcome.
430 NeedsMoreInformation,
431 /// Failed safely workflow state, command, or review outcome.
432 FailedSafely,
433}
434
435#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
436/// Recommended next action for staff, managers, or automation after evaluating a workflow.
437pub enum RecommendedAction {
438 /// Internal task workflow state, command, or review outcome.
439 InternalTask {
440 /// Workflow title value preserved for staff review and audit evidence.
441 title: task::Title,
442 /// Workflow body value preserved for staff review and audit evidence.
443 body: task::Body,
444 },
445 /// Draft message workflow state, command, or review outcome.
446 DraftMessage {
447 /// Workflow channel value preserved for staff review and audit evidence.
448 channel: message::Channel,
449 /// Workflow body value preserved for staff review and audit evidence.
450 body: message::Body,
451 },
452 /// Update status workflow state, command, or review outcome.
453 UpdateStatus {
454 /// Workflow target value preserved for staff review and audit evidence.
455 target: status_update::Target,
456 },
457 /// Request human review workflow state, command, or review outcome.
458 RequestHumanReview(policy::ReviewGate),
459}