360 lines
13 KiB
Markdown
360 lines
13 KiB
Markdown
# Implementation Plan: Filament JSON UI for Policy Views
|
|
|
|
**Branch**: `tenantpilot-v1` | **Date**: 2025-12-13 | **Spec**: [spec.md](./spec.md)
|
|
**Input**: Feature specification from `/specs/002-filament-json/spec.md`
|
|
|
|
## Summary
|
|
|
|
Improve readability of policy snapshots and settings in the admin UI by integrating `pepperfm/filament-json:^4` as a read-only JSON viewer component. Primary target is the **Policies → View Policy** page where raw JSON is currently hard to scan. This is a **UI-only feature** with no changes to sync, backup, restore logic, or Graph integration.
|
|
|
|
Key deliverables:
|
|
- JSON viewer component (fold/collapse, search, copy) on Policy View page
|
|
- Large payload handling (warnings, truncation, optional download)
|
|
- Preserve existing table views where appropriate (Settings Catalog)
|
|
- Tab-based UI: Settings (table) + JSON (viewer)
|
|
- Read-only display with no behavioral changes
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: PHP 8.4.15
|
|
**Primary Dependencies**:
|
|
- Laravel 12
|
|
- Filament 4
|
|
- Livewire 3
|
|
- `pepperfm/filament-json:^4` (to be installed)
|
|
|
|
**Storage**: PostgreSQL (existing, no schema changes)
|
|
**Testing**: Pest 4 (feature + browser tests)
|
|
**Target Platform**: Web (Laravel Sail locally, Dokploy deployment)
|
|
**Project Type**: Web application (Laravel + Filament admin panel)
|
|
**Performance Goals**:
|
|
- Render JSON up to 500 KB inline without freezing
|
|
- Large payloads (>500 KB) show warning + collapsed by default
|
|
- No additional Graph API calls
|
|
|
|
**Constraints**:
|
|
- Read-only viewer (no editing/saving)
|
|
- Tenant-scoped (all actions respect current tenant context)
|
|
- No horizontal overflow beyond card bounds
|
|
- Must preserve existing Settings Catalog table functionality
|
|
|
|
**Scale/Scope**:
|
|
- Single page modification: Policy View (PolicyResource ViewRecord)
|
|
- Optional: Policy Versions View (raw JSON section only)
|
|
- ~3-5 Filament infolist entries/components
|
|
- Asset publishing: document if `public/vendor/` assets must be committed
|
|
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
### I. Safety-First Design
|
|
- ✅ **PASS**: Read-only viewer, no destructive actions
|
|
- ✅ **PASS**: No changes to backup/restore/sync logic (FR-040)
|
|
- ✅ **PASS**: Large payload warnings prevent browser freeze (FR-038, NFR-036.1)
|
|
|
|
### II. Immutable Versioning
|
|
- ✅ **PASS**: No changes to versioning or snapshot storage
|
|
- ✅ **PASS**: Viewer displays existing snapshot data only (NFR-036.4)
|
|
|
|
### III. Defensive Restore
|
|
- ✅ **PASS**: No restore flow changes
|
|
|
|
### IV. Auditability
|
|
- ✅ **PASS**: No new audit requirements (FR-040)
|
|
- ✅ **PASS**: Copy/download actions use existing tenant-scoped records (NFR-036.3)
|
|
|
|
### V. Tenant-Aware Architecture
|
|
- ✅ **PASS**: All UI operates within tenant context (NFR-036.3)
|
|
- ✅ **PASS**: No cross-tenant data exposure
|
|
|
|
### VI. Graph Abstraction
|
|
- ✅ **PASS**: No new Graph calls (FR-040)
|
|
- ✅ **PASS**: No token storage changes
|
|
|
|
### VII. Spec-Driven Development
|
|
- ✅ **PASS**: Spec complete with 6 FRs, 3 user stories, 7 success criteria
|
|
- ✅ **PASS**: Exclusions documented (no global refactor, no editor mode)
|
|
|
|
**GATE STATUS**: ✅ **ALL GATES PASS** — Proceed to Phase 0
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
specs/002-filament-json/
|
|
├── plan.md # This file
|
|
├── research.md # Phase 0: Package compatibility, asset publishing, integration patterns
|
|
├── data-model.md # Phase 1: N/A (no schema changes)
|
|
├── quickstart.md # Phase 1: Installation, usage examples
|
|
├── contracts/ # Phase 1: N/A (no API contracts)
|
|
└── tasks.md # Phase 2: Task breakdown (created by /speckit.tasks)
|
|
```
|
|
|
|
### Source Code (repository root)
|
|
|
|
```text
|
|
app/
|
|
├── Filament/
|
|
│ └── Resources/
|
|
│ └── PolicyResource/
|
|
│ └── Pages/
|
|
│ └── ViewPolicy.php # Primary modification target
|
|
├── View/
|
|
│ └── Components/
|
|
│ └── JsonViewer.php # Optional: Blade component wrapper (if needed)
|
|
|
|
resources/
|
|
└── views/
|
|
└── filament/
|
|
└── resources/
|
|
└── policy-resource/
|
|
└── pages/
|
|
└── view-policy.blade.php # If custom view needed
|
|
|
|
tests/
|
|
├── Feature/
|
|
│ └── Filament/
|
|
│ └── PolicyResourceViewTest.php # Feature tests for Policy View UI
|
|
└── Browser/
|
|
└── PolicyJsonViewerTest.php # Pest 4 browser tests
|
|
|
|
config/
|
|
└── (no changes expected)
|
|
|
|
database/
|
|
└── (no changes - UI only)
|
|
|
|
public/
|
|
└── vendor/
|
|
└── filament-json/ # May appear after asset publishing
|
|
└── (CSS/JS assets)
|
|
```
|
|
|
|
**Structure Decision**: Laravel web application with Filament admin panel. Modifications are scoped to:
|
|
1. `app/Filament/Resources/PolicyResource/Pages/ViewPolicy.php` (primary)
|
|
2. Optional custom Blade views if Filament infolist schema is insufficient
|
|
3. Tests in `tests/Feature/Filament/` and `tests/Browser/`
|
|
|
|
No database migrations, no new models, no service layer changes.
|
|
|
|
---
|
|
|
|
## Complexity Tracking
|
|
|
|
> **Fill ONLY if Constitution Check has violations that must be justified**
|
|
|
|
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
|
|-----------|------------|-------------------------------------|
|
|
| *(none)* | *(none)* | *(none)* |
|
|
|
|
**Justification**: All constitution gates pass. This is a low-risk UI enhancement with no architectural deviations.
|
|
|
|
---
|
|
|
|
## Phase 0: Research & Prerequisites
|
|
|
|
**Goal**: Resolve all NEEDS CLARIFICATION items and gather integration patterns.
|
|
|
|
### Research Tasks
|
|
|
|
1. **Package Compatibility**
|
|
- ✅ Verify `pepperfm/filament-json:^4` is Filament 4 compatible
|
|
- ✅ Check if it supports **infolists** (read-only views) vs. forms
|
|
- ✅ Identify available features: fold/collapse, search, copy, line numbers
|
|
|
|
2. **Asset Publishing**
|
|
- ✅ Determine if `php artisan filament:assets` or similar is required
|
|
- ✅ Check if published assets should be committed or generated during deployment
|
|
- ✅ Test if assets work without explicit publishing (auto-serve from vendor)
|
|
|
|
3. **Integration Patterns**
|
|
- ✅ Find best practice for adding JSON viewer to Filament infolist
|
|
- ✅ Identify how to implement tabs (Settings table + JSON viewer)
|
|
- ✅ Determine payload size detection method (string length, JSON byte count)
|
|
|
|
4. **Large Payload Handling**
|
|
- ✅ Establish truncation strategy (client-side vs. server-side)
|
|
- ✅ Identify safe download mechanism (streaming response, tenant-scoped)
|
|
|
|
5. **Testing Strategy**
|
|
- ✅ Confirm Pest 4 browser tests can interact with Filament infolists
|
|
- ✅ Check if Livewire testing helpers cover tab switching
|
|
|
|
**Output**: `research.md` with decisions, alternatives, and example code snippets.
|
|
|
|
---
|
|
|
|
## Phase 1: Design & Contracts
|
|
|
|
**Prerequisites**: Phase 0 research complete
|
|
|
|
### Design Artifacts
|
|
|
|
1. **Data Model** (`data-model.md`)
|
|
- **N/A** — No schema changes. Document that feature uses existing `Policy` model's `snapshot` column.
|
|
|
|
2. **API Contracts** (`contracts/`)
|
|
- **N/A** — No API endpoints. UI-only feature.
|
|
|
|
3. **Quickstart Guide** (`quickstart.md`)
|
|
- Installation: `composer require pepperfm/filament-json:^4`
|
|
- Asset publishing (if required): `php artisan vendor:publish --tag=filament-json-assets`
|
|
- Usage example: How to add JSON viewer to PolicyResource ViewPolicy page
|
|
- Configuration: Payload size thresholds (500 KB soft limit)
|
|
- Testing: Run `./vendor/bin/pest --filter=PolicyJsonViewer`
|
|
|
|
4. **Component Design**
|
|
- Filament infolist entry: `ViewEntry::make('snapshot')` with custom view rendering `pepperfm/filament-json` component
|
|
- Tab structure: `Tabs::make()` with `Tab::make('Settings')` and `Tab::make('JSON')`
|
|
- Payload size check: `strlen(json_encode($record->snapshot)) > 512000` (500 KB)
|
|
- Warning badge: Filament `Badge::make()` with warning color
|
|
|
|
**Output**:
|
|
- `quickstart.md`: Installation, usage, testing
|
|
- `data-model.md`: Brief note that no schema changes are needed
|
|
- Updated agent context (if new technology added)
|
|
|
|
---
|
|
|
|
## Phase 2: Task Breakdown
|
|
|
|
**Output**: `tasks.md` (created by `/speckit.tasks` command, NOT by `/speckit.plan`)
|
|
|
|
### Anticipated Task Categories
|
|
|
|
1. **Setup & Dependencies** (1-2 tasks)
|
|
- Install `pepperfm/filament-json:^4`
|
|
- Publish assets (if required) and document process
|
|
|
|
2. **Policy View UI Modification** (3-5 tasks)
|
|
- Add JSON viewer component to ViewPolicy infolist
|
|
- Implement tabs: Settings (table) + JSON (viewer)
|
|
- Add large payload detection + warning badge
|
|
- Implement copy-to-clipboard action
|
|
- Optional: Add "Download JSON" action for large payloads
|
|
|
|
3. **Styling & Layout** (2-3 tasks)
|
|
- Prevent horizontal overflow
|
|
- Ensure monospace font, line wrapping
|
|
- Match Filament section padding/spacing
|
|
- Test dark mode compatibility
|
|
|
|
4. **Testing** (3-4 tasks)
|
|
- Feature test: Verify JSON viewer renders with snapshot data
|
|
- Feature test: Large payload shows warning, no freeze
|
|
- Browser test: Tab switching works (Pest 4)
|
|
- Browser test: Copy button populates clipboard
|
|
|
|
5. **Documentation** (1-2 tasks)
|
|
- Update `README.md` or in-app help (if applicable)
|
|
- Document asset publishing in deployment notes
|
|
|
|
6. **Validation** (1 task)
|
|
- Run `./vendor/bin/pest` and `./vendor/bin/pint --dirty`
|
|
- Verify no backup/restore test failures (SC-005)
|
|
|
|
**Estimated Complexity**: 10-15 tasks total
|
|
|
|
---
|
|
|
|
## Constitution Check (Post-Design)
|
|
|
|
*Re-evaluate after Phase 1 design is complete.*
|
|
|
|
### Design Compliance Review
|
|
|
|
- ✅ **Safety-First**: Read-only viewer, large payload warnings implemented
|
|
- ✅ **Immutable Versioning**: No changes to snapshot storage or versioning logic
|
|
- ✅ **Defensive Restore**: No restore flow modifications
|
|
- ✅ **Auditability**: No new audit requirements; tenant-scoped actions preserved
|
|
- ✅ **Tenant-Aware**: All UI respects current tenant context
|
|
- ✅ **Graph Abstraction**: No new Graph calls or token management
|
|
- ✅ **Spec-Driven**: Design artifacts align with spec (FR-036 to FR-041, NFR-036.1 to NFR-036.5)
|
|
|
|
**POST-DESIGN GATE STATUS**: ✅ **ALL GATES PASS**
|
|
|
|
---
|
|
|
|
## Implementation Sequence
|
|
|
|
1. **Phase 0 (Research)**:
|
|
- Run research agents for package compatibility, asset publishing, integration patterns
|
|
- Consolidate findings in `research.md`
|
|
|
|
2. **Phase 1 (Design)**:
|
|
- Create `quickstart.md` with installation/usage examples
|
|
- Document payload size thresholds and tab structure
|
|
- Update agent context (if needed)
|
|
|
|
3. **Phase 2 (Task Generation)**:
|
|
- Execute `/speckit.tasks` to generate `tasks.md`
|
|
- Review task breakdown for completeness (FR coverage, NFR validation)
|
|
|
|
4. **Phase 3 (Implementation)** *(outside of /speckit.plan scope)*:
|
|
- Execute tasks sequentially
|
|
- Run tests after each UI modification
|
|
- Validate no existing functionality breaks
|
|
|
|
5. **Phase 4 (Validation)** *(outside of /speckit.plan scope)*:
|
|
- Full test suite: `./vendor/bin/pest`
|
|
- Code style: `./vendor/bin/pint --dirty`
|
|
- Manual QA: Large payloads, tab switching, copy actions
|
|
- Deploy to Staging, validate before Production
|
|
|
|
---
|
|
|
|
## Risks & Mitigations
|
|
|
|
| Risk | Impact | Mitigation |
|
|
|------|--------|------------|
|
|
| **Asset publishing floods `public/`** | Large commit, slow CI | Document whether to commit assets or rely on deploy build steps; test auto-serving from vendor |
|
|
| **Browser freeze on large JSON** | Poor UX | Implement 500 KB soft limit, show warning + collapsed by default (NFR-036.1) |
|
|
| **Plugin incompatible with infolists** | Blocker | Phase 0 research must confirm infolist support; fallback to custom Blade component if needed |
|
|
| **Horizontal overflow breaks layout** | UX degradation | Add CSS constraints: `max-width: 100%; overflow-wrap: break-word;` (NFR-036.5) |
|
|
| **Existing Settings Catalog table broken** | Regression | Keep table as default tab, JSON as secondary; run existing tests (SC-005) |
|
|
|
|
---
|
|
|
|
## Success Criteria Validation
|
|
|
|
| Criterion | Validation Method | Phase |
|
|
|-----------|-------------------|-------|
|
|
| **SC-001**: JSON viewer visible on Policy View | Feature test: `assertSee('JSON')` | Phase 3 |
|
|
| **SC-002**: No content overflow | Browser test: Check card bounds | Phase 3 |
|
|
| **SC-003**: Large payload warning shown | Feature test: Mock 600 KB snapshot | Phase 3 |
|
|
| **SC-004**: Settings Catalog table usable | Feature test: Existing tests pass | Phase 3 |
|
|
| **SC-005**: No backup/restore changes | Pest suite: All tests pass | Phase 4 |
|
|
| **SC-006**: Build/CI passes | Terminal: `./vendor/bin/pest && ./vendor/bin/pint --dirty` | Phase 4 |
|
|
| **SC-007**: No unintended asset commits | Git diff review | Phase 3 |
|
|
|
|
---
|
|
|
|
## Definition of Done
|
|
|
|
- ✅ All 6 functional requirements (FR-036 to FR-041) implemented
|
|
- ✅ All 5 non-functional requirements (NFR-036.1 to NFR-036.5) validated
|
|
- ✅ 3 user stories tested (US-UI-01, US-UI-02, US-UI-03)
|
|
- ✅ Feature tests + Browser tests (Pest 4) passing
|
|
- ✅ Code style validated (`./vendor/bin/pint --dirty`)
|
|
- ✅ No regressions in backup/restore/sync tests
|
|
- ✅ Asset publishing documented (commit decision made)
|
|
- ✅ Quickstart guide complete
|
|
- ✅ Deployment impact assessed (Staging validation required)
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. Execute Phase 0 research tasks → Generate `research.md`
|
|
2. Execute Phase 1 design tasks → Generate `quickstart.md`
|
|
3. Run `/speckit.tasks` to generate task breakdown
|
|
4. Begin implementation following generated tasks
|
|
|
|
**Branch Ready**: ✅ `tenantpilot-v1`
|
|
**Spec Complete**: ✅ [spec.md](./spec.md)
|
|
**Plan Complete**: ✅ This file
|