Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions SALES.md
Original file line number Diff line number Diff line change
Expand Up @@ -593,3 +593,53 @@ close-date/customer-type fields when their labels cannot be resolved. Default
field IDs apply only to the default report. Forecast does not replace the
recognised-revenue customer matrices. Existing incomplete-source and currency
notices apply. Deploy this API before the companion UI; no migration is required.

## PM-6783: goods-sold date/offering filters and booking costs

`GET /sales-dashboard/payments` now returns both `customerPayments` and
`customerBookingCosts` with identical complete customer series and month buckets.
Booking Cost is the existing member-payment amount (`gross_amount`, falling back
to `total_amount`) plus `finance.payment.challenge_fee`, counted once for the
latest payment version. Cancelled payments remain excluded. Zero fees and
negative adjustments are preserved; a missing fee makes that customer/month's
booking cost `null` and adds a notice that totals include known values only.
No payment is inferred from a fee rate or from a customer's revenue.

`startDate` is inclusive and `endDate` is exclusive, both in UTC and applied at
payment-event precision before aggregation. Existing validation limits ranges
to 732 days. The UI converts the inclusive To date to next-day midnight.

Repeat `offeringType` for OR selections; omit it for ALL. Offerings resolve by the
effective billing-account ID, using the existing payment-account precedence and
challenge-account fallback, through Salesforce:

- `Topcoder_Billing_Account__c.TopCoder_Billing_Account_Id__c`
- `Opportunity__r.Engagement_Offering_Type__c` and `Opportunity__r.Name`

These are exact ID lookups, without a close-date restriction or customer-name
matching. The client validates numeric IDs, queries batches of 200, caches results
for one minute, and rejects incomplete/conflicting results. Known offering labels
are normalized like customer revenue (including TopGear Ops → TopGear and the
existing two blank-offering corrections). Other recorded offerings remain
available. Missing accounts, opportunity links and categories are **Unknown**;
ALL includes them and Unknown can also be selected explicitly.

The query first obtains eligible billing-account IDs alongside the unfiltered
payment aggregates. After resolving the selected offerings, it reruns the
parameterized SQL with the matching IDs, so filtering precedes type/customer
sums, rankings and distinct member counts. `filterOptions.offeringType` retains
the full choices for the date/portal scope, even when a selection matches no rows.
An empty account selection matches nothing; it never becomes ALL. Both matrices
retain the existing Sales/Reports portal scope and TaaS/TopGear-payment exclusions.
The separate TaaS report does not perform offering lookups.

If Salesforce fails, unfiltered member/booking totals remain available with an
explicit offering-unavailable notice. A selected offering fails the request
instead of returning unfiltered totals. Existing report OAuth configuration and
Salesforce object/field read permissions must permit the lookup above.

