number/后端架构设计/10-管理后台-part3-Controller.md

管理后台开发文档 - Part 3（AdminController）

AdminController.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