breakpilot-compliance/ai-compliance-sdk/internal/usecase/models.go

// Package usecase implements the Use-Case Compiler that turns
// Master Controls into interactive compliance questionnaires.
package usecase

import (
	"time"

	"github.com/google/uuid"
)

// ── Use-Case Template ──────────────────────────────────────────────

// Template defines a reusable compliance audit blueprint.
type Template struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	Description string   `json:"description"`
	MCFilters   []string `json:"mc_filters"`
	Regulations []string `json:"regulations"`
	Questions   []Question `json:"questions,omitempty"`
}

// ── Question ───────────────────────────────────────────────────────

// Question is a single compliance check derived from a Master Control.
type Question struct {
	ID               string   `json:"id"`
	MCID             string   `json:"mc_id"`
	MCName           string   `json:"mc_name"`
	Text             string   `json:"question"`
	QuestionType     string   `json:"question_type"`
	EvidenceRequired bool     `json:"evidence_required"`
	PassCriteria     []string `json:"pass_criteria"`
	FailCriteria     []string `json:"fail_criteria"`
	Severity         string   `json:"severity"`
	Regulation       string   `json:"regulation"`
	DependsOn        string   `json:"depends_on,omitempty"`
}

// ── Audit ──────────────────────────────────────────────────────────

// AuditStatus enumerates the lifecycle of an audit.
type AuditStatus string

const (
	StatusDraft      AuditStatus = "draft"
	StatusInProgress AuditStatus = "in_progress"
	StatusCompleted  AuditStatus = "completed"
)

// Audit is a running or completed compliance questionnaire.
type Audit struct {
	ID                uuid.UUID   `json:"id"`
	TenantID          uuid.UUID   `json:"tenant_id"`
	TemplateID        string      `json:"template_id"`
	Name              string      `json:"name"`
	TargetName        string      `json:"target_name,omitempty"`
	Status            AuditStatus `json:"status"`
	TotalQuestions    int         `json:"total_questions"`
	AnsweredQuestions int         `json:"answered_questions"`
	ComplianceScore   float64     `json:"compliance_score"`
	Questions         []Question  `json:"questions"`
	CreatedAt         time.Time   `json:"created_at"`
	UpdatedAt         time.Time   `json:"updated_at"`
	CompletedAt       *time.Time  `json:"completed_at,omitempty"`
}

// ── Answer ─────────────────────────────────────────────────────────

// AnswerStatus enumerates how a question was handled.
type AnswerStatus string

const (
	AnswerStatusAnswered  AnswerStatus = "answered"
	AnswerStatusSkipped   AnswerStatus = "skipped"
	AnswerStatusEscalated AnswerStatus = "escalated"
)

// Answer stores a user's response to a single question.
type Answer struct {
	ID          uuid.UUID    `json:"id"`
	AuditID     uuid.UUID    `json:"audit_id"`
	QuestionID  string       `json:"question_id"`
	MCID        string       `json:"mc_id,omitempty"`
	Value       interface{}  `json:"value"`
	Comment     string       `json:"comment,omitempty"`
	EvidenceIDs []string     `json:"evidence_ids"`
	Status      AnswerStatus `json:"status"`
	AnsweredAt  time.Time    `json:"answered_at"`
}

// AnswerInput is the request payload for answering a question.
type AnswerInput struct {
	QuestionID  string      `json:"question_id" binding:"required"`
	Value       interface{} `json:"value" binding:"required"`
	Comment     string      `json:"comment"`
	EvidenceIDs []string    `json:"evidence_ids"`
	Status      string      `json:"status"`
}

// ── Scoring ────────────────────────────────────────────────────────

// ScoreResult is the compliance summary for an audit.
type ScoreResult struct {
	AuditID         uuid.UUID  `json:"audit_id"`
	TotalQuestions  int        `json:"total_questions"`
	Answered        int        `json:"answered"`
	Passed          int        `json:"passed"`
	Failed          int        `json:"failed"`
	Skipped         int        `json:"skipped"`
	ComplianceScore float64    `json:"compliance_score"`
	ByRegulation    map[string]RegulationScore `json:"by_regulation"`
	BySeverity      map[string]SeverityScore   `json:"by_severity"`
}

// RegulationScore breaks down results per regulation.
type RegulationScore struct {
	Total  int     `json:"total"`
	Passed int     `json:"passed"`
	Score  float64 `json:"score"`
}

// SeverityScore breaks down results per severity.
type SeverityScore struct {
	Total  int `json:"total"`
	Passed int `json:"passed"`
	Failed int `json:"failed"`
}

// ── Gap Detection ──────────────────────────────────────────────────

// MissingSource describes a regulation not yet covered by MCs.
type MissingSource struct {
	Regulation      string   `json:"regulation"`
	AffectsMCs      []string `json:"affects_mcs"`
	EstimatedGap    int      `json:"estimated_controls"`
	SourceURL       string   `json:"source_url,omitempty"`
	Priority        string   `json:"priority"`
}

// CreateAuditInput is the request to start a new audit.
type CreateAuditInput struct {
	TemplateID string `json:"template_id" binding:"required"`
	Name       string `json:"name" binding:"required"`
	TargetName string `json:"target_name"`
}