opportunities-extension/openspec/specs/organization-charts/spec.md

organization-charts Specification

Purpose

Maintain customer organization charts locally while enriching people with Oracle contact information and related opportunities.

Requirements

Requirement: Charts are scoped and stored locally

Charts SHALL persist JSON-compatible records in extension-owned IndexedDB, scoped by user and customer in the browser profile. Records SHALL include revision and update metadata; stale saves SHALL be rejected. Email SHALL not persist in chart nodes.

Scenario: Concurrent chart change

• WHEN a user saves an outdated revision after another window has saved the chart
• THEN the save is rejected with guidance to reopen the current chart

Scenario: Browser profile is different

• WHEN the same user accesses the customer in another browser profile
• THEN this local chart is not automatically synchronized to that profile

Requirement: Hierarchy editing preserves remaining people

The chart SHALL support adding people, changing their manager, notes, branch expansion/collapse, zoom and panning. It SHALL reject invalid hierarchies, support up to 500 people and 60 levels, and promote direct reports to the removed person's manager when a person is deleted.

Scenario: Manager is deleted

• WHEN a user deletes a person with direct reports
• THEN those reports remain in the chart under the deleted person's manager

Scenario: Unsaved chart is closed

• WHEN the user closes a chart with unsaved changes
• THEN the extension requests confirmation before discarding those changes

Requirement: Contact autocomplete is debounced and customer-scoped

Name autocomplete SHALL search contacts after a 350 ms typing pause, filter by the customer's PartyId, display PartyName and JobTitle, and ignore superseded results. Empty queries and opening the chart alone SHALL not issue contact searches.

Scenario: User keeps typing

• WHEN another character arrives before the search delay expires
• THEN the pending search is superseded rather than sending one query per character

Requirement: Person details refresh contact data on demand

Opening a stored person SHALL query contacts using the person's Name as keywords and match by contact PartyId. A matching result SHALL refresh Name and Job Title while preserving notes and reporting relationships; Email SHALL remain transient. Job Title SHALL be eligible for chart persistence.

Scenario: Contact data changed

• WHEN a matching contact response has a new name or job title
• THEN the working chart updates those fields and retains the person's notes and manager

Requirement: Contact PartyNumber is preserved as an opaque identifier

Chart nodes SHALL retain the contact's PartyNumber, including alphanumeric values. Opening person details SHALL persist a returned PartyNumber; opportunity lookup SHALL use an existing stored value and attempt resolution when it is missing.

Scenario: Alphanumeric number is already saved

• WHEN opportunities are requested for a person with PartyNumber A4KCS2P
• THEN that exact value is used in OpportunityContact.ContactPartyNumber, without numeric conversion

Requirement: Contact opportunity tables load all pages

The person card SHALL provide an opportunities action that opens Opportunities | <name>, shows a skeleton while loading and follows hasMore until all pages are collected. The resulting table SHALL be sortable and link each Name to its corresponding opportunity in a new tab.

Scenario: Contact has more than one result page

• WHEN the opportunities response sets hasMore=true
• THEN the next offset is queried using the same contact PartyNumber until the result is complete

Requirement: New contacts are created explicitly

The contact-creation form SHALL require First Name, Last Name and Email, map email/phone consent to their corresponding Do/DoNot flags and obtain account identifiers from the selected customer. Provided phone components SHALL be combined as country code, hyphen and number. Save SHALL submit directly without a payload-preview step.

Scenario: Optional phone is omitted

• WHEN required contact fields are valid but a phone number is not filled
• THEN that absent phone value is not included as a populated contact field

Scenario: Phone components are entered

• WHEN country code 55 and phone number 99999999999 are provided
• THEN the submitted raw phone value is 55-99999999999