number/后端架构设计/10-管理后台-part1-权限与DTO.md

# 管理后台开发文档 - Part 1（权限 + DTO/VO）

> 管理后台复用主应用 Service/Repository 层，新增 Admin Controller，路由前缀 `/api/admin`，通过角色拦截隔离。

## 一、角色常量

```java
package com.openclaw.constant;

public interface AdminRole {
    String ADMIN    = "ROLE_ADMIN";    // 超级管理员
    String OPERATOR = "ROLE_OPERATOR"; // 运营
    String AUDITOR  = "ROLE_AUDITOR";  // 内容审核
    String FINANCE  = "ROLE_FINANCE";  // 财务
}
```

```java
// SecurityConfig.java 追加
http.authorizeHttpRequests(auth -> auth
    .requestMatchers("/api/admin/**")
        .hasAnyRole("ADMIN","OPERATOR","AUDITOR","FINANCE")
);
```

## 二、管理端 DTO

```java
// AdminUserQueryDTO.java
@Data
public class AdminUserQueryDTO {
    private String  keyword;   // 手机号/昵称
    private String  status;    // active / banned
    private Integer pageNum  = 1;
    private Integer pageSize = 20;
}

// AdminSkillQueryDTO.java
@Data
public class AdminSkillQueryDTO {
    private String  keyword;
    private String  status;    // pending/approved/rejected/offline
    private Long    categoryId;
    private Integer pageNum  = 1;
    private Integer pageSize = 20;
}

// SkillAuditDTO.java
@Data
public class SkillAuditDTO {
    @NotNull  private Long   skillId;
    @NotBlank private String action;       // approve / reject
              private String rejectReason;
}

// AdminOrderQueryDTO.java
@Data
public class AdminOrderQueryDTO {
    private String    keyword;   // 订单号
    private String    status;
    private LocalDate startDate;
    private LocalDate endDate;
    private Integer   pageNum  = 1;
    private Integer   pageSize = 20;
}

// AdjustPointsDTO.java
@Data
public class AdjustPointsDTO {
    @NotNull private Integer delta;   // 正数增加，负数扣减
             private String  remark;
}

// RefundProcessDTO.java
@Data
public class RefundProcessDTO {
    @NotBlank private String action;  // approve / reject
              private String remark;
}
```

## 三、管理端 VO

```java
// AdminUserVO.java
@Data
public class AdminUserVO {
    private Long          id;
    private String        phone, nickname, avatarUrl, status;
    private Integer       totalPoints, frozenPoints;
    private LocalDateTime createdAt, lastLoginAt;
}

// AdminSkillVO.java
@Data
public class AdminSkillVO {
    private Long          id;
    private String        name, coverImageUrl, status, rejectReason;
    private BigDecimal    price;
    private Boolean       isFree;
    private Long          creatorId;
    private LocalDateTime createdAt, auditedAt;
}

// AdminOrderVO.java
@Data
public class AdminOrderVO {
    private Long          id;
    private String        orderNo, status, paymentMethod;
    private Long          userId;
    private BigDecimal    totalAmount, cashAmount;
    private Integer       pointsUsed;
    private LocalDateTime createdAt, paidAt;
}

// DashboardVO.java
@Data
public class DashboardVO {
    private Long       totalUsers, todayNewUsers, activeUsersLast7d;
    private BigDecimal totalRevenue, revenueToday;
    private Long       totalOrders, ordersToday;
    private Long       totalSkills, pendingAuditSkills, totalDownloads;
}
```

---
**文档版本**：v1.0 | **创建日期**：2026-03-16