TenantAtlas/spechistory/spec.md

# Feature Specification: TenantPilot v1

**Feature Branch**: `tenantpilot-v1`  
**Created**: 2025-12-10  
**Status**: Draft  
**Input**: TenantPilot v1 scope covering policy inventory, backup, version history, and defensive restore for Intune administrators.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Policy inventory listing (Priority: P1)

Admin can view supported Intune policy types with normalized metadata for selection.

**Why this priority**: Inventory is the entry point for backup/version flows. Without it, no downstream workflows are usable.

**Independent Test**: From Filament, navigate to Policies; verify supported types render with identifiers, platform/type metadata, and tenant scoping.

**Acceptance Scenarios**:

1. **Given** an authenticated admin, **When** they open the Policies list, **Then** they see supported policy types with identifiers, platform, and last-updated metadata.
2. **Given** policy filtering by type, **When** the admin selects a type, **Then** only matching policies appear and the view remains tenant-scoped.

---

### User Story 2 - Backup creation and browsing (Priority: P1)

Admin creates backup sets containing multiple policies with immutable snapshots and can browse backup details in Filament.

**Why this priority**: Backups provide safety and enable restore; immutability and audit are foundational.

**Independent Test**: Initiate a backup set selecting multiple policies; confirm immutable JSONB snapshots persisted, audit log written, and Filament shows backup detail and items.


**Acceptance Scenarios**:

1. **Given** selected policies, **When** the admin creates a backup set, **Then** backup items store immutable payload snapshots with policy identifiers and types.
2. **Given** a completed backup set, **When** the admin opens its detail page, **Then** all items and metadata display along with the audit record of creation.

3. **Given** mehrere Backup-Sets existieren,
   **When** der Admin ein Backup-Set auswählen oder ansehen möchte,
   **Then** sieht er für jedes Set:
   - einen sprechenden Namen (nicht nur Timestamp),
   - das Erstellungsdatum,
   - die Anzahl der enthaltenen Items,
   - und optional eine kurze Beschreibung, damit er das Set sinnvoll unterscheiden kann.

---

### User Story 3 - Version history and diff (Priority: P1)

Admin can capture policy versions, view timelines, and compare any two versions with meaningful diffs.

**Why this priority**: Version visibility and diffs enable rollback readiness and change comprehension.

**Independent Test**: Create multiple versions for a policy; verify timeline ordering, version metadata, and diff output (human summary + JSON diff where feasible) between any two versions.

**Acceptance Scenarios**:

1. **Given** an admin triggers version capture, **When** the version is saved, **Then** an immutable snapshot and metadata (actor, time, type, tenant) are recorded.
2. **Given** two versions of the same policy, **When** the admin requests a comparison, **Then** the UI shows a human-readable summary and structured JSON diff where available.

---

### User Story 4 - Restore with preview and confirmation (Priority: P1)

Admin can run a restore from a backup set with preview/dry-run, selective restore, clear warnings, and required confirmation before execution.

**Why this priority**: Restore is high-risk; safety features are mandatory for production readiness.

**Independent Test**: Start a restore from a backup set in preview; view change summary and warnings; select items; confirm execution; verify audit logs and outcomes recorded (success/failure/partial).

**Acceptance Scenarios**:

1. **Given** a backup set, **When** the admin initiates a restore in preview mode, **Then** the system shows a change summary with selectable items and conflict warnings.
2. **Given** selected items and explicit confirmation, **When** execution proceeds, **Then** applied changes are tenant-scoped and audit logs record start, result, and any failures.

3. **Given** mehrere Backup-Sets existieren,
   **When** der Admin einen Restore Run erstellt,
   **Then** zeigt die Auswahl für das "Backup set" mindestens:
   - den Backup-Namen,
   - das Erstellungsdatum,
   - die Anzahl der Items,
   damit der Admin das richtige Backup-Set sicher auswählen kann.

4. **Given** ein Restore Run wurde erstellt,
   **When** der Admin die Detailseite des Restore Runs öffnet,
   **Then** sieht er, welche Policies/Items in diesem Run enthalten sind
   (z. B. Liste der Policies mit Name/Typ/Plattform).
---

### User Story 5 - Operational readiness and environments (Priority: P2)

Local development uses Sail; deployments target Dokploy staging then production with clear validation steps.

**Why this priority**: Ensures reproducible local setup and safe promotion to production.

**Independent Test**: Run the app locally via Sail; validate migrations on staging before production; confirm required env vars and queues/workers are documented.




### User Story 6 - Berechtigungsübersicht & Health-Status (Priority: P1)

