Sales overview screen contract

publ Reference
# Sales overview screen contract

The sales_overview_get workflow implements the core Sales overview screen as four composed summary reads. It adds one business tool and one partial workflow: 104 tools / 41 partial workflows on this branch. Orders, refunds and installed-feature commerce remain separately scoped. Financial submissions remain human console actions.

Compared sources: PnLPredictionContainer.tsx; SalesOverview.tsx; components/PeriodSettingModal.tsx and ChartList.tsx; salesAggregation saga, reducer, DTO and repository; channels DTO; CurrencyRoute.tsx; channel routes; ProfitableClient authorize/_request and API endpoint inventory. No new browser or REA capture is claimed while the established dev authentication is expired.

## Request composition

The source container requires OWNER or DELEGATEE with MANAGE_SALES_OVERVIEW.
The bridge checks selected-channel identity and the channel's creation date,
base currency and alternate definitions. It uses the selected channel bearer,
never an account-bearer fallback. The observed creation date's YYYY-MM-DD is
the source's lifetime start; current day and selected range use UTC. Alternate
currency order is preserved; inconsistent or duplicate definitions fail closed.

Each row below obtains a fresh ISSUER credential through the existing source
POST /profitable/authorize with role and selected channelId. It then reads
GET /api/v1/sales-aggregation/summary from the private configured PAY origin.
Authorization and data requests use their distinct bearers and the configured
apiKey query field. No caller-selected path, cookie, consumer/channel header,
redirect, automatic retry or stored payment token is used.

| Summary | Date range | unit | needsOnlyTotal | type |
| --- | --- | --- | --- | --- |
| Today | UTC today to today | daily | true | net-income |
| Accumulated | Source creation date to UTC today | daily | true | net-income |
| Monthly | Source creation date to UTC today | monthly | false | net-income |
| Selected period | Supplied/default inclusive dates | daily | false | Omitted, as in the source |

Every query supplies timezone UTC and the same observed selected currency.
The selectable period permits 1–93 inclusive days, within creation and today.
Its default is max(creation date, today minus seven days) through today.
The source lifetime accumulated/monthly queries are not truncated to 93 days.
Channel creation/currency metadata is read again after all four summaries;
channel, actor, permission and credential continuity must also hold. A later
failure discards every earlier summary. Separate observations are not atomic.

## Response and monetary contract

HTTP200 plus the source data.summary envelope is required. Shared transport bounds each body to 2 MiB; summaries permit at most 1,200 records. Selected-period and monthly results must include matching unit/startDate/endDate/timezone and records. Totals-only results may omit those fields; if present they must match. The source DTO's timezone annotation says USD/KST, while executed source queries use UTC.

Known totals include netIncomePrice, transactedIncomeInfo, refundedInfo and
SubscriptionProduct/PAppUnlockProduct model totals. Records additionally retain
year/month/week/day. Price currencies must equal the query currency; daily dates
must be valid, unique and within the range. Monthly year/month pairs must be
unique and within the lifetime range. Counts are nonnegative safe integers.
Unknown properties are omitted. Missing amount/model fields remain absent.

Decimal strings are preserved without Number conversion. The bound is 60
whole-number digits plus 30 fractional digits, with an optional minus sign.
An exact BigInt sum divided by the number of observed monthly records produces
a reduced exactRatio. exactAmount is emitted only for terminating decimals.
Missing net income in any monthly row or an empty row list produces an
unavailable average. Unlike the source's display arithmetic, missing amounts
are never substituted with zero. No new conversion, exchange rate or rounding
policy is inferred from UI formatting.

The destination is the selected channel's sales-overview/home path. With any
alternate currency definition, append the selected lowercase currency, including
for the base currency. This is one console address from central configuration;
no invented date-query deep link or account-home fallback. The source console
still owns its date selector. The tool creates no task, CSV, financial writer,
payout reservation or persisted issuer credential. See the
[tool reference](../tools/sales_overview_get.md) and shared
[private PAY configuration](payment-gateway.md#private-operator-configuration).