Initial commit

2026-03-17 12:09:43 +08:00
commit 70bedcf241
211 changed files with 31464 additions and 0 deletions
--- a/后端架构设计/10-管理后台-part3-Controller.md
+++ b/后端架构设计/10-管理后台-part3-Controller.md
@@ -0,0 +1,157 @@
+# 管理后台开发文档 - Part 3（AdminController）
+
+## AdminController.java
+
+```java
+package com.openclaw.controller.admin;
+
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.openclaw.common.Result;
+import com.openclaw.dto.admin.*;
+import com.openclaw.entity.PointsRule;
+import com.openclaw.service.admin.AdminService;
+import com.openclaw.util.UserContext;
+import com.openclaw.vo.admin.*;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.*;
+import java.util.List;
+
+@RestController
+@RequestMapping("/api/admin")
+@RequiredArgsConstructor
+public class AdminController {
+
+    private final AdminService adminService;
+
+    // ==================== 数据看板 ====================
+
+    @GetMapping("/dashboard")
+    @PreAuthorize("hasAnyRole('ADMIN','OPERATOR')")
+    public Result<DashboardVO> dashboard() {
+        return Result.ok(adminService.getDashboard());
+    }
+
+    // ==================== 用户管理 ====================
+
+    @GetMapping("/users")
+    @PreAuthorize("hasAnyRole('ADMIN','OPERATOR')")
+    public Result<IPage<AdminUserVO>> listUsers(AdminUserQueryDTO query) {
+        return Result.ok(adminService.listUsers(query));
+    }
+
+    @GetMapping("/users/{userId}")
+    @PreAuthorize("hasAnyRole('ADMIN','OPERATOR')")
+    public Result<AdminUserVO> getUser(@PathVariable Long userId) {
+        return Result.ok(adminService.getUserDetail(userId));
+    }
+
+    @PostMapping("/users/{userId}/ban")
+    @PreAuthorize("hasRole('ADMIN')")
+    public Result<Void> banUser(
+            @PathVariable Long userId,
+            @RequestParam(required = false) String reason) {
+        adminService.banUser(userId, reason);
+        return Result.ok();
+    }
+
+    @PostMapping("/users/{userId}/unban")
+    @PreAuthorize("hasRole('ADMIN')")
+    public Result<Void> unbanUser(@PathVariable Long userId) {
+        adminService.unbanUser(userId);
+        return Result.ok();
+    }
+
+    @PostMapping("/users/{userId}/points")
+    @PreAuthorize("hasRole('ADMIN')")
+    public Result<Void> adjustPoints(
+            @PathVariable Long userId,
+            @Valid @RequestBody AdjustPointsDTO dto) {
+        adminService.adjustPoints(userId, dto.getDelta(), dto.getRemark());
+        return Result.ok();
+    }
+
+    // ==================== Skill 审核 ====================
+
+    @GetMapping("/skills")
+    @PreAuthorize("hasAnyRole('ADMIN','OPERATOR','AUDITOR')")
+    public Result<IPage<AdminSkillVO>> listSkills(AdminSkillQueryDTO query) {
+        return Result.ok(adminService.listSkills(query));
+    }
+
+    @PostMapping("/skills/audit")
+    @PreAuthorize("hasAnyRole('ADMIN','AUDITOR')")
+    public Result<Void> auditSkill(@Valid @RequestBody SkillAuditDTO dto) {
+        adminService.auditSkill(dto, UserContext.getUserId());
+        return Result.ok();
+    }
+
+    @PostMapping("/skills/{skillId}/offline")
+    @PreAuthorize("hasAnyRole('ADMIN','OPERATOR')")
+    public Result<Void> offlineSkill(
+            @PathVariable Long skillId,
+            @RequestParam(required = false) String reason) {
+        adminService.offlineSkill(skillId, reason);
+        return Result.ok();
+    }
+
+    // ==================== 订单管理 ====================
+
+    @GetMapping("/orders")
+    @PreAuthorize("hasAnyRole('ADMIN','OPERATOR','FINANCE')")
+    public Result<IPage<AdminOrderVO>> listOrders(AdminOrderQueryDTO query) {
+        return Result.ok(adminService.listOrders(query));
+    }
+
+    @PostMapping("/refunds/{refundId}/process")
+    @PreAuthorize("hasAnyRole('ADMIN','FINANCE')")
+    public Result<Void> processRefund(
+            @PathVariable Long refundId,
+            @Valid @RequestBody RefundProcessDTO dto) {
+        adminService.processRefund(
+            refundId, dto.getAction(), dto.getRemark(), UserContext.getUserId());
+        return Result.ok();
+    }
+
+    // ==================== 积分规则 ====================
+
+    @GetMapping("/points-rules")
+    @PreAuthorize("hasAnyRole('ADMIN','OPERATOR')")
+    public Result<List<PointsRule>> listRules() {
+        return Result.ok(adminService.listPointsRules());
+    }
+
+    @PutMapping("/points-rules/{ruleId}")
+    @PreAuthorize("hasRole('ADMIN')")
+    public Result<Void> updateRule(
+            @PathVariable Long ruleId,
+            @RequestParam int points) {
+        adminService.updatePointsRule(ruleId, points);
+        return Result.ok();
+    }
+}
+```
+
+---
+
+## API 汇总
+
+| 方法 | 路径 | 说明 | 权限 |
+|------|------|------|------|
+| GET  | /api/admin/dashboard | 数据看板 | ADMIN/OPERATOR |
+| GET  | /api/admin/users | 用户列表 | ADMIN/OPERATOR |
+| GET  | /api/admin/users/{id} | 用户详情 | ADMIN/OPERATOR |
+| POST | /api/admin/users/{id}/ban | 封禁用户 | ADMIN |
+| POST | /api/admin/users/{id}/unban | 解封用户 | ADMIN |
+| POST | /api/admin/users/{id}/points | 调整积分 | ADMIN |
+| GET  | /api/admin/skills | Skill列表 | ADMIN/OPERATOR/AUDITOR |
+| POST | /api/admin/skills/audit | Skill审核 | ADMIN/AUDITOR |
+| POST | /api/admin/skills/{id}/offline | Skill下架 | ADMIN/OPERATOR |
+| GET  | /api/admin/orders | 订单列表 | ADMIN/OPERATOR/FINANCE |
+| POST | /api/admin/refunds/{id}/process | 处理退款 | ADMIN/FINANCE |
+| GET  | /api/admin/points-rules | 积分规则列表 | ADMIN/OPERATOR |
+| PUT  | /api/admin/points-rules/{id} | 更新积分规则 | ADMIN |
+
+---
+**文档版本**：v1.0 | **创建日期**：2026-03-16