Robert Bond
37a81522d5
## Representations Refactor — Behaviour-Preserving Structural Improvements This PR delivers a full refactor of the representations flow, improving structure, readability, and maintainability while preserving all existing behaviour. The work was completed using a controlled, slice-based approach with strict guardrails and regression validation at each step. No changes have been made to user journeys, payloads, routing, or EN/CY behaviour. The result is a cleaner, more maintainable codebase with reduced coupling and clearer separation of concerns, ready for future enhancements without increased risk. --- ## What Was Done The refactor was delivered incrementally across the following slices: - **R1** — Representation entry logic extraction - **R2** — Page loader separation (SSR/data orchestration) - **R3** — Journey step resolution extraction - **R4** — Flow shell decomposition - **R5** — Representation elements normalisation - **R6** — Data/service layer cleanup - **R7** — Summary rendering proof slice - **R8** — Submission/finalisation boundary isolation - **R9** — Summary rollout (Batch 1) Each slice: - was isolated to a single concern - followed strict guardrails - was validated before merge Full detail is available in: `context/representations-refactor-tracker.md` --- ## Key Improvements - Reduced coupling across the representations journey - Separated data loading, orchestration, and rendering concerns - Simplified complex conditional logic into testable helpers - Standardised summary rendering using shared primitives (`SummaryCard`, `SummaryRow`) - Isolated submission/finalisation sequencing into explicit boundaries - Improved overall readability and maintainability --- ## Behaviour Preservation This refactor does **not** change: - User journeys (APP / IP / Agent / LPA) - Route and query behaviour - Payload contracts and API interactions - Redux state shape and usage - Validation rules and messaging - EN/CY behaviour - File upload / PDF / email sequencing - Linked-case logic All changes are structural only. --- ## Validation ### Automated - `npm run lint` — passed (warnings only, no new errors) - `npm run test:reps` — passed (7/7) ### Manual Validated end-to-end across: - APP - IP - Agent - LPA Including: - representation creation - editing/resuming representations - submission flow - confirmation/completion behaviour - summary rendering across case types - EN/CY parity --- ## Risk Management The refactor targeted several high-risk areas: - Case summary entry logic - Representation submission/finalisation sequencing - Dual-mode entry (new vs existing representation) Risk was controlled through: - small, incremental slices - one branch per slice - regression validation per slice - strict behaviour-preservation guardrails - controlled rollout for summary rendering changes --- ## Reviewer Guidance Suggested areas to focus on: - End-to-end representation journey (create → submit → complete) - S...
238 lines
6.4 KiB
Markdown
238 lines
6.4 KiB
Markdown
# Representations Refactor Tracker
|
|
|
|
Base branch: `refactor`
|
|
|
|
---
|
|
|
|
## Status
|
|
|
|
Current slice: Slice R9 — Summary Rollout (Batch 1)
|
|
Status: COMPLETE
|
|
|
|
---
|
|
|
|
## Slice List
|
|
|
|
---
|
|
|
|
### Slice R1 — Representation Entry Logic Extraction
|
|
|
|
Status: COMPLETE
|
|
|
|
Notes: Completed in prior refactor slice work; no additional changes required in this closeout.
|
|
|
|
---
|
|
|
|
### Slice R2 — Representation Page Loader Separation
|
|
|
|
Status: COMPLETE
|
|
|
|
Notes: Completed in prior refactor slice work; no additional changes required in this closeout.
|
|
|
|
---
|
|
|
|
### Slice R3 — Journey Step Resolution Extraction
|
|
|
|
Status: COMPLETE
|
|
|
|
Notes: Completed in prior refactor slice work; no additional changes required in this closeout.
|
|
|
|
---
|
|
|
|
### Slice R4 — Flow Shell Decomposition
|
|
|
|
Status: COMPLETE
|
|
|
|
Notes: Completed in prior refactor slice work; no additional changes required in this closeout.
|
|
|
|
**Completion notes (this slice):**
|
|
|
|
- Implemented on feature branch created from `refactor`: `rep-slice-r4-flow-shell`.
|
|
- Extracted render-shell structure from `components/case/representation/index.js` into:
|
|
- `components/case/representation/shell/RepresentationFlowFormStage.js`
|
|
- `components/case/representation/shell/RepresentationTimetablePanel.js`
|
|
- Kept `index.js` as orchestration owner (no side-effect migration):
|
|
- `onHandleSubmit` unchanged in location/ownership
|
|
- `updateRepresentation` unchanged in location/ownership
|
|
- upload/PDF/email sequencing unchanged
|
|
- stage-resolution/questionnaire decisions remain in `index.js`
|
|
- Preserved explicit prop passing; no grouped-prop/view-model abstraction introduced in this slice.
|
|
- Validation evidence:
|
|
- `npm run lint` completed (warnings only, no new errors).
|
|
- `npm run test:reps` completed: **6 passed**.
|
|
- Manual APP/IP/Agent/LPA checks: **passed**.
|
|
- Manual EN/CY parity checks: **passed**.
|
|
|
|
---
|
|
|
|
### Slice R5 — Representation Elements Normalisation
|
|
|
|
Status: COMPLETE
|
|
|
|
Notes: Completed in prior refactor slice work; no additional changes required in this closeout.
|
|
|
|
---
|
|
|
|
### Slice R6 — Async Data / Service Layer Cleanup
|
|
|
|
Status: COMPLETE
|
|
|
|
Notes: Completed in prior refactor slice work; no additional changes required in this closeout.
|
|
|
|
---
|
|
|
|
### Slice R7 — Summary / Case-Type Rendering Simplification (Proof Slice)
|
|
|
|
**Completion notes (this slice):**
|
|
|
|
- Implemented on feature branch created from `refactor`: `rep-slice-r7-summary-rendering-simplification`.
|
|
- Added render-only summary primitives:
|
|
- `components/case/summary/components/SummaryCard.js`
|
|
- `components/case/summary/components/SummaryRow.js`
|
|
- Applied to proof subset:
|
|
- `pinswg_planningappeals78id.js`
|
|
- `pinswg_planningconditionss73s79id.js`
|
|
- Preserved constraints:
|
|
- no translation/date/bilingual logic moved
|
|
- no linked-cases extraction
|
|
- no ordering/visibility changes
|
|
- Validation evidence:
|
|
- `npm run lint` passed (warnings only)
|
|
- `npm run test:reps` passed (**7 passed**)
|
|
- manual APP/IP/Agent/LPA + EN/CY checks passed
|
|
|
|
---
|
|
|
|
### Slice R8 — Submission / Finalisation Boundary Isolation
|
|
|
|
**Completion notes (this slice):**
|
|
|
|
- Implemented on feature branch created from `refactor`: `rep-slice-r8-finalisation-boundary`.
|
|
- Added helper module:
|
|
- `components/case/representation/utils/finalisationBoundary.js`
|
|
- Extracted:
|
|
- `buildRepresentationUpdateBody(...)`
|
|
- `buildSubmitEnrichedValues(...)`
|
|
- `runFinalisationSequence(...)`
|
|
- Preserved:
|
|
- parent-owned branching logic
|
|
- completion-side effects in `representationComplete.js`
|
|
- exact sequencing of finalisation operations
|
|
- Validation evidence:
|
|
- `npm run lint` passed (warnings only)
|
|
- `npm run test:reps` passed (**7 passed**)
|
|
- manual APP/IP/Agent/LPA + EN/CY checks passed
|
|
|
|
---
|
|
|
|
### Slice R9 — Summary Rollout (Batch 1)
|
|
|
|
**Goal:**
|
|
Roll out proven summary rendering primitives across remaining low-risk summary-type files.
|
|
|
|
**Completion notes (this slice):**
|
|
|
|
- Applied `SummaryCard` and `SummaryRow` primitives to Batch 1 summary-type files.
|
|
- Rollout executed incrementally:
|
|
- one summary-type file per commit
|
|
- consistent mechanical application of proven pattern
|
|
- Changes limited strictly to presentational structure:
|
|
- replaced card shell markup with `SummaryCard`
|
|
- replaced row wrapper markup with `SummaryRow` where safe
|
|
- Preserved across all updated files:
|
|
- field visibility rules
|
|
- row and card ordering
|
|
- translation key selection
|
|
- EN/CY branching behaviour
|
|
- date source selection and formatting
|
|
- linked-case logic
|
|
- route/query behaviour
|
|
- payloads and Redux state
|
|
- Parent summary-type files retain all business logic and conditional rendering.
|
|
- Shared components confirmed render-only.
|
|
|
|
**Validation evidence:**
|
|
|
|
- `npm run lint` completed (warnings only, no new errors)
|
|
- `npm run test:reps` passed (**7 passed**)
|
|
- Structured validation confirmed:
|
|
- translation/bilingual logic unchanged
|
|
- date/lookup logic unchanged
|
|
- conditional rendering preserved
|
|
- Targeted manual spot-checks completed:
|
|
- `pinswg_sipscase.js`
|
|
- `pinswg_dnsid.js`
|
|
- `pinswg_electricityactid.js`
|
|
- `pinswg_harbourrevisionorderid.js`
|
|
- No behavioural regressions identified
|
|
|
|
**Outcome:**
|
|
|
|
- Summary rendering layer simplified and standardised
|
|
- Duplication reduced while preserving all behaviour
|
|
- Safer and more maintainable structure
|
|
|
|
**Status: COMPLETE**
|
|
|
|
---
|
|
|
|
## Rules
|
|
|
|
- Only work on ONE slice at a time
|
|
- Do not combine slices
|
|
- One branch per slice (exception: controlled rollout batches)
|
|
- One commit per slice (or per file in rollout batch)
|
|
- Update tracker after slice completion
|
|
- Do not proceed if regression risk exists
|
|
|
|
---
|
|
|
|
## Regression Checklist (Run After Each Slice)
|
|
|
|
### Core Journey
|
|
|
|
- Navigate from case summary → Make representation
|
|
- Select capacity
|
|
- Select representation type
|
|
- Enter content
|
|
- Upload files (if applicable)
|
|
- View check answers
|
|
- Submit representation
|
|
- View confirmation page
|
|
|
|
---
|
|
|
|
### Validation
|
|
|
|
- EN/CY parity maintained
|
|
- No navigation regressions
|
|
- No state inconsistencies
|
|
- No console errors
|
|
|
|
---
|
|
|
|
### Technical
|
|
|
|
- `npm run lint` passes
|
|
- No new warnings/errors introduced
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- CaseSummary is a high-risk entry point
|
|
- Eligibility logic is complex and must not drift
|
|
- Submission flow is highly sensitive
|
|
- Dual-mode entry (new vs existing representation) is a key complexity
|
|
|
|
---
|
|
|
|
## Definition of Done (Per Slice)
|
|
|
|
A slice is complete when:
|
|
|
|
- behaviour is preserved
|
|
- regression checks pass
|
|
- code is cleaner and easier to understand
|
|
- change is small and safe to merge
|