127 lines
6.9 KiB
Markdown
127 lines
6.9 KiB
Markdown
# Refactor Backlog (Maintainability + System Integrity)
|
|
|
|
Last updated: 2026-03-12
|
|
|
|
## Priority 1 — Split `actions/index.js` by concern
|
|
|
|
- **Problem:** Single high-coupling module mixes API clients, hash/token helpers, logging, file/email/domain operations.
|
|
- **Why it matters:** Hard to reason about changes; high regression risk from unrelated edits.
|
|
- **Target outcome:** Small modules with explicit boundaries (e.g. `relayClient`, `fileClient`, `notifyClient`, `caseService`, `authService`).
|
|
- **Initial scope:** create façade layer first, then migrate call sites incrementally.
|
|
- **Detailed plan:** `memory-bank/refactor-plan-actions-index.md`
|
|
- **Test gate:** add unit regression tests + coverage reporting as part of this refactor.
|
|
|
|
## Priority 2 — Centralize relay/hash/token forwarding logic
|
|
|
|
- **Problem:** `pages/api/endpoint/**` and related routes duplicate request-signing + token + forwarding behavior.
|
|
- **Why it matters:** Security-sensitive drift and inconsistent error handling.
|
|
- **Target outcome:** Shared relay utility enforcing one signing contract, one timeout/retry policy, one error map, one redacted logging strategy.
|
|
- **Initial scope:** pilot on a small endpoint group, then roll out pattern.
|
|
|
|
## Priority 3 — Extract breadcrumb/back-link route-state rules
|
|
|
|
- **Problem:** Navigation logic in `components/breadcrumbs.js` and case summary is branch-heavy and query-dependent.
|
|
- **Why it matters:** Frequent regressions in search -> case -> myportal paths.
|
|
- **Target outcome:** Pure route-state helpers with table-driven tests; UI component mainly renders output.
|
|
- **Initial scope:** isolate `va/adv/ads/key` decision matrix first.
|
|
|
|
## Priority 4 — Standardize security guards in `pages/api/file/**`
|
|
|
|
- **Problem:** Hash/guard enforcement appears inconsistent across file endpoints.
|
|
- **Why it matters:** Uneven protection for document upload/download/delete paths.
|
|
- **Target outcome:** Shared guard middleware for hash/auth/input validation + consistent negative-path responses.
|
|
- **Initial scope:** enforce a common pre-handler contract on high-risk routes first.
|
|
|
|
### Priority 4 — Current slice status (2026-03-23)
|
|
|
|
- Completed on `TASK22224-file-endpoint-contract-bundle`:
|
|
- `pages/api/file/downloadblob.js` hardening + hotfix closure
|
|
- path normalization compatibility (filename-only + prefixed path)
|
|
- encoded/raw hash validation compatibility guard
|
|
- Confirmed outcome:
|
|
- user-reported download failures resolved
|
|
- phase21 file + combined contract suites passing
|
|
|
|
### Priority 4 — Next recommended slice on this branch
|
|
|
|
- Target routes:
|
|
- `pages/api/file/deleteblob.js`
|
|
- `pages/api/file/deleteblobcase.js`
|
|
- `pages/api/file/deleteblobrep.js`
|
|
- Scope:
|
|
- align hash canonicalization strategy with `downloadblob.js`
|
|
- enforce explicit `respondError` contracts (`MISSING_REQUIRED_QUERY`, `INVALID_HASH`, route-specific `*_FAILED`)
|
|
- preserve existing success payload shapes
|
|
- extend `tests/phase21/file-handler-contract.test.cjs` with mixed encoded/raw hash variants and negative paths
|
|
|
|
## Priority 5 — Establish minimum automated regression baseline
|
|
|
|
- **Problem:** Limited automated tests for high-risk logic.
|
|
- **Why it matters:** Repeated regressions and heavy manual verification burden.
|
|
- **Target outcome:** Focused test suite for pure logic and high-risk decisions.
|
|
- **Initial scope:**
|
|
1. breadcrumb decision matrix
|
|
2. representation eligibility/date windows
|
|
3. hash utility behavior
|
|
4. locale rewrite mapping sanity checks
|
|
|
|
## Priority 6 — Decompose `components/elements/index.js` monolith (phased)
|
|
|
|
- **Problem:** `components/elements/index.js` has grown into a high-coupling UI monolith (~2700+ LOC) combining field primitives, validation/conditional logic, translation helpers, file-upload orchestration, and field-array behavior.
|
|
- **Why it matters:** Very high regression surface for new appeal/my portal forms, slower change velocity, and poor testability/isolation.
|
|
- **Target outcome:** `components/elements/index.js` reduced to a thin barrel export with responsibility split into focused modules.
|
|
- **Context alignment:** Matches architecture direction in `context/architecture.md` (endpoint/component sprawl reduction, bounded slices) and file boundary guidance in `context/coding-conventions.md` (`pages` thin, reusable logic/components split by concern).
|
|
- **Guardrail constraints:**
|
|
- Preserve public-service reliability for core flows (`search`, `case`, `myportal`, `newappeal`).
|
|
- No auth/session/security header behavior changes (out of scope).
|
|
- Maintain EN/CY parity for user-facing behavior.
|
|
- Keep accessibility behavior unchanged (labels, focus, keyboard flow, errors).
|
|
|
|
### Priority 6 — Phase 1 (start here): extract pure helpers only
|
|
|
|
- **Scope (Phase 1 only):**
|
|
- Move pure/helper logic from `components/elements/index.js` into focused helper modules under `components/elements/` (or `components/elements/helpers/`) without behavior change.
|
|
- Candidate helper extraction set:
|
|
- translation helpers (`FieldsTranslations`, picklist translation helper)
|
|
- file upload helper utilities (icon/doc type naming/pure format helpers)
|
|
- other deterministic pure functions used by field renderers
|
|
- Keep all field renderers/components in place for Phase 1.
|
|
- **Non-goals (Phase 1):**
|
|
- No JSX component relocation yet.
|
|
- No upload flow logic rewrites.
|
|
- No validation rule behavior changes.
|
|
- No prop contract changes for existing consumers.
|
|
|
|
- **Acceptance criteria (Phase 1):**
|
|
- `components/elements/index.js` imports extracted helpers from new helper modules and behavior remains equivalent.
|
|
- No route/API changes.
|
|
- Existing new appeal + myportal form journeys continue to function in EN and CY.
|
|
- Accessibility smoke unchanged for touched form controls (label association, keyboard reachability, inline error visibility).
|
|
- Lint passes for touched files.
|
|
|
|
- **Validation matrix (minimum):**
|
|
1. `npm run lint`
|
|
2. Manual smoke:
|
|
- new appeal form step rendering + validation messages
|
|
- myportal representation/new appeal editing flow controls
|
|
- file upload field icon/name behavior unchanged
|
|
3. Locale parity checks (EN/CY) for touched user-facing labels/routes.
|
|
4. A11y smoke checks on touched fields (focus, labels, errors).
|
|
|
|
- **Rollback plan (Phase 1):**
|
|
- Revert helper module extraction commit(s) to restore single-file implementation.
|
|
- No migration/data rollback required.
|
|
|
|
- **Next phases (for tracking):**
|
|
- **Phase 2:** extract low-risk leaf field renderer components.
|
|
- **Phase 3:** extract `RenderFileUpload` and upload container.
|
|
- **Phase 4:** extract field-array/repeater components.
|
|
- **Phase 5:** finalize `components/elements/index.js` as barrel-only export.
|
|
|
|
## Sequencing recommendation
|
|
|
|
1. Priorities 2 + 4 (security/integrity foundation)
|
|
2. Priority 3 (high-change regression hotspot)
|
|
3. Priority 1 (structural maintainability)
|
|
4. Priority 5 (continuous safety net, starts early and expands)
|