Notification Preferences + Ops KPI Dashboard — Implementation Plan

-- +goose Up
-- Per-user notification preferences. An ABSENT row means all defaults (email on,
-- instant frequency, nothing muted) — the migration seeds nothing, so existing behavior
-- is unchanged until a user opts out. notify.Service reads this BEST-EFFORT at delivery
-- time; a read error falls back to defaults so notification delivery never breaks.
--
-- muted_categories holds notification Kind slugs (workflow, document, document_expiry,
-- records_disposition, meterai_quota); a muted category is suppressed on BOTH the in-app
-- inbox and email. frequency gates ONLY the email channel (in-app is always the source of
-- truth for a non-muted category): 'instant' emails now, 'daily' defers to the digest
-- sweep, 'off' never emails.
CREATE TABLE notification_prefs (
    user_id          uuid PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
    email_enabled    boolean NOT NULL DEFAULT true,
    frequency        text NOT NULL DEFAULT 'instant',
    muted_categories text[] NOT NULL DEFAULT '{}',
    updated_at       timestamptz NOT NULL DEFAULT now(),
    CONSTRAINT notification_prefs_frequency_chk CHECK (frequency IN ('instant', 'daily', 'off'))
);

-- +goose Down
DROP TABLE notification_prefs;

package domain

// Notification frequency values, controlling the EMAIL channel only (the in-app inbox is
// never affected by frequency — only by muting).
const (
    FrequencyInstant = "instant"
    FrequencyDaily   = "daily"
    FrequencyOff     = "off"
)

// Notification categories == the Message.Kind strings passed to Notify across the app. A
// user mutes a category to stop BOTH in-app and email for it. These mirror, exactly, the
// Kinds emitted by the outbox relay (cmd/obscura-server/wire.go) and the scheduled sweeps
// (cmd/obscura-server/jobs.go):
//   workflow            — workflow.task_assigned (an approval task was assigned to you)
//   document            — document.version_added (a document you follow got a new version)
//   document_expiry     — the daily expiry-reminder sweep
//   records_disposition — the daily records-due-for-disposition sweep
//   meterai_quota       — the daily e-Meterai low-quota warning
const (
    CategoryWorkflow           = "workflow"
    CategoryDocument           = "document"
    CategoryDocumentExpiry     = "document_expiry"
    CategoryRecordsDisposition = "records_disposition"
    CategoryMeteraiQuota       = "meterai_quota"
)

// KnownCategories is the canonical, closed set of muteable category slugs. The PUT prefs
// endpoint validates muted_categories against it.
func KnownCategories() []string {
    return []string{
        CategoryWorkflow, CategoryDocument, CategoryDocumentExpiry,
        CategoryRecordsDisposition, CategoryMeteraiQuota,
    }
}

// IsKnownCategory reports whether slug is a recognised notification category.
func IsKnownCategory(slug string) bool {
    switch slug {
    case CategoryWorkflow, CategoryDocument, CategoryDocumentExpiry,
        CategoryRecordsDisposition, CategoryMeteraiQuota:
        return true
    default:
        return false
    }
}

// IsValidFrequency reports whether f is one of the three allowed frequencies.
func IsValidFrequency(f string) bool {
    return f == FrequencyInstant || f == FrequencyDaily || f == FrequencyOff
}

// Prefs is a user's effective notification preferences. The zero value is NOT the default
// (email would read as disabled) — use DefaultPrefs for an absent row.
type Prefs struct {
    EmailEnabled    bool
    Frequency       string
    MutedCategories []string
}

// DefaultPrefs is the behavior for a user with no stored row: everything on, instant email,
// nothing muted. This preserves today's behavior until a user opts out.
func DefaultPrefs() Prefs {
    return Prefs{EmailEnabled: true, Frequency: FrequencyInstant, MutedCategories: []string{}}
}

// Muted reports whether category is in the muted set.
func (p Prefs) Muted(category string) bool {
    for _, c := range p.MutedCategories {
        if c == category {
            return true
        }
    }
    return false
}

package app

import (
    "context"

    "github.com/Virtue-Digital-Indonesia/obscura/internal/kernel"
    "github.com/Virtue-Digital-Indonesia/obscura/internal/notify/domain"
)

// PrefsRepository is the persistence port for per-user notification preferences.
type PrefsRepository interface {
    // Get returns a user's stored prefs. found=false (with a zero Prefs and nil error)
    // when the user has no row — the caller substitutes DefaultPrefs.
    Get(ctx context.Context, userID string) (domain.Prefs, bool, error)
    // Upsert inserts or replaces a user's prefs (stamping updated_at).
    Upsert(ctx context.Context, userID string, p domain.Prefs) error
    // DailyDigestUserIDs returns the ids of users who opted into a daily email digest
    // (frequency='daily' AND email_enabled=true). Used by the digest sweep.
    DailyDigestUserIDs(ctx context.Context) ([]string, error)
}

// PrefsService is the notification-preferences use-case layer: the self-service read/write
// behind GET/PUT /me/notification-prefs, and the daily-digest recipient query. It also
// satisfies the Service's PrefsReader port (Get) for delivery-time enforcement.
type PrefsService struct {
    repo PrefsRepository
}

// NewPrefsService wires the prefs service over its repository.
func NewPrefsService(repo PrefsRepository) *PrefsService { return &PrefsService{repo: repo} }

