Merged PR 2398: amends to appeal policy

Related work items: #23754

lib/domain/appeal-type-policy/README.md

@@ -0,0 +1,128 @@
+# Appeal Type Policy
+
+## Purpose
+
+This boundary currently owns one narrow question only:
+
+> **What family does this appeal type belong to?**
+
+It does not currently own any broader appeal-type behaviour.
+
+This boundary exists to provide a thin, reusable identity/family layer without introducing duplicate mappings or broad appeal-type policy abstractions too early.
+
+---
+
+## Current ownership
+
+The boundary currently exposes:
+
+- `getAppealTypeFamily(appealTypeId)`
+
+This helper answers which family a supplied appeal type belongs to, while preserving the application’s existing behaviour exactly.
+
+---
+
+## Current source of truth
+
+`getAppealTypeFamily(...)` currently delegates to:
+
+- `lib/domain/case-lifecycle/mapAppealType.js`
+
+This is intentional for now.
+
+The goal is to avoid creating duplicate appeal-type family mappings while the family contract is still being stabilised through small characterization and adoption slices.
+
+At this stage, this boundary is a thin wrapper around the existing source of truth rather than an independent mapping table.
+
+---
+
+## Current consumers
+
+The boundary is currently consumed by:
+
+- `lib/domain/representation-policy/`
+- `lib/domain/representation-type-policy/`
+
+Adoption has been limited to rules that were clearly family/group-based.
+
+---
+
+## Explicit non-goals
+
+This boundary does **not** currently own:
+
+- appeal type rollout control
+- `pages/api/endpoint/getappealtypesfornewappeal_api.js`
+- lifecycle stages
+- query-field selection
+- CRM field selection
+- representation windows
+- representation availability
+- dashboard behaviour
+- capability matrices
+- specialist-process logic
+
+Those concerns remain in their existing domain or application-specific homes.
+
+---
+
+## Family vs specific-type rules
+
+An important distinction emerged during adoption.
+
+Some rules are genuinely **family-based**, for example:
+
+- DNS
+- SIP / SIPS
+
+Some rules are genuinely **appeal-type specific**, for example:
+
+- Householder
+- Advert
+- CPO
+- Rights of Way
+- Common Land
+
+Because of this, raw appeal-type IDs should **not** automatically be replaced with family classification.
+
+Family classification should only be adopted where the rule is clearly about a broader family/group identity.
+
+---
+
+## Known behavioural contracts
+
+The current behaviour of `getAppealTypeFamily(...)` is characterized and should be preserved.
+
+That includes:
+
+- numeric inputs
+- string inputs
+- alias mappings
+- unknown values
+- `null` / `undefined` handling
+
+Examples of preserved behaviour include:
+
+- known numeric mappings returning the current family key
+- known aliases resolving to the current family key
+- unknown values falling back to current behaviour
+- `null` / `undefined` preserving current behaviour rather than being normalised
+
+This helper should not be “cleaned up” or broadened without characterization first.
+
+---
+
+## Future guidance
+
+Future slices should:
+
+- characterize first
+- adopt selectively
+- avoid broad replacement of appeal-type checks
+
+Future work should continue to distinguish between:
+
+- **identity/family classification**
+- **specific appeal-type business rules**
+
+This boundary should remain narrow until there is strong evidence that additional shared ownership is both stable and behaviour-preserving.

lib/domain/appeal-type-policy/getAppealTypeFamily.js

@@ -0,0 +1,5 @@
+import { mapAppealType } from "../case-lifecycle/mapAppealType";
+
+export function getAppealTypeFamily(appealTypeId) {
+    return mapAppealType(appealTypeId);
+}

lib/domain/appeal-type-policy/index.js

@@ -0,0 +1 @@
+export { getAppealTypeFamily } from "./getAppealTypeFamily";

lib/domain/representation-policy/canShowRepresentationButtonForAppealType.js

