[IAmJSD]

Root cause

fetchCommitmentPurchases (internal/api/handler_dashboard.go) logged a GetActivePurchaseHistory error ("KPIs will be zeroed") and returned ok=false. calculateCommitmentMetrics turned that into 0, 0, 0, nil, and getDashboardSummary sent a 200 with active_commitments: 0, committed_monthly: 0 and ytd_savings: 0. A store outage looked exactly like an empty portfolio.

cristim's comment on the issue points out a second effect. calculateCurrentCoverage returned a hard-coded 100.0 whenever potentialSavings == 0, even when nothing was committed. So the zeroed commitment half plus an empty recommendations half rendered as "100% coverage, $0 committed". That figure looks consistent, is made up, and reassures instead of alarming. The existing unit test even had a subtest named both zero returns 0% that asserted 100.0.

Fix

Error contract: propagate, and the request returns a 500. I picked this by matching how getDashboardSummary already treats its dependencies:

• Hard data sources fail the request. A ListRecommendations error (failed to get recommendations), an account-scope error and a getAccountScope error all return an error, which becomes a 500 (handleRequestError sends a generic Internal server error body, so store details don't leak). Purchase history is the only source for the commitment KPIs, the same way recommendations are the only source for the savings KPIs. It now follows the same rule.
• Refinements degrade to a documented, non-fabricated default. The per-account coverage cap (resolveCoverageByAccountKey) falls back to un-scaled totals, and the target (resolveTargetCoverage) falls back to the 80% default. Neither invents a $0. The summary response has no partial/unavailable flag anywhere, and adding one would put a new contract on the frontend.
• The frontend already handles a 500 here. loadDashboard treats a rejected summary fetch as an error and renders Failed to load dashboard: …, never zeros.

Changes:

• fetchCommitmentPurchases now returns ([]PurchaseHistoryRecord, error). A store error comes back wrapped as failed to get active purchase history: %w. The explicit zero-account scope sentinel (issue sec(auth): an admin-scoped API key ignores its account and amount constraints on non-strict checks #956) still returns (nil, nil) without querying, because for a scoped user with no accessible accounts the zeros are real.
• calculateCommitmentMetrics gained an error return. getDashboardSummary returns that error.
• Coverage (cristim's compounding effect): calculateCurrentCoverage no longer special-cases potentialSavings == 0. It computes committed / (committed + potential) in every case and returns nil for 0/0. DashboardSummaryResponse.CurrentCoverage is now *float64, so current_coverage is serialized as an explicit null. With commitments and nothing left to buy, coverage is still 100%, now from the ratio itself. Only the case with nothing to measure changed, from an invented 100% to null. openapi.yaml marks the field nullable: true.

Closes #72

Verification

Unit/mock evidence only (testify mocks of the config store and scheduler). The bug is in the handler's error handling, not in SQL, so there's no DB change and no integration test. No concurrent-caller concerns: this adds no writes and no shared state.

New/changed tests in internal/api/handler_dashboard_test.go:

• TestHandleRequest_DashboardSummary_PurchaseHistoryErrorIs500: goes through the router (HandleRequest) using the issue's compounding scenario (no recommendations plus a store error). It asserts a 500, no KPI payload, and that the store error text doesn't leak.
• TestGetDashboardSummary_NothingToMeasure_CoverageIsNull: 0/0 serializes as "current_coverage":null.
• TestHandler_getDashboardSummary_Errors/purchase_history_error: errors.Is the store error, with a nil result.
• TestHandler_calculateCommitmentMetrics/purchase_history_error_is_returned,_not_zeroed: replaces the old purchase history error returns zeros subtest, which pinned the bug.
• TestHandler_calculateCurrentCoverage: pointer results. both zero returns nil, not 100% replaces the mislabeled both zero returns 0%, which asserted 100.
• Mechanical: the existing calculateCommitmentMetrics call sites now also take err and require.NoError.

Fail-before: I copied the two new top-level tests unchanged into a detached origin/main worktree (a14dc8f) and ran:

go test ./internal/api/ -count=1 -run 'TestHandleRequest_DashboardSummary_PurchaseHistoryErrorIs500|TestGetDashboardSummary_NothingToMeasure_CoverageIsNull'
--- FAIL: TestHandleRequest_DashboardSummary_PurchaseHistoryErrorIs500
    expected: 500  actual: 200
    body: {"by_service":{},"potential_monthly_savings":0,"total_recommendations":0,"active_commitments":0,"committed_monthly":0,"current_coverage":100,"target_coverage":80,"ytd_savings":0}
--- FAIL: TestGetDashboardSummary_NothingToMeasure_CoverageIsNull
    Expected nil, but got: 100

That body is the "100% coverage, $0 committed" response from the issue, produced on main.

Pass-after (this branch, Go 1.26.9, AWS_CONFIG_FILE=/dev/null AWS_SHARED_CREDENTIALS_FILE=/dev/null AWS_EC2_METADATA_DISABLED=true):

go build ./...                                   # ok
go vet ./... && go vet -tags integration ./...   # ok
go test ./internal/api/ -count=1                 # ok
go test ./internal/mocks/ -count=1               # ok
golangci-lint run --allow-parallel-runners ./internal/api/                         # 0 issues (v2.10.1)
golangci-lint run --allow-parallel-runners --build-tags integration ./internal/api/ # 0 issues
gocyclo -over 10 -ignore "_test\.go" internal/api/handler_dashboard.go internal/api/types.go  # none (getDashboardSummary 7)

Combined-tree verification. This branch was tested together with the other queued branches on a local, never-pushed tree: queue/platform @ 936996ad = origin/main a14dc8f2 plus these heads, merged in this order:

Branch	Tested head
fix/issue-337	ff3420c
fix/issue-169	7d75eb5
fix/issue-342	66b221f
fix/issue-310	5e11c21
fix/issue-326	5f0ea59
fix/issue-243	365e959
fix/issue-343	6c94036
fix/issue-312	d2848a8
fix/issue-316	acd60dd
fix/issue-339	75ea9b9
fix/issue-339-commitment-type	73bdb19
fix/issue-353	5d25fcd
fix/issue-313	3156bc4
fix/issue-357	53d9e58
fix/issue-368	0ba727d
fix/issue-419	61648c9
fix/issue-111	b04c372
fix/issue-686	0ad90b7
fix/issue-674	793095d
fix/issue-1055	4ec96f1
fix/issue-559	dfa9525
fix/issue-558	034eed4
fix/issue-874	1720539
fix/issue-666	1e120da
fix/issue-668	fb26345
fix/issue-568	ce04173
fix/issue-311	e54f250
fix/issue-177	0cbb88a
fix/issue-151	c21377c
fix/issue-166	41fb77b
fix/issue-27	2d67622
fix/issue-323	69288ae
fix/issue-59	36463e8
fix/issue-43	35e4069
fix/issue-158	6f76f8a
fix/issue-104	bb00491
fix/issue-55	971ef1b
fix/issue-361	89ac220
fix/issue-120	b458719
fix/issue-36	42bac6e
fix/issue-525	57c97dd
fix/issue-712	e5bcda0
fix/issue-72	6cc63ed

fix/issue-72 and fix/issue-312 conflict on one line in internal/api/handler_dashboard.go (both change the calculateCommitmentMetrics call). The tree used #72's side with #312's validated provider variable; whichever PR merges second takes that same resolution.

Linux, Go 1.26.9, AWS_CONFIG_FILE=/dev/null AWS_SHARED_CREDENTIALS_FILE=/dev/null AWS_EC2_METADATA_DISABLED=true; Docker Postgres via testcontainers:

• Passed at 936996ad: go build ./..., go vet ./..., go vet -tags integration ./... and the full go test -race -short -count=1 ./....
• Static checks at 936996ad: golangci-lint v2.10.1 found 0 issues on every changed package, with and without --build-tags integration. tests/e2e is a separate module, so it was vetted under its own e2e tag. gocyclo -over 10 is silent on the changed non-test files.
• Integration tests, every changed package, one package at a time (-tags integration -count=1, 60-minute local timeout because the VM was shared):
  • At 936996ad, these pass: internal/server, internal/credentials, internal/scheduler, internal/database/postgres/migrations, internal/purchase and internal/api.
  • internal/config passes except TestPostgresStoreDB_ResolveStaleRIExchange_ValidatesCloudCheck, which fails the same way on unmodified main (fixed by fix(config): compare resolve checked_at at the database's microsecond precision #1252).
  • These were run on the first build of this tree (26795376, same branches at earlier heads): internal/analytics, internal/auth, internal/commitmentopts, internal/database and cmd/lambda/clear-rate-limit all pass. The later fixes don't touch those packages.
• What the combined run caught, each fixed on its own branch before this PR opened:
  • a compile break between fix/issue-104's test and fix/issue-326's httpToLambdaRequest signature change;
  • fix/issue-316 rejecting legacy-keyed plans;
  • fix/issue-120 versus main's global-filter test.
• Secrets: git-secrets, using the repo's scripts/setup-git-secrets.sh patterns in a fresh repo with an isolated HOME, found nothing in the changed files, and a planted fake key was flagged. scripts/test-git-secrets-allowlist.sh: 137 PASS, 0 FAIL.
• Nothing was applied to any cloud.

API contract change

GET /api/dashboard/summary:

• returns 500 ({"error":"Internal server error"}) when the purchase-history read fails, where it used to return a 200 with zeroed commitment KPIs;
• current_coverage is null when committed and potential monthly savings are both 0, where it used to be 100.

A Go client that decodes into a float64 reads null as 0 without error.

Out of scope

• Sibling in handler_inventory.go (~:224-230), from cristim's comment. A failed ListRecommendations leaves onDemandByKey empty, so coveragePct(covered, 0) gives 100% on every Coverage-tab row. cristim recorded it in the grouped internal/api medium/low issue, and it has a different endpoint and response shape, so I didn't fix it here.
• An empty recommendations cache. If collection has never run or is stale while commitments exist, coverage still computes to 100% (committed / (committed + 0)). Telling "nothing left to buy" apart from "never collected" needs a collection-freshness signal in the summary, which is a separate design question.
• Other best-effort fallbacks in the same handler. resolveCoverageByAccountKey (un-scaled totals) and resolveTargetCoverage (80% default) are documented trade-offs that don't produce a fabricated $0, so I left them unchanged.

Merge note

This touches the calculateCommitmentMetrics call line in getDashboardSummary, which our not-yet-opened branch fix/issue-312 also edits (params["provider"] becomes provider). The conflict is that one line. Resolve it by keeping this branch's side, including the new if err != nil block, and using provider as the argument. I checked that resolution: it builds and go test ./internal/api/ passes. It merges cleanly with #1200.

Frontend follow-up for the UI owner

None of this needs a UI change to be correct: dashboard.ts already renders a rejected summary as Failed to load dashboard: …, and a null current_coverage as -- (data.current_coverage ?? null). Suggested follow-ups:

• frontend/src/api/types.ts: change current_coverage: number to current_coverage: number | null so the type matches the API. frontend/src/types.ts already has it optional.
• Add a jest case for current_coverage: null with total_recommendations > 0, expecting --. Today nothingTracked covers only the case where both counts are 0.
• Optional, product decision: a store error now blanks the whole KPI row. If you'd rather show the recommendation tiles and mark only the commitment tiles unavailable, the backend would need a per-section degraded flag. That's a follow-up, not part of this fix.

Could a maintainer please mirror the issue's triage labels onto this PR: severity/medium, priority/p3, urgency/this-quarter, impact/many, effort/s, type/bug, triaged.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

• Run on-demand review

_{This review includes 4 billable files and costs up to $1.00.}

Or wait 58 minutes for your next included review.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

• Source mode: Auto
• Repository: LeanerCloud/cloud-commitments-platform
• Branch: main
• File: .coderabbit.yaml
• Commit: 503eb2e
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: fe0dfe80-7f52-4b6c-9216-b5f2f8e69424

Commits

Reviewing files that changed from the base of the PR and between 503eb2e and c9e38d9.

Files selected for processing: 4

• internal/api/handler_dashboard.go
• internal/api/handler_dashboard_test.go
• internal/api/openapi.yaml
• internal/api/types.go

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[IAmJSD]

Independent review (IAmJSD's agent, fresh context, given only the diff, the issue and the PR text): VERDICT: APPROVE c9e38d9ee7585364fe127ca25038bdfb331194eb

Blocking:

• none

Non-blocking:

• internal/api/handler_dashboard.go:84: 0/0 coverage now serializes as null. The only consumer I found, frontend/src/dashboard.ts:345, already maps null to NO_VALUE via ?? null, so nothing breaks. frontend/src/api/types.ts:94 still declares current_coverage: number, though, so the follow-up type change the body lists is worth doing to keep TS honest. Neither the CLI nor the MCP repo reads current_coverage.
• A store outage now blanks the whole KPI row, recommendation tiles included. This matches the existing contract for a ListRecommendations error, and the body raises the per-section degraded flag as a product follow-up. I agree it isn't needed for api: fetchCommitmentPurchases swallows store errors into zeroed dashboard KPIs #72.

Attacked:

• Error contract: fetchCommitmentPurchases still short-circuits the explicit zero-account scope sentinel (issue sec(auth): an admin-scoped API key ignores its account and amount constraints on non-strict checks #956) to genuine zeros without querying, so a scoped user can't trigger an all-accounts read. A store error now reaches getDashboardSummary as a wrapped error, and handleRequestError turns it into a generic 500. The router-level test asserts the store text doesn't leak. Both helpers have no other callers.
• Coverage: worked through all four cases. potential=0 with committed>0 still gives 100 (from the ratio), potential>0 with committed=0 gives 0, both >0 is unchanged, and 0/0 gives nil instead of a fabricated 100. This addresses cristim's compounding "100% coverage, $0 committed" comment. The OpenAPI field is marked nullable: true.
• Fail-before: I reverse-applied the PR's handler_dashboard.go and types.go changes and put main's test file back. Then I added only the two new top-level tests. TestHandleRequest_DashboardSummary_PurchaseHistoryErrorIs500 failed (expected 500, got 200, with the "current_coverage":100 ... "active_commitments":0 body), and so did TestGetDashboardSummary_NothingToMeasure_CoverageIsNull (expected nil, got 100). I restored the files afterwards.
• Ran: go build ./...; go vet ./internal/api/ with and without -tags integration; go test -race -short -count=1 ./internal/api/ (ok); go test -race -tags integration -run Dashboard ./internal/api/ (ok); golangci-lint v2.10.1 with and without --build-tags integration (0 issues); gocyclo -over 10 internal/api/handler_dashboard.go (no output).

Body-stale:

• The merge note calls fix/issue-312 a "not-yet-opened branch". It is open now as fix(api): 404 for missing users/groups/API keys, 400 for bad read filters (#312) #1267. The conflict resolution the note describes still applies.

_{Reviewer: rB6. Bar while the maintainers are away (set by IAmJSD as acting owner): one approving independent review on the head, two for money, auth and security paths.}

[IAmJSD]

Local verification at c9e38d9ee7585364fe127ca25038bdfb331194eb merged onto main (5aa3df5b), together with #1155, #1219, #1221, #1223, #1224, #1225, #1226, #1227, #1256, #1262, #1266, #1270, #1272, #1275, #1283, #1286, #1293, #1297, #1299, #1300, #1301, #1304, #1307, #1311, #1313, #1325 in that order (combined tree f3a3331f, Linux, Go 1.26.10): go build ./..., go vet with and without -tags integration, the full go test -race -short -count=1 ./..., and go test -race -tags integration -count=1 on every changed package, against Docker Postgres. All pass. CI Success and pre-commit are green on this head, with 1 approving independent review(s) on it. Nothing was run against any cloud.

[IAmJSD]

Merged by IAmJSD's agent at IAmJSD's request (IAmJSD is acting owner while the maintainers are away), under the bar IAmJSD set: 1 approving independent review(s) on c9e38d9e, green CI, and the combined-tree verification above. Squash-merged at exactly c9e38d9ee7585364fe127ca25038bdfb331194eb.