// Get returns a user's effective prefs — the stored row, or DefaultPrefs when absent. This
// is the method notify.Service calls at delivery time (via PrefsReader), so an absent row
// transparently yields the everything-on default.
func (s *PrefsService) Get(ctx context.Context, userID string) (domain.Prefs, error) {
    p, found, err := s.repo.Get(ctx, userID)
    if err != nil {
        return domain.Prefs{}, err
    }
    if !found {
        return domain.DefaultPrefs(), nil
    }
    return p, nil
}

// Put validates and stores a user's prefs (self-service). Frequency must be one of the three
// enum values; every muted category must be a known slug (unknown input is a validation
// error, never silently dropped). Duplicates are de-duped.
func (s *PrefsService) Put(ctx context.Context, userID string, p domain.Prefs) error {
    if userID == "" {
        return &kernel.Error{Kind: kernel.ErrValidation, Code: "notify.prefs.user_required", Message: "user id is required"}
    }
    if !domain.IsValidFrequency(p.Frequency) {
        return &kernel.Error{Kind: kernel.ErrValidation, Code: "notify.prefs.frequency_invalid", Message: "frequency must be instant, daily, or off"}
    }
    seen := map[string]bool{}
    clean := make([]string, 0, len(p.MutedCategories))
    for _, c := range p.MutedCategories {
        if !domain.IsKnownCategory(c) {
            return &kernel.Error{Kind: kernel.ErrValidation, Code: "notify.prefs.category_unknown", Message: "unknown notification category: " + c}
        }
        if !seen[c] {
            seen[c] = true
            clean = append(clean, c)
        }
    }
    p.MutedCategories = clean
    return s.repo.Upsert(ctx, userID, p)
}

// DailyDigestUserIDs passes through to the repository (used by the digest sweep).
func (s *PrefsService) DailyDigestUserIDs(ctx context.Context) ([]string, error) {
    return s.repo.DailyDigestUserIDs(ctx)
}

// PrefsService satisfies the Service's delivery-time reader port.
var _ PrefsReader = (*PrefsService)(nil)

    // ListForUserSince returns a user's notifications created at/after `since`, newest-first.
    // The daily digest sweep uses it to recap the window's in-app rows.
    ListForUserSince(ctx context.Context, userID string, since time.Time) ([]domain.Notification, error)

// PrefsReader supplies a user's effective preferences to Notify at delivery time.
// Implemented by *PrefsService. Reads are best-effort: Notify treats any error as defaults
// so a prefs outage never breaks delivery.
type PrefsReader interface {
    Get(ctx context.Context, userID string) (domain.Prefs, error)
}

type Service struct {
    repo     Repository
    channels []Channel
    prefs    PrefsReader  // optional; nil → everyone gets everything, instant
    logger   *slog.Logger // optional; used only to log best-effort prefs read failures
}

// WithPrefs attaches the per-user preference reader (and a logger for best-effort read
// failures) used to gate delivery. Returns the same Service for chaining. A Service without
// prefs behaves exactly as before (everyone gets everything, instant email).
func (s *Service) WithPrefs(prefs PrefsReader, logger *slog.Logger) *Service {
    s.prefs = prefs
    s.logger = logger
    return s
}

func (s *Service) Notify(ctx context.Context, to domain.Recipient, msg domain.Message) error {
    if to.UserID == "" {
        return &kernel.Error{Kind: kernel.ErrValidation, Code: "notify.recipient.user_required", Message: "recipient user id is required"}
    }

    // Best-effort preference read. A prefs outage MUST NOT break delivery: any error (or no
    // prefs port wired) yields defaults — everything on, instant.
    prefs := domain.DefaultPrefs()
    if s.prefs != nil {
        if p, err := s.prefs.Get(ctx, to.UserID); err != nil {
            if s.logger != nil {
                s.logger.Warn("notify prefs read failed; using defaults", "user", to.UserID, "err", err)
            }
        } else {
            prefs = p
        }
    }

    // A muted category is suppressed entirely — no in-app row, no email. Unmuting later
    // restores delivery; subscriptions/data flow are untouched.
    if prefs.Muted(msg.Kind) {
        return nil
    }

    // In-app is the source of truth: always persisted for a non-muted category, regardless of
    // the email/frequency settings below.
    n := domain.NewNotification(kernel.NewID(), to, msg, kernel.SystemClock().Now())
    if err := s.repo.Insert(ctx, n); err != nil {
        return err
    }

    // Out-of-band fan-out, best-effort. The email channel is gated by the user's prefs:
    //   email_enabled=false → no email (in-app only)
    //   frequency='off'     → no email ever
    //   frequency='daily'   → suppress the instant email; the daily digest sweep sends it
    //   frequency='instant' → send now
    // Non-email channels (none today) are unaffected by the frequency/email controls.
    for _, ch := range s.channels {
        if ch.Name() == "email" {
            if to.Email == "" || !prefs.EmailEnabled || prefs.Frequency != domain.FrequencyInstant {
                continue
            }
        }
        _ = ch.Send(ctx, to, msg)
    }
    return nil
}

// ListForUserSince returns a user's notifications created at/after `since` (newest-first).
func (s *Service) ListForUserSince(ctx context.Context, userID string, since time.Time) ([]domain.Notification, error) {
    return s.repo.ListForUserSince(ctx, userID, since)
}

// SendEmailOnly delivers msg via out-of-band email channels WITHOUT persisting an in-app row
// and WITHOUT consulting prefs. It exists for the daily digest sweep, whose recipients have
// already opted into a daily email; the digest body recaps in-app rows that were recorded
// (unmuted) during the window. Best-effort — channel errors are dropped.
func (s *Service) SendEmailOnly(ctx context.Context, to domain.Recipient, msg domain.Message) {
    if to.Email == "" {
        return
    }
    for _, ch := range s.channels {
        if ch.Name() == "email" {
            _ = ch.Send(ctx, to, msg)
        }
    }
}

