opportunities-extension/openspec/specs/service-requests/spec.md

service-requests Specification

Purpose

Expose service requests linked to opportunities and customers, with progressive status badges, detail views and explicit record creation.

Requirements

Requirement: CRM SR queries resolve their saved search

Before the first CRM Service Request page, the extension SHALL retrieve SR search resources using the general Token Relay Bearer and use the first item's valid savedSearchNumber as queries/<savedSearchNumber> in copiedFrom.

Scenario: Search resources have no identifier

• WHEN the first item has no valid saved-search number
• THEN the dependent CRM SR query fails explicitly instead of using a fixed fallback

Requirement: SR enrichment is progressive and nonblocking

For eligible users, CRM SR pages SHALL load after opportunities are displayed and update their linked badges in the background. The query SHALL select pending-delivery team SRs and match opportunities through the returned opportunity number.

Scenario: First SR page arrives

• WHEN more SR pages remain after the first successful page
• THEN information received so far can update the visible opportunities without waiting for all pages

Requirement: Failed SR loading remains distinguishable from no matches

The extension SHALL distinguish loading, failed and confirmed empty SR results. Pagination SHALL detect lack of progress, retry each failed page at most five total attempts, and stop work superseded by a newer query.

Scenario: SR lookup fails

• WHEN a lookup cannot establish whether an opportunity has matching SRs
• THEN its badge indicates an unknown or failed state rather than confirmed absence

Scenario: Successful SR snapshot is reused

• WHEN a subsequent cycle can reuse the completed SR result within the current page session
• THEN it does not repeat the completed query unless explicitly invalidated

Requirement: Customer SR details use the resolved account identifier

Customer Service Requests SHALL resolve account summary first, use its id for the customer SR query and consolidate pages of open SRs. The dialog SHALL provide a loading skeleton, searchable sortable results, and guards against late results after closure.

Scenario: Account has distinct identifiers

• WHEN account summary returns different id and registryId values
• THEN customer SR retrieval uses id, not registryId

Requirement: Internal SR recovery is bounded

Internal SR details SHALL report failed requests and use bounded, shared session recovery rather than continuously issuing requests or opening a visible recovery tab.

Scenario: Endpoint remains unavailable

• WHEN an Internal SR read continues to fail after its allowed recovery attempts
• THEN the view shows failure and does not keep sending an unbounded automatic request loop

Requirement: SR creation validates before writing

Service Request creation SHALL require valid form inputs before submission, retain entered data on failure and prevent duplicate submissions while saving. Internal SR creation SHALL resolve parent SR and current resource information before linking the new record to its parent.

Scenario: Required fields are missing

• WHEN Save is clicked on an incomplete SR form
• THEN the missing fields are highlighted and no create request is sent

Scenario: Create request fails

• WHEN a submitted SR creation fails
• THEN the user receives error feedback and their form values remain available