chore: 重写初始提交(清空历史,整理后全量提交)

2026-08-16 16:54:14 +08:00
commit 6c1a106bc1
1808 changed files with 238144 additions and 0 deletions
@@ -0,0 +1,158 @@
+# YwxApp 自定义命令清单
+
+> 生成日期：2026-07-30
+> 运行方式：在项目根目录执行 `php think <命令> [参数] [选项]`
+> 命令注册入口：`ywxapp/service/AppService.php` 的 `boot()` 方法（`$this->commands([...])`）
+> 命令类扫描范围：`app/command`、`ywxapp/command`、`addon/*/command`
+
+---
+
+## 一、已注册命令（实际可用，共 14 个）
+
+按功能分组列出。
+
+### 1. 插件管理
+
+#### `addon:manage <插件名> -a <action>`
+- **文件**：`ywxapp/command/addon/Manage.php`（health 动作委托 `app/command/AddonHealth.php`）
+- **用途**：插件统一管理入口，合并原 `addon:develop` / `addon:install` / `addon:refresh-menu` / `addon:reload` / `addon:health` 五条命令为单入口。
+- **参数**：
+  - `<插件名>`（可选）：部分动作需要；留空语义见各动作
+  - `-a, --action`（必填）：`develop` | `install` | `refresh-menu` | `reload` | `health`
+- **动作与选项**：
+  - `develop`：开发者模式安装（源码已在 `addon/<name>`，原地建表 / 注入菜单 / 启用，免打包）。例：`php think addon:manage mqttbroker -a develop`
+  - `install`：安装插件。`--local=<zip>` 离线安装；`--force` 在线强制覆盖。例：`php think addon:manage demo -a install` / `php think addon:manage demo -a install --local=/path/addon.zip`
+  - `refresh-menu`：重导菜单（`menu.json → admin_power / user_rule`），不改安装 / 启用、不跑 SQL；插件名留空 = 刷新全部。例：`php think addon:manage` / `php think addon:manage blog -a refresh-menu`
+  - `reload`：热重载（需 `app_debug`）。`--force` 强制；`--status` 查看状态；插件名留空 = 全部。例：`php think addon:manage myplugin -a reload --force` / `php think addon:manage -a reload --status`
+  - `health`：健康检查（委托 `AddonHealth`）。`[插件名]` 可选；`--detail` 详情；`--fix` 修复；`--output=text|json|html`；`--send-alert`；`--webhook=<url>`；`--email=<addr>`；`--save-report`。例：`php think addon:manage -a health` / `php think addon:manage myplugin -a health --fix` / `php think addon:manage -a health --output=json --send-alert`
+
+#### `ywxapp:upgrade`
+- **文件**：`ywxapp/command/Upgrade.php`
+- **用途**：本地离线升级一键命令。绕过在线下载，直接对本地打包产物执行升级，复用系统既有升级逻辑：
+  - **框架**：`FrameworkService::apply()` —— 备份、解压覆盖、跑 `upgrade.sql`、写回 `config/ywxapp.php` 版本号（自动备份到 `runtime/framework/backup/`）。
+  - **插件**：`AddonService::localUpgrade()` —— 备份旧目录、解压覆盖（含 Zip Slip 防护与 static 资源处理）、增量 SQL、更新 `info.php` 版本（自动备份到 `runtime/addon/backup/`）。
+  - 区别于 `addon:manage -a install --local=`（首次安装，插件已存在会拒绝）：本命令支持**覆盖已安装插件**的离线升级。
+- **选项**：
+  - `-f, --file=<zip>`（必填）：升级包本地路径（绝对或相对项目根）
+  - `-t, --type=<type>`（必填）：`framework` | `addon`
+  - `-r, --ver=<ver>`（可选）：目标版本号。**framework 必填**（写入 `config/ywxapp.php`）；addon 自动从 zip 内 `info.php` 读取
+  - `-p, --patch`：框架补丁包标记（核心包，解压时剥离 `ywxapp/` 前缀解到 `ywxapp/`；整站包**勿加**）
+- **示例**：
+  - 框架整站包：`php think ywxapp:upgrade -f runtime/framework/ywxapp-1.0.9.zip -t framework -r 1.0.9`
+  - 框架核心补丁包：`php think ywxapp:upgrade -f runtime/framework/ywxapp-1.0.9.zip -t framework -r 1.0.9 -p`
+  - 插件升级：`php think ywxapp:upgrade -f runtime/market/forum-1.0.2.zip -t addon`
+- **注意**：执行后会提示清理 `runtime/cache`、`runtime/temp`；插件升级前会自动备份到 `runtime/addon/backup/<name>-<ver>-<时间戳>/`，失败可回滚。
+
+### 2. 数据库
+
+#### `install:copy`
+- **文件**：`app/command/InstallCopy.php`
+- **用途**：复制 / 初始化本项目数据库安装（核心表 + 插件表）。脚本只执行 `CREATE TABLE / INSERT`（白名单），对已存在的表 / 数据做幂等跳过。
+- **选项**：
+  - `-c, --core`：仅安装核心表
+  - `-a, --addon=<name>`：仅安装指定插件（逗号分隔），默认全部插件
+- **示例**：
+  - `php think install:copy`
+  - `php think install:copy --core`
+  - `php think install:copy --addon=blog,wxchat`
+
+### 3. 服务进程（常驻 / 网关）
+
+#### `workerman:gateway`
+- **文件**：`ywxapp/command/GatewayWorker.php`
+- **用途**：启动 Workerman GatewayWorker 服务（Register / Gateway / BusinessWorker）。
+- **选项**：
+  - `-a, --acthon=<val>`：操作（start / stop / restart 等，透传给 Workerman）
+- **示例**：`php think workerman:gateway -a start`
+
+#### `wxchat:server`
+- **文件**：`addon/wxchat/command/ChatServer.php`
+- **用途**：启动 wxchat 的 GatewayWorker 即时通讯服务。
+- **选项**：
+  - `-a, --action=<val>`：操作（如 start）
+- **示例**：`php think wxchat:server -a start`
+
+#### `mqttbroker:start`
+- **文件**：`addon/mqttbroker/command/MqttBroker.php`
+- **用途**：启动 MQTT Broker 常驻进程（兼容 MQTT 3.1.1 / 5.0，类 EMQX 轻量 broker，零外部依赖；转发规则桥接 EMQX 需 `workerman/mqtt`，未安装时自动跳过）。
+- **选项**：
+  - `-p, --port=<val>`：监听端口（默认 `1883`）
+  - `-H, --host=<val>`：监听地址（默认 `0.0.0.0`）
+- **示例**：`php think mqttbroker:start` / `php think mqttbroker:start -p 1883`
+
+### 4. 插件运维 / 监控
+
+#### `addon:health` / `addon:reload` 已并入 `addon:manage`
+- 原 `addon:health`、`addon:reload` 现统一为 `addon:manage -a health` / `addon:manage -a reload`，选项与行为不变。详见上文 §1 `addon:manage`。
+
+#### `addon:license-check`
+- **文件**：`ywxapp/command/AddonLicenseCheck.php`
+- **用途**：运行期授权巡检（Discuz 式：已启用付费插件定期复查授权，过期自动禁用）。遍历 `addon/` 下已启用且 `info['license']=true` 的付费插件，逐个向中心站 `validDomain` 校验，校验拒绝或（非 `offline_tolerant` 时）中心站不可达 → 落库 `status=0` 禁用并写 `Log::warning`。放行条件：调试+未知来源 / `config('ywxapp.addon_license_check')===false` / 非客户机（`!is_market_client()`）时直接跳过。
+- **依赖**：仅客户机（`is_market_client()===true`）且 `addon_license_check` 开启时生效。
+- **示例**：
+  - `php think addon:license-check`
+  - crontab（建议每日 03:10 巡检一次）：
+    ```
+    10 3 * * * cd /path/to/site && php think addon:license-check >> runtime/license_check.log 2>&1
+    ```
+  - 仅观察不禁用：临时设 `addon_license_check=offline_tolerant` 后运行，中心站不可达不禁用（仅真实过期拒绝仍禁用）。
+
+### 5. 代码生成
+
+#### `make:modely <name>`
+- **文件**：`ywxapp/command/ModelY.php`
+- **用途**：创建一个新模型类（继承自 `think\console\command\Make`）。
+- **参数**：
+  - `name`（必填）：模型类名，例如 `Yasd`
+- **示例**：`php think make:modely Yasd`
+
+### 6. 第三方 / 业务集成
+
+#### `mqttbroker:acltest`
+- **文件**：`addon/mqttbroker/command/TestAcl.php`
+- **用途**：ACL 实网决策验证，用真实 DB 规则校验 `Auth::checkAcl` 的放行 / 拒绝逻辑（deny 拒绝、默认放行、用户定向拒绝、超管绕过、`$SYS` 只读）。不依赖运行中的 Broker。
+- **示例**：`php think mqttbroker:acltest`
+
+#### `haonav:checklinks`
+- **文件**：`addon/haonav/command/CheckLinks.php`
+- **用途**：haonav 网址导航死链巡检，更新 `status_code / last_check_at`。适合放 crontab。
+- **选项**：
+  - `--limit=<n>`：本次最多检测条数（`0`=全部，按最久未检测优先，默认 `0`）
+  - `--timeout=<s>`：单条检测超时秒数（默认 `8`）
+- **示例**：
+  - `php think haonav:checklinks`
+  - `php think haonav:checklinks --limit=50`
+  - crontab：`0 3 * * * cd /path/to/site && php think haonav:checklinks >> runtime/haonav_check.log 2>&1`
+
+---
+
+## 二、已定义但未注册命令（共 4 个）
+
+以下命令类已实现 `setName`，但**未写入 `config/console.php`**，因此 `php think list` 不会列出、直接执行会报「命令不存在」。如需启用，把对应键值加入 `config/console.php` 的 `commands` 数组即可（注意 `clear` 重名冲突问题）。
+
+| 命令名 | 类 | 文件 | 说明 / 参数 |
+|--------|-----|------|-------------|
+| `addon:make` | `ywxapp\command\addon\Addon` | `ywxapp/command/addon/Addon.php` | **统一脚手架/生成器**（已通过 `AppService` 注册，替代原 `addon:build`/`addon:clear`/`addon:controller`/`addon:model`/`addon:middleware`/`addon:validate`/`addon:event`/`addon:listener`/`addon:service`/`addon:subscribe`）。用法 `php think addon:make <插件名> -a <action>`；`-a` 取 `build`/`clear`/`controller`/`model`/`middleware`/`validate`/`event`/`listener`/`service`/`subscribe`；生成器用 `--name=<类>`；`controller` 另支持 `--api`/`--plain`；`clear` 支持 `-c`/`-l`/`-r`。 |
+| `app` | `ywxapp\command\AppCommand` | `ywxapp/command/AppCommand.php` | **应用命令统一入口**（已通过 `AppService` 注册）。聚合 `ywxapp/command/app/*` 全部命令：`build`/`clear`/`controller`/`model`/`event`/`listener`/`middleware`/`service`/`subscribe`/`validate`。用法 `php think app <子命令> [参数]`；如 `php think app controller app\index --api`、`php think app clear --cache`。子命令专有选项（`--api`/`--plain`/`--cache` 等）透传至原命令类，未内联、不另立独立命令名。 |
+
+> 说明：`ywxapp/command/Create.php` 中的 `YMake` 是**抽象基类**（`abstract class YMake extends Command`），本身不是可执行命令，供 `ModelY` 等生成类继承，不在清单内。
+
+---
+
+## 三、附：`config/console.php` 当前注册表（去重后）
+
+```php
+'commands' => [
+    "workerman:gateway"      => \ywxapp\command\GatewayWorker::class,
+    "make:modely"            => \ywxapp\command\ModelY::class,
+    "wxchat:server"          => \addon\wxchat\command\ChatServer::class,
+    "install:copy"           => \app\command\InstallCopy::class,
+    "mqttbroker:start"       => \addon\mqttbroker\command\MqttBroker::class,
+    "mqttbroker:acltest"     => \addon\mqttbroker\command\TestAcl::class,
+    "addon:manage"           => \ywxapp\command\addon\Manage::class,
+    "addon:license-check"   => \ywxapp\command\AddonLicenseCheck::class,
+    "haonav:checklinks"     => \addon\haonav\command\CheckLinks::class,
+]
+```
+
+> 注：原文件中 `install:copy` 出现了两次（重复键），实际生效一份，建议清理重复项。