// ListForUserSince returns a user's notifications created at/after `since`, newest-first
// (the daily digest window). No LIMIT — a day's notifications for one user is bounded.
func (s *Store) ListForUserSince(ctx context.Context, userID string, since time.Time) ([]domain.Notification, error) {
    rows, err := s.db.Exec(ctx).Query(ctx,
        `SELECT id, user_id, kind, title, body, read, created_at
           FROM notifications
          WHERE user_id = $1 AND created_at >= $2
          ORDER BY created_at DESC`, userID, since)
    if err != nil {
        return nil, fmt.Errorf("notify list for user since: %w", err)
    }
    defer rows.Close()

    var out []domain.Notification
    for rows.Next() {
        var n domain.Notification
        if err := rows.Scan(&n.ID, &n.UserID, &n.Kind, &n.Title, &n.Body, &n.Read, &n.CreatedAt); err != nil {
            return nil, fmt.Errorf("notify scan notification (since): %w", err)
        }
        out = append(out, n)
    }
    if err := rows.Err(); err != nil {
        return nil, fmt.Errorf("notify list since rows: %w", err)
    }
    return out, nil
}

package adapters

import (
    "context"
    "errors"
    "fmt"

    "github.com/jackc/pgx/v5"

    "github.com/Virtue-Digital-Indonesia/obscura/internal/notify/app"
    "github.com/Virtue-Digital-Indonesia/obscura/internal/notify/domain"
    "github.com/Virtue-Digital-Indonesia/obscura/internal/platform/db"
)

// PrefsStore implements app.PrefsRepository over the notification_prefs table. Like the
// inbox Store it runs every statement through s.db.Exec(ctx) and never opens its own tx.
type PrefsStore struct {
    db *db.DB
}

// NewPrefsStore constructs the notification-preferences repository.
func NewPrefsStore(d *db.DB) *PrefsStore { return &PrefsStore{db: d} }

// Get loads a user's prefs. A missing row is reported found=false (nil error) so the caller
// substitutes DefaultPrefs.
func (s *PrefsStore) Get(ctx context.Context, userID string) (domain.Prefs, bool, error) {
    var p domain.Prefs
    err := s.db.Exec(ctx).QueryRow(ctx,
        `SELECT email_enabled, frequency, muted_categories
           FROM notification_prefs WHERE user_id = $1`, userID).
        Scan(&p.EmailEnabled, &p.Frequency, &p.MutedCategories)
    if errors.Is(err, pgx.ErrNoRows) {
        return domain.Prefs{}, false, nil
    }
    if err != nil {
        return domain.Prefs{}, false, fmt.Errorf("notify prefs get: %w", err)
    }
    return p, true, nil
}

// Upsert inserts or replaces a user's prefs (stamping updated_at server-side).
func (s *PrefsStore) Upsert(ctx context.Context, userID string, p domain.Prefs) error {
    muted := p.MutedCategories
    if muted == nil {
        muted = []string{} // never write SQL NULL into a NOT NULL text[] column
    }
    if _, err := s.db.Exec(ctx).Exec(ctx,
        `INSERT INTO notification_prefs (user_id, email_enabled, frequency, muted_categories, updated_at)
         VALUES ($1, $2, $3, $4, now())
         ON CONFLICT (user_id) DO UPDATE SET
             email_enabled = EXCLUDED.email_enabled,
             frequency = EXCLUDED.frequency,
             muted_categories = EXCLUDED.muted_categories,
             updated_at = now()`,
        userID, p.EmailEnabled, p.Frequency, muted); err != nil {
        return fmt.Errorf("notify prefs upsert: %w", err)
    }
    return nil
}

// DailyDigestUserIDs returns users who want a daily email digest (frequency='daily' AND
// email_enabled=true). 'off' users and email-disabled users are excluded.
func (s *PrefsStore) DailyDigestUserIDs(ctx context.Context) ([]string, error) {
    rows, err := s.db.Exec(ctx).Query(ctx,
        `SELECT user_id FROM notification_prefs
          WHERE frequency = 'daily' AND email_enabled = true`)
    if err != nil {
        return nil, fmt.Errorf("notify prefs daily digest users: %w", err)
    }
    defer rows.Close()
    var out []string
    for rows.Next() {
        var id string
        if err := rows.Scan(&id); err != nil {
            return nil, fmt.Errorf("notify prefs daily digest scan: %w", err)
        }
        out = append(out, id)
    }
    if err := rows.Err(); err != nil {
        return nil, fmt.Errorf("notify prefs daily digest rows: %w", err)
    }
    return out, nil
}

var _ app.PrefsRepository = (*PrefsStore)(nil)

