---
name: backend-gen-api-controller
description: Generate API controller for madong module前台API控制器. Supports both app (main project) and plugin targets. Creates controller extending Base class with OpenAPI attributes and standard REST endpoints for public/member access.
globs:
  - "app/api/controller/**/*.php"
  - "plugin/**/app/api/controller/**/*.php"
---

# Generate API Controller (前台 API 控制器)

Create API controller for module前台用户访问).

## File Location

**App (主项目):**
```
app/api/controller/{module}/{Model}Controller.php
```

**Plugin (插件):**
```
plugin/{plugin}/app/api/controller/{module}/{Model}Controller.php
```

## Target Variables

| 变量 | App | Plugin |
|------|-----|--------|
| `{prefix}` | `` (空) | `plugin\{Plugin}` |
| `{ns}` | `app` | `plugin\{Plugin}\app` |
| `{service_ns}` | `app\service\api` | `plugin\{Plugin}\app\service\api` |

## API Controller Features

- **继承 Base**: 继承 `app\api\controller\Base` 基类
- **无需权限验证**: 不使用 PermissionMiddleware
- **支持会员认证**: 认证属性和中间件必须先以当前项目 `app/api` 的实际实现为准。当前项目已核对的 `app/api` 控制器中未发现 `MemberAuthRequired` 的实际使用，不应直接套用该属性。
- **轻量级**: 只返回必要的数据
- **雪花ID**: 主键使用雪花ID

## API Controller Template

