feat(usage): 在 /admin/usage 支持查看已删除用户的历史使用情况

用户软删除后使用记录仍在,但身份(邮箱)被 ent 软删除拦截器隐藏。本次在
三条管理员只读路径定点穿透软删除过滤,并把删除状态传播到前端标记,零新表/
迁移/回填:

- 后端穿透:富化 usage 日志(loadUsers)、用户搜索(ListWithFilters +
  UserListFilters.IncludeDeleted)、点击详情(GetByIDIncludeDeleted /
  GetUserIncludeDeleted + getById ?include_deleted 分支)
- 状态传播:service.User / dto.User 新增 DeletedAt;SearchUsers 标记 deleted
- 前端:表格与余额弹窗展示"已删除"徽标、筛选下拉标注并排序、点击走
  include_deleted;新增 i18n admin.usage.userDeletedBadge
- 安全:普通用户 usage 仅查本人(无 PII 泄漏);主用户列表与默认 getById
  行为不变(已删用户仍 404);仅 admin 搜索设 IncludeDeleted

后端 build / 三态 vet / unit 全量 / 仓储集成全绿;前端 typecheck / vitest /
改动文件 eslint 全清。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/internal/handler/admin/admin_service_stub_test.go

@@ -160,6 +160,10 @@ func (s *stubAdminService) GetUser(ctx context.Context, id int64) (*service.User
 	return &user, nil
 }
 