// runNotificationDigest emails a once-a-day recap to every user who chose the 'daily'
// frequency (with email on). The recap lists the in-app notifications recorded for them in
// the last 24h — muted categories never created an in-app row, so they are already excluded.
// A user with no notifications in the window is skipped. Best-effort: a per-user failure is
// logged and does not abort the sweep. Runs daily (no boot TriggerNow — a boot digest is
// never urgent). The 24h window aligns with the 24h cadence so each notification appears in
// exactly one digest.
func runNotificationDigest(
    ctx context.Context,
    notify *notifyapp.Service,
    prefs *notifyapp.PrefsService,
    auth *authapp.Service,
    logger *slog.Logger,
) error {
    userIDs, err := prefs.DailyDigestUserIDs(ctx)
    if err != nil {
        return err
    }
    since := time.Now().Add(-24 * time.Hour)
    for _, uid := range userIDs {
        if uid == "" {
            continue
        }
        items, lerr := notify.ListForUserSince(ctx, uid, since)
        if lerr != nil {
            logger.Error("daily digest list failed", "user", uid, "err", lerr)
            continue
        }
        if len(items) == 0 {
            continue
        }
        u, gerr := auth.GetUser(ctx, uid)
        if gerr != nil || u.Email == "" {
            continue // no address; the in-app rows are still in their inbox
        }
        body := fmt.Sprintf("You have %d new notification(s) from the last 24 hours:\n\n", len(items))
        for _, n := range items {
            body += "• " + n.Title + "\n"
        }
        notify.SendEmailOnly(ctx,
            notifydomain.Recipient{UserID: uid, Email: u.Email},
            notifydomain.Message{Kind: "digest", Title: "Your daily notification digest", Body: body})
    }
    return nil
}

    notifyPrefsSvc := notifyapp.NewPrefsService(notifyadapters.NewPrefsStore(database))
    notifySvc := notifyapp.NewService(
        notifyadapters.NewStore(database),
        notifyadapters.NewSMTPChannel(notifyadapters.SMTPConfig{Host: cfg.SMTP.Host, Port: cfg.SMTP.Port, From: cfg.SMTP.From}),
    ).WithPrefs(notifyPrefsSvc, logger)

    // Daily notification digest: one recap email to each user on the 'daily' frequency
    // (email on). No TriggerNow — a boot digest is never urgent.
    schedulerSvc.Register("notify.daily_digest", 24*time.Hour, func(ctx context.Context) error {
        return runNotificationDigest(ctx, notifySvc, notifyPrefsSvc, authSvc, logger)
    })

git add go/migrations/00081_notification_prefs.sql go/internal/notify/domain/prefs.go go/internal/notify/app/prefs.go go/internal/notify/app/service.go go/internal/notify/adapters/pg.go go/internal/notify/adapters/prefs_pg.go go/cmd/obscura-server/jobs.go go/cmd/obscura-server/wire.go
git commit -m "feat(notify): per-user notification prefs — store, delivery-time enforcement, daily digest sweep"

import (
    "encoding/json"
    "net/http"

    "github.com/go-chi/chi/v5"

    "github.com/Virtue-Digital-Indonesia/obscura/internal/kernel"
    notifydomain "github.com/Virtue-Digital-Indonesia/obscura/internal/notify/domain"
)

// notifPrefsView is the JSON shape for a user's notification preferences.
type notifPrefsView struct {
    EmailEnabled    bool     `json:"email_enabled"`
    Frequency       string   `json:"frequency"`
    MutedCategories []string `json:"muted_categories"`
}

func toNotifPrefsView(p notifydomain.Prefs) notifPrefsView {
    muted := p.MutedCategories
    if muted == nil {
        muted = []string{} // JSON [] not null, so the client always gets an array
    }
    return notifPrefsView{EmailEnabled: p.EmailEnabled, Frequency: p.Frequency, MutedCategories: muted}
}

// GetNotificationPrefs returns the caller's notification preferences (self only). An absent
// row yields the defaults (everything on, instant).
func (s *Server) GetNotificationPrefs(w http.ResponseWriter, r *http.Request) {
    p, _ := PrincipalFrom(r.Context())
    prefs, err := s.notifyPrefs.Get(r.Context(), string(p.UserID))
    if err != nil {
        writeProblem(w, err)
        return
    }
    writeJSON(w, http.StatusOK, toNotifPrefsView(prefs))
}

// PutNotificationPrefs replaces the caller's notification preferences (self only). Validates
// the frequency enum and that every muted category is a known slug; returns the normalized,
// stored value.
func (s *Server) PutNotificationPrefs(w http.ResponseWriter, r *http.Request) {
    p, _ := PrincipalFrom(r.Context())
    var body struct {
        EmailEnabled    bool     `json:"email_enabled"`
        Frequency       string   `json:"frequency"`
        MutedCategories []string `json:"muted_categories"`
    }
    if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
        writeProblem(w, &kernel.Error{Kind: kernel.ErrValidation, Code: "request.invalid_json", Message: "invalid request body"})
        return
    }
    prefs := notifydomain.Prefs{
        EmailEnabled:    body.EmailEnabled,
        Frequency:       body.Frequency,
        MutedCategories: body.MutedCategories,
    }
    if err := s.notifyPrefs.Put(r.Context(), string(p.UserID), prefs); err != nil {
        writeProblem(w, err)
        return
    }
    // Re-read so the response reflects the normalized (de-duped) stored value.
    stored, err := s.notifyPrefs.Get(r.Context(), string(p.UserID))
    if err != nil {
        writeProblem(w, err)
        return
    }
    writeJSON(w, http.StatusOK, toNotifPrefsView(stored))
}

            // Self-service notification preferences (per-category mutes, email on/off, frequency).
            r.Get("/me/notification-prefs", s.GetNotificationPrefs)
            r.Put("/me/notification-prefs", s.PutNotificationPrefs)

  /api/v1/me/notification-prefs:
    get:
      operationId: getNotificationPrefs
      summary: Get my notification preferences
      description: >-
        Returns the caller's notification preferences. An absent row yields the defaults
        (email on, instant frequency, nothing muted). Self only.
      tags: [me]
      responses:
        '200':
          description: The caller's notification preferences.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPrefs'
        '401':
          $ref: '#/components/responses/Problem'
    put:
      operationId: putNotificationPrefs
      summary: Replace my notification preferences
      description: >-
        Replaces the caller's notification preferences. `frequency` must be one of
        instant|daily|off; every entry in `muted_categories` must be a known category slug
        (workflow, document, document_expiry, records_disposition, meterai_quota). Self only.
      tags: [me]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationPrefs'
      responses:
        '200':
          description: The stored (normalized) preferences.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPrefs'
        '400':
          $ref: '#/components/responses/Problem'
        '401':
          $ref: '#/components/responses/Problem'

    NotificationPrefs:
      type: object
      description: A user's notification preferences.
      properties:
        email_enabled:
          type: boolean
          description: When false, no emails are sent (in-app inbox is unaffected).
        frequency:
          type: string
          enum: [instant, daily, off]
          description: >-
            Email cadence. instant = email immediately; daily = suppress the instant email,
            include the item in the once-daily digest; off = never email. In-app is unaffected.
        muted_categories:
          type: array
          items:
            type: string
            enum: [workflow, document, document_expiry, records_disposition, meterai_quota]
          description: Categories suppressed on BOTH in-app inbox and email.
      required: [email_enabled, frequency, muted_categories]

