# Backend Sort Alignment Plan (Superadmin)

## Goal
Align backend sort support with the superadmin UI for the following lists:
- Tenants list: `user_count`, `income_amount_paid_sum`
- Balance anomalies: `user_id`, `created_at`
- Order anomalies: `order_id`

## Scope
- Backend services only (no UI changes).
- Sorting behavior and documentation updates.
- Add service-level tests to cover the new sort fields.

## Non-Goals
- Changing pagination logic or query filters.
- Adding new UI sorting fields.
- Changing business semantics of existing aggregates.

## Proposed Approach
### 1) Tenants list sorting (已完成)
Backend: `services.Super.ListTenants`

Add two aggregate subqueries and join them for ordering:
- `user_count`
  - `tenant_users` aggregate: `SELECT tenant_id, COUNT(*) AS user_count FROM tenant_users GROUP BY tenant_id`
- `income_amount_paid_sum`
  - `orders` aggregate: `SELECT tenant_id, COALESCE(SUM(amount_paid), 0) AS income_amount_paid_sum FROM orders WHERE status IN (paid, refunding, refunded) GROUP BY tenant_id`

Ordering behavior:
- Extend the sort switch to accept `user_count` and `income_amount_paid_sum`.
- Map sort to the joined aggregate columns (use `COALESCE` to avoid null ordering issues).

Count safety:
- Keep `Count()` on the base tenant query or use `COUNT(DISTINCT tenants.id)` after joins to avoid inflation.
- Apply joins only for the query that fetches paged data when possible.

### 2) Balance anomalies sorting (已完成)
Backend: `services.Super.ListBalanceAnomalies`

Extend sort switch:
- `user_id` -> `tbl.ID`
- `created_at` -> `tbl.CreatedAt`

### 3) Order anomalies sorting (已完成)
Backend: `services.Super.ListOrderAnomalies`

Extend sort switch:
- `order_id` -> `tbl.ID`

### 4) Documentation updates (DTO comments) (已完成)
Update sort field documentation to reflect new options:
- `TenantListFilter` (add `user_count`, `income_amount_paid_sum`)
- `SuperBalanceAnomalyFilter` (add `user_id`, `created_at`)
- `SuperOrderAnomalyFilter` (add `order_id`)

## Tests (已完成)
Add service-level tests (in `backend/app/services/super_test.go` or a new test file):
- Tenants list sorting:
  - Create tenants with different member counts and income sums.
  - Verify `asc`/`desc` on `user_count` and `income_amount_paid_sum`.
- Balance anomalies sorting:
  - Create users with negative balances and controlled `created_at`.
  - Verify `asc`/`desc` on `created_at` and `user_id`.
- Order anomalies sorting:
  - Create anomaly orders with distinct IDs.
  - Verify ordering by `order_id`.

Run:
- `go test ./...`

## Files to Change
- `backend/app/services/super.go`
- `backend/app/http/super/v1/dto/super.go`
- `backend/app/http/super/v1/dto/super_finance.go`
- `backend/app/services/super_test.go` (or new test file)

## Risks / Notes
- Join-based sorting can impact performance on large tables; consider indexes on `tenant_users.tenant_id` and `orders.tenant_id`.
- Ensure aggregate semantics match current `buildTenantItems` logic to keep UI numbers consistent.