feat(backend): add user custom attributes system

Add a flexible user attribute system that allows admins to define custom fields for users (text, textarea, number, email, url, date, select, multi_select types). - Add Ent schemas for UserAttributeDefinition and UserAttributeValue - Add service layer with validation logic - Add repository layer with batch operations support - Add admin API endpoints for CRUD and reorder operations - Add batch API for loading attribute values for multiple users - Add database migration (018_user_attributes.sql) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-01 18:58:34 +08:00
parent 7331220e06
commit 3c3fed886f
36 changed files with 10649 additions and 122 deletions
--- a/backend/internal/handler/admin/user_attribute_handler.go
+++ b/backend/internal/handler/admin/user_attribute_handler.go
@@ -0,0 +1,342 @@
+package admin
+
+import (
+	"strconv"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+// UserAttributeHandler handles user attribute management
+type UserAttributeHandler struct {
+	attrService *service.UserAttributeService
+}
+
+// NewUserAttributeHandler creates a new handler
+func NewUserAttributeHandler(attrService *service.UserAttributeService) *UserAttributeHandler {
+	return &UserAttributeHandler{attrService: attrService}
+}
+
+// --- Request/Response DTOs ---
+
+// CreateAttributeDefinitionRequest represents create attribute definition request
+type CreateAttributeDefinitionRequest struct {
+	Key         string                          `json:"key" binding:"required,min=1,max=100"`
+	Name        string                          `json:"name" binding:"required,min=1,max=255"`
+	Description string                          `json:"description"`
+	Type        string                          `json:"type" binding:"required"`
+	Options     []service.UserAttributeOption   `json:"options"`
+	Required    bool                            `json:"required"`
+	Validation  service.UserAttributeValidation `json:"validation"`
+	Placeholder string                          `json:"placeholder"`
+	Enabled     bool                            `json:"enabled"`
+}
+
+// UpdateAttributeDefinitionRequest represents update attribute definition request
+type UpdateAttributeDefinitionRequest struct {
+	Name        *string                          `json:"name"`
+	Description *string                          `json:"description"`
+	Type        *string                          `json:"type"`
+	Options     *[]service.UserAttributeOption   `json:"options"`
+	Required    *bool                            `json:"required"`
+	Validation  *service.UserAttributeValidation `json:"validation"`
+	Placeholder *string                          `json:"placeholder"`
+	Enabled     *bool                            `json:"enabled"`
+}
+
+// ReorderRequest represents reorder attribute definitions request
+type ReorderRequest struct {
+	IDs []int64 `json:"ids" binding:"required"`
+}
+
+// UpdateUserAttributesRequest represents update user attributes request
+type UpdateUserAttributesRequest struct {
+	Values map[int64]string `json:"values" binding:"required"`
+}
+
+// BatchGetUserAttributesRequest represents batch get user attributes request
+type BatchGetUserAttributesRequest struct {
+	UserIDs []int64 `json:"user_ids" binding:"required"`
+}
+
+// BatchUserAttributesResponse represents batch user attributes response
+type BatchUserAttributesResponse struct {
+	// Map of userID -> map of attributeID -> value
+	Attributes map[int64]map[int64]string `json:"attributes"`
+}
+
+// AttributeDefinitionResponse represents attribute definition response
+type AttributeDefinitionResponse struct {
+	ID           int64                           `json:"id"`
+	Key          string                          `json:"key"`
+	Name         string                          `json:"name"`
+	Description  string                          `json:"description"`
+	Type         string                          `json:"type"`
+	Options      []service.UserAttributeOption   `json:"options"`
+	Required     bool                            `json:"required"`
+	Validation   service.UserAttributeValidation `json:"validation"`
+	Placeholder  string                          `json:"placeholder"`
+	DisplayOrder int                             `json:"display_order"`
+	Enabled      bool                            `json:"enabled"`
+	CreatedAt    string                          `json:"created_at"`
+	UpdatedAt    string                          `json:"updated_at"`
+}
+
+// AttributeValueResponse represents attribute value response
+type AttributeValueResponse struct {
+	ID          int64  `json:"id"`
+	UserID      int64  `json:"user_id"`
+	AttributeID int64  `json:"attribute_id"`
+	Value       string `json:"value"`
+	CreatedAt   string `json:"created_at"`
+	UpdatedAt   string `json:"updated_at"`
+}
+
+// --- Helpers ---
+
+func defToResponse(def *service.UserAttributeDefinition) *AttributeDefinitionResponse {
+	return &AttributeDefinitionResponse{
+		ID:           def.ID,
+		Key:          def.Key,
+		Name:         def.Name,
+		Description:  def.Description,
+		Type:         string(def.Type),
+		Options:      def.Options,
+		Required:     def.Required,
+		Validation:   def.Validation,
+		Placeholder:  def.Placeholder,
+		DisplayOrder: def.DisplayOrder,
+		Enabled:      def.Enabled,
+		CreatedAt:    def.CreatedAt.Format("2006-01-02T15:04:05Z07:00"),
+		UpdatedAt:    def.UpdatedAt.Format("2006-01-02T15:04:05Z07:00"),
+	}
+}
+
+func valueToResponse(val *service.UserAttributeValue) *AttributeValueResponse {
+	return &AttributeValueResponse{
+		ID:          val.ID,
+		UserID:      val.UserID,
+		AttributeID: val.AttributeID,
+		Value:       val.Value,
+		CreatedAt:   val.CreatedAt.Format("2006-01-02T15:04:05Z07:00"),
+		UpdatedAt:   val.UpdatedAt.Format("2006-01-02T15:04:05Z07:00"),
+	}
+}
+
+// --- Handlers ---
+
+// ListDefinitions lists all attribute definitions
+// GET /admin/user-attributes
+func (h *UserAttributeHandler) ListDefinitions(c *gin.Context) {
+	enabledOnly := c.Query("enabled") == "true"
+
+	defs, err := h.attrService.ListDefinitions(c.Request.Context(), enabledOnly)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]*AttributeDefinitionResponse, 0, len(defs))
+	for i := range defs {
+		out = append(out, defToResponse(&defs[i]))
+	}
+
+	response.Success(c, out)
+}
+
+// CreateDefinition creates a new attribute definition
+// POST /admin/user-attributes
+func (h *UserAttributeHandler) CreateDefinition(c *gin.Context) {
+	var req CreateAttributeDefinitionRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	def, err := h.attrService.CreateDefinition(c.Request.Context(), service.CreateAttributeDefinitionInput{
+		Key:         req.Key,
+		Name:        req.Name,
+		Description: req.Description,
+		Type:        service.UserAttributeType(req.Type),
+		Options:     req.Options,
+		Required:    req.Required,
+		Validation:  req.Validation,
+		Placeholder: req.Placeholder,
+		Enabled:     req.Enabled,
+	})
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, defToResponse(def))
+}
+
+// UpdateDefinition updates an attribute definition
+// PUT /admin/user-attributes/:id
+func (h *UserAttributeHandler) UpdateDefinition(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid attribute ID")
+		return
+	}
+
+	var req UpdateAttributeDefinitionRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	input := service.UpdateAttributeDefinitionInput{
+		Name:        req.Name,
+		Description: req.Description,
+		Options:     req.Options,
+		Required:    req.Required,
+		Validation:  req.Validation,
+		Placeholder: req.Placeholder,
+		Enabled:     req.Enabled,
+	}
+	if req.Type != nil {
+		t := service.UserAttributeType(*req.Type)
+		input.Type = &t
+	}
+
+	def, err := h.attrService.UpdateDefinition(c.Request.Context(), id, input)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, defToResponse(def))
+}
+
+// DeleteDefinition deletes an attribute definition
+// DELETE /admin/user-attributes/:id
+func (h *UserAttributeHandler) DeleteDefinition(c *gin.Context) {
+	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid attribute ID")
+		return
+	}
+
+	if err := h.attrService.DeleteDefinition(c.Request.Context(), id); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Attribute definition deleted successfully"})
+}
+
+// ReorderDefinitions reorders attribute definitions
+// PUT /admin/user-attributes/reorder
+func (h *UserAttributeHandler) ReorderDefinitions(c *gin.Context) {
+	var req ReorderRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	// Convert IDs array to orders map (position in array = display_order)
+	orders := make(map[int64]int, len(req.IDs))
+	for i, id := range req.IDs {
+		orders[id] = i
+	}
+
+	if err := h.attrService.ReorderDefinitions(c.Request.Context(), orders); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, gin.H{"message": "Reorder successful"})
+}
+
+// GetUserAttributes gets a user's attribute values
+// GET /admin/users/:id/attributes
+func (h *UserAttributeHandler) GetUserAttributes(c *gin.Context) {
+	userID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid user ID")
+		return
+	}
+
+	values, err := h.attrService.GetUserAttributes(c.Request.Context(), userID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]*AttributeValueResponse, 0, len(values))
+	for i := range values {
+		out = append(out, valueToResponse(&values[i]))
+	}
+
+	response.Success(c, out)
+}
+
+// UpdateUserAttributes updates a user's attribute values
+// PUT /admin/users/:id/attributes
+func (h *UserAttributeHandler) UpdateUserAttributes(c *gin.Context) {
+	userID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.BadRequest(c, "Invalid user ID")
+		return
+	}
+
+	var req UpdateUserAttributesRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	inputs := make([]service.UpdateUserAttributeInput, 0, len(req.Values))
+	for attrID, value := range req.Values {
+		inputs = append(inputs, service.UpdateUserAttributeInput{
+			AttributeID: attrID,
+			Value:       value,
+		})
+	}
+
+	if err := h.attrService.UpdateUserAttributes(c.Request.Context(), userID, inputs); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	// Return updated values
+	values, err := h.attrService.GetUserAttributes(c.Request.Context(), userID)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	out := make([]*AttributeValueResponse, 0, len(values))
+	for i := range values {
+		out = append(out, valueToResponse(&values[i]))
+	}
+
+	response.Success(c, out)
+}
+
+// GetBatchUserAttributes gets attribute values for multiple users
+// POST /admin/user-attributes/batch
+func (h *UserAttributeHandler) GetBatchUserAttributes(c *gin.Context) {
+	var req BatchGetUserAttributesRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "Invalid request: "+err.Error())
+		return
+	}
+
+	if len(req.UserIDs) == 0 {
+		response.Success(c, BatchUserAttributesResponse{Attributes: map[int64]map[int64]string{}})
+		return
+	}
+
+	attrs, err := h.attrService.GetBatchUserAttributes(c.Request.Context(), req.UserIDs)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	response.Success(c, BatchUserAttributesResponse{Attributes: attrs})
+}
--- a/backend/internal/handler/handler.go
+++ b/backend/internal/handler/handler.go
@@ -20,6 +20,7 @@ type AdminHandlers struct {
 	System           *admin.SystemHandler
 	Subscription     *admin.SubscriptionHandler
 	Usage            *admin.UsageHandler
+	UserAttribute    *admin.UserAttributeHandler
 }

 // Handlers contains all HTTP handlers
