196 lines
8.2 KiB
Markdown
196 lines
8.2 KiB
Markdown
# 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.
|