```php
<?php

declare(strict_types=1);
/**
 *+------------------
 * madong
 *+------------------
 * Copyright (c) https://gitee.com/motion-code All rights reserved.
 *+------------------
 * Author: Mr. April (405784684@qq.com)
 *+------------------
 */

namespace {ns}\api\controller\{module};

use app\api\controller\Base;
use app\api\attribute\MemberAuthRequired;
use {service_ns}\{module}\{Model}Service;
use core\tool\Json;
use madong\swagger\annotation\response\SimpleResponse;
use madong\swagger\attribute\AllowAnonymous;
use OpenApi\Attributes as OA;
use Webman\Http\Request;
use Webman\Http\Response;

/**
 * {Model}前台API控制器
 */
#[OA\Tag(name: '{Module}模块')]
final class {Model}Controller extends Base
{
    public function __construct(private {Model}Service $service)
    {
    }

    /**
     * 获取列表
     */
    #[OA\Get(
        path: '/{api_prefix}',
        summary: '获取{Model}列表',
        tags: ['{Module}模块'],
        responses: [
            new OA\Response(response: 200, description: '获取成功'),
        ]
    )]
    #[AllowAnonymous(requireToken: false, requirePermission: false)]
    #[SimpleResponse(schema: [], example: [])]
    public function index(Request $request): Response
    {
        try {
            $page    = (int) $request->input('page', 1);
            $limit   = (int) $request->input('limit', 20);
            $where   = $this->buildWhere($request);
            $order   = $request->input('order', 'id desc');

            $total = $this->service->count($where);
            $list  = $this->service->selectList($where, '*', $page, $limit, $order);

            return Json::success('ok', compact('list', 'total'));
        } catch (\Exception $e) {
            return Json::fail($e->getMessage());
        }
    }

    /**
     * 获取详情
     */
    #[OA\Get(
        path: '/{api_prefix}/{id}',
        summary: '获取{Model}详情',
        tags: ['{Module}模块'],
        parameters: [
            new OA\Parameter(name: 'id', description: '{Model}ID', in: 'path', required: true, schema: new OA\Schema(type: 'integer')),
        ],
        responses: [
            new OA\Response(response: 200, description: '获取成功'),
            new OA\Response(response: 404, description: '不存在'),
        ]
    )]
    #[AllowAnonymous(requireToken: false, requirePermission: false)]
    #[SimpleResponse(schema: [], example: [])]
    public function show(Request $request, int $id): Response
    {
        try {
            $data = $this->service->get($id);
            if (empty($data)) {
                return Json::fail('{Model}不存在', [], 404);
            }
            return Json::success('ok', $data);
        } catch (\Exception $e) {
            return Json::fail($e->getMessage());
        }
    }

    /**
     * 创建{Model}
     */
    #[OA\Post(
        path: '/{api_prefix}',
        summary: '创建{Model}',
        tags: ['{Module}模块'],
        requestBody: new OA\RequestBody(
            required: true,
            content: new OA\JsonContent(
                required: [{required_fields}],
                properties: [
                    {form_fields}
                ]
            )
        ),
        responses: [
            new OA\Response(response: 200, description: '创建成功'),
            new OA\Response(response: 401, description: '未登录'),
        ]
    )]
    #[MemberAuthRequired]
    #[SimpleResponse(schema: [], example: [])]
    public function store(Request $request): Response
    {
        try {
            $data  = $request->post();
            $model = $this->service->save($data);

            $pk = $model->getPk();
            return Json::success('创建成功', [$pk => $model->getAttribute($pk)]);
        } catch (\Exception $e) {
            return Json::fail($e->getMessage());
        }
    }

    /**
     * 更新{Model}
     */
    #[OA\Put(
        path: '/{api_prefix}/{id}',
        summary: '更新{Model}',
        tags: ['{Module}模块'],
        parameters: [
            new OA\Parameter(name: 'id', description: '{Model}ID', in: 'path', required: true, schema: new OA\Schema(type: 'integer')),
        ],
        responses: [
            new OA\Response(response: 200, description: '更新成功'),
            new OA\Response(response: 401, description: '未登录'),
        ]
    )]
    #[MemberAuthRequired]
    #[SimpleResponse(schema: [], example: [])]
    public function update(Request $request, int $id): Response
    {
        try {
            $data = $request->post();
            $this->service->update($id, $data);
            return Json::success('更新成功');
        } catch (\Exception $e) {
            return Json::fail($e->getMessage());
        }
    }

    /**
     * 删除{Model}
     */
    #[OA\Delete(
        path: '/{api_prefix}/{id}',
        summary: '删除{Model}',
        tags: ['{Module}模块'],
        parameters: [
            new OA\Parameter(name: 'id', description: '{Model}ID', in: 'path', required: true, schema: new OA\Schema(type: 'integer')),
        ],
        responses: [
            new OA\Response(response: 200, description: '删除成功'),
            new OA\Response(response: 401, description: '未登录'),
        ]
    )]
    #[MemberAuthRequired]
    #[SimpleResponse(schema: [], example: [])]
    public function destroy(Request $request, int $id): Response
    {
        try {
            $this->service->delete($id);
            return Json::success('删除成功');
        } catch (\Exception $e) {
            return Json::fail($e->getMessage());
        }
    }

    /**
     * 构建查询条件
     */
    protected function buildWhere(Request $request): array
    {
        $where = [];

        // 添加常用的查询条件
        $searchFields = [{search_fields}];

        foreach ($searchFields as $field) {
            $value = $request->input($field);
            if ($value !== null && $value !== '') {
                $where[$field] = $value;
            }
        }

        // 状态条件
        if ($request->input('status') !== null) {
            $where['status'] = (int) $request->input('status');
        }

        return $where;
    }
}
```

## Complete Example (App)

