contracts

type Assigned struct {
	TaskID   uuid.UUID `json:"taskId"`
	Assignee uuid.UUID `json:"assigneeId"`
	// Status is what the assignment moved the task to, so a subscriber that
	// only wants acknowledgements does not have to read the task back.
	Status string    `json:"status"`
	At     time.Time `json:"at"`
}

type Resolved struct {
	TaskID     uuid.UUID `json:"taskId"`
	Resolution string    `json:"resolution,omitempty"`
	At         time.Time `json:"at"`
}

type SLABreached struct {
	TaskID   uuid.UUID `json:"taskId"`
	Priority string    `json:"priority"`
	Deadline time.Time `json:"deadline"`
	At       time.Time `json:"at"`
}

type Service interface {
	// Assign makes assignee responsible and acknowledges an open task. The
	// same person again changes nothing and publishes nothing.
	Assign(ctx context.Context, tx db.Tx[db.Tenant], id, assignee uuid.UUID) (*Task, error)

	// Resolve closes the loop. The same resolution again, or none, changes
	// nothing; a different one is a conflict, because a resolved task's account
	// of itself is not something a retry may quietly rewrite.
	Resolve(ctx context.Context, tx db.Tx[db.Tenant], id uuid.UUID, resolution string) (*Task, error)

	// CheckSLA records a breach if the deadline has passed and the task is
	// neither resolved nor already breached. The sweep calls it once a minute
	// for every overdue task, so it publishes at most once per task.
	CheckSLA(ctx context.Context, tx db.Tx[db.Tenant], id uuid.UUID) (*Task, error)
}

type Task struct {
	crud.Base

	// Title is the one-line summary. It is what a list screen shows.
	Title string `` /* 179-byte string literal not displayed */
	// Description is the optional long form.
	Description string `json:"description,omitempty" gorm:"type:text" ui:"widget:textarea;hide:list" doc:"Detailed description of the task"`

	// Status and Priority are closed sets; the enum tag is what a form renders
	// as a select and what Validate refuses a value outside.
	//
	// Both carry required:"false", and so does SLABreached below. huma reads a
	// struct field with no omitempty as a required request property, so without
	// it a create would have to send the three fields the server sets itself —
	// which is the same reasoning as crud.Base's, one level out.
	Status   string `` /* 187-byte string literal not displayed */
	Priority string `` /* 170-byte string literal not displayed */

	// Source and SourceRef link a task back to whatever raised it — a sensor, a
	// form — without a foreign key into another module's table. That is what
	// "cross-module dependencies are Go interfaces" costs at the database, and
	// it is cheaper than the alternative.
	Source    string `json:"source,omitempty" gorm:"type:varchar(40)" ui:"hide:list" doc:"Origin of the task" example:"sensor"`
	SourceRef string `` /* 131-byte string literal not displayed */

	// AssigneeID is who is responsible, nil while nobody is. Service.Assign
	// sets it, not a PATCH: assignment moves the status and publishes.
	AssigneeID *uuid.UUID `json:"assigneeId,omitempty" gorm:"type:uuid" ui:"widget:entity-picker" doc:"User responsible for the task" format:"uuid"`

	// DueAt is the soft target and SLADeadline the contractual one: two fields,
	// because "due soon" and "the promise is broken" are different things to
	// show, and only the second is what SLABreached is measured against.
	DueAt       *time.Time `json:"dueAt,omitempty" gorm:"type:timestamptz" ui:"widget:datetime" doc:"Soft target completion time"`
	SLADeadline *time.Time `` /* 132-byte string literal not displayed */
	// SLABreached is stored rather than derived, so that a breach stays a fact
	// after the task is resolved and the deadline stops being in the future.
	SLABreached bool `` /* 164-byte string literal not displayed */

	// ResolvedAt and Resolution close the loop. Both are set by Service.Resolve.
	ResolvedAt *time.Time `` /* 131-byte string literal not displayed */
	Resolution string     `json:"resolution,omitempty" gorm:"type:text" ui:"widget:textarea;hide:list" doc:"How the task was resolved"`
}