Robert Bond
0de9268255
## 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
118 lines
3.3 KiB
Markdown
118 lines
3.3 KiB
Markdown
# 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:
|
|
|
|
1. Start a new S78 appeal
|
|
2. Create case / initial journey entry
|
|
3. Section rendering from form definition
|
|
4. Section progression
|
|
5. Save and exit
|
|
6. Resume saved appeal
|
|
7. File/document upload behaviour
|
|
8. Check answers page
|
|
9. Appeal PDF generation/download path
|
|
10. Final submit/finalisation
|
|
11. Confirmation page behaviour
|
|
12. Email/notification side effects
|
|
13. English/Welsh parity for touched areas
|
|
|
|
## Required Refactor Approach
|
|
|
|
When refactoring:
|
|
|
|
1. Understand current behaviour first
|
|
2. Identify the smallest safe boundary
|
|
3. Prefer extraction of pure/helper logic
|
|
4. Keep public interfaces stable where possible
|
|
5. Avoid changing UI, business rules, and structure in one step
|
|
6. 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:
|
|
|
|
1. protect current behaviour
|
|
2. extract one concern
|
|
3. run focused validation
|
|
4. keep rollback straightforward
|
|
5. 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`
|