Backlog/v12 compilance (#2317)

* fix[frontend](compilance): added controls visualization inside framework

* fix[frontend](compilance): added controls details visualization

* fix[backend](compilance): added manual state changes on framework-controls

* fix[frontend](compilance): added controls status change button

* fix[frontend](compilance): added controls notes

* fix[backend](compilance): added control notes

* fix[backend](compilance): added new entities on database migration schedule

* fix[frontend](compilance): re added framework report generator

---------

Co-authored-by: Yorjander Hernandez Vergara <99102374+Kbayero@users.noreply.github.com>

Author: AlexSanchez-bit

backend/database/migrations.go

@@ -48,6 +48,8 @@ func Models() []any {
 		arr_domain.UtmIncidentActionCommand{},
 		arr_domain.UtmIncidentJob{},
 		compliance_domain.UtmComplianceReportSchedule{},
+		compliance_domain.UtmComplianceControlStatusOverride{},
+		compliance_domain.UtmComplianceControlNote{},
 		opensearch_domain.UtmIndexPattern{},
 		integrations_domain.UtmModule{},
 		incidents_domain.UtmIncident{},

backend/modules/compliance/connectors/repository.go

@@ -30,3 +30,21 @@ type ReportStore interface {
 	Get(ctx context.Context, id string) (*domain.ReportSnapshot, error)
 	Delete(ctx context.Context, id string) error
 }
+
+// ControlStatusOverrideRepository stores manual (framework, control) → status
+// overrides. Upsert on the unique (framework_key, control_id) pair; ListByFramework
+// returns a controlID → status map for the evaluator to consume.
+type ControlStatusOverrideRepository interface {
+	Upsert(ctx context.Context, o *domain.UtmComplianceControlStatusOverride) error
+	Delete(ctx context.Context, frameworkKey, controlID string) error
+	ListByFramework(ctx context.Context, frameworkKey string) (map[string]string, error)
+}
+
+// ControlNoteRepository stores freeform notes per (framework, control). Same
+// upsert-on-unique pattern; ListByFramework returns a controlID → note map for
+// the evaluator to attach to report rows.
+type ControlNoteRepository interface {
+	Upsert(ctx context.Context, n *domain.UtmComplianceControlNote) error
+	Delete(ctx context.Context, frameworkKey, controlID string) error
+	ListByFramework(ctx context.Context, frameworkKey string) (map[string]string, error)
+}

backend/modules/compliance/connectors/usecase.go

@@ -44,6 +44,17 @@ type EvaluatorUsecase interface {
 	DeleteReport(ctx context.Context, id string) error
 	FrameworkReportPDF(ctx context.Context, frameworkKey string) ([]byte, string, error) // live eval → PDF + framework name
 	SnapshotPDF(ctx context.Context, id string) ([]byte, string, error)                  // stored snapshot → PDF + framework name
+
+	// Manual status overrides — applied on live evaluations only (historical
+	// snapshots are frozen). SetStatusOverride upserts; ClearStatusOverride
+	// removes the override so the row falls back to the computed status.
+	SetStatusOverride(ctx context.Context, frameworkKey, controlID, status, reason string) error
+	ClearStatusOverride(ctx context.Context, frameworkKey, controlID string) error
+
+	// User notes on (framework, control) — freeform text, surfaced on live report
+	// rows. Empty note deletes the row.
+	SetControlNote(ctx context.Context, frameworkKey, controlID, note string) error
+	ClearControlNote(ctx context.Context, frameworkKey, controlID string) error
 }
 
 type ScheduleUsecase interface {

backend/modules/compliance/domain/control_note.go

@@ -0,0 +1,17 @@
+package domain
+
+import "time"
+
+// UtmComplianceControlNote is a freeform user note attached to a (framework, control)
+// pair. Doesn't affect status; surfaced on the report row for the frontend to display.
+type UtmComplianceControlNote struct {
+	ID           int64     `gorm:"column:id;primaryKey;autoIncrement"`
+	FrameworkKey string    `gorm:"column:framework_key;size:100;not null;uniqueIndex:ux_note_fw_ctl,priority:1"`
+	ControlID    string    `gorm:"column:control_id;size:100;not null;uniqueIndex:ux_note_fw_ctl,priority:2"`
+	Note         string    `gorm:"column:note;type:text;not null"`
+	UpdatedAt    time.Time `gorm:"column:updated_at;not null"`
+}
+
+func (UtmComplianceControlNote) TableName() string {
+	return "utm_compliance_control_note"
+}

backend/modules/compliance/domain/control_status_override.go

@@ -0,0 +1,26 @@
+package domain
+
+import "time"
+
+// UtmComplianceControlStatusOverride is a manual status assignment for a
+// (framework, control) pair. Applied on top of the evaluator's computed status
+type UtmComplianceControlStatusOverride struct {
+	ID           int64     `gorm:"column:id;primaryKey;autoIncrement"`
+	FrameworkKey string    `gorm:"column:framework_key;size:100;not null;uniqueIndex:ux_ovr_fw_ctl,priority:1"`
+	ControlID    string    `gorm:"column:control_id;size:100;not null;uniqueIndex:ux_ovr_fw_ctl,priority:2"`
+	Status       string    `gorm:"column:status;size:32;not null"`
+	Reason       string    `gorm:"column:reason;size:500"`
+	UpdatedAt    time.Time `gorm:"column:updated_at;not null"`
+}
+
+func (UtmComplianceControlStatusOverride) TableName() string {
+	return "utm_compliance_control_status_override"
+}
+
+func ValidStatus(s string) bool {
+	switch s {
+	case StatusCompliant, StatusNonCompliant, StatusAtRisk, StatusNotCovered, StatusOutOfScope, StatusPending:
+		return true
+	}
+	return false
+}

backend/modules/compliance/domain/errors.go

@@ -14,4 +14,5 @@ var (
 	ErrInvalidID         = errors.New("invalid id/key (must be non-empty and contain no path separators)")
 	ErrFrameworkLocked   = errors.New("this framework requires an Enterprise license")
 	ErrControlLocked     = errors.New("this control requires an Enterprise license")
+	ErrInvalidStatus     = errors.New("invalid control status")
 )

backend/modules/compliance/domain/report.go

@@ -34,9 +34,6 @@ type ReportSection struct {
 	Controls []ReportControlRow `json:"controls"`
 }
 
-// ReportSnapshot is a stored, point-in-time compliance report (in OpenSearch).
-// The report is DATA: the frontend renders it, the PDF path renders it, and the
-// snapshot is the durable history — no binary PDF is stored.
 type ReportSnapshot struct {
 	ID            string `json:"id"`
 	FrameworkKey  string `json:"frameworkKey"`
@@ -56,10 +53,12 @@ type ReportSnapshotMeta struct {
 }
 
 type ReportControlRow struct {
-	ControlID string `json:"controlId"`
-	Name      string `json:"name"`
-	Status    string `json:"status"` // COMPLIANT | NON_COMPLIANT | AT_RISK | NOT_COVERED | OUT_OF_SCOPE | PENDING
-	Evidence  string `json:"evidence"`
-	Coverage  int    `json:"coverage"` // # enabled correlation rules covering this control
-	Activity  int    `json:"activity"` // # alerts from those rules in the window
+	ControlID  string `json:"controlId"`
+	Name       string `json:"name"`
+	Status     string `json:"status"` // COMPLIANT | NON_COMPLIANT | AT_RISK | NOT_COVERED | OUT_OF_SCOPE | PENDING
+	Evidence   string `json:"evidence"`
+	Coverage   int    `json:"coverage"`             // # enabled correlation rules covering this control
+	Activity   int    `json:"activity"`             // # alerts from those rules in the window
+	Overridden bool   `json:"overridden,omitempty"` // true when status came from a manual override
+	Note       string `json:"note,omitempty"`       // user note attached to this (framework, control)
 }

backend/modules/compliance/handler/common.go

@@ -22,7 +22,7 @@ func writeError(c *gin.Context, err error) {
 		c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
 	case errors.Is(err, domain.ErrControlExists), errors.Is(err, domain.ErrFrameworkExists):
 		c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
-	case errors.Is(err, domain.ErrInvalidCron), errors.Is(err, domain.ErrInvalidID):
+	case errors.Is(err, domain.ErrInvalidCron), errors.Is(err, domain.ErrInvalidID), errors.Is(err, domain.ErrInvalidStatus):
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 	default:
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})

backend/modules/compliance/handler/report.go

@@ -159,6 +159,115 @@ func (h *ReportHandler) GetFrameworkReportPDF(c *gin.Context) {
 	writePDF(c, pdf, name)
 }
 
+// SetStatusOverride godoc
+//
+//	@Summary     Set a manual status override for a control
+//	@Description Overrides the evaluator's computed status for a (framework, control) pair. Applied on live evaluations only; historical snapshots are unchanged.
+//	@Tags        Compliance Reports
+//	@Security    BearerAuth
+//	@Accept      json
+//	@Produce     json
+//	@Param       key    path     string true "Framework key"
+//	@Param       id     path     string true "Control id"
+//	@Param       body   body     object true "New status (COMPLIANT | NON_COMPLIANT | AT_RISK | NOT_COVERED | OUT_OF_SCOPE | PENDING) and optional reason"
+//	@Success     204
+//	@Failure     400 {object} map[string]string
+//	@Failure     404 {object} map[string]string
+//	@Router      /compliance/frameworks/{key}/controls/{id}/status [put]
+func (h *ReportHandler) SetStatusOverride(c *gin.Context) {
+	var body struct {
+		Status string `json:"status"`
+		Reason string `json:"reason"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	err := h.uc.SetStatusOverride(c.Request.Context(), c.Param("key"), c.Param("id"), body.Status, body.Reason)
+	audit.Record(c, audit_connectors.Event{Action: "compliance.control.status.override", ResourceType: "compliance_control", ResourceID: c.Param("id")},
+		audit_domain.COMPLIANCE_CONTROL_UPDATE_ATTEMPT, audit_domain.COMPLIANCE_CONTROL_UPDATE_SUCCESS, err)
+	if err != nil {
+		writeError(c, err)
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+// ClearStatusOverride godoc
+//
+//	@Summary     Clear a manual status override
+//	@Description Removes the manual override so the control status falls back to the evaluator's computed value.
+//	@Tags        Compliance Reports
+//	@Security    BearerAuth
+//	@Param       key path string true "Framework key"
+//	@Param       id  path string true "Control id"
+//	@Success     204
+//	@Failure     404 {object} map[string]string
+//	@Router      /compliance/frameworks/{key}/controls/{id}/status [delete]
+func (h *ReportHandler) ClearStatusOverride(c *gin.Context) {
+	err := h.uc.ClearStatusOverride(c.Request.Context(), c.Param("key"), c.Param("id"))
+	audit.Record(c, audit_connectors.Event{Action: "compliance.control.status.override.clear", ResourceType: "compliance_control", ResourceID: c.Param("id")},
+		audit_domain.COMPLIANCE_CONTROL_UPDATE_ATTEMPT, audit_domain.COMPLIANCE_CONTROL_UPDATE_SUCCESS, err)
+	if err != nil {
+		writeError(c, err)
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+// SetControlNote godoc
+//
+//	@Summary     Set / update a user note on a control
+//	@Description Upserts a freeform note attached to a (framework, control). Empty body deletes the note.
+//	@Tags        Compliance Reports
+//	@Security    BearerAuth
+//	@Accept      json
+//	@Produce     json
+//	@Param       key  path     string true "Framework key"
+//	@Param       id   path     string true "Control id"
+//	@Param       body body     object true "Note body ({note: string})"
+//	@Success     204
+//	@Failure     400 {object} map[string]string
+//	@Failure     404 {object} map[string]string
+//	@Router      /compliance/frameworks/{key}/controls/{id}/note [put]
+func (h *ReportHandler) SetControlNote(c *gin.Context) {
+	var body struct {
+		Note string `json:"note"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	err := h.uc.SetControlNote(c.Request.Context(), c.Param("key"), c.Param("id"), body.Note)
+	audit.Record(c, audit_connectors.Event{Action: "compliance.control.note.set", ResourceType: "compliance_control", ResourceID: c.Param("id")},
+		audit_domain.COMPLIANCE_CONTROL_UPDATE_ATTEMPT, audit_domain.COMPLIANCE_CONTROL_UPDATE_SUCCESS, err)
+	if err != nil {
+		writeError(c, err)
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+// ClearControlNote godoc
+//
+//	@Summary     Delete a user note on a control
+//	@Tags        Compliance Reports
+//	@Security    BearerAuth
+//	@Param       key path string true "Framework key"
+//	@Param       id  path string true "Control id"
+//	@Success     204
+//	@Router      /compliance/frameworks/{key}/controls/{id}/note [delete]
+func (h *ReportHandler) ClearControlNote(c *gin.Context) {
+	err := h.uc.ClearControlNote(c.Request.Context(), c.Param("key"), c.Param("id"))
+	audit.Record(c, audit_connectors.Event{Action: "compliance.control.note.clear", ResourceType: "compliance_control", ResourceID: c.Param("id")},
+		audit_domain.COMPLIANCE_CONTROL_UPDATE_ATTEMPT, audit_domain.COMPLIANCE_CONTROL_UPDATE_SUCCESS, err)
+	if err != nil {
+		writeError(c, err)
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
 // @Summary     Download a stored report snapshot as PDF
 // @Tags        Compliance Reports
 // @Security    BearerAuth

backend/modules/compliance/module.go

@@ -36,6 +36,8 @@ func (m *Module) GetScheduleUsecase() connectors.ScheduleUsecase   { return m.sc
 
 func NewModule(db *gorm.DB, mailSvc mail_connectors.MailService, brand connectors.BrandingProvider, isEnterprise func() bool) *Module {
 	scheduleRepo := repository.NewScheduleRepository(db)
+	overrideRepo := repository.NewControlStatusOverrideRepository(db)
+	noteRepo := repository.NewControlNoteRepository(db)
 
 	root := env.String("COMPLIANCE_DIR", "/workdir/compliance", false)
 	src := env.String("COMPLIANCE_SRC_DIR", "/utmstack/compliance", false)
@@ -62,7 +64,7 @@ func NewModule(db *gorm.DB, mailSvc mail_connectors.MailService, brand connector
 
 	entitlement := usecase.NewEntitlement(isEnterprise)
 	frameworkUC := usecase.NewFrameworkUsecase(controlStore, frameworkStore, entitlement)
-	evaluatorUC := usecase.NewEvaluator(controlStore, frameworkStore, repository.NewOpenSearchSQL(), coverageIdx, repository.NewOpenSearchAlerts(), repository.NewReportStore(), brand, entitlement)
+	evaluatorUC := usecase.NewEvaluator(controlStore, frameworkStore, repository.NewOpenSearchSQL(), coverageIdx, repository.NewOpenSearchAlerts(), repository.NewReportStore(), overrideRepo, noteRepo, brand, entitlement)
 	scheduleUC := usecase.NewScheduleUsecase(scheduleRepo, frameworkStore, entitlement)
 
 	mailSender := &mailSender{svc: mailSvc}