quyun-v2/docs/backend_sort_alignment_plan.md

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.