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

# 管理后台开发文档 - 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