docs(governance): track context docs and add relay rollout controls
This commit is contained in:
@@ -0,0 +1,195 @@
|
||||
# Domain Flows Reference
|
||||
|
||||
## 1) Public Search and Case Discovery
|
||||
|
||||
**Representative routes**
|
||||
|
||||
- `/search`, `/searchresults`, `/advancedsearch`, `/advancedsearchresults`, `/addresssearch`, `/addresssearchresults`
|
||||
- `/case/[ticketnumber]`, `/dnsapplications`, `/dnsdetails`
|
||||
|
||||
**Expected behavior**
|
||||
|
||||
- Users can discover case information without authentication for public data.
|
||||
- Search and result pagination should remain performant and stable.
|
||||
- Route aliases in Welsh should mirror English flow intent.
|
||||
- Search/case data queries route through frontend APIs to Dynamics 365 CRM via Azure Service Bus Relay.
|
||||
- Relay-bound requests include path-based hash validation (computed client-side and verified relay-side with shared key).
|
||||
- Case reference selection from results routes the user to a case summary page where representations may be initiated.
|
||||
|
||||
### 1a) Basic search results page (UI behaviour)
|
||||
|
||||
- Route is served from the public search flow and presents a dedicated **Search results** page for a simple keyword/reference query.
|
||||
- Results heading shows:
|
||||
- a result count (`@odata.count` from CRM response)
|
||||
- the searched term in context (for basic search)
|
||||
- a linked-case title variant when `lk=1` is present.
|
||||
- Results are displayed as a tabular summary list with columns for:
|
||||
- Case reference
|
||||
- Site address
|
||||
- Applicant
|
||||
- Authority (including LPA reference where available)
|
||||
- Case type
|
||||
- Status
|
||||
- Case reference links route to case detail (`/case/[ticketnumber]` or locale/my-portal equivalents), carrying current query context.
|
||||
|
||||
### 1b) Search results interaction model
|
||||
|
||||
- Supports column sorting (reference, applicant, authority, case type, status), with ascending/descending state.
|
||||
- Supports page size selection (5/10/20/30/50) and paginated retrieval.
|
||||
- While data is loading, page shows a spinner/loading message; CRM error paths render the CRM error component.
|
||||
- If no matches are returned, page shows a clear no-records state.
|
||||
- A follow-on CTA links users to advanced search.
|
||||
|
||||
### 1c) Search matching and data presentation
|
||||
|
||||
- Basic search can match on case/application references and surfaced metadata (for example authority refs shown in results rows).
|
||||
- Matching query terms are highlighted in key visible fields where applicable.
|
||||
- User-facing formatted values (case type/status/authority labels) are locale-aware, with EN/CY translation mapping applied.
|
||||
|
||||
**Change risks**
|
||||
|
||||
- Breaking query/filters or pagination contracts.
|
||||
- Locale rewrite divergence causing EN/CY mismatch.
|
||||
- Relay or CRM query regressions causing empty/slow/inconsistent results.
|
||||
- Hash mismatch regressions causing relay rejection of otherwise valid requests.
|
||||
|
||||
## 2) Account and Authentication
|
||||
|
||||
**Representative routes/APIs**
|
||||
|
||||
- `/auth/signin`, `/auth/verify-request`, `/account/register`
|
||||
- `pages/api/auth/[...nextauth].js`
|
||||
|
||||
**Expected behavior**
|
||||
|
||||
- Email sign-in and callback flow should preserve secure redirect behavior.
|
||||
- Session and account persistence must align with Prisma next-auth models in SQL Server.
|
||||
- Locale-aware sign-in experience should remain coherent.
|
||||
- Newly registered/authenticated users are assigned **Interested Party** involvement by default.
|
||||
|
||||
**Change risks**
|
||||
|
||||
- Callback URL mishandling, cross-domain issues, insecure redirects.
|
||||
- Session expiry/update or cookie behavior regressions.
|
||||
|
||||
## 3) My Portal / Casework Actions
|
||||
|
||||
**Representative routes**
|
||||
|
||||
- `/myportal`, `/myportal/viewall`, `/myportal/case/[ticketnumber]`
|
||||
- new appeal, watched-cases, submissions, and representation workflows
|
||||
|
||||
**Expected behavior**
|
||||
|
||||
- Authenticated users manage personal case interactions reliably.
|
||||
- Redux persistence + hydration should keep client/server state coherent.
|
||||
- Portal data retrieval should remain stable through relay-backed CRM API queries.
|
||||
- Dashboard capabilities include:
|
||||
- **Make a new appeal** (guided appeal-type selection)
|
||||
- **Search for a case** by case/application/project reference
|
||||
- panel-based worklists for in-progress and submitted user activity
|
||||
|
||||
### 3a) Portal dashboard panel architecture
|
||||
|
||||
- The dashboard is a panel grid with two panel types:
|
||||
- **Action panels:** start key actions (new appeal, case search, DNS/project listing).
|
||||
- **Worklist panels:** list records by user relationship and workflow state.
|
||||
- Worklist panel groups shown in UI include:
|
||||
- Appeals awaiting submission
|
||||
- My cases
|
||||
- Watched cases
|
||||
- Representations awaiting submission
|
||||
- Submitted representations
|
||||
|
||||
### 3b) Case lifecycle and statuses (portal-visible)
|
||||
|
||||
- From dashboard behavior, case/representation records appear in practical states:
|
||||
- **Awaiting submission** (draft/incomplete, resumable)
|
||||
- **Pending** (submitted and active in processing)
|
||||
- **Submission processing** (recently submitted representation still being processed)
|
||||
- The UI separates these states into distinct panels rather than one combined status list.
|
||||
|
||||
### 3c) Domain entities used in dashboard flows
|
||||
|
||||
- **Case:** core planning case record identified by case reference (for example `CAS-...`).
|
||||
- **Appeal:** a casework submission type associated with an appeal type and LPA.
|
||||
- **Representation:** a statement/consultation response linked to a case.
|
||||
- **LPA:** Local Planning Authority associated with the case/appeal and shown as context metadata.
|
||||
|
||||
### 3d) User-to-case relationships
|
||||
|
||||
- **Owner / My case:** user is the primary submitting party (“My cases” panel).
|
||||
- **Watcher:** user follows case updates without being the owning submitter (“Watched cases” panel).
|
||||
- **Representative / On behalf of:** user acts for another party in case/appeal activity (shown as “On behalf of” in case cards).
|
||||
- Related role constraints remain:
|
||||
- users become **Appellants** when they raise a new appeal
|
||||
- CRM contact constraints allow only one role type, so Appellant remains their role once assigned
|
||||
- **Agents** can submit appeals on behalf of multiple Appellants
|
||||
- **LPA** users receive a different dashboard view focused on appeals in their local authority
|
||||
- LPA users do not have the raise-appeal action in dashboard UI
|
||||
- LPA users can raise/submit representations on appeals
|
||||
|
||||
**Change risks**
|
||||
|
||||
- HYDRATE/persist regressions causing stale or missing state.
|
||||
- Unauthorized access gaps in protected paths.
|
||||
|
||||
## 4) New Appeal and Representation Submission
|
||||
|
||||
**Representative areas**
|
||||
|
||||
- `pages/newappeal/**`, `components/newappeal/**`
|
||||
- representation flows in `components/case/representation/**`
|
||||
|
||||
**Expected behavior**
|
||||
|
||||
- Form progression, save/continue, and submission paths are resilient.
|
||||
- Generated PDFs/documents and notifications are consistent with submitted data.
|
||||
- “Make representation” availability on case summary is criteria/date dependent.
|
||||
- Users can begin representation flow from summary, but must be authenticated to submit.
|
||||
|
||||
### 4a) Representation submission workflow (dashboard view)
|
||||
|
||||
1. User finds/selects a case (search or existing case list).
|
||||
2. User starts a representation (for example statement/consultation response).
|
||||
3. Incomplete work appears in **Representations awaiting submission**.
|
||||
4. On submit, status may briefly show **Submission processing**.
|
||||
5. Completed items move to **Submitted representations**.
|
||||
|
||||
### 4b) Case search behaviour (portal dashboard)
|
||||
|
||||
- Search accepts multiple reference types from one input:
|
||||
- case reference
|
||||
- infrastructure project reference
|
||||
- LPA application reference
|
||||
- UI guidance shows accepted patterns similar to:
|
||||
- `APP-A12345-A-21-1234567`
|
||||
- `CAS-12345-A1B2C3`
|
||||
- Search panel provides direct links to **Address search** and **Advanced Search** for broader discovery routes.
|
||||
|
||||
**Change risks**
|
||||
|
||||
- Data mapping/validation drift; malformed uploads or document payloads.
|
||||
- Missing notifications or incorrect template/locale usage.
|
||||
|
||||
## 5) Document, Upload, and Notification Processing
|
||||
|
||||
**Representative APIs**
|
||||
|
||||
- `pages/api/file/**`
|
||||
- `pages/api/email/**`
|
||||
|
||||
**Expected behavior**
|
||||
|
||||
- File handling respects allowed types/size and error paths.
|
||||
- Email/notification side effects are reliable and observable.
|
||||
|
||||
**Change risks**
|
||||
|
||||
- Unsafe file handling, leakage of sensitive details in logs, or queue failures.
|
||||
|
||||
## Cross-Flow Non-Functional Expectations
|
||||
|
||||
- Accessibility: keyboard/focus/labels/semantic headings for UI changes.
|
||||
- Bilingual parity: EN/CY text/routes maintained together.
|
||||
- Public-service reliability: avoid user-visible regressions in key journeys.
|
||||
Reference in New Issue
Block a user