Deploy this API change before the PM-6783 platform-ui change. No database migration
or new configuration variables are required. Validation covers real PostgreSQL
aggregation, inclusive/exclusive/leap-day boundaries, latest/cancelled versions,
multiple account selections, unknown links/fees, negative/zero fees, customer
scope, Salesforce ID validation/batching/cache, and upstream failure handling.
29 changes: 25 additions & 4 deletions sql/reports/dashboard/sales-payments.sql
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
-- $1/$2 inclusive/exclusive UTC bounds; $3 restricts to customer work for Sales.
-- $4 selects TaaS only; false selects non-TaaS Topcoder payments.
-- $5 optionally selects effective billing-account IDs resolved from Salesforce offerings.
-- NULL means ALL; an empty array matches none; unknown includes unlinked accounts.
-- Exclude TaaS, internal Topcoder and unlinked payments BEFORE any sums or rankings.
-- Uses the established dashboard payment version, category and customer-label rules.
WITH bounds AS (
Expand Down Expand Up @@ -27,6 +29,8 @@ payment_events AS MATERIALIZED (
END AS payment_type,
NULLIF(BTRIM(cl.name), '') AS client_name,
COALESCE(p.gross_amount, p.total_amount, 0) AS amount,
p.challenge_fee,
COALESCE(payment_ba.id::text, challenge_ba.id::text, 'unknown') AS billing_account_id,
NULLIF(TRIM(cl.id), '') AS customer_id,
NULLIF(TRIM(CASE
WHEN w.category::text = 'TAAS_PAYMENT'
Expand Down Expand Up @@ -66,7 +70,7 @@ payment_events AS MATERIALIZED (
AND NULLIF(TRIM(w.winner_id), '') IS NOT NULL
AND w.category::text IS DISTINCT FROM 'TOPGEAR_PAYMENT'
),
selected_events AS (
scoped_events AS (
SELECT pe.*
FROM payment_events pe
CROSS JOIN bounds b
Expand All @@ -80,11 +84,17 @@ selected_events AS (
AND LOWER(pe.client_name) <> 'topcoder'
AND LOWER(COALESCE(pe.customer_label, '')) NOT IN ('topcoder', 'taas')
))
),
selected_events AS (
SELECT * FROM scoped_events
WHERE $5::text[] IS NULL OR billing_account_id = ANY($5::text[])
)
SELECT TO_CHAR(DATE_TRUNC('month', activity_at), 'YYYY-MM-01') AS month,
CASE WHEN GROUPING(payment_type) = 0 THEN 'type' ELSE 'customer' END AS kind,
payment_type, customer_id, customer_label,
SUM(amount) AS amount, COUNT(DISTINCT member_id) AS members
SUM(amount) AS amount, COUNT(DISTINCT member_id) AS members,
CASE WHEN COUNT(challenge_fee) = COUNT(*) THEN SUM(amount + challenge_fee) END AS booking_amount,
NULL::text AS billing_account_id
FROM selected_events
GROUP BY GROUPING SETS (
(DATE_TRUNC('month', activity_at), payment_type),
Expand All @@ -93,13 +103,24 @@ GROUP BY GROUPING SETS (
UNION ALL
SELECT TO_CHAR(DATE_TRUNC('quarter', activity_at), 'YYYY-MM-01') AS month,
'quarter' AS kind, payment_type, NULL AS customer_id, NULL AS customer_label,
SUM(amount) AS amount, COUNT(DISTINCT member_id) AS members
SUM(amount) AS amount, COUNT(DISTINCT member_id) AS members,
CASE WHEN COUNT(challenge_fee) = COUNT(*) THEN SUM(amount + challenge_fee) END AS booking_amount,
NULL::text AS billing_account_id
FROM selected_events
GROUP BY DATE_TRUNC('quarter', activity_at), payment_type
UNION ALL
SELECT NULL AS month, 'annual' AS kind, payment_type,
NULL AS customer_id, NULL AS customer_label,
SUM(amount) AS amount, COUNT(DISTINCT member_id) AS members
SUM(amount) AS amount, COUNT(DISTINCT member_id) AS members,
CASE WHEN COUNT(challenge_fee) = COUNT(*) THEN SUM(amount + challenge_fee) END AS booking_amount,
NULL::text AS billing_account_id
FROM selected_events
GROUP BY payment_type
UNION ALL
-- Retain every in-range account before offering filtering so filter choices stay stable.
SELECT NULL AS month, 'billing-account' AS kind, NULL AS payment_type,
NULL AS customer_id, NULL AS customer_label, NULL AS amount, NULL AS members,
NULL AS booking_amount, billing_account_id
FROM scoped_events
GROUP BY billing_account_id
ORDER BY month, kind, payment_type, customer_id, customer_label;
3 changes: 3 additions & 0 deletions src/reports/dashboard/sales-dashboard.dto.ts
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,9 @@ export class SalesDashboardDto extends SalesCustomerRevenueDto {
/** Full customer series for the payments matrix, before top-five/Other grouping. */
@ApiPropertyOptional({ type: SalesDashboardChartDto })
customerPayments?: SalesDashboardChartDto;
/** Same payment/customer scope, with challenge fees included once per payment. */
@ApiPropertyOptional({ type: SalesDashboardChartDto })
customerBookingCosts?: SalesDashboardChartDto;
/** Offering-scoped customer matrices, including intersections with Account Category. */
@ApiPropertyOptional({ type: Object })
customerRevenueByOfferingType?: Partial<
Expand Down
166 changes: 166 additions & 0 deletions src/reports/dashboard/sales-dashboard.payments.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,166 @@
import { BadGatewayException } from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
import { SqlLoaderService } from "../../common/sql-loader.service";
import { DbService } from "../../db/db.service";
import { SalesReportsService } from "../sales/sales-reports.service";
import { SalesDashboardSection } from "./sales-dashboard.dto";
import { SalesDashboardService } from "./sales-dashboard.service";

describe("Goods sold customer payment scopes", () => {
const query = jest.fn();
const getBillingAccountOfferings = jest.fn();
const range = { startDate: "2028-02-15", endDate: "2028-03-01" };
const accounts = ["1", "2", "3", "unknown"].map((billing_account_id) => ({
kind: "billing-account",
billing_account_id,
}));
const customer = (
month: string,
amount: string,
booking_amount: string | null,
) => ({
month,
amount,
booking_amount,
kind: "customer",
customer_id: "client",
customer_label: "Customer",
});
const api = () =>
new SalesDashboardService(
{ query } as unknown as DbService,
new SqlLoaderService(),
{ getBillingAccountOfferings } as unknown as SalesReportsService,
new ConfigService(),
);
beforeEach(() => {
jest.resetAllMocks();
query.mockResolvedValue([
...accounts,
customer("2028-02-01", "100", "125"),
]);
getBillingAccountOfferings.mockResolvedValue(
new Map([
["1", "AI Training"],
["2", "Flexible Talent"],
]),
);
});

it("exposes both measures and all offerings without changing member totals", async () => {
const result = await api().load(SalesDashboardSection.Payments, range);
expect(query).toHaveBeenCalledTimes(1);
expect(
result.customerPayments?.months[0].values['["client","Customer"]'],
).toBe(100);
expect(
result.customerBookingCosts?.months[0].values['["client","Customer"]'],
).toBe(125);
expect(result.customerBookingCosts?.series).toEqual(
result.customerPayments?.series,
);
expect(result.filterOptions?.offeringType).toEqual([
"AI Training",
"Flexible Talent",
"Unknown",
]);
expect(result.notices).toEqual([]);
});

it.each([
[
["AI Training", "Flexible Talent"],
["1", "2"],
],
[["Unknown"], ["3", "unknown"]],
[["Not present"], []],
])(
"resolves %j to account IDs before aggregation",
async (offeringType, selected) => {
query
.mockResolvedValueOnce(accounts)
.mockResolvedValueOnce([customer("2028-02-01", "80", "100")]);
const result = await api().load(SalesDashboardSection.Payments, {
...range,
portal: "sales",
offeringType,
});
expect(query).toHaveBeenLastCalledWith(expect.any(String), [
"2028-02-15T00:00:00.000Z",
"2028-03-01T00:00:00.000Z",
true,
false,
selected,
]);
expect(
result.customerPayments?.months[0].values['["client","Customer"]'],
).toBe(80);
expect(
result.customerBookingCosts?.months[0].values['["client","Customer"]'],
).toBe(100);
expect(result.filterOptions?.offeringType).toEqual([
"AI Training",
"Flexible Talent",
"Unknown",
]);
},
);

it("keeps all-payment and booking amounts available on a lookup failure, but rejects filtered requests", async () => {
getBillingAccountOfferings.mockRejectedValue(
new BadGatewayException("upstream unavailable"),
);
const service = api();
const result = await service.load(SalesDashboardSection.Payments, range);
expect(
result.customerBookingCosts?.months[0].values['["client","Customer"]'],
).toBe(125);
expect(result.notices).toContain(
"Offering type details are unavailable. All payment offerings are included.",
);
await expect(
service.load(SalesDashboardSection.Payments, {
...range,
offeringType: ["AI Training"],
}),
).rejects.toThrow("upstream unavailable");
});

it("preserves unavailable fees, negative adjustments and zero-filled months", async () => {
query.mockResolvedValue([
customer("2028-02-01", "100", null),
customer("2028-03-01", "-20", "-25"),
]);
const result = await api().load(SalesDashboardSection.Payments, {
...range,
endDate: "2028-05-01",
});
expect(
result.customerBookingCosts?.months.map(
(month) => month.values['["client","Customer"]'],
),
).toEqual([null, -25, 0]);
expect(result.notices[0]).toContain("Some challenge fees are unavailable");
});

it("returns empty matrices without Salesforce requests for empty data", async () => {
query.mockResolvedValue([]);
const result = await api().load(SalesDashboardSection.Payments, range);
expect(result.customerPayments?.series).toEqual([]);
expect(result.customerBookingCosts?.series).toEqual([]);
expect(getBillingAccountOfferings).not.toHaveBeenCalled();
});

it("keeps TaaS independent from offering lookups and booking matrices", async () => {
const result = await api().load(SalesDashboardSection.TaasPayments, range);
expect(getBillingAccountOfferings).not.toHaveBeenCalled();
expect(result.customerBookingCosts).toBeUndefined();
expect(query).toHaveBeenLastCalledWith(expect.any(String), [
"2028-02-15T00:00:00.000Z",
"2028-03-01T00:00:00.000Z",
false,
true,
null,
]);
});
});
Loading
Loading