Merged PR 2246: refactor reps first slice
Related work items: #22570, #22576, #22577, #22583, #22586, #22587, #22588, #22590, #22591
This commit is contained in:
Robert Bond
@@ -0,0 +1,300 @@
|
||||
# Representations Refactor — Current State of Play
|
||||
|
||||
## Purpose
|
||||
|
||||
This document captures the **pre-refactor state** of the representations flow and defines the starting point for the behaviour-preserving refactor stream.
|
||||
|
||||
It mirrors the approach used for the new appeal refactor and will be updated as slices are completed.
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The representations flow is:
|
||||
|
||||
- functionally complete and live
|
||||
- behaviourally stable
|
||||
- structurally complex and tightly coupled
|
||||
|
||||
The flow currently:
|
||||
|
||||
- spans multiple entry points
|
||||
- mixes UI, workflow, and data logic
|
||||
- contains duplicated branching and rendering logic
|
||||
- relies heavily on shared global state (`currentView`, `searchResultsObj`)
|
||||
|
||||
---
|
||||
|
||||
## Journey Overview
|
||||
|
||||
The user journey is:
|
||||
|
||||
1. Navigate to case summary page
|
||||
2. Click **Make representation / consultation**
|
||||
3. Enter representation flow
|
||||
4. Select capacity
|
||||
5. Select representation type
|
||||
6. Enter content and upload files
|
||||
7. Review check answers
|
||||
8. Submit representation
|
||||
9. View confirmation/completion
|
||||
|
||||
---
|
||||
|
||||
## Entry Points
|
||||
|
||||
### Primary Entry
|
||||
|
||||
- `CaseSummary` component
|
||||
- CTA button logic determines:
|
||||
- whether representation is allowed
|
||||
- which label to display
|
||||
- which route to navigate to
|
||||
|
||||
### Route
|
||||
|
||||
- `/myportal/representation?case=<caseRef>`
|
||||
|
||||
---
|
||||
|
||||
## Dual Mode Behaviour (Critical)
|
||||
|
||||
The flow operates in two modes:
|
||||
|
||||
### 1. New Representation (from search/case)
|
||||
|
||||
- triggered from case summary CTA
|
||||
- loads case data via search + details APIs
|
||||
- initializes new representation state
|
||||
|
||||
---
|
||||
|
||||
### 2. Existing Representation (resume/edit)
|
||||
|
||||
- triggered via query param (`state`)
|
||||
- loads representation from blob storage
|
||||
- hydrates existing data and files
|
||||
|
||||
---
|
||||
|
||||
This dual-mode behaviour is a **major complexity driver**.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### High-Level Structure
|
||||
|
||||
- Page layer (SSR + Redux hydration)
|
||||
- Case component (core orchestration)
|
||||
- Representation flow components (capacity/type/content/check)
|
||||
- Shared helpers (`representationElements`)
|
||||
- Service layer (case data, blob storage, CRM integration)
|
||||
|
||||
---
|
||||
|
||||
### Key Components
|
||||
|
||||
- `CaseSummary` → entry + CTA logic
|
||||
- `Case` → main orchestration component
|
||||
- Representation flow components:
|
||||
- capacity selection
|
||||
- representation type selection
|
||||
- content entry
|
||||
- check answers
|
||||
- completion
|
||||
|
||||
---
|
||||
|
||||
### State Management
|
||||
|
||||
Primary state dependencies:
|
||||
|
||||
- `currentView`
|
||||
- `searchResultsObj`
|
||||
- `myRepresentations`
|
||||
- `filesForRepresentations`
|
||||
|
||||
Heavy reliance on deeply nested props.
|
||||
|
||||
---
|
||||
|
||||
## Current Architecture Issues
|
||||
|
||||
### 1. High Coupling
|
||||
|
||||
- UI, workflow logic, and data fetching are tightly mixed
|
||||
- large components handle multiple responsibilities
|
||||
|
||||
---
|
||||
|
||||
### 2. Deep Prop Chains
|
||||
|
||||
Examples:
|
||||
|
||||
- `props.currentView.caseReference.*`
|
||||
- `props.searchResultsObj.*`
|
||||
|
||||
This reduces readability and increases fragility.
|
||||
|
||||
---
|
||||
|
||||
### 3. Duplicated Logic
|
||||
|
||||
- appeal-type branching repeated across components
|
||||
- summary rendering duplicated by case type
|
||||
- representation form structure repeated across capacity types
|
||||
|
||||
---
|
||||
|
||||
### 4. Dual Entry Complexity
|
||||
|
||||
- separate logic paths for new vs existing representation
|
||||
- mixed within the same components
|
||||
|
||||
---
|
||||
|
||||
### 5. Async Data Complexity
|
||||
|
||||
- chained service calls:
|
||||
- `getCase`
|
||||
- `getPortalModuleDetails`
|
||||
- repeated across different contexts
|
||||
- hard to reason about and test
|
||||
|
||||
---
|
||||
|
||||
### 6. Inline Business Logic
|
||||
|
||||
- eligibility rules embedded in UI components
|
||||
- date checks and appeal-type logic duplicated
|
||||
- LPA-specific behaviour scattered
|
||||
|
||||
---
|
||||
|
||||
## Risk Areas
|
||||
|
||||
High-risk areas that require extra caution:
|
||||
|
||||
- CaseSummary eligibility logic
|
||||
- SSR/data-loading logic for representation page
|
||||
- submission/finalisation flow
|
||||
- file upload handling
|
||||
- dual-mode entry (new vs existing)
|
||||
- Redux hydration and state consistency
|
||||
|
||||
---
|
||||
|
||||
## Behavioural Constraints (Must Not Change)
|
||||
|
||||
- eligibility rules for making a representation
|
||||
- journey step order and navigation
|
||||
- validation rules and messaging
|
||||
- payload structure sent to backend/CRM
|
||||
- file upload and metadata behaviour
|
||||
- submission/finalisation behaviour
|
||||
- confirmation page behaviour
|
||||
- route/query parameter structure
|
||||
- EN/CY parity
|
||||
|
||||
---
|
||||
|
||||
## Comparison to New Appeal Flow
|
||||
|
||||
### Similarities
|
||||
|
||||
- step-based user journey
|
||||
- check answers before submission
|
||||
- file upload and validation steps
|
||||
- finalisation/confirmation stage
|
||||
|
||||
---
|
||||
|
||||
### Differences (Important)
|
||||
|
||||
- dual-mode entry (new vs existing)
|
||||
- more reliance on external data sources
|
||||
- less structured “engine” (more implicit logic)
|
||||
- heavier coupling to case summary and search flows
|
||||
|
||||
---
|
||||
|
||||
## Refactor Readiness
|
||||
|
||||
The flow is suitable for refactor because:
|
||||
|
||||
- behaviour is stable
|
||||
- clear boundaries can be identified
|
||||
- repeated patterns exist
|
||||
- appeal refactor provides a proven model
|
||||
|
||||
---
|
||||
|
||||
## Refactor Strategy
|
||||
|
||||
The refactor will follow a **slice-based, behaviour-preserving approach**:
|
||||
|
||||
1. Extract entry logic (CaseSummary)
|
||||
2. Separate SSR/data-loading concerns
|
||||
3. isolate step resolution logic
|
||||
4. decompose large components
|
||||
5. clean up shared helpers
|
||||
6. stabilize async/service layers
|
||||
7. isolate submission/finalisation
|
||||
|
||||
---
|
||||
|
||||
## Initial Slice Focus
|
||||
|
||||
### Slice R1 — Entry Logic Extraction
|
||||
|
||||
Target:
|
||||
|
||||
- representation eligibility logic in `CaseSummary`
|
||||
|
||||
Goal:
|
||||
|
||||
- reduce coupling
|
||||
- isolate decision logic
|
||||
- prepare for safe downstream refactor
|
||||
|
||||
---
|
||||
|
||||
## Validation Position
|
||||
|
||||
At start of refactor:
|
||||
|
||||
- behaviour is assumed correct
|
||||
- no structural isolation exists
|
||||
- regression testing is manual
|
||||
|
||||
Each slice must:
|
||||
|
||||
- prove behaviour unchanged
|
||||
- reduce complexity incrementally
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
The representations flow is:
|
||||
|
||||
- behaviourally stable
|
||||
- structurally complex
|
||||
- suitable for controlled refactor
|
||||
|
||||
The goal is to:
|
||||
|
||||
- reduce coupling
|
||||
- improve clarity
|
||||
- enable safer future changes
|
||||
|
||||
without altering live behaviour.
|
||||
|
||||
---
|
||||
|
||||
## Next Step
|
||||
|
||||
Begin **Slice R1 — Representation Entry Logic Extraction**
|
||||
|
||||
Following strict guardrails and regression validation.
|
||||
Reference in New Issue
Block a user