@@ -1,7 +1,20 @@
-const EXCLUDED_APPEAL_TYPE_IDS = new Set([
-    846040012, 846040013, 846040014, 846040020, 846040021, 846040023, 846040024
+import { getAppealTypeFamily } from "../appeal-type-policy";
+
+const EXCLUDED_APPEAL_TYPE_FAMILIES = new Set([
+    "ELECTRICITY_ACT",
+    "TRANSPORT_WORKS",
+    "HARBOUR_REVISION_ORDER",
+    "WAYLEAVE",
+    "NON_VALIDATION"
 ]);
 
+const EXCLUDED_APPEAL_TYPE_IDS = new Set([846040020, 846040023]);
+
 export function canShowRepresentationButtonForAppealType(appealType) {
-    return EXCLUDED_APPEAL_TYPE_IDS.has(Number(appealType)) ? false : true;
+    const appealTypeFamily = getAppealTypeFamily(appealType);
+
+    return EXCLUDED_APPEAL_TYPE_FAMILIES.has(appealTypeFamily) ||
+        EXCLUDED_APPEAL_TYPE_IDS.has(Number(appealType))
+        ? false
+        : true;
 }

lib/domain/representation-type-policy/getAvailableRepresentationTypes.js

@@ -1,3 +1,5 @@
+import { getAppealTypeFamily } from "../appeal-type-policy";
+
 const APPEAL_TYPES = {
     SIPS: 846040002,
     DNS: 846040011,
@@ -22,6 +24,11 @@ const REPRESENTATION_OPTIONS = {
     MARINE_IMPACT_REPORT: "Marine Impact Report"
 };
 
+const APPEAL_TYPE_FAMILIES = {
+    DNS: "DNS",
+    SIPS: "SIP"
+};
+
 const isValidDate = (date) =>
     date instanceof Date && !Number.isNaN(date.getTime());
 
@@ -34,15 +41,16 @@ const isWithinWindow = (now, start, end) => {
 };
 
 const addQuestionnaire = (options, ctx) => {
+    const appealTypeFamily = getAppealTypeFamily(ctx.appealType);
     const excludedTypes = [
         APPEAL_TYPES.EXCLUDE_QUESTIONNAIRE_1,
-        APPEAL_TYPES.DNS,
         APPEAL_TYPES.EXCLUDE_QUESTIONNAIRE_2,
         APPEAL_TYPES.EXCLUDE_QUESTIONNAIRE_3
     ];
 
     const canAdd =
         ctx.isLPA &&
+        appealTypeFamily !== APPEAL_TYPE_FAMILIES.DNS &&
         !excludedTypes.includes(ctx.appealType) &&
         isWithinWindow(ctx.now, ctx.startDate, ctx.finalCommentsDueDate);
 
@@ -52,6 +60,9 @@ const addQuestionnaire = (options, ctx) => {
 };
 
 const addStatements = (options, ctx) => {
+    const appealTypeFamily = getAppealTypeFamily(ctx.appealType);
+    const isDnsAppeal = appealTypeFamily === APPEAL_TYPE_FAMILIES.DNS;
+
     const isLpaAdvertPart3NoStatement =
         ctx.isLPA &&
         ctx.appealType === APPEAL_TYPES.ADVERT &&
@@ -59,7 +70,7 @@ const addStatements = (options, ctx) => {
 
     const canAddDnsLpaDocs =
         ctx.isLPA &&
-        ctx.isDNS &&
+        isDnsAppeal &&
         ctx.appealType !== APPEAL_TYPES.EXCLUDE_QUESTIONNAIRE_1 &&
         !ctx.isCaseOwner &&
         isWithinWindow(ctx.now, ctx.startDate, ctx.finalCommentsDueDate);
@@ -70,7 +81,7 @@ const addStatements = (options, ctx) => {
     }
 
     const canAddStatementForNonDns =
-        !ctx.isDNS &&
+        !isDnsAppeal &&
         ctx.appealType !== APPEAL_TYPES.HOUSEHOLDER &&
         !isLpaAdvertPart3NoStatement &&
         !ctx.isCaseOwner &&
@@ -81,7 +92,7 @@ const addStatements = (options, ctx) => {
     }
 
     const canAddStatementForDnsNonLpa =
-        ctx.isDNS &&
+        isDnsAppeal &&
         !ctx.isLPA &&
         !ctx.isCaseOwner &&
         isWithinWindow(ctx.now, ctx.startDate, ctx.statementDueDate);
@@ -92,20 +103,23 @@ const addStatements = (options, ctx) => {
 };
 
 const addFinalComments = (options, ctx) => {
+    const appealTypeFamily = getAppealTypeFamily(ctx.appealType);
+    const isDnsAppeal = appealTypeFamily === APPEAL_TYPE_FAMILIES.DNS;
+
     const canSubmitFinalCommentsDefault =
         ctx.isSelectedAppellant ||
         ctx.isSelectedAgent ||
         ctx.isSelectedInterestedParty ||
         ctx.isLPA;
 
-    const canSubmitFinalComments = ctx.isDNS
+    const canSubmitFinalComments = isDnsAppeal
         ? ctx.isLPA
         : canSubmitFinalCommentsDefault;
 
     const isSpecialistNonHearing =
         ctx.specialistProcess !== SPECIALIST_PROCESS.HEARING;
 
-    const finalCommentsWindowStart = ctx.isDNS
+    const finalCommentsWindowStart = isDnsAppeal
         ? ctx.startDate
         : ctx.statementDueDate;
 
@@ -124,7 +138,9 @@ const addFinalComments = (options, ctx) => {
 };
 
 const addConsultation = (options, ctx) => {
-    if (!ctx.isSIPS) return;
+    const appealTypeFamily = getAppealTypeFamily(ctx.appealType);
+
+    if (appealTypeFamily !== APPEAL_TYPE_FAMILIES.SIPS) return;
 
     options.add(REPRESENTATION_OPTIONS.CONSULTATION_RESPONSE);