+func (s *stubAdminService) GetUserIncludeDeleted(ctx context.Context, id int64) (*service.User, error) {
+	return s.GetUser(ctx, id)
+}
+
 func (s *stubAdminService) CreateUser(ctx context.Context, input *service.CreateUserInput) (*service.User, error) {
 	user := service.User{ID: 100, Email: input.Email, Status: service.StatusActive}
 	return &user, nil

backend/internal/handler/admin/usage_handler.go

@@ -344,23 +344,25 @@ func (h *UsageHandler) SearchUsers(c *gin.Context) {
 	}
 
 	// Limit to 30 results
-	users, _, err := h.adminService.ListUsers(c.Request.Context(), 1, 30, service.UserListFilters{Search: keyword}, "email", "asc")
+	users, _, err := h.adminService.ListUsers(c.Request.Context(), 1, 30, service.UserListFilters{Search: keyword, IncludeDeleted: true}, "email", "asc")
 	if err != nil {
 		response.ErrorFrom(c, err)
 		return
 	}
 
-	// Return simplified user list (only id and email)
+	// Return simplified user list (only id, email and deleted flag)
 	type SimpleUser struct {
-		ID    int64  `json:"id"`
-		Email string `json:"email"`
+		ID      int64  `json:"id"`
+		Email   string `json:"email"`
+		Deleted bool   `json:"deleted"`
 	}
 
 	result := make([]SimpleUser, len(users))
 	for i, u := range users {
 		result[i] = SimpleUser{
-			ID:    u.ID,
-			Email: u.Email,
+			ID:      u.ID,
+			Email:   u.Email,
+			Deleted: u.DeletedAt != nil,
 		}
 	}
 

backend/internal/handler/admin/usage_handler_search_users_test.go

@@ -0,0 +1,56 @@
+package admin
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+// 捕获 ListUsers 入参、返回一个已删用户的 admin service 桩。
+type searchUsersAdminStub struct {
+	service.AdminService
+	gotFilters service.UserListFilters
+}
+
+func (s *searchUsersAdminStub) ListUsers(ctx context.Context, page, pageSize int, filters service.UserListFilters, sortBy, sortOrder string) ([]service.User, int64, error) {
+	s.gotFilters = filters
+	ts := time.Date(2026, 5, 28, 0, 0, 0, 0, time.UTC)
+	return []service.User{
+		{ID: 1, Email: "active@test.com"},
+		{ID: 2, Email: "deleted@test.com", DeletedAt: &ts},
+	}, 2, nil
+}
+
+func TestAdminUsageSearchUsers_IncludesDeletedAndFlags(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	stub := &searchUsersAdminStub{}
+	handler := NewUsageHandler(nil, nil, stub, nil)
+	router := gin.New()
+	router.GET("/admin/usage/search-users", handler.SearchUsers)
+
+	req := httptest.NewRequest(http.MethodGet, "/admin/usage/search-users?q=test", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	require.True(t, stub.gotFilters.IncludeDeleted, "SearchUsers 必须请求 IncludeDeleted")
+
+	var resp struct {
+		Data []struct {
+			ID      int64  `json:"id"`
+			Email   string `json:"email"`
+			Deleted bool   `json:"deleted"`
+		} `json:"data"`
+	}
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Len(t, resp.Data, 2)
+	require.False(t, resp.Data[0].Deleted)
+	require.True(t, resp.Data[1].Deleted, "已删用户必须标记 deleted=true")
+}

backend/internal/handler/admin/user_handler.go

@@ -195,7 +195,12 @@ func (h *UserHandler) GetByID(c *gin.Context) {
 		return
 	}
 
-	user, err := h.adminService.GetUser(c.Request.Context(), userID)
+	var user *service.User
+	if c.Query("include_deleted") == "true" {
+		user, err = h.adminService.GetUserIncludeDeleted(c.Request.Context(), userID)
+	} else {
+		user, err = h.adminService.GetUser(c.Request.Context(), userID)
+	}
 	if err != nil {
 		response.ErrorFrom(c, err)
 		return

backend/internal/handler/admin/user_handler_get_deleted_test.go

@@ -0,0 +1,51 @@
+package admin
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+type getByIDAdminStub struct {
+	service.AdminService
+}
+
+func (s *getByIDAdminStub) GetUser(_ context.Context, _ int64) (*service.User, error) {
+	return nil, service.ErrUserNotFound
+}
+
+func (s *getByIDAdminStub) GetUserIncludeDeleted(_ context.Context, id int64) (*service.User, error) {
+	return &service.User{ID: id, Email: "del@test.com"}, nil
+}
+
+func setupGetByIDRouter(svc service.AdminService) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	h := NewUserHandler(svc, nil, nil, nil)
+	r.GET("/admin/users/:id", h.GetByID)
+	return r
+}
+
+func TestAdminUserGetByID_IncludeDeleted(t *testing.T) {
+	svc := &getByIDAdminStub{AdminService: newStubAdminService()}
+	router := setupGetByIDRouter(svc)
+
+	t.Run("normal path returns 404 for deleted user", func(t *testing.T) {
+		w := httptest.NewRecorder()
+		req, _ := http.NewRequest(http.MethodGet, "/admin/users/7", nil)
+		router.ServeHTTP(w, req)
+		require.Equal(t, http.StatusNotFound, w.Code)
+	})
+
+	t.Run("include_deleted=true returns 200", func(t *testing.T) {
+		w := httptest.NewRecorder()
+		req, _ := http.NewRequest(http.MethodGet, "/admin/users/7?include_deleted=true", nil)
+		router.ServeHTTP(w, req)
+		require.Equal(t, http.StatusOK, w.Code)
+	})
+}

backend/internal/handler/auth_oauth_pending_flow_test.go

@@ -2914,6 +2914,10 @@ func (r *oauthPendingFlowUserRepo) DisableTotp(ctx context.Context, userID int64
 		Exec(ctx)
 }
 
+func (r *oauthPendingFlowUserRepo) GetByIDIncludeDeleted(ctx context.Context, id int64) (*service.User, error) {
+	return r.GetByID(ctx, id)
+}
+
 func oauthPendingFlowServiceUser(entity *dbent.User) *service.User {
 	if entity == nil {
 		return nil

backend/internal/handler/dto/mappers.go

@@ -30,6 +30,7 @@ func UserFromServiceShallow(u *service.User) *User {
 		BalanceNotifyExtraEmails:   NotifyEmailEntriesFromService(u.BalanceNotifyExtraEmails),
 		TotalRecharged:             u.TotalRecharged,
 		RPMLimit:                   u.RPMLimit,
+		DeletedAt:                  u.DeletedAt,
 	}
 }
 

backend/internal/handler/dto/mappers_deleted_user_test.go

@@ -0,0 +1,20 @@
+package dto
+
+import (
+	"testing"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/stretchr/testify/require"
+)
+
+func TestUserFromServiceShallow_MapsDeletedAt(t *testing.T) {
+	ts := time.Date(2026, 5, 28, 10, 0, 0, 0, time.UTC)
+
+	deleted := UserFromServiceShallow(&service.User{ID: 1, Email: "d@test.com", DeletedAt: &ts})
+	require.NotNil(t, deleted.DeletedAt)
+	require.Equal(t, ts, *deleted.DeletedAt)
+
+	active := UserFromServiceShallow(&service.User{ID: 2, Email: "a@test.com"})
+	require.Nil(t, active.DeletedAt, "active user must have nil DeletedAt")
+}

backend/internal/handler/dto/types.go

@@ -20,6 +20,7 @@ type User struct {
 	LastActiveAt  *time.Time `json:"last_active_at,omitempty"`
 	CreatedAt     time.Time  `json:"created_at"`
 	UpdatedAt     time.Time  `json:"updated_at"`
+	DeletedAt     *time.Time `json:"deleted_at,omitempty"`
 
 	// 余额不足通知
 	BalanceNotifyEnabled       bool               `json:"balance_notify_enabled"`

backend/internal/handler/user_handler_test.go

@@ -118,6 +118,9 @@ func (s *userHandlerRepoStub) RemoveGroupFromUserAllowedGroups(context.Context,
 func (s *userHandlerRepoStub) UpdateTotpSecret(context.Context, int64, *string) error { return nil }
 func (s *userHandlerRepoStub) EnableTotp(context.Context, int64) error                { return nil }
 func (s *userHandlerRepoStub) DisableTotp(context.Context, int64) error               { return nil }
+func (s *userHandlerRepoStub) GetByIDIncludeDeleted(ctx context.Context, id int64) (*service.User, error) {
+	return s.GetByID(ctx, id)
+}
 func (s *userHandlerRepoStub) ListUserAuthIdentities(context.Context, int64) ([]service.UserAuthIdentityRecord, error) {
 	out := make([]service.UserAuthIdentityRecord, len(s.identities))
 	copy(out, s.identities)