robbond/pedwfrontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
60a2ff4594a20e01d914e8b13d8df481eebdccd7
pedwfrontend/docs/representation-participation-availability.md
T
Robert Bond 81a6276f44 Merged PR 2401: docs: document representation participation availability model 
docs: document representation participation availability model

Related work items: #23754
2026-06-18 10:27:53 +00:00

594 lines
20 KiB
Markdown
Raw Blame History

# Representation Participation Availability
## Purpose
This document records the current live **Representation Participation Availability** model used by the PEDW portal.
It is intended to preserve knowledge established through characterization and discovery work so that future developers, architects, and maintainers do not need to repeat the same investigations.
This document is based on observed current behaviour across the live decision paths, including:
- `lib/domain/representation-policy/*`
- `components/case/summary/utils/representationEntry.js`
- `components/search/repsonresults.js`
- existing characterization documentation and tests
This is a **behaviour characterization document**, not a redesign proposal.
---
## Executive Summary
Current portal behaviour appears to be making one broad business decision:
> Can this participant engage in representation or consultation activity for this case right now?
The current system does not behave like a set of unrelated button rules.
Instead, it behaves like a broadly coherent participation-availability policy with layered exceptions based on:
- appeal type
- specialist process
- participant type
- date-window state
- consultation state
- CRM field availability/variants
The policy has evolved organically over time.
As a result, some behaviours are clearly structured and repeatable, while others are compatibility-sensitive and exception-driven. A small number of current divergences between consumers appear historical rather than explicitly modelled, but they are now characterized and must be treated as preserved live behaviour unless a deliberate business change is approved.
---
## Core Business Decision
The decision being made is:
> Can this participant engage in representation or consultation activity for this case right now?
This is broader than a simple CTA visibility question.
In practice, the live system decides a combination of:
- whether participation is available at all
- whether the relevant participation window is open
- whether an exception applies for the case/process/participant combination
- whether unavailable-state messaging should be shown, suppressed, or rendered differently
- whether the case is currently handled as a consultation rather than a representation
This means the model should be understood as a **participation-availability decision**, not merely a rendering decision.
---
## Decision Inputs
The following inputs have been confirmed to affect the current live decision.
### 1. Appeal type
**Purpose**
Appeal type is the main top-level discriminator for participation behaviour.
**Effect on decision**
- determines whether the case is excluded entirely
- determines whether appeal-type-specific rules apply
- determines whether Householder, CPO, ROW, Advert, or consultation-specific logic is used
- affects which date fields are relevant in some branches
### 2. Appeal type family
**Purpose**
Appeal type family is used for broad exclusion rules.
**Effect on decision**
- certain families are blocked from representation participation regardless of other conditions
- explicit excluded appeal type IDs are also blocked even where family grouping might otherwise allow them
Current excluded families/IDs are characterized through `canShowRepresentationButtonForAppealType(...)`.
### 3. Specialist process
**Purpose**
Specialist process acts as an overlay for certain appeal types, especially ROW and Advert.
**Effect on decision**
- determines whether ROW is treated as hearing vs non-hearing
- determines whether Advert is treated as written reps, hearing, or other
- can change whether date gating applies
- can change whether participation is allowed, blocked, or permissively allowed by fallback
### 4. Participant type
**Purpose**
Some participation rules depend on who the actor is.
**Effect on decision**
- Householder is LPA-only
- Advert written reps is LPA-only
- non-LPA Householder unavailable state also triggers message suppression
### 5. Representation window
**Purpose**
For general cases, participation depends on whether the current representation period is open.
**Effect on decision**
- controls whether general participation is available
- controls blocked/ended-state behaviour for many cases
- uses field fallbacks in general resolution logic, but not all appeal-type exceptions use those fallbacks
### 6. Consultation window
**Purpose**
Some participation is treated as consultation activity rather than general representation activity.
**Effect on decision**
- consultation routes are controlled by consultation open/close dates
- consultation behaviour is separate from the general representation window path
### 7. Date state
**Purpose**
The system distinguishes between currently open, expired, future, and incomplete/missing windows.
**Effect on decision**
- open windows allow participation where no other exception blocks it
- expired windows block date-gated participation
- future windows also block date-gated participation
- missing/incomplete dates currently block some date-gated paths
### 8. CRM compatibility variants
**Purpose**
Historic CRM field variants are part of the live contract.
**Effect on decision**
- different consumers can reach different results depending on which field variant is present
- canonical vs misspelled specialist-process fields are especially important for ROW and Advert
- start-date and due-date variants can change participation availability when specific branches do not use the broader fallbacks
### 9. Field presence / absence
**Purpose**
Some branches make permissive decisions when data is absent; others make blocking decisions.
**Effect on decision**
- missing ROW specialist-process data currently falls through to allowed behaviour
- missing Advert specialist-process data currently falls through to blocked behaviour
- missing date data blocks CPO and ROW hearing paths
### 10. String vs numeric appeal type handling
**Purpose**
Appeal type format affects which special-case branch executes.
**Effect on decision**
- some helper paths coerce string values safely
- some consumer `switch` branches depend on numeric values and can be bypassed by string input
- this is characterized live behaviour and must be preserved unless intentionally changed
---
## Rule Catalogue
## Core Rules
### Excluded appeal categories
Participation is blocked entirely for the currently excluded appeal-type families:
- `ELECTRICITY_ACT`
- `TRANSPORT_WORKS`
- `HARBOUR_REVISION_ORDER`
- `WAYLEAVE`
- `NON_VALIDATION`
Participation is also blocked for explicit excluded appeal type IDs:
- `846040020`
- `846040023`
### General participation window model
For most non-excluded cases:
- participation is generally available
- participation depends on the relevant window being open
- once the period is no longer open, participation becomes unavailable
The general representation-window resolver currently uses:
- start: `pinswg_startdate` or `pinswg_startdates` or `pinswg_applicationacceptedasvalid`
- end: `pinswg_finalcommentsduedate` or `pinswg_endofrepresentationperiod`
### Permissive default model
For many non-special cases, once broad exclusion rules are passed, behaviour is permissive unless a specific exception blocks participation.
This permissive model is important in explaining current ROW non-hearing and missing-data fallbacks.
---
## Appeal-Type Exceptions
### Householder
Current live behaviour:
- participation is LPA-only
- non-LPA actors are blocked
- blocked explanatory messaging is suppressed for non-LPA Householder users
### CPO
Current live behaviour:
- participation is controlled by a CPO-specific date window
- the CPO rule uses `pinswg_startdate` → `pinswg_statementduedate`
- it does not broaden to general start-date fallbacks
- missing, future, or expired window values block participation
### ROW
Current live behaviour:
- hearing specialist process is date-gated
- non-hearing specialist process values are generally allowed
- missing specialist-process information currently falls through to permissive behaviour
- only `pinswg_startdate` and `pinswg_finalcommentsduedate` are used for hearing date gating
### Advert
Current live behaviour:
- written reps is LPA-only
- hearing is allowed for LPA and non-LPA
- other specialist-process values are blocked
- Advert is not currently date-gated
### Consultation participation
Current live behaviour:
- consultation participation is handled separately from general representation participation
- consultation availability depends on consultation open/close dates
---
## Specialist Process Overlays
### Hearing
- ROW hearing is date-gated
- Advert hearing is allowed and not date-gated
### Written reps
- Advert written reps is LPA-only
### Other process-specific restrictions
- ROW non-hearing remains permissive
- Advert non-allowlisted specialist-process values are blocked
---
## Participant-Type Overlays
### LPA-only behaviour
Confirmed current LPA-only participation rules:
- Householder participation
- Advert written reps participation
### Non-LPA suppression behaviour
Confirmed current suppression rule:
- non-LPA Householder users receive neither CTA nor blocked explanatory message
---
## Unavailable-State Behaviour
Current unavailable-state handling is part of the decision model.
### Blocked messaging
When a participation branch is in scope and the relevant path is unavailable, the portal may show blocked explanatory text.
### Ended-period messaging
Some consumers also render period-ended messaging once a participation period is considered closed.
### Suppression rules
Blocked messaging is currently suppressed for non-LPA Householder users.
### Important note
Unavailable-state rendering is not fully centralized. This contributes to a small number of current compatibility-sensitive differences in how blocked and ended states are expressed.
---
## Decision Tree
The current live decision can be reconstructed at a business-logic level as follows.
1. **Is this appeal type excluded from representation participation?**
- If yes → participation unavailable.
- If no → continue.
2. **Is this case currently being handled as a consultation route?**
- If yes → use consultation availability rules based on consultation dates.
- If no → continue with general representation availability.
3. **Is the general participation route in scope and is the relevant window open?**
- If no → participation unavailable or ended-state behaviour may apply.
- If yes → continue.
4. **Does this appeal type have a specific exception rule?**
- Householder → allow only LPA.
- CPO → allow only if CPO window (`startdate` → `statementduedate`) is open.
- ROW → use specialist-process overlay.
- Advert → use specialist-process overlay.
- Other types → permissive allow.
5. **If specialist process is relevant, what process applies?**
- ROW hearing → date-gated.
- ROW non-hearing → allowed.
- Advert written reps → LPA-only.
- Advert hearing → allowed.
- Advert other values → blocked.
6. **If participation is unavailable, should unavailable-state messaging be shown or suppressed?**
- non-LPA Householder → suppress blocked message.
- otherwise → blocked and/or ended messaging may be shown depending on consumer and date state.
This decision tree describes the live logic conceptually. It does not imply that the current implementation is centralized.
---
## Behaviour Matrix Summary
This section intentionally summarizes the characterized matrix rather than reproducing every row.
| Scenario | Current summarized behaviour |
| -------------------------- | ---------------------------------------------------------------------------------- |
| General cases | Participation generally available while the relevant representation window is open |
| Excluded categories | Participation unavailable regardless of other conditions |
| Householder | LPA-only participation; non-LPA blocked; blocked message suppressed for non-LPA |
| CPO | Participation date-gated using a CPO-specific due date |
| ROW hearing | Participation allowed only while the ROW hearing window is open |
| ROW non-hearing | Participation generally available |
| Advert written reps | LPA-only participation |
| Advert hearing | Participation available for LPA and non-LPA |
| Advert other process types | Participation unavailable |
| Consultation participation | Controlled separately by consultation dates |
For the full characterization detail, maintainers should refer back to the investigation outputs and phase22 tests.
---
## Known Compatibility Constraints
### CRM Field Variants
The following are confirmed compatibility-sensitive inputs and must be preserved as live contract.
#### Specialist-process variants
- `pinswg_specialistcaseprocess`
- `pinswg_speacialistcaseprocess`
These are not interchangeable in current live behaviour.
#### Start-date variants
- `pinswg_startdate`
- `pinswg_startdates`
- `pinswg_applicationacceptedasvalid`
These are used differently across general vs exception-specific paths.
#### Due-date variants
- `pinswg_statementduedate`
- `pinswg_finalcommentsduedate`
- `pinswg_endofrepresentationperiod`
These are not uniformly applied across all consumers and exception paths.
These variants are compatibility requirements, not cleanup targets.
### String vs Numeric Appeal Types
Current behaviour is format-sensitive.
- some top-level exclusions still apply because helper logic coerces numeric values
- some appeal-type-specific branches depend on numeric `switch` matching
- as a result, string values such as `"846040015"` or `"846040018"` can bypass special-case logic and fall through to permissive behaviour
This behaviour is characterized and must not be changed accidentally.
### Preserved Consumer Divergence
Current live behaviour is not fully standardized across consumers.
Known divergence currently exists between:
- case summary behaviour
- search-results behaviour
- extracted domain helpers
These differences must be treated as preserved live behaviour unless an explicit business decision authorizes standardization.
---
## Known Divergences
### 1. ROW misspelled specialist-process behaviour
**Observed behaviour**
- summary uses only `pinswg_specialistcaseprocess` for ROW
- search uses normalized fallback across canonical + misspelled fields
- where only the misspelled field is present with hearing value, summary can allow participation while search date-gates/block it
**Why it matters**
The same underlying case can appear available in one portal area and unavailable in another.
**Status**
Characterized and preserved.
### 2. Advert canonical vs misspelled specialist-process behaviour
**Observed behaviour**
- summary reads only `pinswg_speacialistcaseprocess`
- search uses canonical-first normalization
- canonical-only field population can block summary while allowing search
**Why it matters**
Portal behaviour depends on which CRM field variant is populated.
**Status**
Characterized and preserved.
### 3. Conflicting field precedence for Advert
**Observed behaviour**
- when both canonical and misspelled specialist-process fields exist with different values, summary uses the misspelled field directly
- search gives precedence to the canonical field
**Why it matters**
Conflicting field values produce deterministic user-facing divergence.
**Status**
Characterized and preserved.
### 4. CPO ended-message behaviour
**Observed behaviour**
- CPO participation gating uses `pinswg_statementduedate`
- blocked-state date display also uses the CPO due date
- ended-message closure checks still rely on general ended-period logic using `pinswg_finalcommentsduedate`
**Why it matters**
Participation can be blocked using one deadline while ended-period messaging is determined differently.
**Status**
Characterized; business intent still needs validation.
---
## Characterization Coverage
### Existing characterization tests
The repository already contains phase22 characterization tests covering key areas of this behaviour, including:
- `tests/phase22/representation-row-entry-rule.test.cjs`
- `tests/phase22/representation-advert-entry-rule.test.cjs`
- `tests/phase22/representation-cpo-entry-rule.test.cjs`
### Behaviour currently protected by tests
Existing tests cover, among other things:
- ROW hearing date gating
- ROW non-hearing permissive behaviour
- ROW canonical vs misspelled specialist-process divergence
- ROW string appeal-type bypass behaviour
- Advert written reps LPA-only behaviour
- Advert hearing availability
- Advert blocking for other process values
- Advert canonical vs misspelled divergence
- Advert conflicting precedence divergence
- Advert string appeal-type bypass behaviour
- CPO open / future / expired / missing date behaviour
- CPO refusal to broaden to fallback start fields
### Behaviour still requiring additional validation
The following remain especially valuable for ongoing protection:
- summary vs search unavailable-state rendering differences
- Householder blocked-message suppression
- consultation availability behaviour
- CPO ended-message inconsistency
- broader excluded-family coverage at documentation and test level
---
## Business Validation Questions
The following open questions emerged from characterization.
1. Should the general rule remain: participation is available only while the relevant participation period is open?
2. Should Householder participation remain LPA-only?
3. If Householder participation is unavailable, should users be shown an explanation?
4. Should CPO use a separate participation deadline from most other cases?
5. Should all CPO unavailable/ended messages use the same deadline consistently?
6. Should ROW hearing remain date-gated?
7. Should ROW non-hearing remain generally available?
8. What should happen when ROW process information is missing or unclear?
9. Should Advert written reps remain LPA-only?
10. Should Advert hearing remain available to all participant types?
11. Should Advert other process types remain blocked?
12. Should consultation participation remain intentionally separate from general representation participation?
13. Should missing process information ever default to allowed participation?
14. Should portal areas interpret the same process information consistently when different compatibility fields are populated?
15. Should string and numeric appeal-type inputs behave the same way?
---
## Architectural Conclusions
The characterization work supports the following conclusions.
1. The portal is making **one broad participation-availability decision**, not a set of unrelated visibility decisions.
2. The current behaviour is best described as a **coherent policy with layered exceptions**.
3. The policy has grown **organically over time**, which explains the mix of structured rules and compatibility-sensitive divergence.
4. Future work in this area should be driven by **business decision modelling**, not by superficial code cleanup.
5. CRM field variants, string-vs-number input behaviour, and consumer divergence are all part of the current live contract and must be preserved unless a deliberate behaviour change is approved.
---
## Related Documentation
- `docs/representation-participation-business-review.md`
- `lib/domain/representation-policy/README.md`
- `docs/query-profile-compatibility.md`
Reference in New Issue View Git Blame Copy Permalink