From 148f8b7a6f11d4e9edd7e2bd8ce96aaa0af55bbd Mon Sep 17 00:00:00 2001
From: augushong <augushong@163.com>
Date: Mon, 26 Jan 2026 23:09:45 +0800
Subject: [PATCH] =?UTF-8?q?docs(command):=20=E6=B7=BB=E5=8A=A0tools?=
 =?UTF-8?q?=E5=91=BD=E4=BB=A4=E5=91=BD=E5=90=8D=E8=A7=84=E8=8C=83=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 extend/base/common/command/tools/README.md | 194 +++++++++++++++++++++
 1 file changed, 194 insertions(+)
 create mode 100644 extend/base/common/command/tools/README.md

diff --git a/extend/base/common/command/tools/README.md b/extend/base/common/command/tools/README.md
new file mode 100644
index 0000000..6f43bf8
--- /dev/null
+++ b/extend/base/common/command/tools/README.md
@@ -0,0 +1,194 @@
+# Tools 命令命名规范
+
+## 概述
+
+`tools` 目录下的命令是系统级工具命令，主要用于开发调试、系统维护等场景。与普通命令不同，tools 命令有独特的命名规则和目录结构。
+
+## 目录结构
+
+```
+extend/base/common/
+├── service/
+│   ├── ToolsDbServiceBase.php       # 数据库工具服务
+│   ├── ToolsLogServiceBase.php      # 日志工具服务
+│   └── ToolsBackupServiceBase.php  # 备份工具服务
+└── command/
+    └── tools/
+        ├── README.md                # 本文件（命名规范说明）
+        └── db/                     # 数据库工具
+            ├── ToolsDbQueryBase.php   # 基础命令类
+            ├── ToolsDbExecuteBase.php
+            └── ...
+
+app/common/command/
+├── tools/
+│   └── db/                       # 数据库工具
+│       ├── ToolsDbQuery.php         # 业务命令类
+│       ├── ToolsDbExecute.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:log:clear` - 日志清理
+  - `tools:backup:create` - 创建备份
+
+### 3. 目录结构规则
+
+```
+tools/
+├── db/           # 数据库工具（db）
+├── 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` - 统计表记录数