Initial commit

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

@@ -0,0 +1,127 @@
+# 管理后台开发文档 - 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