git add go/internal/httpapi/handlers_notify.go go/internal/httpapi/server.go go/cmd/obscura-server/wire.go api/openapi.yaml web/src/api/schema.ts
git commit -m "feat(api): GET/PUT /me/notification-prefs (self-service, validated) + OpenAPI"

export type NotifFrequency = 'instant' | 'daily' | 'off'

export interface NotifPrefs {
  emailEnabled: boolean
  frequency: NotifFrequency
  mutedCategories: string[]
}

// The five real notification categories (== server Message.Kind slugs). Order = display order.
export const NOTIF_CATEGORIES = [
  'workflow',
  'document',
  'document_expiry',
  'records_disposition',
  'meterai_quota',
] as const

export function useNotifPrefs() {
  return useQuery<NotifPrefs>({
    queryKey: ['notif-prefs'],
    queryFn: async () => {
      const r = ok(await api.GET('/api/v1/me/notification-prefs', {}))
      return {
        emailEnabled: r.email_enabled ?? true,
        frequency: (r.frequency ?? 'instant') as NotifFrequency,
        mutedCategories: r.muted_categories ?? [],
      }
    },
  })
}

export function useUpdateNotifPrefs() {
  const qc = useQueryClient()
  return useMutation({
    mutationFn: (p: NotifPrefs) =>
      api
        .PUT('/api/v1/me/notification-prefs', {
          body: { email_enabled: p.emailEnabled, frequency: p.frequency, muted_categories: p.mutedCategories },
        })
        .then(ok),
    onSuccess: () => qc.invalidateQueries({ queryKey: ['notif-prefs'] }),
  })
}

function NotificationsPanel() {
  const { t } = useTranslation()
  const { data, isLoading } = useNotifPrefs()
  const update = useUpdateNotifPrefs()
  const [emailEnabled, setEmailEnabled] = useState(true)
  const [frequency, setFrequency] = useState<NotifFrequency>('instant')
  const [muted, setMuted] = useState<Set<string>>(new Set())
  const [loaded, setLoaded] = useState(false)

  // Seed local state once, from the loaded prefs.
  if (data && !loaded) {
    setEmailEnabled(data.emailEnabled)
    setFrequency(data.frequency)
    setMuted(new Set(data.mutedCategories))
    setLoaded(true)
  }

  const toggleCategory = (cat: string, on: boolean) => {
    setMuted((prev) => {
      const next = new Set(prev)
      // Toggle ON = "receive this category" = NOT muted.
      if (on) next.delete(cat)
      else next.add(cat)
      return next
    })
  }

  const save = () => {
    update.mutate({ emailEnabled, frequency, mutedCategories: [...muted] })
  }

  return (
    <section className="page__section">
      <h2 className="page__section-title">{t('profile.notif.title')}</h2>
      <p className="muted">{t('profile.notif.meta')}</p>
      {isLoading ? (
        <p className="muted">{t('profile.notif.loading')}</p>
      ) : (
        <div className="notif-prefs">
          <Toggle
            id="notif-email"
            size="sm"
            labelText={t('profile.notif.emailLabel')}
            labelA={t('profile.notif.off')}
            labelB={t('profile.notif.on')}
            toggled={emailEnabled}
            onToggle={setEmailEnabled}
          />
          <Select
            id="notif-frequency"
            labelText={t('profile.notif.frequencyLabel')}
            value={frequency}
            onChange={(e) => setFrequency(e.target.value as NotifFrequency)}
            disabled={!emailEnabled}
          >
            <SelectItem value="instant" text={t('profile.notif.freq.instant')} />
            <SelectItem value="daily" text={t('profile.notif.freq.daily')} />
            <SelectItem value="off" text={t('profile.notif.freq.off')} />
          </Select>

          <h3 className="notif-prefs__subtitle">{t('profile.notif.categoriesTitle')}</h3>
          <div className="notif-prefs__cats">
            {NOTIF_CATEGORIES.map((cat) => (
              <Toggle
                key={cat}
                id={`notif-cat-${cat}`}
                size="sm"
                labelText={t(`profile.notif.cat.${cat}`)}
                labelA={t('profile.notif.muted')}
                labelB={t('profile.notif.on')}
                toggled={!muted.has(cat)}
                onToggle={(on) => toggleCategory(cat, on)}
              />
            ))}
          </div>

          <div className="profile-actions">
            <Button kind="tertiary" size="sm" onClick={save} disabled={update.isPending || !loaded}>
              {t('profile.notif.save')}
            </Button>
          </div>
          {update.isSuccess && <p className="muted">{t('profile.notif.saved')}</p>}
          {update.isError && <p className="edit-attrs__error">{t('profile.notif.error')}</p>}
        </div>
      )}
    </section>
  )
}

    notif: {
      title: 'Notifications',
      meta: 'Choose which notifications you receive and how you’re emailed.',
      loading: 'Loading preferences…',
      emailLabel: 'Email notifications',
      on: 'On',
      off: 'Off',
      muted: 'Muted',
      frequencyLabel: 'Email frequency',
      freq: { instant: 'Instant', daily: 'Daily digest', off: 'Never' },
      categoriesTitle: 'Categories',
      cat: {
        workflow: 'Approval tasks',
        document: 'Document updates you follow',
        document_expiry: 'Document expiry reminders',
        records_disposition: 'Records due for disposition',
        meterai_quota: 'e-Meterai quota warnings',
      },
      save: 'Save preferences',
      saved: 'Preferences saved.',
      error: 'Couldn’t save preferences — try again.',
    },

    notif: {
      title: 'Notifikasi',
      meta: 'Pilih notifikasi yang Anda terima dan cara pengirimannya lewat email.',
      loading: 'Memuat preferensi…',
      emailLabel: 'Notifikasi email',
      on: 'Aktif',
      off: 'Nonaktif',
      muted: 'Dibisukan',
      frequencyLabel: 'Frekuensi email',
      freq: { instant: 'Langsung', daily: 'Ringkasan harian', off: 'Tidak pernah' },
      categoriesTitle: 'Kategori',
      cat: {
        workflow: 'Tugas persetujuan',
        document: 'Pembaruan dokumen yang Anda ikuti',
        document_expiry: 'Pengingat kedaluwarsa dokumen',
        records_disposition: 'Arsip jatuh tempo penyusutan',
        meterai_quota: 'Peringatan kuota e-Meterai',
      },
      save: 'Simpan preferensi',
      saved: 'Preferensi tersimpan.',
      error: 'Gagal menyimpan preferensi — coba lagi.',
    },