Als Admin möchte ich für jeden Tenant sehen, welche Microsoft Graph-Berechtigungen
erforderlich sind, welche bereits erteilt wurden und welche fehlen, damit ich
sicherstellen kann, dass alle Funktionen von TenantPilot sicher und vollständig
arbeiten.

**Why this priority**: Jede neue Funktion kann zusätzliche Berechtigungen benötigen.
Ohne transparente Übersicht und Abgleich besteht das Risiko, dass Features still
kaputt sind oder unsicher laufen.

**Acceptance Scenarios**:

1. **Given** ein Tenant ist in TenantPilot hinterlegt,
   **When** der Admin die Tenant-Detailseite öffnet,
   **Then** sieht er eine Liste aller *erforderlichen* Berechtigungen mit Status
   (z. B. OK, fehlt).

2. **Given** neue Funktionen wurden eingeführt, die zusätzliche Berechtigungen benötigen
   und diese wurden in der zentralen Permissions-Liste hinzugefügt,
   **When** der Admin die Tenant-Detailseite öffnet,
   **Then** erscheinen die neuen Berechtigungen automatisch in der Übersicht und
   fehlende Berechtigungen werden klar als fehlend markiert.

3. **Given** der Admin klickt auf "Verify configuration",
   **When** TenantPilot einen Graph-Twestcall und/oder das Permission-Setup prüft,
   **Then** wird der Status der Berechtigungen aktualisiert (OK/fehlt/Fehler) und
   es wird ein Audit-Eintrag erstellt.

4. **Given** ein Tenant hat fehlende kritische Berechtigungen,
   **When** andere Features (Policy-Sync, Backup, Restore) diesen Tenant verwenden,
   **Then** kann TenantPilot dem Admin entsprechende Warnungen anzeigen oder die
   Funktion mit einem klaren Fehler abbrechen.


**Acceptance Scenarios**:

1. **Given** a fresh checkout, **When** Sail commands run (`./vendor/bin/sail up -d`, `./vendor/bin/sail artisan migrate`), **Then** the app boots with PostgreSQL and Filament admin available.
2. **Given** a pending release, **When** migrations and restore flows are validated on staging, **Then** production deployment proceeds with documented steps and environment parity.

### Edge Cases

- Graph permissions missing or expired, causing policy fetch/restore failures with clear error mapping and audit entries.
- Large policy payloads or many items in a backup set; ensure JSONB storage and pagination handle load without timeouts.
- Restore conflicts when target tenant already has newer versions; preview must surface warnings and allow skip.
- Partial restore failures; audits must capture per-item outcomes and surface retry guidance.
- Diff generation for incompatible or malformed payloads should fail gracefully with admin-facing messaging.
- Retention/size concerns for snapshots; document defaults and guard against unbounded growth.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: System MUST list supported Intune policies with normalized metadata and tenant scoping for selection.
- **FR-002**: System MUST allow admins to create backup sets containing multiple policies with immutable JSONB payload snapshots.
- **FR-003**: Backup creation MUST log audit events including actor, timestamp, tenant, items, and outcome.
- **FR-004**: System MUST capture policy versions on demand and present per-policy timelines.
- **FR-005**: Users MUST be able to diff any two versions with a human-readable summary and structured JSON diff where feasible.
- **FR-006**: Restore MUST support preview/dry-run, selective item restore, and explicit confirmation before applying changes.
- **FR-007**: Restore execution MUST produce audit logs covering success, failure, and partial outcomes.
- **FR-008**: Graph integration MUST route through a dedicated abstraction layer with standardized error mapping, safe retries, and high-level logging without secrets.
- **FR-009**: All policy, version, backup, and restore data MUST be tenant-aware; queries enforce tenant isolation.
- **FR-010**: Application MUST run locally via Laravel Sail with PostgreSQL and provide Filament admin flows.
- **FR-011**: Deployments MUST target Dokploy staging before production with documented migration and worker implications.
- **FR-012**: Tests MUST cover backup composition rules, version immutability, audit events, and Filament backup/restore flows (with Graph boundaries mocked).
- **FR-013**: Raw policy snapshots and backup payloads MUST be stored as JSONB with indexes justified by query needs (e.g., FK and time-based; GIN when filters require).
- **FR-014**: UI MUST provide clear warnings for potential restore conflicts and require confirmation for destructive operations.
- **FR-015**: Admins MUST be able to safely delete (archive) backup sets that are no
  longer needed. Deletion is implemented as soft-delete with audit logging, and
  backup sets referenced by completed restore runs cannot be removed.

- **FR-016**: Admins MUST be able to delete individual policy versions for housekeeping.
  Deletion is implemented as soft-delete with audit logging.

