think-plugs-recorder/CONTROLLER_ANNOTATION_EXAMPLE.md

# 控制器方法注释示例

think-plugs-recorder 中间件可以自动读取控制器方法的注释来获取准确的操作类型和描述，提供更精确的操作记录。

## 支持的注释格式

### 1. 使用专用注解

#### @operation - 推荐使用
```php
<?php
class UserController extends Controller
{
    /**
     * @operation 创建用户
     */
    public function save()
    {
        // 保存用户逻辑
    }

    /**
     * @operation 删除用户
     */
    public function delete()
    {
        // 删除用户逻辑  
    }

    /**
     * @operation 导出用户数据
     */
    public function export()
    {
        // 导出逻辑
    }
}
```

#### @recorder - 专用于记录插件
```php
/**
 * @recorder 审核用户申请
 */
public function audit()
{
    // 审核逻辑
}

/**
 * @recorder 批量启用用户
 */
public function batchEnable()
{
    // 批量启用逻辑
}
```

#### @record_type - 仅指定操作类型
```php
/**
 * @record_type 更新
 */
public function updateProfile()
{
    // 更新个人信息
}
```

#### @action - 通用动作注解
```php
/**
 * @action 发布文章
 */
public function publish()
{
    // 发布文章逻辑
}
```

#### @title - 使用标题作为描述
```php
/**
 * @title 用户密码重置
 */
public function resetPassword()
{
    // 重置密码逻辑
}
```

#### 中文注解
```php
/**
 * @操作类型 创建
 */
public function create()
{
    // 创建逻辑
}

/**
 * @操作描述 生成统计报表
 */
public function generateReport()
{
    // 生成报表逻辑
}
```

### 2. 使用注释首行

如果没有专用注解，插件会尝试解析注释的第一行：

```php
/**
 * 创建新用户
 * 该方法用于创建新的用户账户
 */
public function create()
{
    // 创建用户逻辑
}

/**
 * 删除用户账户
 */
public function delete()
{
    // 删除用户逻辑
}

/**
 * 导出用户列表到Excel
 */
public function exportExcel()
{
    // 导出逻辑
}
```

## 操作类型识别

中间件支持识别以下操作类型关键词：

### 基础操作
- **创建相关**: 创建、新增、添加、新建
- **更新相关**: 更新、修改、编辑、保存  
- **删除相关**: 删除、移除、清除
- **查询相关**: 查看、读取、获取、查询、列表

### 高级操作
- **数据处理**: 导出、导入、上传、下载
- **用户操作**: 登录、登出、注销
- **审核流程**: 审核、审批、通过、拒绝
- **发布管理**: 发布、取消发布
- **状态管理**: 启用、禁用、开启、关闭
- **内容管理**: 排序、移动、复制
- **搜索功能**: 搜索、检索、筛选
- **分析统计**: 统计、分析、报表

## 实际应用示例

### 用户管理控制器
```php
<?php
namespace app\admin\controller;

use think\admin\Controller;

class UserController extends Controller
{
    /**
     * @operation 查看用户列表
     */
    public function index()
    {
        // 用户列表逻辑
    }

    /**
     * @operation 创建用户
     */
    public function add()
    {
        // 添加用户页面
    }

    /**
     * @operation 保存用户信息
     */
    public function save()
    {
        // 保存用户逻辑
    }

    /**
     * @operation 编辑用户
     */
    public function edit()
    {
        // 编辑用户页面
    }

    /**
     * @operation 删除用户
     */
    public function delete()
    {
        // 删除用户逻辑
    }

    /**
     * @operation 批量启用用户
     */
    public function enable()
    {
        // 批量启用逻辑
    }

    /**
     * @operation 导出用户数据
     */
    public function export()
    {
        // 导出Excel
    }

    /**
     * @operation 重置用户密码
     */
    public function resetPassword()
    {
        // 重置密码逻辑
    }
}
```

### 订单管理控制器
```php
<?php
namespace app\admin\controller;

use think\admin\Controller;

class OrderController extends Controller
{
    /**
     * @operation 查看订单列表
     */
    public function index()
    {
        // 订单列表
    }

    /**
     * @operation 查看订单详情
     */
    public function detail()
    {
        // 订单详情
    }

    /**
     * @operation 审核订单
     */
    public function audit()
    {
        // 审核订单
    }

    /**
     * @operation 发货处理
     */
    public function ship()
    {
        // 发货逻辑
    }

    /**
     * @operation 取消订单
     */
    public function cancel()
    {
        // 取消订单
    }

    /**
     * @operation 生成订单报表
     */
    public function report()
    {
        // 生成报表
    }
}
```

### 内容管理控制器
```php
<?php
namespace app\admin\controller;

use think\admin\Controller;

class ArticleController extends Controller
{
    /**
     * @recorder 创建文章
     */
    public function create()
    {
        // 创建文章
    }

    /**
     * @recorder 发布文章
     */
    public function publish()
    {
        // 发布文章
    }

    /**
     * @recorder 撤回文章
     */
    public function revoke()
    {
        // 撤回发布
    }

    /**
     * @recorder 置顶文章
     */
    public function setTop()
    {
        // 设置置顶
    }
}
```

## 优先级说明

中间件按以下优先级获取操作信息：

1. **专用注解** (最高优先级)
   - @operation、@recorder、@record_type 等专用注解
   
2. **通用注解** 
   - @action、@title、@desc、@description 等通用注解
   
3. **注释首行**
   - 解析注释第一行内容
   
4. **路由特征**
   - 根据URL路径特征判断 (export、import、login等)
   
5. **HTTP方法**
   - 根据请求方法推断 (GET->读取, POST->创建等)

## 注意事项

1. **注释格式**: 使用标准的PHPDoc格式注释
2. **操作类型**: 建议使用中文操作类型，更直观
3. **描述长度**: 操作描述建议控制在100字符以内
4. **关键词匹配**: 操作类型会自动匹配预定义关键词
5. **性能考虑**: 注释解析使用反射，有轻微性能开销，但可接受

## 配置示例

如果要在项目中全面使用注释驱动的操作记录，建议的配置：

```php
// config/recorder.php
return [
    'enabled' => true,
    'auto_record' => [
        'enabled' => true,
        'exclude_operations' => [], // 不排除任何操作，全部记录
        'exclude_controllers' => ['captcha', 'upload'], // 排除验证码和上传控制器
    ],
    // ...其他配置
];
```

通过合理使用方法注释，可以让操作记录更加准确和有意义，为系统审计和分析提供更好的数据支持。