Files

T

Robert Bond 0de9268255 Merged PR 2242: Refactor: New Appeal flow structural cleanup (Slices 1–8, no behaviour change)

## Summary

This PR merges the completed new-appeal refactor stream (Slices 1–8) into SIPS-Development.

This refactor was executed in controlled slices with regression validation at each step.

## Scope

Structural and readability improvements only:
- XML/form derivation extraction
- payload and file helper extraction
- side-effect facade introduction
- BuildSection and BuildCheckSection decomposition
- BuildCheckRow formatter map refactor
- nested prop boundary cleanup
- start-flow cleanup (CreateCase / AboutYou)

## Behaviour

No intended behavioural changes.

The following were explicitly preserved:
- S78 journey behaviour
- payload shapes and field names/ids
- HASCAS mapping logic
- appellant/agent branching
- validation rules and messages
- redirect/query parameters (`lpa`, `apt`, `id`)
- navigation and side-effect sequencing
- EN/CY output parity

## Validation

Full regression has been performed on:
- start flow (CreateCase / AboutYou)
- save and resume flows
- file upload handling
- check answers rendering
- submit/finalisation sequence
- confirmation flow
- CRM insertion path
- EN/CY parity

Additional checks:
- docsOffline branch behaviour
- completion and partial-save email paths
- negative-path validation scenarios
- lint (warnings baseline unchanged)

## Risk

Low:
- changes are structural only
- no business logic changes
- no contract changes

## Rollback

Safe rollback via reverting this merge commit.

## Notes

This refactor reduces coupling and prepares the new-appeal flow for future appeal-type expansion.

Related work items: #22570, #22576, #22577, #22583, #22586, #22587, #22588, #22590

2026-04-13 13:09:12 +00:00

3.3 KiB

Raw Blame History

New Appeal Refactor Guardrails

Purpose

These guardrails apply to all AI-assisted and human-assisted work on the refactor branch for the new appeal flow.

Critical Rule

Preserve the current live S78 behaviour unless the task explicitly requires a behaviour change.

Do not assume a cleaner implementation is allowed to alter behaviour.

Protected Areas

Treat the following as protected flow files:

pages/newappeal/index.js
pages/newappeal/[appealtypes].js
components/newappeal/buildsection.js
components/newappeal/buildchecksection.js
components/newappeal/buildrow.js
components/newappeal/buildfield.js
components/newappeal/buildcheckrow.js
components/newappeal/complete.js
components/newappeal/aboutyou.js
components/newappeal/createCase.js
any helpers or service modules used directly by save/progress/upload/submit/finalise logic

Protected Behaviour

The following must not regress:

Start a new S78 appeal
Create case / initial journey entry
Section rendering from form definition
Section progression
Save and exit
Resume saved appeal
File/document upload behaviour
Check answers page
Appeal PDF generation/download path
Final submit/finalisation
Confirmation page behaviour
Email/notification side effects
English/Welsh parity for touched areas

Required Refactor Approach

When refactoring:

Understand current behaviour first
Identify the smallest safe boundary
Prefer extraction of pure/helper logic
Keep public interfaces stable where possible
Avoid changing UI, business rules, and structure in one step
Keep each slice easy to review and revert

Required Testing Mindset

Before changing critical flow behaviour, add or update protection such as:

characterization tests for current behaviour
targeted integration/service tests
journey-level regression checks
payload-shape assertions for save/submit/finalise paths

If automation is not practical yet, include an explicit manual verification matrix.

Payload/Integration Safety

Do not change without explicit need:

CRM payload field names or structure
boolean/value normalization behaviour
document/file metadata shape
save/resume payload expectations
PDF generation inputs
notification template selection or personalisation structure

i18n / Accessibility Safety

For touched user-facing behaviour:

keep EN/CY behaviour aligned
keep labels, messages, and route behaviour consistent
preserve semantic structure, focus behaviour, and validation messaging

Delivery Safety

Preferred pattern for each change:

protect current behaviour
extract one concern
run focused validation
keep rollback straightforward
merge only when safe

What To Avoid

Do not:

perform broad rewrites
mix feature delivery with refactor work
replace dynamic/config-driven logic with one-off hardcoding
move many responsibilities at once
introduce new dependencies unless clearly justified
silently change business rules while “cleaning up”

Refactor Success Criteria

A refactor slice is successful when it:

preserves behaviour
reduces complexity or coupling
improves readability or testability
keeps regression risk controlled
remains small enough to merge safely into SIPS-Development

3.3 KiB Raw Blame History