- **FR-017**: Admins MUST be able to deactivate (soft-delete) a tenant. 
Deactivated
  tenants:
  - do not appear in default lists,
  - cannot be used for new sync/backup/restore operations,
  - keep their historical data and audit logs for traceability.
- **FR-018**: Admins MAY soft-delete restore runs to keep the UI clean; underlying
  backup and policy data remains untouched.

### Key Entities *(include if feature involves data)*

- **tenants**: Represents the deployment tenant context; referenced by all scoped data.
- **policies**: Normalized metadata for supported Intune policies.
- **policy_versions**: Immutable snapshots with metadata (actor, timestamp, tenant, policy type).
- **backup_sets**: Group of backup items with creator, timestamp, and tenant context.
- **backup_items**: Individual policy snapshots within a backup set (immutable JSONB payload + identifiers).
- **restore_runs**: Execution records for restores, including preview/actual flags and outcomes.
- **audit_logs**: Audit trail entries for backups, restores, version captures, and significant Graph actions.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: Admin can create a backup set selecting multiple policies and view immutable backup items with audit logs in Filament.
- **SC-002**: Policy version history timeline is available per policy and supports comparing any two versions with summary and JSON diff outputs.
- **SC-003**: Restore preview shows change summaries and conflict warnings; execution requires explicit confirmation and produces audit logs for all outcomes.
- **SC-004**: Core flows run locally via Sail; staging validation of migrations and restore paths completes before production deployments.
- **SC-005**: Automated tests covering backup composition, version immutability, audit logging, and Filament backup/restore flows pass via `./vendor/bin/sail artisan test`.


### Technical Story – Enforce Single Current Tenant ("Highlander Principle")

**Context**

Aktuell können mehrere Tenants `status = active` sein. Graph-Operationen (Policy Sync,
Backup, Restore) wählen den Kontext über Heuristiken (`findOrCreateDefault`,
`local-tenant`), was zu falschen Tenants und Fehlern führt.

**Goal**

Es soll **immer genau einen klar definierten "current" Tenant** geben, über den
alle Graph-Operationen laufen. Die Auswahl dieses Tenants ist explizit und
transparent (UI + Env), nicht implizit.

**Requirements**

- Es gibt ein Flag `is_current` in `tenants`, das den aktuell verwendeten Kontext
  markiert.
- Die Datenbank erzwingt per partiellem Unique Index, dass höchstens ein
  nicht-gelöschter Tenant `is_current = true` haben kann.
- `Tenant::current()` liefert:
  - falls `INTUNE_TENANT_ID` gesetzt ist, **genau diesen** Tenant (Fehler, wenn
    er nicht existiert oder deaktiviert ist),
  - sonst den Tenant mit `is_current = true` und `status = active`.
  - falls keiner gefunden wird, eine klare Exception (“No current tenant selected”);
    es werden keine Dummy-Tenants erzeugt.
- In der Tenant-Verwaltung gibt es eine Action "Make current", die:
  - in einer Transaktion alle anderen Tenants auf `is_current = false` setzt
    und den gewählten Tenant auf `is_current = true`,
  - nur für aktive Tenants verfügbar ist.
- Der frühere Placeholder `local-tenant` darf nicht mehr als Graph-Kontext genutzt
  werden; sobald ein echter Tenant existiert, wird er archiviert und ist nie
  `is_current`.
- Alle Graph-basierten Funktionen (Policy Sync, Backup, Restore) verwenden
  konsistent `Tenant::current()` oder einen explizit übergebenen Tenant.

  Tenant-level actions such as "Admin consent" and "Verify configuration"
MUST be exposed on the tenant detail view (and/or row actions), not as a
global button without explicit tenant context.


### UX Guideline – Table Actions / Dropdowns

- Tabellen in Filament mit mehr als zwei Zeilen-Aktionen (z.B. View, Edit,
  Admin consent, Verify, Deactivate, Force delete) MÜSSEN ihre Aktionen in
  einem kompakten Dropdown / ActionGroup bündeln, statt alle Buttons nebeneinander
  anzuzeigen.
- Ausnahmen: besonders häufige, nicht-destruktive Aktionen (z.B. "View")
  dürfen weiterhin als einzelner Button sichtbar bleiben; alle weiteren
  Aktionen (z.B. Admin-Aktionen, Housekeeping) sollen im Dropdown liegen.
- Ziel: die Tabellen bleiben übersichtlich, Spaltenbreite wird begrenzt,
  und Admins bekommen eine konsistente "⋯"-Interaktion für erweiterte Aktionen.