/* notification preferences (profile) */
.notif-prefs { display: flex; flex-direction: column; gap: 1rem; max-width: 32rem; }
.notif-prefs__subtitle { font-size: 0.875rem; font-weight: 600; margin-top: 0.5rem; color: var(--cds-text-secondary); }
.notif-prefs__cats { display: flex; flex-direction: column; gap: 0.75rem; }

git add web/src/features/profile/data.ts web/src/features/profile/ProfilePage.tsx web/src/features/profile/i18n.ts web/src/styles/app.css
git commit -m "feat(web): /profile Notifications panel (category mutes, email toggle, frequency)"

// DurationStat is an average + 90th-percentile elapsed time (seconds) over a sample set.
type DurationStat struct {
    AvgSeconds float64 `json:"avg_seconds"`
    P90Seconds float64 `json:"p90_seconds"`
    Samples    int     `json:"samples"`
}

// UnitVolume is one org unit's letter volume in the window.
type UnitVolume struct {
    Unit  string `json:"unit"`
    Count int    `json:"count"`
}

// WeeklyPoint is one ISO week's document + letter creation volume. WeekStart is the Monday
// (YYYY-MM-DD).
type WeeklyPoint struct {
    WeekStart string `json:"week_start"`
    Documents int    `json:"documents"`
    Letters   int    `json:"letters"`
}

// CompletionRate is a completed/total ratio (Rate in [0,1]) over the window.
type CompletionRate struct {
    Total     int     `json:"total"`
    Completed int     `json:"completed"`
    Rate      float64 `json:"rate"`
}

// OpsMetrics bundles the operational KPIs. Pointer fields are nil (JSON null) when their
// source area is empty/unlicensed so the UI hides the card. Slices are [] when empty;
// weekly_volume always has 12 points; overdue/escalations are plain counts (workflow is
// core, so 0 is a meaningful "healthy" answer).
type OpsMetrics struct {
    LetterProcessing *DurationStat   `json:"letter_processing"`
    WorkflowApproval *DurationStat   `json:"workflow_approval"`
    TopSenderUnits   []UnitVolume    `json:"top_sender_units"`
    TopTargetUnits   []UnitVolume    `json:"top_target_units"`
    WeeklyVolume     []WeeklyPoint   `json:"weekly_volume"`
    OpenOverdueTasks int             `json:"open_overdue_tasks"`
    Escalations      int             `json:"escalations"`
    EsignCompletion  *CompletionRate `json:"esign_completion"`
}

// OpsStats is the operational KPI dashboard payload for a trailing window of days.
type OpsStats struct {
    GeneratedAt time.Time  `json:"generated_at"`
    WindowDays  int        `json:"window_days"`
    Metrics     OpsMetrics `json:"metrics"`
}

// OpsStats returns the operational KPI aggregates over the trailing window. The generated-at
// stamp is applied here (the repo is a pure aggregator).
func (s *Service) OpsStats(ctx context.Context, days int) (OpsStats, error) {
    stats, err := s.repo.OpsStats(ctx, days)
    if err != nil {
        return OpsStats{}, err
    }
    stats.GeneratedAt = time.Now().UTC()
    return stats, nil
}

