# Dashboard Optional Total

## Background and goal

The dashboard cluster-list routes currently execute an exact `COUNT(*)` before every list page. Callers that only need to traverse rows pay that cost even though they do not read `total`. The goal is to make the lower-cost no-total path the default while preserving an explicit exact-total option.

## Current behavior

- `/dashboard/clusters` always returns `total` and list rows.
- `/dashboard/clusters2` also always runs an exact count before fetching the page.
- Internal metadata code calls the existing datasource wrapper and expects its current result shape.

## Target contract

- Both `/dashboard/clusters` and `/dashboard/clusters2` accept optional `include_total`, defaulting to `false`.
- With `include_total=false`, the ordinary path performs no COUNT, fetches `limit + 1` rows once, returns at most `limit` items, omits `total`, and reports `has_more`. A numeric query may first run a per-branch `LIMIT 1` existence probe to preserve exact-match precedence, but it still performs no COUNT.
- With `include_total=true`, the response includes the exact `total`; callers that require it must opt in explicitly.
- Numeric exact search keeps exact-ID precedence without using COUNT on the no-total path.
- Both routes use the same optional-total response contract; `/dashboard/clusters2` keeps its additional filters.
- The existing `ListOrganizationAndCluster` wrapper remains compatible for internal callers.

## Affected modules and route

- Go module: repository root, `github.com/pingcap-inc/clinic`.
- Packages: `pkg/api/cloud`, `pkg/datasource`.
- Entrypoint and routes: `cmd/server/main.go`, `GET /clinic/api/v1/dashboard/clusters` and `GET /clinic/api/v1/dashboard/clusters2`.
- Generated default-server Swagger documents.

Deployment chain: root module -> `cmd/server` -> `clinic` image -> Clinic CD `components=clinic` -> app-delivery `clinic-api` -> Clinic Deployment. No app-delivery configuration change is required. The Internal API, Task Manager, Clinic Data Service, Cloud Server, NGM, and Kong images do not require deployment for this route change.

## Implementation steps

1. Add the optional response fields and handler parameter.
2. Add a datasource result type and keep the compatibility wrapper.
3. Implement the one-query `limit + 1` list path and bounded numeric existence probe.
4. Add handler-contract and datasource regression tests.
5. Regenerate and verify Swagger output.

## Exclusions and compatibility

- Do not change `/dashboard/clusters2` filters or time-predicate semantics.
- Do not change search fields, search semantics, sorting, filters, or pagination limits.
- Do not migrate unknown external callers in this PR.
- Callers that depend on `total` must explicitly send `include_total=true`; omitting the parameter now selects the no-total response.

## Test plan

- `go test ./pkg/api/cloud ./pkg/datasource ./pkg/api/internal_api`
- `go vet ./pkg/api/cloud ./pkg/datasource ./pkg/api/internal_api`
- `make check-swagger`

## Staging and release boundary

Per the agreed scope, the later `/dashboard/clusters2` adoption is covered by focused local tests and CI and is not deployed to staging. The earlier `/dashboard/clusters` and Clinic UI behavior was already validated in staging. Do not merge until required checks and review pass and the user explicitly authorizes merge. Production release requires separate explicit authorization.