```php
<?php

declare(strict_types=1);
/**
 *+------------------
 * madong
 *+------------------
 * Copyright (c) https://gitee.com/motion-code All rights reserved.
 *+------------------
 * Author: Mr. April (405784684@qq.com)
 *+------------------
 */

namespace app\api\controller\question;

use app\api\controller\Base;
use app\api\attribute\MemberAuthRequired;
use app\service\api\question\QuestionService;
use core\tool\Json;
use madong\swagger\annotation\response\SimpleResponse;
use madong\swagger\attribute\AllowAnonymous;
use OpenApi\Attributes as OA;
use Webman\Http\Request;
use Webman\Http\Response;

/**
 * 问题前台API控制器
 */
#[OA\Tag(name: '问答模块')]
final class QuestionController extends Base
{
    public function __construct(private QuestionService $service)
    {
    }

    #[OA\Get(path: '/ask/question', summary: '获取问题列表', tags: ['问答模块'])]
    #[AllowAnonymous(requireToken: false, requirePermission: false)]
    public function index(Request $request): Response
    {
        try {
            $page = (int) $request->input('page', 1);
            $limit = (int) $request->input('limit', 20);
            $where = $this->buildWhere($request);

            $total = $this->service->count($where);
            $list = $this->service->selectList($where, '*', $page, $limit, 'id desc');

            return Json::success('ok', compact('list', 'total'));
        } catch (\Exception $e) {
            return Json::fail($e->getMessage());
        }
    }

    #[OA\Get(path: '/ask/question/{id}', summary: '获取问题详情', tags: ['问答模块'])]
    #[AllowAnonymous(requireToken: false, requirePermission: false)]
    public function show(Request $request, int $id): Response
    {
        try {
            $data = $this->service->get($id);
            if (empty($data)) {
                return Json::fail('问题不存在', [], 404);
            }
            return Json::success('ok', $data);
        } catch (\Exception $e) {
            return Json::fail($e->getMessage());
        }
    }

    #[OA\Post(path: '/ask/question', summary: '发布问题', tags: ['问答模块'])]
    #[MemberAuthRequired]
    public function store(Request $request): Response
    {
        try {
            $data = $request->post();
            $model = $this->service->save($data);
            return Json::success('发布成功', ['id' => $model->id]);
        } catch (\Exception $e) {
            return Json::fail($e->getMessage());
        }
    }

    protected function buildWhere(Request $request): array
    {
        $where = [];
        if ($request->input('category_id')) {
            $where['category_id'] = (int) $request->input('category_id');
        }
        $where['status'] = 1;
        return $where;
    }
}
```

## Complete Example (Plugin)

```php
<?php

declare(strict_types=1);
/**
 *+------------------
 * madong
 *+------------------
 * Copyright (c) https://gitee.com/motion-code All rights reserved.
 *+------------------
 * Author: Mr. April (405784684@qq.com)
 *+------------------
 */

namespace plugin\official\app\api\controller\question;

use app\api\controller\Base;
use app\api\attribute\MemberAuthRequired;
use plugin\official\app\service\api\question\QuestionService;
use core\tool\Json;
use madong\swagger\annotation\response\SimpleResponse;
use madong\swagger\attribute\AllowAnonymous;
use OpenApi\Attributes as OA;
use Webman\Http\Request;
use Webman\Http\Response;

/**
 * 问题前台API控制器
 */
#[OA\Tag(name: '问答模块')]
final class QuestionController extends Base
{
    public function __construct(private QuestionService $service)
    {
    }

    #[OA\Get(path: '/ask/question', summary: '获取问题列表', tags: ['问答模块'])]
    #[AllowAnonymous(requireToken: false, requirePermission: false)]
    public function index(Request $request): Response
    {
        try {
            $page = (int) $request->input('page', 1);
            $limit = (int) $request->input('limit', 20);
            $where = $this->buildWhere($request);

            $total = $this->service->count($where);
            $list = $this->service->selectList($where, '*', $page, $limit, 'id desc');

            return Json::success('ok', compact('list', 'total'));
        } catch (\Exception $e) {
            return Json::fail($e->getMessage());
        }
    }

    // ... 其他方法同上
}
```

## API Path Convention

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/{api_prefix}` | 公开 | 列表（分页） |
| GET | `/{api_prefix}/{id}` | 公开 | 详情 |
| POST | `/{api_prefix}` | 会员 | 创建 |
| PUT | `/{api_prefix}/{id}` | 会员 | 更新 |
| DELETE | `/{api_prefix}/{id}` | 会员 | 删除 |

## Authentication Options

### 公开接口
```php
#[AllowAnonymous(requireToken: false, requirePermission: false)]
```

### 会员专用接口

请先检查当前项目 `app/api` 的真实认证中间件、控制器属性和 token 解析方式，再配置会员认证；不要假设项目一定存在 `MemberAuthRequired`。

## Auto-generation Checklist

When generating API controller:
- [ ] Set correct namespace based on target
- [ ] Import required classes according to the actual project implementation (Base, Json, and verified authentication attributes/middleware)
- [ ] Extend Base controller
- [ ] Inject Service in constructor
- [ ] Add OpenAPI attributes for each action
- [ ] Use appropriate auth attribute (AllowAnonymous or MemberAuthRequired)
- [ ] Implement standard CRUD methods
- [ ] Use proper API path convention
- [ ] Add buildWhere() for query building