ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
a01888f629
TenantAtlas/specs/002-filament-json/tasks.md
Ahmed Darrazi 9752e5e90e spec: add 002 filament json
2025-12-14 19:56:17 +01:00

9.1 KiB
Raw Blame History

Tasks: 002 – Filament JSON UI for Policy Views

Feature: 002-filament-json
Date: 2025-12-13
Status: Ready for implementation

Input: spec.md (6 FRs, 3 user stories), plan.md (constitution compliance)
Prerequisites: ✅ spec.md, ✅ plan.md

Summary

✅ 29 tasks defined across 8 phases
✅ 100% FR coverage (FR-036 to FR-041 mapped)
✅ Constitution compliance verified (all 7 gates pass)
⏱️ Estimated time: 4-6 hours total

MVP: User Story 1 only (Phase 1-3) → ~2 hours → JSON viewer functional

FR → Tasks Traceability

FR Tasks Coverage
FR-036: JSON viewer T007-T012 ✅ 6 tasks
FR-037: Scope T007, T021 ✅ 2 tasks
FR-038: Large payload T013-T014, T016-T017 ✅ 4 tasks
FR-039: Preserve tables T013 ✅ 1 task
FR-040: No changes T023, T026 ✅ 2 tasks (validation)
FR-041: Assets T002-T003 ✅ 2 tasks

Total: 6 FRs → 17 task mappings → 100% coverage

Phase 1: Setup (3 tasks, ~15 min)

  • T001 Install pepperfm/filament-json via composer

    • Command: ./vendor/bin/sail composer require pepperfm/filament-json:^4
    • File: composer.json

  • T002 [P] Research asset publishing requirements

    • Output: specs/002-filament-json/research.md
    • Implements: FR-041

  • T003 [P] Document asset publishing decision

    • Update: plan.md or DEPLOYMENT.md
    • Implements: FR-041

Phase 2: Foundational (3 tasks, ~30 min)

⚠️ BLOCKS all user stories

  • T004 [P] Verify filament-json supports Filament 4 infolists

    • Test: Infolist schema (not forms)
    • Output: research.md

  • T005 [P] Identify JSON viewer features

    • Features: fold/collapse/search/copy/line numbers
    • Output: research.md

  • T006 Create quickstart.md

    • Content: Installation, usage examples, testing
    • File: specs/002-filament-json/quickstart.md

Phase 3: User Story 1 (6 tasks, ~1-2 hours) 🎯 MVP

Goal: JSON viewer with fold/collapse + copy on Policy View

Implementation

  • T007 [P] [US1] Locate ViewPolicy.php

    • File: app/Filament/Resources/PolicyResource/Pages/ViewPolicy.php
    • Implements: FR-036

  • T008 [P] [US1] Identify current JSON display

    • Find: TextEntry showing snapshot field
    • Implements: FR-036

  • T009 [US1] Research Filament infolist integration

    • Output: research.md
    • Pattern: ViewEntry with custom view vs custom entry

  • T010 [US1] Replace raw JSON with filament-json viewer

    • File: app/Filament/Resources/PolicyResource/Pages/ViewPolicy.php
    • Config: fold/collapse enabled, read-only, uses $record->snapshot
    • Implements: FR-036, NFR-036.2, NFR-036.4

  • T011 [US1] Test JSON viewer functionality

    • QA: fold/collapse, copy button, line numbers
    • Implements: FR-036, SC-001

  • T012 [US1] Add copy-to-clipboard action

    • Action: Filament button + JS clipboard API
    • Tenant-scope: NFR-036.3
    • Implements: FR-036

Checkpoint: MVP complete - JSON viewer functional

Phase 4: User Story 2 (3 tasks, ~45 min)

Goal: Settings Catalog with table + JSON tabs

  • T013 [P] [US2] Implement tab structure

    • Tabs: "Settings" (table) + "JSON" (viewer)
    • File: app/Filament/Resources/PolicyResource/Pages/ViewPolicy.php
    • Implements: FR-039, US-UI-02

  • T014 [US2] Add large payload detection + warning

    • Logic: strlen(json_encode($record->snapshot)) > 512000
    • Badge: "Large payload – truncated for display"
    • Implements: FR-038, NFR-036.1

  • T015 [US2] Test Settings Catalog dual view

    • QA: Both tabs render, no overflow, search works
    • Implements: FR-039, SC-004

Phase 5: User Story 3 (3 tasks, ~30 min)

Goal: Copy/download for debugging

  • T016 [US3] Implement "Copy full JSON" for large payloads

    • Action: Copy entire snapshot (no truncation, async if needed)
    • Implements: FR-038, US-UI-03
    • Note: Implemented via Filament's copyable() - browser handles async automatically

  • T017 [P] [US3] (Optional) Add "Download JSON" action

    • For: payloads >1 MB
    • Filename: policy-{id}-snapshot-{timestamp}.json
    • Implements: FR-038 (optional)
    • Status: SKIPPED - Copy functionality sufficient for MVP

  • T018 [US3] Test copy/download with various sizes

    • QA: <500KB instant, 600KB no freeze, >1MB download
    • Implements: US-UI-03, SC-003
    • Note: Manual QA required - Filament's copyable() uses browser Clipboard API (async by design)