// OpsStats computes the operational KPI aggregates over a trailing window of `days` days.
// Every query is READ-ONLY. Empty/unlicensed areas (correspondence, esign) leave the
// corresponding pointer nil (→ JSON null) so the UI hides that card. The weekly trend always
// returns 12 zero-filled buckets. Interval arithmetic uses make_interval(days => $1) so the
// window is a single bind parameter. Sized for demo data (<500ms); no caching (v1).
func (s *Store) OpsStats(ctx context.Context, days int) (app.OpsStats, error) {
    ex := s.db.Exec(ctx)
    out := app.OpsStats{
        WindowDays: days,
        Metrics: app.OpsMetrics{
            TopSenderUnits: []app.UnitVolume{},
            TopTargetUnits: []app.UnitVolume{},
            WeeklyVolume:   []app.WeeklyPoint{},
        },
    }

    // 1. Letter processing time (created → completed). A letter is "completed" when it reaches
    // a finalized status ('numbered' outbound / 'registered' inbound); updated_at is its last
    // state change — the completion instant (there is no dedicated completed_at column). Nil
    // when no completed letters in the window.
    {
        var avg, p90 float64
        var n int
        if err := ex.QueryRow(ctx,
            `SELECT
                 COALESCE(AVG(EXTRACT(EPOCH FROM (updated_at - created_at))), 0)::float8,
                 COALESCE(PERCENTILE_CONT(0.9) WITHIN GROUP (ORDER BY EXTRACT(EPOCH FROM (updated_at - created_at))), 0)::float8,
                 COUNT(*)
               FROM letters
              WHERE status IN ('numbered', 'registered')
                AND updated_at >= created_at
                AND created_at >= now() - make_interval(days => $1)`, days).
            Scan(&avg, &p90, &n); err != nil {
            return app.OpsStats{}, fmt.Errorf("reporting ops letter processing: %w", err)
        }
        if n > 0 {
            out.Metrics.LetterProcessing = &app.DurationStat{AvgSeconds: avg, P90Seconds: p90, Samples: n}
        }
    }

    // 2. Workflow approval time (instance created → the 'approved' transition). The append-only
    // transition log pins the exact approval instant (instance.updated_at would drift if the
    // instance later moved on, e.g. approved → archived). Nil when no approvals in the window.
    {
        var avg, p90 float64
        var n int
        if err := ex.QueryRow(ctx,
            `SELECT
                 COALESCE(AVG(EXTRACT(EPOCH FROM (t.created_at - i.created_at))), 0)::float8,
                 COALESCE(PERCENTILE_CONT(0.9) WITHIN GROUP (ORDER BY EXTRACT(EPOCH FROM (t.created_at - i.created_at))), 0)::float8,
                 COUNT(*)
               FROM workflow_transitions t
               JOIN workflow_instances i ON i.id = t.instance_id
              WHERE t.to_state = 'approved'
                AND t.created_at >= now() - make_interval(days => $1)`, days).
            Scan(&avg, &p90, &n); err != nil {
            return app.OpsStats{}, fmt.Errorf("reporting ops workflow approval: %w", err)
        }
        if n > 0 {
            out.Metrics.WorkflowApproval = &app.DurationStat{AvgSeconds: avg, P90Seconds: p90, Samples: n}
        }
    }

    // 3. Top 5 sender units — the org unit of each OUTBOUND letter's author, resolved through
    // the author's position assignment active now. LATERAL LIMIT 1 (earliest assignment) makes
    // a multi-position author deterministic; an author with no resolvable unit drops out.
    senderRows, err := ex.Query(ctx,
        `SELECT ou.name, COUNT(*) AS n
           FROM letters l
           JOIN LATERAL (
                SELECT p.org_unit_id
                  FROM position_assignments pa
                  JOIN positions p ON p.id = pa.position_id
                 WHERE pa.user_id = l.created_by
                   AND pa.valid_from <= now()
                   AND (pa.valid_to IS NULL OR pa.valid_to > now())
                 ORDER BY pa.valid_from
                 LIMIT 1
           ) sp ON true
           JOIN org_units ou ON ou.id = sp.org_unit_id
          WHERE l.direction = 'outbound'
            AND l.created_at >= now() - make_interval(days => $1)
          GROUP BY ou.name
          ORDER BY n DESC
          LIMIT 5`, days)
    if err != nil {
        return app.OpsStats{}, fmt.Errorf("reporting ops sender units: %w", err)
    }
    for senderRows.Next() {
        var uv app.UnitVolume
        if err := senderRows.Scan(&uv.Unit, &uv.Count); err != nil {
            senderRows.Close()
            return app.OpsStats{}, fmt.Errorf("reporting ops sender scan: %w", err)
        }
        out.Metrics.TopSenderUnits = append(out.Metrics.TopSenderUnits, uv)
    }
    if err := senderRows.Err(); err != nil {
        senderRows.Close()
        return app.OpsStats{}, err
    }
    senderRows.Close()

    // 4. Top 5 target units — the org unit each letter was dispositioned TO (disposisi targets
    // a position; the position belongs to an org unit). COUNT(DISTINCT letter_id) so several
    // assignments of one letter to one unit count once.
    targetRows, err := ex.Query(ctx,
        `SELECT ou.name, COUNT(DISTINCT la.letter_id) AS n
           FROM letter_assignments la
           JOIN positions p ON p.id = la.assignee_position_id
           JOIN org_units ou ON ou.id = p.org_unit_id
          WHERE la.assigned_at >= now() - make_interval(days => $1)
          GROUP BY ou.name
          ORDER BY n DESC
          LIMIT 5`, days)
    if err != nil {
        return app.OpsStats{}, fmt.Errorf("reporting ops target units: %w", err)
    }
    for targetRows.Next() {
        var uv app.UnitVolume
        if err := targetRows.Scan(&uv.Unit, &uv.Count); err != nil {
            targetRows.Close()
            return app.OpsStats{}, fmt.Errorf("reporting ops target scan: %w", err)
        }
        out.Metrics.TopTargetUnits = append(out.Metrics.TopTargetUnits, uv)
    }
    if err := targetRows.Err(); err != nil {
        targetRows.Close()
        return app.OpsStats{}, err
    }
    targetRows.Close()

    // 5. Weekly volume trend — 12 ISO weeks, zero-filled via generate_series so empty weeks
    // still return a bucket. documents + letters created per week (creation volume includes
    // since-deleted rows — an honest count of what was filed).
    weekRows, err := ex.Query(ctx,
        `WITH weeks AS (
             SELECT generate_series(
                 date_trunc('week', now()) - interval '11 weeks',
                 date_trunc('week', now()),
                 interval '1 week'
             ) AS wk
         )
         SELECT to_char(w.wk, 'YYYY-MM-DD'),
                (SELECT COUNT(*) FROM documents d WHERE date_trunc('week', d.created_at) = w.wk),
                (SELECT COUNT(*) FROM letters   l WHERE date_trunc('week', l.created_at) = w.wk)
           FROM weeks w
          ORDER BY w.wk`)
    if err != nil {
        return app.OpsStats{}, fmt.Errorf("reporting ops weekly volume: %w", err)
    }
    for weekRows.Next() {
        var wp app.WeeklyPoint
        if err := weekRows.Scan(&wp.WeekStart, &wp.Documents, &wp.Letters); err != nil {
            weekRows.Close()
            return app.OpsStats{}, fmt.Errorf("reporting ops weekly scan: %w", err)
        }
        out.Metrics.WeeklyVolume = append(out.Metrics.WeeklyVolume, wp)
    }
    if err := weekRows.Err(); err != nil {
        weekRows.Close()
        return app.OpsStats{}, err
    }
    weekRows.Close()

    // 6. Open overdue tasks (current state) + escalations in window. Workflow is core, so these
    // are always meaningful (0 = healthy). Overdue = still-pending, SLA set and passed.
    if err := ex.QueryRow(ctx,
        `SELECT COUNT(*) FROM workflow_tasks
          WHERE state = 'pending' AND sla_deadline IS NOT NULL AND sla_deadline < now()`).
        Scan(&out.Metrics.OpenOverdueTasks); err != nil {
        return app.OpsStats{}, fmt.Errorf("reporting ops overdue tasks: %w", err)
    }
    if err := ex.QueryRow(ctx,
        `SELECT COUNT(*) FROM workflow_escalations
          WHERE created_at >= now() - make_interval(days => $1)`, days).
        Scan(&out.Metrics.Escalations); err != nil {
        return app.OpsStats{}, fmt.Errorf("reporting ops escalations: %w", err)
    }

    // 7. E-sign envelope completion rate over the window. completed_at is set on finalize
    // (equivalent to status='completed'). Nil when no envelopes were created in the window.
    {
        var total, completed int
        if err := ex.QueryRow(ctx,
            `SELECT COUNT(*), COUNT(*) FILTER (WHERE completed_at IS NOT NULL)
               FROM esign_sign_envelopes
              WHERE created_at >= now() - make_interval(days => $1)`, days).
            Scan(&total, &completed); err != nil {
            return app.OpsStats{}, fmt.Errorf("reporting ops esign completion: %w", err)
        }
        if total > 0 {
            out.Metrics.EsignCompletion = &app.CompletionRate{
                Total: total, Completed: completed, Rate: float64(completed) / float64(total),
            }
        }
    }

    return out, nil
}

