ulthon_admin/extend/base/common/command/tools/README.md

# Tools 命令命名规范

## 概述

`tools` 目录下的命令是系统级工具命令，主要用于开发调试、系统维护等场景。与普通命令不同，tools 命令有独特的命名规则和目录结构。

## 目录结构

```
 extend/base/common/
 ├── service/
 │   ├── ToolsDbServiceBase.php       # 数据库工具服务
 │   ├── ToolsLogServiceBase.php      # 日志工具服务
 │   └── ToolsBackupServiceBase.php  # 备份工具服务
 └── command/
     └── tools/
         ├── README.md                # 本文件（命名规范说明）
         ├── db/                     # 数据库工具
         │   ├── ToolsDbQueryBase.php   # 基础命令类
         │   ├── ToolsDbExecuteBase.php
         │   └── ...
         ├── http/                    # HTTP 工具
         │   └── ToolsHttpCallBase.php
         └── ...

 app/common/command/
 ├── tools/
 │   ├── db/                       # 数据库工具
 │   │   ├── ToolsDbQuery.php         # 业务命令类
 │   │   ├── ToolsDbExecute.php
 │   │   └── ...
 │   └── http/                     # HTTP 工具
 │       └── ToolsHttpCall.php
 ├── admin/                        # 普通命令（无前缀）
 ├── scheme/
 ├── curd/
 └── ...
```

## 命名规则对比

### 普通命令（admin、scheme、curd 等）

| 项目 | 规则 | 示例 |
|------|------|------|
| 类名 | 无前缀，直接使用功能名称 | `Clear`、`MigrateFileData`、`ViewDebugLog` |
| 命名空间 | `app\common\command\[模块]` | `app\common\command\admin` |
| 命令名称 | `[模块]:[功能]` | `admin:clear`、`admin:migrate-file-data` |
| 目录 | 按模块分组 | `admin/`、`scheme/`、`curd/` |
| Service | 使用现有的 service 层或无 | - |

### Tools 命令（tools 目录）

| 项目 | 规则 | 示例 |
|------|------|------|
| 类名前缀 | `Tools[类型]` | `ToolsDbQuery`、`ToolsLogClear`、`ToolsBackupCreate` |
| 类名后缀 | 基础类加 `Base` | `ToolsDbQueryBase`、`ToolsDbExecuteBase` |
| 命名空间 | `app\common\command\tools\[类型]` | `app\common\command\tools\db` |
| 命令名称 | `tools:[类型]:[功能]` | `tools:db:query`、`tools:db:execute` |
| 目录 | 按工具类型分组（二级） | `tools/db/`、`tools/log/`、`tools/backup/` |
| Service | 专用 Service（base 层加 Base 后缀） | `base\common\service\ToolsDbServiceBase` |

## 命名规则详解

### 1. 类名规则

**Service 类：**
- 命名空间：`base\common\service`
- 格式：`Tools[类型]ServiceBase`
- 示例：`ToolsDbServiceBase`、`ToolsLogServiceBase`、`ToolsBackupServiceBase`

**基础命令类：**
- 命名空间：`base\common\command\tools\[类型]`
- 格式：`Tools[类型][功能]Base`
- 示例：`ToolsDbQueryBase`、`ToolsDbExecuteBase`、`ToolsLogClearBase`

**业务命令类：**
- 命名空间：`app\common\command\tools\[类型]`
- 格式：`Tools[类型][功能]`
- 示例：`ToolsDbQuery`、`ToolsDbExecute`、`ToolsLogClear`
- 继承：继承对应的 Base 类

### 2. 命令名称规则

 - 格式：`tools:[类型]:[功能]`
 - 示例：
   - `tools:db:query` - 数据库查询
   - `tools:db:execute` - 数据库执行
   - `tools:http:call` - HTTP 调用（类似 curl）
   - `tools:log:clear` - 日志清理
   - `tools:backup:create` - 创建备份

### 3. 目录结构规则

```
 tools/
 ├── db/           # 数据库工具（db）
 ├── http/         # HTTP 工具（http）
 ├── log/          # 日志工具（log）
 ├── backup/       # 备份工具（backup）
 ├── cache/        # 缓存工具（cache）
 └── ...
```

## 创建新 Tools 命令的步骤

### 示例：创建日志清理命令

#### 1. 创建 Service 类

```php
<?php
// extend/base/common/service/ToolsLogServiceBase.php
namespace base\common\service;

class ToolsLogServiceBase
{
    public function checkDebugMode(Output $output): bool
    {
        // 实现调试模式检查
    }

    public function formatOutput(array $data, Output $output): void
    {
        // 实现输出格式化
    }
}
```

#### 2. 创建基础命令类

```php
<?php
// extend/base/common/command/tools/log/ToolsLogClearBase.php
namespace base\common\command\tools\log;

use base\common\service\ToolsLogServiceBase;
use think\console\Command;

class ToolsLogClearBase extends Command
{
    protected function configure()
    {
        $this->setName('tools:log:clear')
            ->setDescription('清理日志文件')
            ->addOption('all', null, Option::VALUE_NONE, '清理所有日志');
    }

    protected function execute($input, $output)
    {
        $service = new ToolsLogServiceBase();
        // 实现命令逻辑
    }
}
```

#### 3. 创建业务命令类

```php
<?php
// app/common/command/tools/log/ToolsLogClear.php
namespace app\common\command\tools\log;

use base\common\command\tools\log\ToolsLogClearBase;

class ToolsLogClear extends ToolsLogClearBase
{
}
```

#### 4. 注册命令

在 `extend/think/UlthonAdminService.php` 中注册：

```php
use app\common\command\tools\log\ToolsLogClear;

$this->commands([
    // ...
    ToolsLogClear::class,
]);
```

## 注意事项

1. **命名一致性**：所有 tools 命令必须遵循统一的命名规则
2. **Service 层**：每个工具类型应有对应的 Service 类
3. **开发者模式**：大多数 tools 命令应仅在开发者模式下可用
4. **安全性**：涉及数据修改的命令应有确认机制（如 `--force` 选项）
5. **帮助文档**：每个命令都应提供详细的 `--help` 说明
6. **扩展性**：tools 目录的设计便于添加新的系统级工具

## 已实现的工具

 - **数据库工具 (db)**
   - `tools:db:query` - 执行 SQL 查询
   - `tools:db:execute` - 执行 SQL 非查询语句
   - `tools:db:table` - 使用查询构建器操作表
   - `tools:db:info` - 显示数据库信息
   - `tools:db:desc` - 显示表结构
   - `tools:db:count` - 统计表记录数

- **HTTP 工具 (http)**
  - `tools:http:call` - HTTP 调用工具，类似 curl
    - 支持标准 curl 参数：`--url`, `--method`, `--data`, `--body`, `--headers`
    - 支持框架特性参数：`--app`, `--controller`, `--action`, `--super-token`, `--user-id`
    - JSON 输出格式：`{ success, response: { status, data, headers }, execution_time, exception }`