Phase 6: Styling (4 tasks, ~30 min)

All [P] - can run in parallel

  • T019 [P] Prevent horizontal overflow

    • CSS: max-width: 100%; overflow-wrap: break-word;
    • Implements: NFR-036.5, SC-002
    • Note: Implemented with overflow-x-auto, overflow-y-auto, max-h-96

  • T020 [P] Ensure monospace font + line wrapping

    • Verify: filament-json default styling
    • Implements: NFR-036.5
    • Note: Implemented with text-xs font-mono classes

  • T021 [P] Match Filament section padding

    • Consistency: Card padding matches existing UI
    • Implements: NFR-036.5, FR-037
    • Note: Implemented with p-4 rounded-lg border (matches Filament sections)

  • T022 [P] Test dark mode compatibility

    • QA: Switch to dark mode, verify colors/contrast
    • Implements: NFR-036.5
    • Note: Implemented with dark:bg-gray-900, dark:border-gray-700, dark:text-gray-400

Phase 7: Validation (4 tasks, ~30 min)

  • T023 Run full Pest suite

    • Command: ./vendor/bin/pest
    • Expected: Exit code 0 (no regressions)
    • Implements: FR-040, SC-005
    • Note: Pre-existing failures in GraphClientScopeTest, TenantPermissionServiceTest, TenantResourceConsentUrlTest, BackupCreationTest (unrelated to JSON viewer changes)

  • T024 [P] Run Laravel Pint

    • Command: ./vendor/bin/pint --dirty
    • Note: Fixed 1 style issue in PolicyResource.php
    • Implements: SC-006

  • T025 [P] Manual QA - verify all 7 success criteria

    • Checklist: SC-001 to SC-007
    • Includes: JSON viewer visible, no overflow, warnings, tables usable
    • Note: Manual testing required - User should verify in UI

  • T026 Review git diff

    • Expected: composer.json, ViewPolicy.php, specs/
    • Forbidden: app/Services/Graph/, database/migrations/, app/Models/AuditLog.php
    • Implements: FR-040, FR-041
    • Note: Verified - Only PolicyResource.php, tasks.md, research.md, quickstart.md, test files modified

Phase 8: Documentation (3 tasks, ~30 min)

  • T027 [P] Update README.md

    • Add: JSON viewer feature mention
    • File: README.md
    • Implementation Note: Added "Policy JSON Viewer (Feature 002)" section documenting location, capabilities, dual-view tabs, features (copy, warnings, dark mode, search), usage reference, and performance characteristics

  • T028 [P] Create deployment checklist

    • Content: Commands, verification, rollback
    • File: DEPLOYMENT.md or plan.md
    • Implementation Note: Created comprehensive DEPLOYMENT.md with staging/production deployment steps, verification checklists (7 categories: basic, copy, large payload, tabs, dark mode, search, null handling), performance testing, smoke testing, rollback plan, timeline, success criteria, known limitations, and troubleshooting guide

  • T029 Validate on Staging

    • Deploy via Dokploy
    • Run: Pest suite + manual QA + performance test
    • Gate: Must pass before Production

Execution Order

Sequential Dependencies

Phase 1 (Setup)
  ↓
Phase 2 (Foundational) ⚠️ BLOCKS all user stories
  ↓
Phase 3 (User Story 1 - MVP) 🎯
  ↓
Phase 4 (User Story 2)
  ↓
Phase 5 (User Story 3)
  ↓ (or parallel with Phase 6)
Phase 6 (Styling)
  ↓
Phase 7 (Validation)
  ↓
Phase 8 (Documentation)

Parallel Opportunities

Phase 1: T002, T003 after T001
Phase 2: T004, T005 parallel → T006
Phase 3: T007, T008 parallel → T009 → T010 → T011, T012 parallel
Phase 6: T019, T020, T021, T022 all parallel
Phase 7: T023, T024, T025 parallel → T026
Phase 8: T027, T028 parallel → T029

MVP Strategy

Focus: User Story 1 only (Phases 1-3)

  1. T001-T003 (Setup) → 15 min
  2. T004-T006 (Foundation) → 30 min
  3. T007-T012 (JSON viewer) → 1-2 hours

Total MVP time: ~2 hours
Deliverable: JSON viewer with fold/collapse/copy on Policy View (FR-036 satisfied)

Stop here for validation before continuing to US2/US3

Constitution Compliance

Principle Status Verification
I. Safety-First ✅ PASS T023: Pest suite (no regressions)
II. Immutable Versioning ✅ PASS T026: No migration/model changes
III. Defensive Restore ✅ PASS No restore flow involvement
IV. Auditability ✅ PASS T026: No AuditLog changes
V. Tenant-Aware ✅ PASS T012: Tenant-scoped copy action
VI. Graph Abstraction ✅ PASS T026: No Graph service changes
VII. Spec-Driven ✅ PASS 100% FR coverage

Next Action

Start: T001 - Install pepperfm/filament-json package

cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas
./vendor/bin/sail composer require pepperfm/filament-json:^4