Skip to content

feat(admin): add balance management page #487

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
s-Joshua-s wants to merge 8 commits into
base: main
Choose a base branch
from
Open

feat(admin): add balance management page #487

s-Joshua-s wants to merge 8 commits into from
+1,043 −5

Conversation

@s-Joshua-s
Copy link

@s-Joshua-s s-Joshua-s commented Feb 5, 2026

Summary

  • Add a dedicated admin "Balance Management" page for standard-type (balance mode) groups
  • Aggregate per-user usage stats (cost, requests, tokens) with server-side search, sort, and pagination
  • Integrate model distribution chart, balance deposit, and balance history modals inline
  • Full i18n support (zh/en), sidebar navigation, and route registration

Changes

Backend (10 files)

  • Types: BalanceGroupUserStats, BalanceGroupUserStatsResponse, BalanceGroupUserStatsParams
  • Database: Composite index (group_id, created_at) on usage_logs
  • Repository: GetBalanceGroupUserStats with CTE aggregation, JOIN users, ILIKE search (with metacharacter escaping), parameterized queries, whitelist-based sort
  • Service: Input validation (90-day max range, page bounds, sort whitelist)
  • Handler: GET /admin/balance/stats with validation/internal error distinction
  • DI/Routes: Wire integration + admin route group

Frontend (7 files)

  • API module: TypeScript interfaces + getBalanceGroupUserStats with AbortSignal support
  • BalanceView.vue: Full-featured page with group selector (standard only), DateRangePicker, debounced search, server-side DataTable, pagination, model distribution dialog, balance modals
  • i18n: admin.balance namespace in zh.ts and en.ts
  • Navigation: WalletIcon + sidebar nav item (hidden in simple mode)
  • Router: /admin/balance route with admin auth guard

Security

  • SQL injection prevention: parameterized queries + sort column whitelist
  • ILIKE wildcard escaping (%, _, \)
  • Internal errors logged server-side, generic message returned to client
  • Admin-only access (middleware + route guard)

Test plan

  • Verify page loads with standard-type groups in the group selector
  • Verify date range filtering updates usage data correctly
  • Verify search filters by email/username
  • Verify server-side sort on all sortable columns
  • Verify pagination works correctly
  • Verify model distribution dialog shows per-user model stats
  • Verify deposit modal and balance history modal function correctly
  • Verify non-admin users cannot access the page
  • Verify i18n switching between zh and en
  • Verify page hidden in simple mode

🤖 Generated with Claude Code

JIA-ss and others added 8 commits February 5, 2026 14:26
@JIA-ss @claude
task(T2.1,T2.2): implement balance group user stats repo and service
2f1e357 
Add GetBalanceGroupUserStats to repository with CTE aggregation query,
JOIN with users table, ILIKE search with metacharacter escaping, and
whitelisted sort columns. Add service method with parameter validation
including 90-day max range and sort column whitelist.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JIA-ss @claude
task(T2.3): add balance handler, DI wiring, and admin routes
14e28a1 
Create BalanceHandler with GetStats endpoint parsing query params.
Register in wire ProviderSet, AdminHandlers struct, and wire_gen.go.
Add GET /admin/balance/stats route.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JIA-ss @claude
task(T2.4): add frontend balance API module
8becaf3 
Create balance.ts with TypeScript interfaces and getBalanceGroupUserStats
API function. Register in admin API barrel export.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JIA-ss @claude
task(T3.1-T3.4): add BalanceView admin page
2e3c491 
Implement full-featured balance management page with group selector
(standard type only), date range picker (90-day max), debounced search,
server-side sort/pagination DataTable, model distribution dialog,
balance deposit modal, and balance history modal. Includes empty states
and cost/token formatting helpers.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JIA-ss @claude
task(T4.1,T4.2): add i18n translations, sidebar nav, and route
12a66e1 
Add admin.balance namespace translations for zh and en locales.
Add WalletIcon and balance nav item to admin sidebar (hidden in
simple mode). Register /admin/balance route with lazy loading.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JIA-ss @claude
fix(balance): address code review findings
39943cb 
- Handler: distinguish validation errors (400) from internal errors (500),
  log internal errors server-side instead of exposing to client
- Repo: add nil pointer guard for StartDate/EndDate parameters
- Frontend: add AbortController for request cancellation to prevent race
  conditions, clean up debounce timer on unmount, remove unused watch import

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JIA-ss @claude
task(T1.1,T1.2): add balance group user stats types and database index
c86bcec 
Add BalanceGroupUserStats, BalanceGroupUserStatsResponse, and
BalanceGroupUserStatsParams type definitions. Add composite index
on (group_id, created_at) for usage_log to optimize balance queries.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@JIA-ss @claude
fix: resolve CI failures for balance management feature
576b678 
- Fix gofmt formatting issue in usage_log_repo.go (map alignment)
- Add missing GetBalanceGroupUserStats method to stubUsageLogRepo in tests

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@Wei-Shaw
Copy link
Owner

Wei-Shaw commented Feb 5, 2026

image 这个icon看起来很奇怪。其次是这个页面功能跟usage_logs有点重叠的感觉

@JIA-ss
Copy link
Contributor

JIA-ss commented Feb 5, 2026

image 这个icon看起来很奇怪。其次是这个页面功能跟usage_logs有点重叠的感觉

要不麻烦大佬直接上手改一波，这块我不太专业

@JIA-ss
Copy link
Contributor

JIA-ss commented Feb 5, 2026

image 这个icon看起来很奇怪。其次是这个页面功能跟usage_logs有点重叠的感觉

主要想的是，希望 余额分组 可以单独筛选 查看各个余额分组的用户使用情况

@Wei-Shaw
Copy link
Owner

Wei-Shaw commented Feb 5, 2026

感觉多开一个页面有点多余

@JIA-ss
Copy link
Contributor

JIA-ss commented Feb 5, 2026

感觉多开一个页面有点多余

因为我们的分组 区分为 余额类型 和 订阅类型，这两个功能是并列的。
订阅管理有单独的sider，所以我直接给 余额类型也加了一个侧标签。

而且从用户使用习惯来讲，我在侧标签看到了订阅管理，也会第一时间想着从对应的位置找到余额分组管理。

直接放到账户管理再加个筛选也行，但是感觉不够直观，容易找不到入口

@JIA-ss
Copy link
Contributor

JIA-ss commented Feb 5, 2026

感觉多开一个页面有点多余

怎么说大佬，要咋改

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@s-Joshua-s @Wei-Shaw @JIA-ss