datahub/backend/app/Controller/api/v1/RouteGroupController.php

<?php

declare(strict_types=1);

namespace App\Controller\Api\V1;

use App\Controller\AbstractController;
use App\Middleware\AuthMiddleware;
use App\Middleware\PermissionMiddleware;
use App\Model\Route;
use App\Model\RouteGroup;
use App\Service\RouteSyncService;
use Hyperf\DbConnection\Db;
use Hyperf\HttpServer\Annotation\Controller;
use Hyperf\HttpServer\Annotation\Middleware;
use Hyperf\HttpServer\Annotation\RequestMapping;
use OpenApi\Attributes as OA;
use Psr\Http\Message\ResponseInterface;

#[OA\Tag(name: 'Route Groups', description: '路由组管理')]
#[Controller(prefix: "/api/v1/route-groups")]
class RouteGroupController extends AbstractController
{
    /**
     * 路由组列表
     *
     * 返回所有路由组，包含每组的路由数量
     */
    #[OA\Get(
        path: '/route-groups',
        summary: '路由组列表',
        description: '返回所有路由组，包含每组的路由数量',
        security: [['bearerAuth' => []]],
        tags: ['Route Groups'],
        responses: [
            new OA\Response(
                response: 200,
                description: '获取成功',
                content: new OA\JsonContent(properties: [
                    new OA\Property(property: 'code', type: 'integer', example: 0),
                    new OA\Property(property: 'message', type: 'string', example: '获取成功'),
                    new OA\Property(property: 'data', type: 'array', items: new OA\Items(properties: [
                        new OA\Property(property: 'id', type: 'integer', example: 1),
                        new OA\Property(property: 'name', type: 'string', example: 'user-management'),
                        new OA\Property(property: 'label', type: 'string', nullable: true, example: '用户管理'),
                        new OA\Property(property: 'description', type: 'string', nullable: true, example: '用户相关路由'),
                        new OA\Property(property: 'sort_order', type: 'integer', example: 0),
                        new OA\Property(property: 'routes_count', type: 'integer', example: 5),
                        new OA\Property(property: 'created_at', type: 'string', format: 'date-time'),
                    ])),
                ])
            ),
            new OA\Response(response: 401, description: '未认证', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')),
        ]
    )]
    #[RequestMapping(path: "", methods: "GET")]
    #[Middleware(AuthMiddleware::class)]
    #[Middleware(PermissionMiddleware::class)]
    public function index(): array
    {
        $groups = RouteGroup::query()
            ->withCount('routes')
            ->orderBy('sort_order')
            ->orderBy('id')
            ->get();

        return [
            'code' => 0,
            'message' => '获取成功',
            'data' => $groups,
        ];
    }

    /**
     * 创建路由组
     */
    #[OA\Post(
        path: '/route-groups',
        summary: '创建路由组',
        security: [['bearerAuth' => []]],
        tags: ['Route Groups'],
        requestBody: new OA\RequestBody(
            required: true,
            content: new OA\JsonContent(
                required: ['name'],
                properties: [
                    new OA\Property(property: 'name', type: 'string', maxLength: 100, example: 'user-management'),
                    new OA\Property(property: 'label', type: 'string', maxLength: 200, nullable: true, example: '用户管理'),
                    new OA\Property(property: 'description', type: 'string', nullable: true, example: '用户相关路由'),
                    new OA\Property(property: 'sort_order', type: 'integer', default: 0, example: 0),
                ]
            )
        ),
        responses: [
            new OA\Response(
                response: 200,
                description: '创建成功',
                content: new OA\JsonContent(properties: [
                    new OA\Property(property: 'code', type: 'integer', example: 0),
                    new OA\Property(property: 'message', type: 'string', example: '创建成功'),
                    new OA\Property(property: 'data', properties: [
                        new OA\Property(property: 'id', type: 'integer', example: 1),
                        new OA\Property(property: 'name', type: 'string', example: 'user-management'),
                        new OA\Property(property: 'label', type: 'string', nullable: true, example: '用户管理'),
                        new OA\Property(property: 'description', type: 'string', nullable: true),
                        new OA\Property(property: 'sort_order', type: 'integer', example: 0),
                        new OA\Property(property: 'created_at', type: 'string', format: 'date-time'),
                    ], type: 'object'),
                ])
            ),
            new OA\Response(response: 400, description: '参数校验失败或名称重复', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')),
            new OA\Response(response: 401, description: '未认证', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')),
        ]
    )]
    #[RequestMapping(path: "", methods: "POST")]
    #[Middleware(AuthMiddleware::class)]
    #[Middleware(PermissionMiddleware::class)]
    public function store(): ResponseInterface|array
    {
        $name = $this->request->input('name');
        $label = $this->request->input('label');
        $description = $this->request->input('description');
        $sort_order = $this->request->input('sort_order');

        // 校验 name
        if (!is_string($name) || trim($name) === '') {
            return $this->response->json([
                'code' => 400,
                'message' => 'name 不能为空',
            ])->withStatus(400);
        }

        $name = trim($name);
        if (strlen($name) > 100) {
            return $this->response->json([
                'code' => 400,
                'message' => 'name 长度不能超过 100 个字符',
            ])->withStatus(400);
        }

        if (RouteGroup::query()->where('name', $name)->exists()) {
            return $this->response->json([
                'code' => 400,
                'message' => '路由组名称已存在',
            ])->withStatus(400);
        }

        // 校验 label
        if ($label !== null && $label !== '') {
            if (!is_string($label)) {
                return $this->response->json([
                    'code' => 400,
                    'message' => 'label 必须为字符串',
                ])->withStatus(400);
            }
            $label = trim($label);
            if (strlen($label) > 200) {
                return $this->response->json([
                    'code' => 400,
                    'message' => 'label 长度不能超过 200 个字符',
                ])->withStatus(400);
            }
        } else {
            $label = null;
        }

        // 校验 sort_order
        if ($sort_order !== null && $sort_order !== '') {
            if (!is_numeric($sort_order)) {
                return $this->response->json([
                    'code' => 400,
                    'message' => 'sort_order 必须为整数',
                ])->withStatus(400);
            }
            $sort_order = (int) $sort_order;
        } else {
            $sort_order = 0;
        }

        $group = RouteGroup::query()->create([
            'name' => $name,
            'label' => $label,
            'description' => is_string($description) ? trim($description) : null,
            'sort_order' => $sort_order,
        ]);

        return [
            'code' => 0,
            'message' => '创建成功',
            'data' => $group,
        ];
    }

    /**
     * 更新路由组
     *
     * @param int $id 路由组 ID
     */
    #[OA\Put(
        path: '/route-groups/{id}',
        summary: '更新路由组',
        security: [['bearerAuth' => []]],
        tags: ['Route Groups'],
        parameters: [
            new OA\Parameter(name: 'id', in: 'path', required: true, description: '路由组 ID', schema: new OA\Schema(type: 'integer')),
        ],
        requestBody: new OA\RequestBody(
            required: true,
            content: new OA\JsonContent(properties: [
                new OA\Property(property: 'name', type: 'string', maxLength: 100, example: 'user-management'),
                new OA\Property(property: 'label', type: 'string', maxLength: 200, nullable: true, example: '用户管理'),
                new OA\Property(property: 'description', type: 'string', nullable: true, example: '用户相关路由'),
                new OA\Property(property: 'sort_order', type: 'integer', example: 0),
            ])
        ),
        responses: [
            new OA\Response(
                response: 200,
                description: '更新成功',
                content: new OA\JsonContent(properties: [
                    new OA\Property(property: 'code', type: 'integer', example: 0),
                    new OA\Property(property: 'message', type: 'string', example: '更新成功'),
                    new OA\Property(property: 'data', properties: [
                        new OA\Property(property: 'id', type: 'integer', example: 1),
                        new OA\Property(property: 'name', type: 'string', example: 'user-management'),
                        new OA\Property(property: 'label', type: 'string', nullable: true, example: '用户管理'),
                        new OA\Property(property: 'description', type: 'string', nullable: true),
                        new OA\Property(property: 'sort_order', type: 'integer', example: 0),
                        new OA\Property(property: 'created_at', type: 'string', format: 'date-time'),
                    ], type: 'object'),
                ])
            ),
            new OA\Response(response: 400, description: '参数校验失败或名称重复', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')),
            new OA\Response(response: 401, description: '未认证', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')),
            new OA\Response(response: 404, description: '路由组不存在', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')),
        ]
    )]
    #[RequestMapping(path: "{id}", methods: "PUT")]
    #[Middleware(AuthMiddleware::class)]
    #[Middleware(PermissionMiddleware::class)]
    public function update(int $id): ResponseInterface|array
    {
        $group = RouteGroup::query()->find($id);

        if (!$group) {
            return $this->response->json([
                'code' => 404,
                'message' => '路由组不存在',
            ])->withStatus(404);
        }

        $name = $this->request->input('name');
        $label = $this->request->input('label');
        $description = $this->request->input('description');
        $sort_order = $this->request->input('sort_order');
        $updates = [];

        if ($name !== null) {
            if (!is_string($name) || trim($name) === '') {
                return $this->response->json([
                    'code' => 400,
                    'message' => 'name 不能为空',
                ])->withStatus(400);
            }
            $name = trim($name);
            if (strlen($name) > 100) {
                return $this->response->json([
                    'code' => 400,
                    'message' => 'name 长度不能超过 100 个字符',
                ])->withStatus(400);
            }
            if (RouteGroup::query()->where('name', $name)->where('id', '!=', $group->id)->exists()) {
                return $this->response->json([
                    'code' => 400,
                    'message' => '路由组名称已存在',
                ])->withStatus(400);
            }
            $updates['name'] = $name;
        }

        if ($label !== null) {
            if (!is_string($label)) {
                return $this->response->json([
                    'code' => 400,
                    'message' => 'label 必须为字符串',
                ])->withStatus(400);
            }
            $updates['label'] = trim($label);
        }

        if ($description !== null) {
            $updates['description'] = is_string($description) ? trim($description) : null;
        }

        if ($sort_order !== null) {
            if (!is_numeric($sort_order)) {
                return $this->response->json([
                    'code' => 400,
                    'message' => 'sort_order 必须为整数',
                ])->withStatus(400);
            }
            $updates['sort_order'] = (int) $sort_order;
        }

        if ($updates === []) {
            return $this->response->json([
                'code' => 400,
                'message' => '缺少可更新字段',
            ])->withStatus(400);
        }

        $group->fill($updates);
        $group->save();
        $group->refresh();

        return [
            'code' => 0,
            'message' => '更新成功',
            'data' => $group,
        ];
    }

    /**
     * 删除路由组
     *
     * 组内路由 group_id 自动设为 NULL（ON DELETE SET NULL）
     * role_route_groups 关联自动级联删除（ON DELETE CASCADE）
     *
     * @param int $id 路由组 ID
     */
    #[OA\Delete(
        path: '/route-groups/{id}',
        summary: '删除路由组',
        description: '删除路由组，组内路由 group_id 自动设为 NULL，role_route_groups 关联自动级联删除',
        security: [['bearerAuth' => []]],
        tags: ['Route Groups'],
        parameters: [
            new OA\Parameter(name: 'id', in: 'path', required: true, description: '路由组 ID', schema: new OA\Schema(type: 'integer')),
        ],
        responses: [
            new OA\Response(
                response: 200,
                description: '删除成功',
                content: new OA\JsonContent(properties: [
                    new OA\Property(property: 'code', type: 'integer', example: 0),
                    new OA\Property(property: 'message', type: 'string', example: '删除成功'),
                ])
            ),
            new OA\Response(response: 401, description: '未认证', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')),
            new OA\Response(response: 404, description: '路由组不存在', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')),
        ]
    )]
    #[RequestMapping(path: "{id}", methods: "DELETE")]
    #[Middleware(AuthMiddleware::class)]
    #[Middleware(PermissionMiddleware::class)]
    public function destroy(int $id): ResponseInterface|array
    {
        $group = RouteGroup::query()->find($id);

        if (!$group) {
            return $this->response->json([
                'code' => 404,
                'message' => '路由组不存在',
            ])->withStatus(404);
        }

        $group->delete();

        return [
            'code' => 0,
            'message' => '删除成功',
        ];
    }

    /**
     * 全部路由列表
     *
     * 含分组信息，支持按 group_id 筛选（传 0 或 "ungrouped" 筛选未分组路由）
     */
    #[OA\Get(
        path: '/routes',
        summary: '路由列表',
        description: '获取全部路由列表，含分组信息，支持按 group_id、method、path 筛选',
        security: [['bearerAuth' => []]],
        tags: ['Route Groups'],
        parameters: [
            new OA\Parameter(name: 'group_id', in: 'query', required: false, description: '路由组 ID，传 0 或 "ungrouped" 筛选未分组路由', schema: new OA\Schema(type: 'string')),
            new OA\Parameter(name: 'method', in: 'query', required: false, description: 'HTTP 方法筛选', schema: new OA\Schema(type: 'string')),
            new OA\Parameter(name: 'path', in: 'query', required: false, description: '路径模糊搜索', schema: new OA\Schema(type: 'string')),
        ],
        responses: [
            new OA\Response(
                response: 200,
                description: '获取成功',
                content: new OA\JsonContent(properties: [
                    new OA\Property(property: 'code', type: 'integer', example: 0),
                    new OA\Property(property: 'message', type: 'string', example: '获取成功'),
                    new OA\Property(property: 'data', type: 'array', items: new OA\Items(properties: [
                        new OA\Property(property: 'id', type: 'integer', example: 1),
                        new OA\Property(property: 'method', type: 'string', example: 'GET'),
                        new OA\Property(property: 'path', type: 'string', example: '/api/v1/users'),
                        new OA\Property(property: 'group_id', type: 'integer', nullable: true, example: 1),
                        new OA\Property(property: 'group', nullable: true, properties: [
                            new OA\Property(property: 'id', type: 'integer', example: 1),
                            new OA\Property(property: 'name', type: 'string', example: 'user-management'),
                            new OA\Property(property: 'label', type: 'string', nullable: true, example: '用户管理'),
                        ], type: 'object'),
                    ])),
                ])
            ),
            new OA\Response(response: 401, description: '未认证', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')),
        ]
    )]
    #[RequestMapping(path: "/api/v1/routes", methods: "GET")]
    #[Middleware(AuthMiddleware::class)]
    #[Middleware(PermissionMiddleware::class)]
    public function routes(): array
    {
        $query = Route::query()->with('group');

        // 按 group_id 筛选
        $group_id = $this->request->input('group_id');
        if ($group_id !== null && $group_id !== '') {
            if ($group_id === '0' || $group_id === 'ungrouped') {
                // 未分组路由
                $query->whereNull('group_id');
            } else {
                $query->where('group_id', (int) $group_id);
            }
        }

        // 按 method 筛选
        $method = $this->request->input('method');
        if ($method !== null && $method !== '') {
            $query->where('method', strtoupper($method));
        }

        // 按 path 模糊搜索
        $path = $this->request->input('path');
        if ($path !== null && $path !== '') {
            $query->where('path', 'like', '%' . $path . '%');
        }

        $routes = $query->orderBy('path')->orderBy('method')->get();

        return [
            'code' => 0,
            'message' => '获取成功',
            'data' => $routes,
        ];
    }

    /**
     * 将路由分配到路由组
     *
     * 传 group_id=null 表示从分组中移出
     *
     * @param int $id 路由 ID
     */
    #[OA\Put(
        path: '/routes/{id}/group',
        summary: '分配路由到路由组',
        description: '将路由分配到指定路由组，传 group_id=null 表示从分组中移出',
        security: [['bearerAuth' => []]],
        tags: ['Route Groups'],
        parameters: [
            new OA\Parameter(name: 'id', in: 'path', required: true, description: '路由 ID', schema: new OA\Schema(type: 'integer')),
        ],
        requestBody: new OA\RequestBody(
            required: true,
            content: new OA\JsonContent(
                required: ['group_id'],
                properties: [
                    new OA\Property(property: 'group_id', type: 'integer', nullable: true, description: '路由组 ID，传 null 移出分组', example: 1),
                ]
            )
        ),
        responses: [
            new OA\Response(
                response: 200,
                description: '分配成功',
                content: new OA\JsonContent(properties: [
                    new OA\Property(property: 'code', type: 'integer', example: 0),
                    new OA\Property(property: 'message', type: 'string', example: '分配成功'),
                    new OA\Property(property: 'data', properties: [
                        new OA\Property(property: 'id', type: 'integer', example: 1),
                        new OA\Property(property: 'method', type: 'string', example: 'GET'),
                        new OA\Property(property: 'path', type: 'string', example: '/api/v1/users'),
                        new OA\Property(property: 'group_id', type: 'integer', nullable: true, example: 1),
                        new OA\Property(property: 'group', nullable: true, properties: [
                            new OA\Property(property: 'id', type: 'integer', example: 1),
                            new OA\Property(property: 'name', type: 'string', example: 'user-management'),
                            new OA\Property(property: 'label', type: 'string', nullable: true, example: '用户管理'),
                        ], type: 'object'),
                    ], type: 'object'),
                ])
            ),
            new OA\Response(response: 400, description: '参数校验失败', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')),
            new OA\Response(response: 401, description: '未认证', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')),
            new OA\Response(response: 404, description: '路由或目标路由组不存在', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')),
        ]
    )]
    #[RequestMapping(path: "/api/v1/routes/{id}/group", methods: "PUT")]
    #[Middleware(AuthMiddleware::class)]
    #[Middleware(PermissionMiddleware::class)]
    public function assignRouteGroup(int $id): ResponseInterface|array
    {
        $route = Route::query()->find($id);

        if (!$route) {
            return $this->response->json([
                'code' => 404,
                'message' => '路由不存在',
            ])->withStatus(404);
        }

        // group_id 可以为 null（移出分组）或整数（分配到指定分组）
        $body = $this->request->getParsedBody();
        if (!array_key_exists('group_id', $body)) {
            return $this->response->json([
                'code' => 400,
                'message' => '缺少 group_id 参数',
            ])->withStatus(400);
        }

        $group_id = $body['group_id'];

        if ($group_id !== null) {
            if (!is_numeric($group_id)) {
                return $this->response->json([
                    'code' => 400,
                    'message' => 'group_id 必须为整数或 null',
                ])->withStatus(400);
            }

            $group_id = (int) $group_id;

            // 校验目标路由组存在
            if (!RouteGroup::query()->where('id', $group_id)->exists()) {
                return $this->response->json([
                    'code' => 404,
                    'message' => '目标路由组不存在',
                ])->withStatus(404);
            }
        }

        $route->group_id = $group_id;
        $route->save();
        $route->load('group');

        return [
            'code' => 0,
            'message' => $group_id === null ? '已从分组中移出' : '分配成功',
            'data' => $route,
        ];
    }

    /**
     * 批量同步路由到路由组
     *
     * 替换式同步：先清空旧归属，再设置新归属，事务保证原子性
     *
     * @param int $id 路由组 ID
     */
    #[OA\Put(
        path: '/route-groups/{id}/routes',
        summary: '批量同步路由到路由组',
        description: '替换式同步：提交 route_ids 数组，组内路由将被完全替换为指定路由。提交空数组清空组内所有路由。若指定路由已属于其他组，将自动从原组移出。',
        security: [['bearerAuth' => []]],
        tags: ['Route Groups'],
        parameters: [
            new OA\Parameter(name: 'id', in: 'path', required: true, description: '路由组 ID', schema: new OA\Schema(type: 'integer')),
        ],
        requestBody: new OA\RequestBody(
            required: true,
            content: new OA\JsonContent(
                required: ['route_ids'],
                properties: [
                    new OA\Property(property: 'route_ids', type: 'array', items: new OA\Items(type: 'integer'), description: '路由 ID 数组，空数组表示清空', example: [1, 2, 3]),
                ]
            )
        ),
        responses: [
            new OA\Response(
                response: 200,
                description: '同步成功',
                content: new OA\JsonContent(properties: [
                    new OA\Property(property: 'code', type: 'integer', example: 0),
                    new OA\Property(property: 'message', type: 'string', example: '同步成功'),
                    new OA\Property(property: 'data', properties: [
                        new OA\Property(property: 'id', type: 'integer', example: 1),
                        new OA\Property(property: 'name', type: 'string', example: 'user-management'),
                        new OA\Property(property: 'label', type: 'string', nullable: true, example: '用户管理'),
                        new OA\Property(property: 'routes_count', type: 'integer', example: 5),
                    ], type: 'object'),
                ])
            ),
            new OA\Response(response: 401, description: '未认证', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')),
            new OA\Response(response: 404, description: '路由组不存在', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')),
            new OA\Response(response: 422, description: '参数校验失败', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')),
        ]
    )]
    #[RequestMapping(path: "{id}/routes", methods: "PUT")]
    #[Middleware(AuthMiddleware::class)]
    #[Middleware(PermissionMiddleware::class)]
    public function syncRoutes(int $id): ResponseInterface|array
    {
        $group = RouteGroup::query()->find($id);

        if (!$group) {
            return $this->response->json([
                'code' => 404,
                'message' => '路由组不存在',
            ])->withStatus(404);
        }

        $body = $this->request->getParsedBody();
        if (!array_key_exists('route_ids', $body) || !is_array($body['route_ids'])) {
            return $this->response->json([
                'code' => 422,
                'message' => 'route_ids 必须为数组',
            ])->withStatus(422);
        }

        $route_ids = array_values(array_map('intval', array_filter($body['route_ids'], 'is_numeric')));

        Db::transaction(function () use ($id, $route_ids): void {
            // 清空旧归属
            Route::query()->where('group_id', $id)->update(['group_id' => null]);

            // 设置新归属
            if ($route_ids !== []) {
                Route::query()->whereIn('id', $route_ids)->update(['group_id' => $id]);
            }
        });

        $group->loadCount('routes');

        return [
            'code' => 0,
            'message' => '同步成功',
            'data' => $group,
        ];
    }

    /**
     * 同步注解路由到数据库
     *
     * 将 Hyperf 注解定义的 API 路由同步到 routes 表，管理员专用
     */
    #[OA\Post(
        path: '/routes/sync',
        summary: '同步注解路由到数据库',
        description: '将 Hyperf 注解定义的 API 路由同步到 routes 表，支持重复调用（幂等）',
        security: [['bearerAuth' => []]],
        tags: ['Route Groups'],
        responses: [
            new OA\Response(
                response: 200,
                description: '同步成功',
                content: new OA\JsonContent(properties: [
                    new OA\Property(property: 'code', type: 'integer', example: 0),
                    new OA\Property(property: 'message', type: 'string', example: '同步成功'),
                    new OA\Property(property: 'data', properties: [
                        new OA\Property(property: 'synced', type: 'integer', description: '同步的路由数量', example: 50),
                        new OA\Property(property: 'total', type: 'integer', description: '总路由数量', example: 50),
                    ], type: 'object'),
                ])
            ),
            new OA\Response(response: 401, description: '未认证', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')),
            new OA\Response(response: 403, description: '无权限', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')),
        ]
    )]
    #[RequestMapping(path: "/api/v1/routes/sync", methods: "POST")]
    #[Middleware(AuthMiddleware::class)]
    #[Middleware(PermissionMiddleware::class)]
    public function sync(): array
    {
        $result = $this->container->get(RouteSyncService::class)->sync();

        return [
            'code' => 0,
            'message' => '同步成功',
            'data' => $result,
        ];
    }
}