// ReportOps returns the operational KPI dashboard aggregates over a trailing window
// (?days=, default 30, clamped to [1,365]). Same reporting.read gate as the other reports.
// Areas whose module is unlicensed/empty return JSON null (the UI hides the card).
func (s *Server) ReportOps(w http.ResponseWriter, r *http.Request) {
    days := 30
    if q := r.URL.Query().Get("days"); q != "" {
        if n, err := strconv.Atoi(q); err == nil && n > 0 {
            days = n
        }
    }
    if days < 1 {
        days = 1
    }
    if days > 365 {
        days = 365
    }
    stats, err := s.reporting.OpsStats(r.Context(), days)
    if err != nil {
        writeProblem(w, err)
        return
    }
    writeJSON(w, http.StatusOK, stats)
}

            r.With(s.requirePerm("reporting.read")).Get("/admin/stats/ops", s.ReportOps)

  /api/v1/admin/stats/ops:
    get:
      operationId: reportOps
      summary: Operational KPI dashboard
      description: >-
        Returns operational KPIs over a trailing window (letter processing + workflow
        approval avg/p90, top sender/target units, 12-week volume trend, open overdue tasks,
        escalations, e-sign completion rate). Nullable metrics are null when their area is
        empty/unlicensed. Requires `reporting.read`.
      tags: [reporting]
      parameters:
        - name: days
          in: query
          required: false
          schema:
            type: integer
            default: 30
            minimum: 1
            maximum: 365
          description: Trailing window in days (default 30, clamped to 1..365).
      responses:
        '200':
          description: The operational KPIs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpsStats'
        '401':
          $ref: '#/components/responses/Problem'
        '403':
          $ref: '#/components/responses/Problem'