192 lines
9.0 KiB
Markdown
192 lines
9.0 KiB
Markdown
---
|
||
feature: "002-filament-json"
|
||
description: "Policy View UI: readable JSON + structured settings using pepperfm/filament-json (Filament v4)"
|
||
date: "2025-12-13"
|
||
owner: "TenantPilot"
|
||
branch: "tenantpilot-v1"
|
||
related_features:
|
||
- "001-rbac-onboarding (core v1)"
|
||
status: "draft"
|
||
---
|
||
|
||
# Spec: 002 – Filament JSON UI for Policy Views
|
||
|
||
## Summary
|
||
|
||
Improve **readability** of policy snapshots/settings in the admin UI by using a JSON viewer/editor-style component (read-only) for places where raw JSON is currently hard to scan (especially `settingsCatalogPolicy` and large snapshots).
|
||
|
||
This feature is **UI-only**: it does not change sync, backup, restore logic, or the restore matrix. It must not introduce new Graph calls, token storage, or tenant-scope changes.
|
||
|
||
Primary implementation target:
|
||
- **Policies → View Policy** (first)
|
||
Secondary (optional in this feature, if low-risk):
|
||
- **Policy Versions → View Policy Version** (Raw JSON section only)
|
||
|
||
We intend to use `pepperfm/filament-json:^4` (Filament 4 compatible) to render JSON blocks elegantly (folding, search, copy, monospace, line wrapping) while keeping tables where tables are clearly better (e.g., flattened settings rows).
|
||
|
||
---
|
||
|
||
## Goals
|
||
|
||
- Make Policy snapshots/settings **human-readable** for admins without scrolling horizontally forever.
|
||
- Provide a **JSON viewer** that supports:
|
||
- folding/collapsing
|
||
- search within JSON
|
||
- copy-to-clipboard
|
||
- stable monospace formatting
|
||
- safe truncation or "large payload" handling
|
||
- Apply this primarily in **Policy View** (not everywhere), to keep blast radius small.
|
||
|
||
## Non-Goals
|
||
|
||
- No new policy types, no changes to supported types, restore matrix, contract registry behavior.
|
||
- No new domain behavior (no diff algorithm changes, no restore logic changes).
|
||
- No new background jobs, no new persistence of normalized output.
|
||
- No replacing tables universally — only where JSON viewer clearly improves UX.
|
||
|
||
---
|
||
|
||
## User Scenarios & Testing *(mandatory)*
|
||
|
||
### User Story 1 - Admin reads policy snapshot quickly (Priority: P1)
|
||
|
||
As an admin, I can open a policy detail page and view the snapshot/settings in a readable format (foldable JSON + structured highlights), so I can understand what the policy does without digging through raw dumps.
|
||
|
||
**Why this priority**: Core value proposition of this feature - making existing data readable.
|
||
|
||
**Independent Test**: Open any policy with a captured snapshot; verify JSON viewer renders with fold/collapse + copy button.
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** a policy with a captured snapshot, **When** admin opens Policy View, **Then** JSON viewer renders the snapshot with fold/collapse controls.
|
||
2. **Given** a large policy snapshot, **When** admin opens Policy View, **Then** UI shows "Large payload" warning and collapses by default.
|
||
|
||
---
|
||
|
||
### User Story 2 - Admin inspects large settings catalog policies without pain (Priority: P1)
|
||
|
||
As an admin, I can view `settingsCatalogPolicy` settings with both:
|
||
- a **table** view for quick scanning (definition/value)
|
||
- an optional **JSON viewer** view for deep inspection (full hydrated snapshot/settings)
|
||
|
||
**Why this priority**: Settings Catalog policies are the most complex and need both table + JSON representations.
|
||
|
||
**Independent Test**: Open a Settings Catalog policy; verify both tabs (Settings table + JSON viewer) exist and render correctly.
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** a settingsCatalogPolicy with hydrated settings, **When** admin opens Policy View, **Then** Settings tab shows table AND JSON tab shows full snapshot.
|
||
2. **Given** a settingsCatalogPolicy, **When** admin switches between tabs, **Then** no content overflow or layout break occurs.
|
||
|
||
---
|
||
|
||
### User Story 3 - Admin copies a relevant JSON fragment (Priority: P2)
|
||
|
||
As an admin, I can copy JSON (whole snapshot or selected view) to share/debug safely, without secrets.
|
||
|
||
**Why this priority**: Enables debugging and support workflows.
|
||
|
||
**Independent Test**: Click copy button in JSON viewer; verify clipboard contains valid JSON.
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** JSON viewer is open, **When** admin clicks "Copy JSON", **Then** clipboard contains the full snapshot JSON.
|
||
2. **Given** a large payload with truncation, **When** admin clicks "Copy full JSON", **Then** action completes without freezing browser.
|
||
|
||
---
|
||
|
||
### Edge Cases
|
||
|
||
- Snapshot missing or malformed: show "No snapshot available" or "Malformed snapshot" warning.
|
||
- Extremely large payloads (>1 MB): show warning + collapsed by default + optional download.
|
||
- Missing settings hydration (settingsCatalogPolicy): show "Settings not hydrated" hint.
|
||
|
||
## Requirements *(mandatory)*
|
||
|
||
### Functional Requirements
|
||
|
||
- **FR-036**: JSON viewer component on Policy View
|
||
- **Policies → View Policy** MUST render the policy's snapshot/settings (where raw JSON is shown) using a **read-only JSON viewer** based on `pepperfm/filament-json`.
|
||
- Viewer MUST support fold/collapse + search + copy.
|
||
|
||
- **FR-037**: Placement and scope
|
||
- JSON viewer MUST be implemented **only** on **Policy View** for this feature.
|
||
- Policy Versions page changes are OPTIONAL and only apply to the **Raw JSON** block if included.
|
||
|
||
- **FR-038**: Large payload handling
|
||
- If a JSON payload exceeds thresholds (see NFRs), the UI MUST:
|
||
- show a warning badge ("Large payload – truncated for display")
|
||
- provide a "Copy full JSON" action **only if** it can be done without freezing the browser
|
||
- otherwise "Copy truncated JSON" + "Download JSON" (optional) may be used, but download MUST be access-controlled and tenant-scoped.
|
||
|
||
- **FR-039**: Preserve existing table UI where it's better
|
||
- Existing structured/tabled settings views (e.g., Settings Catalog table) SHOULD remain.
|
||
- JSON viewer is an additional/alternative representation, preferably behind tabs:
|
||
- Tab A: "Settings" (table/search)
|
||
- Tab B: "JSON" (viewer)
|
||
|
||
- **FR-040**: No behavioral changes
|
||
- This feature MUST NOT add Graph calls, modify restore behavior, or change snapshot capture logic.
|
||
- No changes to audit logging schema required.
|
||
|
||
- **FR-041**: Asset publishing safety
|
||
- Installing the plugin MUST NOT accidentally commit massive published assets unless explicitly intended.
|
||
- If assets must be published, the process MUST be documented and repeatable (see NFR + Ops).
|
||
|
||
### Non-Functional Requirements (Measurable)
|
||
|
||
- **NFR-036.1 Performance**: UI should remain responsive when rendering JSON up to:
|
||
- 500 KB inline viewer payload (soft limit)
|
||
- Above that: show warning + fallback (collapsed by default + optional download)
|
||
- **NFR-036.2 Safety**: Viewer is **read-only** (no editing, no save).
|
||
- **NFR-036.3 Tenant isolation**: Any download/copy action must operate only on the current tenant's record.
|
||
- **NFR-036.4 Consistency**: Viewer uses the same snapshot source as existing UI (no "different data" between table and JSON).
|
||
- **NFR-036.5 Styling**:
|
||
- no horizontal overflow beyond card bounds
|
||
- long keys/values wrap or are truncated with tooltip
|
||
- spacing consistent with Filament sections (padding, max width)
|
||
|
||
### UX Requirements
|
||
|
||
- Default view on Policy page:
|
||
- If settings table exists (settings catalog): show table first.
|
||
- Provide "JSON" tab for deep inspection.
|
||
- JSON viewer:
|
||
- start collapsed for huge payloads
|
||
- show line numbers (if supported)
|
||
- copy button visible
|
||
- For missing settings hydration:
|
||
- show "Settings not hydrated" warning with hint to re-sync/capture.
|
||
|
||
## Success Criteria *(mandatory)*
|
||
|
||
### Measurable Outcomes
|
||
|
||
- **SC-001**: On **Policies → View Policy**, a JSON viewer is visible and readable (fold/search/copy).
|
||
- **SC-002**: No content overflows the card/container.
|
||
- **SC-003**: For large payloads, UI shows a warning and does not freeze.
|
||
- **SC-004**: Existing Settings Catalog table remains usable (search works, values not cut off silently).
|
||
- **SC-005**: No changes in backup/restore behavior (same tests pass).
|
||
- **SC-006**: Build/CI passes: `./vendor/bin/pest` and `./vendor/bin/pint --dirty`.
|
||
- **SC-007**: No unintended committed asset floods (or, if committed, documented and intentional).
|
||
|
||
## Exclusions *(optional - only if scope needs clarification)*
|
||
|
||
The following is intentionally excluded from this specification:
|
||
- Global refactor of all JSON views across the app.
|
||
- Replacing diff UI with a new viewer.
|
||
- Introducing a full "policy editor" experience.
|
||
- Changing contract registry/hydration/restore payload rules.
|
||
|
||
## Risks / Notes
|
||
|
||
- Composer post-update hooks may fail locally if DB is unreachable (e.g., `boost:update` touching cache DB). This must not block the feature conceptually; document a safe local workflow (Sail up first or skip hook locally).
|
||
- `filament:upgrade` / asset publishing can overwrite `public/` assets; decide explicitly whether to commit these artifacts or rely on deploy build steps.
|
||
- Plugin fit: ensure `pepperfm/filament-json` is compatible with Filament 4 and used in **infolists** / **view pages** (not forms) in read-only mode.
|
||
|
||
## Traceability
|
||
|
||
- Implements: US-UI-01, US-UI-02, US-UI-03
|
||
- Implements: FR-036, FR-037, FR-038, FR-039, FR-040, FR-041
|
||
- NFRs: NFR-036.1, NFR-036.2, NFR-036.3, NFR-036.4, NFR-036.5
|