feat(profile): 余额记录可点击查看，用户可在个人资料页查看自己的余额变更历史

DouDOU-start · DouDOU-start · commit c324cf88fab1 · 2026-05-08T08:36:37.000+08:00
新增用户端 GET /api/v1/users/me/balance-history 接口，个人资料页余额行
点击后弹出分页表格展示操作类型、金额、变更前后余额、备注和时间。
diff --git a/backend/internal/server/handler/user_handler_routes.go b/backend/internal/server/handler/user_handler_routes.go
@@ -119,6 +119,34 @@ func (h *UserHandler) ChangePassword(c *gin.Context) {
 	response.Success(c, nil)
 }
 
+// GetMyBalanceHistory 查询当前用户余额变更记录。
+func (h *UserHandler) GetMyBalanceHistory(c *gin.Context) {
+	userID, ok := currentUserID(c)
+	if !ok {
+		response.Unauthorized(c, "用户未认证")
+		return
+	}
+
+	var page dto.PageReq
+	if err := c.ShouldBindQuery(&page); err != nil {
+		response.BindError(c, err)
+		return
+	}
+
+	result, err := h.service.ListBalanceLogs(c.Request.Context(), userID, page.Page, page.PageSize)
+	if err != nil {
+		httpCode, message := h.handleError("查询余额日志失败", "查询失败", err)
+		response.Error(c, httpCode, httpCode, message)
+		return
+	}
+
+	list := make([]dto.BalanceLogResp, 0, len(result.List))
+	for _, item := range result.List {
+		list = append(list, toBalanceLogResp(item))
+	}
+	response.Success(c, response.PagedData(list, result.Total, result.Page, result.PageSize))
+}
+
 // ListUsers 管理员查询用户列表。
 func (h *UserHandler) ListUsers(c *gin.Context) {
 	var page dto.PageReq
diff --git a/backend/internal/server/router.go b/backend/internal/server/router.go
@@ -68,6 +68,7 @@ func (s *Server) registerRoutes() {
 		userGroup.PUT("/users/me", handlers.User.UpdateProfile)
 		userGroup.POST("/users/me/password", handlers.User.ChangePassword)
 		userGroup.PUT("/users/me/balance-alert", handlers.User.UpdateBalanceAlert)
+		userGroup.GET("/users/me/balance-history", handlers.User.GetMyBalanceHistory)
 
 		// API Key 管理
 		userGroup.GET("/api-keys", handlers.APIKey.ListKeys)
diff --git a/web/src/i18n/en.json b/web/src/i18n/en.json
@@ -919,7 +919,8 @@
     "balance_alert_desc": "Send email notification when balance drops below threshold",
     "balance_alert_threshold": "Alert Threshold (USD)",
     "balance_alert_hint": "Current balance: ${{balance}}",
-    "balance_alert_saved": "Balance alert settings saved"
+    "balance_alert_saved": "Balance alert settings saved",
+    "balance_history": "Balance History"
   },
 
   "user_keys": {
diff --git a/web/src/i18n/zh.json b/web/src/i18n/zh.json
@@ -922,7 +922,8 @@
     "balance_alert_desc": "当余额低于设定阈值时，发送邮件通知",
     "balance_alert_threshold": "预警阈值（美元）",
     "balance_alert_hint": "当前余额：${{balance}}",
-    "balance_alert_saved": "余额预警设置已保存"
+    "balance_alert_saved": "余额预警设置已保存",
+    "balance_history": "余额记录"
   },
 
   "user_keys": {
diff --git a/web/src/pages/user/ProfilePage.tsx b/web/src/pages/user/ProfilePage.tsx
@@ -1,12 +1,15 @@
 import { useState, type FormEvent } from 'react';
 import { useTranslation } from 'react-i18next';
-import { Button, Card, Chip, Description, Form, Input, Label, Switch, TextField as HeroTextField } from '@heroui/react';
+import { Button, Card, Chip, Description, EmptyState, Form, Input, Label, Modal, Skeleton, Switch, Table as HeroTable, TextField as HeroTextField, useOverlayState } from '@heroui/react';
 import { useAuth } from '../../app/providers/AuthProvider';
 import { usersApi } from '../../shared/api/users';
 import { useToast } from '../../shared/ui';
 import { useCrudMutation } from '../../shared/hooks/useCrudMutation';
 import { queryKeys } from '../../shared/queryKeys';
-import { useMutation } from '@tanstack/react-query';
+import { useMutation, useQuery } from '@tanstack/react-query';
+import { getTotalPages } from '../../shared/utils/pagination';
+import { TablePaginationFooter } from '../../shared/components/TablePaginationFooter';
+import type { BalanceLogResp } from '../../shared/types';
 import {
   User,
   Mail,
@@ -17,6 +20,7 @@ import {
   Lock,
   KeyRound,
   Bell,
+  ChevronRight,
 } from 'lucide-react';
 
 export default function ProfilePage() {
@@ -75,6 +79,8 @@ export default function ProfilePage() {
     });
   }
 
+  const [balanceHistoryOpen, setBalanceHistoryOpen] = useState(false);
+
   if (!user) return null;
 
   return (
@@ -102,15 +108,20 @@ export default function ProfilePage() {
                 {user.role === 'admin' ? t('nav.admin') : t('nav.user')}
               </Chip>
             </div>
-            <div className="flex items-center gap-4">
+            <button
+              type="button"
+              className="flex items-center gap-4 w-full rounded-md px-1 -mx-1 py-1 transition-colors hover:bg-surface-hover cursor-pointer text-left"
+              onClick={() => setBalanceHistoryOpen(true)}
+            >
               <div className="flex items-center gap-2 w-28 shrink-0">
                 <Wallet className="w-4 h-4 text-text-tertiary" />
                 <span className="text-xs font-medium text-text-secondary">{t('profile.balance')}</span>
               </div>
               <span className="text-sm text-text font-mono">
                 ${user.balance.toFixed(4)}
               </span>
-            </div>
+              <ChevronRight className="w-4 h-4 text-text-tertiary ml-auto" />
+            </button>
             <div className="flex items-center gap-4">
               <div className="flex items-center gap-2 w-28 shrink-0">
                 <Layers className="w-4 h-4 text-text-tertiary" />
@@ -164,6 +175,13 @@ export default function ProfilePage() {
         </Card.Content>
       </Card>
 
+      {/* 余额记录 */}
+      <MyBalanceHistoryModal
+        open={balanceHistoryOpen}
+        balance={user.balance}
+        onClose={() => setBalanceHistoryOpen(false)}
+      />
+
       {/* 修改密码 */}
       <Card className="mb-6">
         <Card.Header>
@@ -241,6 +259,150 @@ export default function ProfilePage() {
   );
 }
 
+/* ==================== 余额记录弹窗 ==================== */
+
+function MyBalanceHistoryModal({ open, balance, onClose }: { open: boolean; balance: number; onClose: () => void }) {
+  const { t } = useTranslation();
+  const [page, setPage] = useState(1);
+
+  const { data, isLoading } = useQuery({
+    queryKey: ['my-balance-history', page],
+    queryFn: () => usersApi.myBalanceHistory({ page, page_size: 10 }),
+    enabled: open,
+  });
+
+  const actionLabel = (action: string) => {
+    switch (action) {
+      case 'add': return t('users.action_add');
+      case 'subtract': return t('users.action_subtract');
+      case 'set': return t('users.action_set');
+      default: return action;
+    }
+  };
+
+  const actionColor = (action: string): 'success' | 'warning' | 'accent' => {
+    switch (action) {
+      case 'add': return 'success';
+      case 'subtract': return 'warning';
+      default: return 'accent';
+    }
+  };
+
+  const rows = data?.list ?? [];
+  const total = data?.total ?? 0;
+  const totalPages = getTotalPages(total, 10);
+  const modalState = useOverlayState({
+    isOpen: open,
+    onOpenChange: (nextOpen) => {
+      if (!nextOpen) onClose();
+    },
+  });
+
+  return (
+    <Modal state={modalState}>
+      <Modal.Backdrop>
+        <Modal.Container placement="center" scroll="inside" size="md">
+          <Modal.Dialog
+            className="ag-elevation-modal"
+            style={{ maxWidth: '750px', width: 'min(100%, calc(100vw - 2rem))' }}
+          >
+            <Modal.Header>
+              <Modal.Heading>{t('profile.balance_history')}</Modal.Heading>
+              <Modal.CloseTrigger />
+            </Modal.Header>
+            <Modal.Body>
+              <div className="mb-4 rounded-md border border-glass-border bg-surface px-4 py-3">
+                <p className="text-xs text-text-tertiary">{t('users.current_balance')}</p>
+                <p className="mt-1 font-mono text-lg font-bold">${balance.toFixed(2)}</p>
+              </div>
+
+              <HeroTable variant="primary">
+                <HeroTable.ScrollContainer>
+                  <HeroTable.Content aria-label={t('profile.balance_history')}>
+                    <HeroTable.Header>
+                      <HeroTable.Column id="action" isRowHeader style={{ width: 96 }}>
+                        {t('users.action_type')}
+                      </HeroTable.Column>
+                      <HeroTable.Column id="amount">{t('users.amount')}</HeroTable.Column>
+                      <HeroTable.Column id="balance_change">
+                        {t('users.before_balance')} → {t('users.after_balance')}
+                      </HeroTable.Column>
+                      <HeroTable.Column id="remark">{t('users.remark')}</HeroTable.Column>
+                      <HeroTable.Column id="created_at">{t('users.created_at')}</HeroTable.Column>
+                    </HeroTable.Header>
+                    <HeroTable.Body>
+                      {isLoading ? (
+                        Array.from({ length: 5 }).map((_, index) => (
+                          <HeroTable.Row id={`loading-${index}`} key={`loading-${index}`}>
+                            {Array.from({ length: 5 }).map((__, cellIndex) => (
+                              <HeroTable.Cell key={cellIndex}>
+                                <Skeleton className="h-4 w-24" />
+                              </HeroTable.Cell>
+                            ))}
+                          </HeroTable.Row>
+                        ))
+                      ) : rows.length === 0 ? (
+                        <HeroTable.Row id="empty">
+                          <HeroTable.Cell colSpan={5}>
+                            <EmptyState>
+                              <div className="text-sm text-default-500">{t('common.no_data')}</div>
+                            </EmptyState>
+                          </HeroTable.Cell>
+                        </HeroTable.Row>
+                      ) : (
+                        rows.map((row: BalanceLogResp) => (
+                          <HeroTable.Row id={String(row.id)} key={row.id}>
+                            <HeroTable.Cell>
+                              <Chip color={actionColor(row.action)} size="sm" variant="soft">
+                                {actionLabel(row.action)}
+                              </Chip>
+                            </HeroTable.Cell>
+                            <HeroTable.Cell>
+                              <span className={`font-mono text-xs font-semibold ${row.action === 'add' ? 'text-success' : row.action === 'subtract' ? 'text-danger' : 'text-info'}`}>
+                                {row.action === 'add' ? '+' : row.action === 'subtract' ? '-' : '='}{row.amount.toFixed(2)}
+                              </span>
+                            </HeroTable.Cell>
+                            <HeroTable.Cell>
+                              <span className="font-mono text-xs text-text-secondary">
+                                ${row.before_balance.toFixed(2)} → ${row.after_balance.toFixed(2)}
+                              </span>
+                            </HeroTable.Cell>
+                            <HeroTable.Cell>
+                              <span className="text-xs text-text-tertiary">{row.remark || '-'}</span>
+                            </HeroTable.Cell>
+                            <HeroTable.Cell>
+                              <span className="text-xs text-text-secondary">
+                                {new Date(row.created_at).toLocaleString('zh-CN', {
+                                  day: '2-digit',
+                                  hour: '2-digit',
+                                  minute: '2-digit',
+                                  month: '2-digit',
+                                })}
+                              </span>
+                            </HeroTable.Cell>
+                          </HeroTable.Row>
+                        ))
+                      )}
+                    </HeroTable.Body>
+                  </HeroTable.Content>
+                </HeroTable.ScrollContainer>
+                <HeroTable.Footer>
+                  <TablePaginationFooter
+                    page={page}
+                    setPage={setPage}
+                    total={total}
+                    totalPages={totalPages}
+                  />
+                </HeroTable.Footer>
+              </HeroTable>
+            </Modal.Body>
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </Modal>
+  );
+}
+
 /* ==================== 余额预警卡片 ==================== */
 
 function BalanceAlertCard({ threshold, balance }: { threshold: number; balance: number }) {
diff --git a/web/src/shared/api/users.ts b/web/src/shared/api/users.ts
@@ -14,6 +14,8 @@ export const usersApi = {
   updateProfile: (data: UpdateProfileReq) => put<void>('/api/v1/users/me', data),
   changePassword: (data: ChangePasswordReq) => post<void>('/api/v1/users/me/password', data),
   updateBalanceAlert: (threshold: number) => put<void>('/api/v1/users/me/balance-alert', { threshold }),
+  myBalanceHistory: (params: PageReq) =>
+    get<PagedData<BalanceLogResp>>('/api/v1/users/me/balance-history', params),
 
   // 管理员接口
   list: (params: PageReq & { status?: string; role?: string }) =>