--- a/backend/internal/handler/wire.go
+++ b/backend/internal/handler/wire.go
@@ -23,6 +23,7 @@ func ProvideAdminHandlers(
 	systemHandler *admin.SystemHandler,
 	subscriptionHandler *admin.SubscriptionHandler,
 	usageHandler *admin.UsageHandler,
+	userAttributeHandler *admin.UserAttributeHandler,
 ) *AdminHandlers {
 	return &AdminHandlers{
 		Dashboard:        dashboardHandler,
@@ -39,6 +40,7 @@ func ProvideAdminHandlers(
 		System:           systemHandler,
 		Subscription:     subscriptionHandler,
 		Usage:            usageHandler,
+		UserAttribute:    userAttributeHandler,
 	}
 }

@@ -107,6 +109,7 @@ var ProviderSet = wire.NewSet(
 	ProvideSystemHandler,
 	admin.NewSubscriptionHandler,
 	admin.NewUsageHandler,
+	admin.NewUserAttributeHandler,

 	// AdminHandlers and Handlers constructors
 	ProvideAdminHandlers,
--- a/backend/internal/repository/user_attribute_repo.go
+++ b/backend/internal/repository/user_attribute_repo.go
@@ -0,0 +1,387 @@
+package repository
+
+import (
+	"context"
+	"database/sql"
+
+	dbent "github.com/Wei-Shaw/sub2api/ent"
+	"github.com/Wei-Shaw/sub2api/ent/userattributedefinition"
+	"github.com/Wei-Shaw/sub2api/ent/userattributevalue"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+)
+
+// UserAttributeDefinitionRepository implementation
+type userAttributeDefinitionRepository struct {
+	client *dbent.Client
+}
+
+// NewUserAttributeDefinitionRepository creates a new repository instance
+func NewUserAttributeDefinitionRepository(client *dbent.Client) service.UserAttributeDefinitionRepository {
+	return &userAttributeDefinitionRepository{client: client}
+}
+
+func (r *userAttributeDefinitionRepository) Create(ctx context.Context, def *service.UserAttributeDefinition) error {
+	client := clientFromContext(ctx, r.client)
+
+	created, err := client.UserAttributeDefinition.Create().
+		SetKey(def.Key).
+		SetName(def.Name).
+		SetDescription(def.Description).
+		SetType(string(def.Type)).
+		SetOptions(toEntOptions(def.Options)).
+		SetRequired(def.Required).
+		SetValidation(toEntValidation(def.Validation)).
+		SetPlaceholder(def.Placeholder).
+		SetEnabled(def.Enabled).
+		Save(ctx)
+
+	if err != nil {
+		return translatePersistenceError(err, nil, service.ErrAttributeKeyExists)
+	}
+
+	def.ID = created.ID
+	def.DisplayOrder = created.DisplayOrder
+	def.CreatedAt = created.CreatedAt
+	def.UpdatedAt = created.UpdatedAt
+	return nil
+}
+
+func (r *userAttributeDefinitionRepository) GetByID(ctx context.Context, id int64) (*service.UserAttributeDefinition, error) {
+	client := clientFromContext(ctx, r.client)
+
+	e, err := client.UserAttributeDefinition.Query().
+		Where(userattributedefinition.IDEQ(id)).
+		Only(ctx)
+	if err != nil {
+		return nil, translatePersistenceError(err, service.ErrAttributeDefinitionNotFound, nil)
+	}
+	return defEntityToService(e), nil
+}
+
+func (r *userAttributeDefinitionRepository) GetByKey(ctx context.Context, key string) (*service.UserAttributeDefinition, error) {
+	client := clientFromContext(ctx, r.client)
+
+	e, err := client.UserAttributeDefinition.Query().
+		Where(userattributedefinition.KeyEQ(key)).
+		Only(ctx)
+	if err != nil {
+		return nil, translatePersistenceError(err, service.ErrAttributeDefinitionNotFound, nil)
+	}
+	return defEntityToService(e), nil
+}
+
+func (r *userAttributeDefinitionRepository) Update(ctx context.Context, def *service.UserAttributeDefinition) error {
+	client := clientFromContext(ctx, r.client)
+
+	updated, err := client.UserAttributeDefinition.UpdateOneID(def.ID).
+		SetName(def.Name).
+		SetDescription(def.Description).
+		SetType(string(def.Type)).
+		SetOptions(toEntOptions(def.Options)).
+		SetRequired(def.Required).
+		SetValidation(toEntValidation(def.Validation)).
+		SetPlaceholder(def.Placeholder).
+		SetDisplayOrder(def.DisplayOrder).
+		SetEnabled(def.Enabled).
+		Save(ctx)
+
+	if err != nil {
+		return translatePersistenceError(err, service.ErrAttributeDefinitionNotFound, service.ErrAttributeKeyExists)
+	}
+
+	def.UpdatedAt = updated.UpdatedAt
+	return nil
+}
+
+func (r *userAttributeDefinitionRepository) Delete(ctx context.Context, id int64) error {
+	client := clientFromContext(ctx, r.client)
+
+	_, err := client.UserAttributeDefinition.Delete().
+		Where(userattributedefinition.IDEQ(id)).
+		Exec(ctx)
+	return translatePersistenceError(err, service.ErrAttributeDefinitionNotFound, nil)
+}
+
+func (r *userAttributeDefinitionRepository) List(ctx context.Context, enabledOnly bool) ([]service.UserAttributeDefinition, error) {
+	client := clientFromContext(ctx, r.client)
+
+	q := client.UserAttributeDefinition.Query()
+	if enabledOnly {
+		q = q.Where(userattributedefinition.EnabledEQ(true))
+	}
+
+	entities, err := q.Order(dbent.Asc(userattributedefinition.FieldDisplayOrder)).All(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	result := make([]service.UserAttributeDefinition, 0, len(entities))
+	for _, e := range entities {
+		result = append(result, *defEntityToService(e))
+	}
+	return result, nil
+}
+
+func (r *userAttributeDefinitionRepository) UpdateDisplayOrders(ctx context.Context, orders map[int64]int) error {
+	tx, err := r.client.Tx(ctx)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = tx.Rollback() }()
+
+	for id, order := range orders {
+		if _, err := tx.UserAttributeDefinition.UpdateOneID(id).
+			SetDisplayOrder(order).
+			Save(ctx); err != nil {
+			return translatePersistenceError(err, service.ErrAttributeDefinitionNotFound, nil)
+		}
+	}
+
+	return tx.Commit()
+}
+
+func (r *userAttributeDefinitionRepository) ExistsByKey(ctx context.Context, key string) (bool, error) {
+	client := clientFromContext(ctx, r.client)
+	return client.UserAttributeDefinition.Query().
+		Where(userattributedefinition.KeyEQ(key)).
+		Exist(ctx)
+}
+
+// UserAttributeValueRepository implementation
+type userAttributeValueRepository struct {
+	client *dbent.Client
+	sql    *sql.DB
+}
+
+// NewUserAttributeValueRepository creates a new repository instance
+func NewUserAttributeValueRepository(client *dbent.Client, sqlDB *sql.DB) service.UserAttributeValueRepository {
+	return &userAttributeValueRepository{client: client, sql: sqlDB}
+}
+
+func (r *userAttributeValueRepository) GetByUserID(ctx context.Context, userID int64) ([]service.UserAttributeValue, error) {
+	client := clientFromContext(ctx, r.client)
+
+	entities, err := client.UserAttributeValue.Query().
+		Where(userattributevalue.UserIDEQ(userID)).
+		All(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	result := make([]service.UserAttributeValue, 0, len(entities))
+	for _, e := range entities {
+		result = append(result, service.UserAttributeValue{
+			ID:          e.ID,
+			UserID:      e.UserID,
+			AttributeID: e.AttributeID,
+			Value:       e.Value,
+			CreatedAt:   e.CreatedAt,
+			UpdatedAt:   e.UpdatedAt,
+		})
+	}
+	return result, nil
+}
+
+func (r *userAttributeValueRepository) GetByUserIDs(ctx context.Context, userIDs []int64) ([]service.UserAttributeValue, error) {
+	if len(userIDs) == 0 {
+		return []service.UserAttributeValue{}, nil
+	}
+
+	client := clientFromContext(ctx, r.client)
+
+	entities, err := client.UserAttributeValue.Query().
+		Where(userattributevalue.UserIDIn(userIDs...)).
+		All(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	result := make([]service.UserAttributeValue, 0, len(entities))
+	for _, e := range entities {
+		result = append(result, service.UserAttributeValue{
+			ID:          e.ID,
+			UserID:      e.UserID,
+			AttributeID: e.AttributeID,
+			Value:       e.Value,
+			CreatedAt:   e.CreatedAt,
+			UpdatedAt:   e.UpdatedAt,
+		})
+	}
+	return result, nil
+}
+
+func (r *userAttributeValueRepository) UpsertBatch(ctx context.Context, userID int64, inputs []service.UpdateUserAttributeInput) error {
+	if len(inputs) == 0 {
+		return nil
+	}
+
+	tx, err := r.client.Tx(ctx)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = tx.Rollback() }()
+
+	for _, input := range inputs {
+		// Use upsert (ON CONFLICT DO UPDATE)
+		err := tx.UserAttributeValue.Create().
+			SetUserID(userID).
+			SetAttributeID(input.AttributeID).
+			SetValue(input.Value).
+			OnConflictColumns(userattributevalue.FieldUserID, userattributevalue.FieldAttributeID).
+			UpdateValue().
+			UpdateUpdatedAt().
+			Exec(ctx)
+		if err != nil {
+			return err
+		}
+	}
+
+	return tx.Commit()
+}
+
+func (r *userAttributeValueRepository) DeleteByAttributeID(ctx context.Context, attributeID int64) error {
+	client := clientFromContext(ctx, r.client)
+
+	_, err := client.UserAttributeValue.Delete().
+		Where(userattributevalue.AttributeIDEQ(attributeID)).
+		Exec(ctx)
+	return err
+}
+
+func (r *userAttributeValueRepository) DeleteByUserID(ctx context.Context, userID int64) error {
+	client := clientFromContext(ctx, r.client)
+
+	_, err := client.UserAttributeValue.Delete().
+		Where(userattributevalue.UserIDEQ(userID)).
+		Exec(ctx)
+	return err
+}
+
+// Helper functions for entity to service conversion
+func defEntityToService(e *dbent.UserAttributeDefinition) *service.UserAttributeDefinition {
+	if e == nil {
+		return nil
+	}
+	return &service.UserAttributeDefinition{
+		ID:           e.ID,
+		Key:          e.Key,
+		Name:         e.Name,
+		Description:  e.Description,
+		Type:         service.UserAttributeType(e.Type),
+		Options:      toServiceOptions(e.Options),
+		Required:     e.Required,
+		Validation:   toServiceValidation(e.Validation),
+		Placeholder:  e.Placeholder,
+		DisplayOrder: e.DisplayOrder,
+		Enabled:      e.Enabled,
+		CreatedAt:    e.CreatedAt,
+		UpdatedAt:    e.UpdatedAt,
+	}
+}
+
+// Type conversion helpers (map types <-> service types)
+func toEntOptions(opts []service.UserAttributeOption) []map[string]any {
+	if opts == nil {
+		return []map[string]any{}
+	}
+	result := make([]map[string]any, len(opts))
+	for i, o := range opts {
+		result[i] = map[string]any{"value": o.Value, "label": o.Label}
+	}
+	return result
+}
+
+func toServiceOptions(opts []map[string]any) []service.UserAttributeOption {
+	if opts == nil {
+		return []service.UserAttributeOption{}
+	}
+	result := make([]service.UserAttributeOption, len(opts))
+	for i, o := range opts {
+		result[i] = service.UserAttributeOption{
+			Value: getString(o, "value"),
+			Label: getString(o, "label"),
+		}
+	}
+	return result
+}
+
+func toEntValidation(v service.UserAttributeValidation) map[string]any {
+	result := map[string]any{}
+	if v.MinLength != nil {
+		result["min_length"] = *v.MinLength
+	}
+	if v.MaxLength != nil {
+		result["max_length"] = *v.MaxLength
+	}
+	if v.Min != nil {
+		result["min"] = *v.Min
+	}
+	if v.Max != nil {
+		result["max"] = *v.Max
+	}
+	if v.Pattern != nil {
+		result["pattern"] = *v.Pattern
+	}
+	if v.Message != nil {
+		result["message"] = *v.Message
+	}
+	return result
+}
+
+func toServiceValidation(v map[string]any) service.UserAttributeValidation {
+	result := service.UserAttributeValidation{}
+	if val := getInt(v, "min_length"); val != nil {
+		result.MinLength = val
+	}
+	if val := getInt(v, "max_length"); val != nil {
+		result.MaxLength = val
+	}
+	if val := getInt(v, "min"); val != nil {
+		result.Min = val
+	}
+	if val := getInt(v, "max"); val != nil {
+		result.Max = val
+	}
+	if val := getStringPtr(v, "pattern"); val != nil {
+		result.Pattern = val
+	}
+	if val := getStringPtr(v, "message"); val != nil {
+		result.Message = val
+	}
+	return result
+}
+
+// Helper functions for type conversion
+func getString(m map[string]any, key string) string {
+	if v, ok := m[key]; ok {
+		if s, ok := v.(string); ok {
+			return s
+		}
+	}
+	return ""
+}
+
+func getStringPtr(m map[string]any, key string) *string {
+	if v, ok := m[key]; ok {
+		if s, ok := v.(string); ok {
+			return &s
+		}
+	}
+	return nil
+}
+
+func getInt(m map[string]any, key string) *int {
+	if v, ok := m[key]; ok {
+		switch n := v.(type) {
+		case int:
+			return &n
+		case int64:
+			i := int(n)
+			return &i
+		case float64:
+			i := int(n)
+			return &i
+		}
+	}
+	return nil
+}
--- a/backend/internal/repository/wire.go
+++ b/backend/internal/repository/wire.go
@@ -36,6 +36,8 @@ var ProviderSet = wire.NewSet(
 	NewUsageLogRepository,
 	NewSettingRepository,
 	NewUserSubscriptionRepository,
+	NewUserAttributeDefinitionRepository,
+	NewUserAttributeValueRepository,

 	// Cache implementations
 	NewGatewayCache,
--- a/backend/internal/server/routes/admin.go
+++ b/backend/internal/server/routes/admin.go
@@ -54,6 +54,9 @@ func RegisterAdminRoutes(

 		// 使用记录管理
 		registerUsageRoutes(admin, h)
+
+		// 用户属性管理
+		registerUserAttributeRoutes(admin, h)
 	}
 }

@@ -82,6 +85,10 @@ func registerUserManagementRoutes(admin *gin.RouterGroup, h *handler.Handlers) {
 		users.POST("/:id/balance", h.Admin.User.UpdateBalance)
 		users.GET("/:id/api-keys", h.Admin.User.GetUserAPIKeys)
 		users.GET("/:id/usage", h.Admin.User.GetUserUsage)
+
+		// User attribute values
+		users.GET("/:id/attributes", h.Admin.UserAttribute.GetUserAttributes)
+		users.PUT("/:id/attributes", h.Admin.UserAttribute.UpdateUserAttributes)
 	}
 }

@@ -242,3 +249,15 @@ func registerUsageRoutes(admin *gin.RouterGroup, h *handler.Handlers) {
 		usage.GET("/search-api-keys", h.Admin.Usage.SearchApiKeys)
 	}
 }
+
+func registerUserAttributeRoutes(admin *gin.RouterGroup, h *handler.Handlers) {
+	attrs := admin.Group("/user-attributes")
+	{
+		attrs.GET("", h.Admin.UserAttribute.ListDefinitions)
+		attrs.POST("", h.Admin.UserAttribute.CreateDefinition)
+		attrs.POST("/batch", h.Admin.UserAttribute.GetBatchUserAttributes)
+		attrs.PUT("/reorder", h.Admin.UserAttribute.ReorderDefinitions)
+		attrs.PUT("/:id", h.Admin.UserAttribute.UpdateDefinition)
+		attrs.DELETE("/:id", h.Admin.UserAttribute.DeleteDefinition)
+	}
+}
--- a/backend/internal/service/user_attribute.go
+++ b/backend/internal/service/user_attribute.go
@@ -0,0 +1,125 @@
+package service
+
+import (
+	"context"
+	"time"
+
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/pkg/errors"
+)
+
+// Error definitions for user attribute operations
+var (
+	ErrAttributeDefinitionNotFound = infraerrors.NotFound("ATTRIBUTE_DEFINITION_NOT_FOUND", "attribute definition not found")
+	ErrAttributeKeyExists          = infraerrors.Conflict("ATTRIBUTE_KEY_EXISTS", "attribute key already exists")
+	ErrInvalidAttributeType        = infraerrors.BadRequest("INVALID_ATTRIBUTE_TYPE", "invalid attribute type")
+	ErrAttributeValidationFailed   = infraerrors.BadRequest("ATTRIBUTE_VALIDATION_FAILED", "attribute value validation failed")
+)
+
+// UserAttributeType represents supported attribute types
+type UserAttributeType string
+
+const (
+	AttributeTypeText        UserAttributeType = "text"
+	AttributeTypeTextarea    UserAttributeType = "textarea"
+	AttributeTypeNumber      UserAttributeType = "number"
+	AttributeTypeEmail       UserAttributeType = "email"
+	AttributeTypeURL         UserAttributeType = "url"
+	AttributeTypeDate        UserAttributeType = "date"
+	AttributeTypeSelect      UserAttributeType = "select"
+	AttributeTypeMultiSelect UserAttributeType = "multi_select"
+)
+
+// UserAttributeOption represents a select option for select/multi_select types
+type UserAttributeOption struct {
+	Value string `json:"value"`
+	Label string `json:"label"`
+}
+
+// UserAttributeValidation represents validation rules for an attribute
+type UserAttributeValidation struct {
+	MinLength *int    `json:"min_length,omitempty"`
+	MaxLength *int    `json:"max_length,omitempty"`
+	Min       *int    `json:"min,omitempty"`
+	Max       *int    `json:"max,omitempty"`
+	Pattern   *string `json:"pattern,omitempty"`
+	Message   *string `json:"message,omitempty"`
+}
+
+// UserAttributeDefinition represents a custom attribute definition
+type UserAttributeDefinition struct {
+	ID           int64
+	Key          string
+	Name         string
+	Description  string
+	Type         UserAttributeType
+	Options      []UserAttributeOption
+	Required     bool
+	Validation   UserAttributeValidation
+	Placeholder  string
+	DisplayOrder int
+	Enabled      bool
+	CreatedAt    time.Time
+	UpdatedAt    time.Time
+}
+
+// UserAttributeValue represents a user's attribute value
+type UserAttributeValue struct {
+	ID          int64
+	UserID      int64
+	AttributeID int64
+	Value       string
+	CreatedAt   time.Time
+	UpdatedAt   time.Time
+}
+
+// CreateAttributeDefinitionInput for creating new definition
+type CreateAttributeDefinitionInput struct {
+	Key         string
+	Name        string
+	Description string
+	Type        UserAttributeType
+	Options     []UserAttributeOption
+	Required    bool
+	Validation  UserAttributeValidation
+	Placeholder string
+	Enabled     bool
+}
+
+// UpdateAttributeDefinitionInput for updating definition
+type UpdateAttributeDefinitionInput struct {
+	Name        *string
+	Description *string
+	Type        *UserAttributeType
+	Options     *[]UserAttributeOption
+	Required    *bool
+	Validation  *UserAttributeValidation
+	Placeholder *string
+	Enabled     *bool
+}
+
+// UpdateUserAttributeInput for updating a single attribute value
+type UpdateUserAttributeInput struct {
+	AttributeID int64
+	Value       string
+}
+
+// UserAttributeDefinitionRepository interface for attribute definition persistence
+type UserAttributeDefinitionRepository interface {
+	Create(ctx context.Context, def *UserAttributeDefinition) error
+	GetByID(ctx context.Context, id int64) (*UserAttributeDefinition, error)
+	GetByKey(ctx context.Context, key string) (*UserAttributeDefinition, error)
+	Update(ctx context.Context, def *UserAttributeDefinition) error
+	Delete(ctx context.Context, id int64) error
+	List(ctx context.Context, enabledOnly bool) ([]UserAttributeDefinition, error)
+	UpdateDisplayOrders(ctx context.Context, orders map[int64]int) error
+	ExistsByKey(ctx context.Context, key string) (bool, error)
+}
+
+// UserAttributeValueRepository interface for user attribute value persistence
+type UserAttributeValueRepository interface {
+	GetByUserID(ctx context.Context, userID int64) ([]UserAttributeValue, error)
+	GetByUserIDs(ctx context.Context, userIDs []int64) ([]UserAttributeValue, error)
+	UpsertBatch(ctx context.Context, userID int64, values []UpdateUserAttributeInput) error
+	DeleteByAttributeID(ctx context.Context, attributeID int64) error
+	DeleteByUserID(ctx context.Context, userID int64) error
+}
--- a/backend/internal/service/user_attribute_service.go
+++ b/backend/internal/service/user_attribute_service.go
@@ -0,0 +1,295 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"strconv"
+	"strings"
+
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/pkg/errors"
+)
+
+// UserAttributeService handles attribute management
+type UserAttributeService struct {
+	defRepo   UserAttributeDefinitionRepository
+	valueRepo UserAttributeValueRepository
+}
+
+// NewUserAttributeService creates a new service instance
+func NewUserAttributeService(
+	defRepo UserAttributeDefinitionRepository,
+	valueRepo UserAttributeValueRepository,
+) *UserAttributeService {
+	return &UserAttributeService{
+		defRepo:   defRepo,
+		valueRepo: valueRepo,
+	}
+}
+
+// CreateDefinition creates a new attribute definition
+func (s *UserAttributeService) CreateDefinition(ctx context.Context, input CreateAttributeDefinitionInput) (*UserAttributeDefinition, error) {
+	// Validate type
+	if !isValidAttributeType(input.Type) {
+		return nil, ErrInvalidAttributeType
+	}
+
+	// Check if key exists
+	exists, err := s.defRepo.ExistsByKey(ctx, input.Key)
+	if err != nil {
+		return nil, fmt.Errorf("check key exists: %w", err)
+	}
+	if exists {
+		return nil, ErrAttributeKeyExists
+	}
+
+	def := &UserAttributeDefinition{
+		Key:         input.Key,
+		Name:        input.Name,
+		Description: input.Description,
+		Type:        input.Type,
+		Options:     input.Options,
+		Required:    input.Required,
+		Validation:  input.Validation,
+		Placeholder: input.Placeholder,
+		Enabled:     input.Enabled,
+	}
+
+	if err := s.defRepo.Create(ctx, def); err != nil {
+		return nil, fmt.Errorf("create definition: %w", err)
+	}
+
+	return def, nil
+}
+
+// GetDefinition retrieves a definition by ID
+func (s *UserAttributeService) GetDefinition(ctx context.Context, id int64) (*UserAttributeDefinition, error) {
+	return s.defRepo.GetByID(ctx, id)
+}
+
+// ListDefinitions lists all definitions
+func (s *UserAttributeService) ListDefinitions(ctx context.Context, enabledOnly bool) ([]UserAttributeDefinition, error) {
+	return s.defRepo.List(ctx, enabledOnly)
+}
+
+// UpdateDefinition updates an existing definition
+func (s *UserAttributeService) UpdateDefinition(ctx context.Context, id int64, input UpdateAttributeDefinitionInput) (*UserAttributeDefinition, error) {
+	def, err := s.defRepo.GetByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+
+	if input.Name != nil {
+		def.Name = *input.Name
+	}
+	if input.Description != nil {
+		def.Description = *input.Description
+	}
+	if input.Type != nil {
+		if !isValidAttributeType(*input.Type) {
+			return nil, ErrInvalidAttributeType
+		}
+		def.Type = *input.Type
+	}
+	if input.Options != nil {
+		def.Options = *input.Options
+	}
+	if input.Required != nil {
+		def.Required = *input.Required
+	}
+	if input.Validation != nil {
+		def.Validation = *input.Validation
+	}
+	if input.Placeholder != nil {
+		def.Placeholder = *input.Placeholder
+	}
+	if input.Enabled != nil {
+		def.Enabled = *input.Enabled
+	}
+
+	if err := s.defRepo.Update(ctx, def); err != nil {
+		return nil, fmt.Errorf("update definition: %w", err)
+	}
+
+	return def, nil
+}
+
+// DeleteDefinition soft-deletes a definition and hard-deletes associated values
+func (s *UserAttributeService) DeleteDefinition(ctx context.Context, id int64) error {
+	// Check if definition exists
+	_, err := s.defRepo.GetByID(ctx, id)
+	if err != nil {
+		return err
+	}
+
+	// First delete all values (hard delete)
+	if err := s.valueRepo.DeleteByAttributeID(ctx, id); err != nil {
+		return fmt.Errorf("delete values: %w", err)
+	}
+
+	// Then soft-delete the definition
+	if err := s.defRepo.Delete(ctx, id); err != nil {
+		return fmt.Errorf("delete definition: %w", err)
+	}
+
+	return nil
+}
+
+// ReorderDefinitions updates display order for multiple definitions
+func (s *UserAttributeService) ReorderDefinitions(ctx context.Context, orders map[int64]int) error {
+	return s.defRepo.UpdateDisplayOrders(ctx, orders)
+}
+
+// GetUserAttributes retrieves all attribute values for a user
+func (s *UserAttributeService) GetUserAttributes(ctx context.Context, userID int64) ([]UserAttributeValue, error) {
+	return s.valueRepo.GetByUserID(ctx, userID)
+}
+
+// GetBatchUserAttributes retrieves attribute values for multiple users
+// Returns a map of userID -> map of attributeID -> value
+func (s *UserAttributeService) GetBatchUserAttributes(ctx context.Context, userIDs []int64) (map[int64]map[int64]string, error) {
+	values, err := s.valueRepo.GetByUserIDs(ctx, userIDs)
+	if err != nil {
+		return nil, err
+	}
+
+	result := make(map[int64]map[int64]string)
+	for _, v := range values {
+		if result[v.UserID] == nil {
+			result[v.UserID] = make(map[int64]string)
+		}
+		result[v.UserID][v.AttributeID] = v.Value
+	}
+
+	return result, nil
+}
+
+// UpdateUserAttributes batch updates attribute values for a user
+func (s *UserAttributeService) UpdateUserAttributes(ctx context.Context, userID int64, inputs []UpdateUserAttributeInput) error {
+	// Validate all values before updating
+	defs, err := s.defRepo.List(ctx, true)
+	if err != nil {
+		return fmt.Errorf("list definitions: %w", err)
+	}
+
+	defMap := make(map[int64]*UserAttributeDefinition, len(defs))
+	for i := range defs {
+		defMap[defs[i].ID] = &defs[i]
+	}
+
+	for _, input := range inputs {
+		def, ok := defMap[input.AttributeID]
+		if !ok {
+			return ErrAttributeDefinitionNotFound
+		}
+
+		if err := s.validateValue(def, input.Value); err != nil {
+			return err
+		}
+	}
+
+	return s.valueRepo.UpsertBatch(ctx, userID, inputs)
+}
+
+// validateValue validates a value against its definition
+func (s *UserAttributeService) validateValue(def *UserAttributeDefinition, value string) error {
+	// Skip validation for empty non-required fields
+	if value == "" && !def.Required {
+		return nil
+	}
+
+	// Required check
+	if def.Required && value == "" {
+		return validationError(fmt.Sprintf("%s is required", def.Name))
+	}
+
+	v := def.Validation
+
+	// String length validation
+	if v.MinLength != nil && len(value) < *v.MinLength {
+		return validationError(fmt.Sprintf("%s must be at least %d characters", def.Name, *v.MinLength))
+	}
+	if v.MaxLength != nil && len(value) > *v.MaxLength {
+		return validationError(fmt.Sprintf("%s must be at most %d characters", def.Name, *v.MaxLength))
+	}
+
+	// Number validation
+	if def.Type == AttributeTypeNumber && value != "" {
+		num, err := strconv.Atoi(value)
+		if err != nil {
+			return validationError(fmt.Sprintf("%s must be a number", def.Name))
+		}
+		if v.Min != nil && num < *v.Min {
+			return validationError(fmt.Sprintf("%s must be at least %d", def.Name, *v.Min))
+		}
+		if v.Max != nil && num > *v.Max {
+			return validationError(fmt.Sprintf("%s must be at most %d", def.Name, *v.Max))
+		}
+	}
+
+	// Pattern validation
+	if v.Pattern != nil && *v.Pattern != "" && value != "" {
+		re, err := regexp.Compile(*v.Pattern)
+		if err == nil && !re.MatchString(value) {
+			msg := def.Name + " format is invalid"
+			if v.Message != nil && *v.Message != "" {
+				msg = *v.Message
+			}
+			return validationError(msg)
+		}
+	}
+
+	// Select validation
+	if def.Type == AttributeTypeSelect && value != "" {
+		found := false
+		for _, opt := range def.Options {
+			if opt.Value == value {
+				found = true
+				break
+			}
+		}
+		if !found {
+			return validationError(fmt.Sprintf("%s: invalid option", def.Name))
+		}
+	}
+
+	// Multi-select validation (stored as JSON array)
+	if def.Type == AttributeTypeMultiSelect && value != "" {
+		var values []string
+		if err := json.Unmarshal([]byte(value), &values); err != nil {
+			// Try comma-separated fallback
+			values = strings.Split(value, ",")
+		}
+		for _, val := range values {
+			val = strings.TrimSpace(val)
+			found := false
+			for _, opt := range def.Options {
+				if opt.Value == val {
+					found = true
+					break
+				}
+			}
+			if !found {
+				return validationError(fmt.Sprintf("%s: invalid option %s", def.Name, val))
+			}
+		}
+	}
+
+	return nil
+}
+
+// validationError creates a validation error with a custom message
+func validationError(msg string) error {
+	return infraerrors.BadRequest("ATTRIBUTE_VALIDATION_FAILED", msg)
+}
+
+func isValidAttributeType(t UserAttributeType) bool {
+	switch t {
+	case AttributeTypeText, AttributeTypeTextarea, AttributeTypeNumber,
+		AttributeTypeEmail, AttributeTypeURL, AttributeTypeDate,
+		AttributeTypeSelect, AttributeTypeMultiSelect:
+		return true
+	}
+	return false
+}
--- a/backend/internal/service/wire.go
+++ b/backend/internal/service/wire.go
@@ -125,4 +125,5 @@ var ProviderSet = wire.NewSet(
 	ProvideTimingWheelService,
 	ProvideDeferredService,
 	ProvideAntigravityQuotaRefresher,
+	NewUserAttributeService,
 )