From 6f4056f64da277adbd55f92ceb61da45e192e98b Mon Sep 17 00:00:00 2001 From: Anyon Date: Fri, 8 May 2026 15:31:22 +0800 Subject: [PATCH] =?UTF-8?q?docs(architecture):=20=E5=AE=8C=E5=96=84=20v8?= =?UTF-8?q?=20=E6=9E=B6=E6=9E=84=E4=B8=8E=E8=BF=81=E7=A7=BB=E8=AF=B4?= =?UTF-8?q?=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 补充 v8 重构后的架构文档、组件说明和迁移记录，方便后续维护者理解插件边界。 主要内容： - 更新根 README，说明 v8 插件分层、系统模块、交付命令和验证流程。 - 新增组件明细、插件边界、路由分发、软删除和稳定性文档。 - 记录 Storage 合并到 System、旧 View 移除和 Helper 并入 System 的决策。 - 补充文档注释报告和后续重构计划，便于持续演进。 --- docs/STORAGE_MERGE.md | 280 +++++ docs/UPDATE_NOTES.md | 205 ++++ docs/architecture/auth-token-session.md | 149 +++ docs/architecture/doc-comments-report.md | 260 ++++ docs/architecture/plugin-boundaries.md | 92 ++ docs/architecture/plugin-first-refactor.md | 76 ++ docs/architecture/plugin-standard.md | 188 +++ docs/architecture/plugins-detail.md | 774 ++++++++++++ docs/architecture/route-dispatch-standard.md | 118 ++ docs/architecture/soft-delete-standard.md | 54 + docs/architecture/stability-status.md | 72 ++ .../system-module-refactor-plan.md | 489 ++++++++ docs/components-detail.md | 1023 ++++++++++++++++ readme.md | 1088 ++++++----------- 14 files changed, 4138 insertions(+), 730 deletions(-) create mode 100644 docs/STORAGE_MERGE.md create mode 100644 docs/UPDATE_NOTES.md create mode 100644 docs/architecture/auth-token-session.md create mode 100644 docs/architecture/doc-comments-report.md create mode 100644 docs/architecture/plugin-boundaries.md create mode 100644 docs/architecture/plugin-first-refactor.md create mode 100644 docs/architecture/plugin-standard.md create mode 100644 docs/architecture/plugins-detail.md create mode 100644 docs/architecture/route-dispatch-standard.md create mode 100644 docs/architecture/soft-delete-standard.md create mode 100644 docs/architecture/stability-status.md create mode 100644 docs/architecture/system-module-refactor-plan.md create mode 100644 docs/components-detail.md diff --git a/docs/STORAGE_MERGE.md b/docs/STORAGE_MERGE.md new file mode 100644 index 000000000..5cf58e255 --- /dev/null +++ b/docs/STORAGE_MERGE.md @@ -0,0 +1,280 @@ +# Storage 组件合并说明 + +## 更新概述 + +**Storage 组件已合并到 System 组件**，不再作为独立插件存在。 + +## 架构变更 + +### 变更前的架构 +``` +ThinkLibrary → Storage (独立组件) + → System (独立组件) +``` + +### 变更后的架构 +``` +ThinkLibrary → System (包含 Storage 功能) +``` + +## 代码结构调整 + +### 原 Storage 组件位置 +``` +plugin/think-plugs-storage/ (已删除) +├── src/ +│ ├── storage/ +│ ├── controller/ +│ └── ... +└── ... +``` + +### 现 Storage 功能位置 +``` +plugin/think-plugs-system/src/storage/ +├── LocalStorage.php # 本地存储驱动 +├── AliossStorage.php # 阿里云 OSS 驱动 +├── TxcosStorage.php # 腾讯云 COS 驱动 +├── QiniuStorage.php # 七牛云 Kodo 驱动 +├── UpyunStorage.php # 又牛云存储驱动 +├── AlistStorage.php # Alist 网络存储驱动 +├── StorageManager.php # 存储管理器 +├── StorageAuthorize.php # 上传授权管理 +├── StorageConfig.php # 存储配置管理 +└── extra/ + ├── mimes.php # MIME 类型配置 + └── upload.js # 前端上传脚本 +``` + +驱动注册表（default / global / drivers 元数据）固定在 `StorageConfig::registryDefinition()` 中维护，**不再**使用 `config/storage.php`；用户在各驱动下填写的密钥、地域等仍保存在 sysdata(`system.storage`)。 + +## 数据表归属 + +### system_file 表 +- **原归属**: Storage 组件 +- **现归属**: System 组件 +- **迁移脚本**: `plugin/think-plugs-system/stc/database/20241010000001_install_system20241010.php` + +## 控制器和功能 + +### 文件管理控制器 +- `plugin/system/src/controller/File.php` - 文件管理后台页面 +- `plugin/system/src/controller/api/Upload.php` - 上传 API 接口 + +### 数据模型 +- `plugin/system/src/model/SystemFile.php` - 文件数据模型 + +## 依赖关系更新 + +### 更新前的依赖 +```json +{ + "require": { + "zoujingli/think-plugs-storage": "^8.0" + } +} +``` + +### 更新后的依赖 +```json +{ + "require": { + "zoujingli/think-plugs-system": "^8.0" + } +} +``` + +## 各插件依赖更新 + +### Account 组件 +- **原依赖**: `ThinkPlugsStorage` +- **现依赖**: `ThinkPlugsSystem` (包含 Storage 功能) + +### Payment 组件 +- **原依赖**: `ThinkPlugsStorage` +- **现依赖**: `ThinkPlugsSystem` (包含 Storage 功能) + +### Wemall 组件 +- **原依赖**: `ThinkPlugsStorage` +- **现依赖**: `ThinkPlugsSystem` (包含 Storage 功能) + +### Wuma 组件 +- **原依赖**: `ThinkPlugsStorage` +- **现依赖**: `ThinkPlugsSystem` (包含 Storage 功能) + +## 功能说明 + +### 存储驱动管理 +Storage 功能合并后，System 组件现在支持以下存储驱动： + +1. **LocalStorage** - 本地文件存储 +2. **AliossStorage** - 阿里云对象存储 OSS +3. **TxcosStorage** - 腾讯云对象存储 COS +4. **QiniuStorage** - 七牛云对象存储 Kodo +5. **UpyunStorage** - 又牛云存储 +6. **AlistStorage** - Alist 网络存储（支持多种网盘） + +### 核心功能 +- 统一的 Storage 门面接口 +- 多存储驱动支持和管理 +- 上传授权和临时令牌生成 +- 文件元数据管理 +- 文件上传、删除、清理 +- 文件类型统计和管理 + +## 使用示例 + +### 存储管理器使用 +```php +use plugin\system\storage\StorageManager; + +// 获取存储管理器 +$storage = StorageManager::instance(); + +// 上传文件 +$result = $storage->upload($file, 'local'); + +// 获取文件 URL +$url = $storage->url('local', $filename); +``` + +### 上传授权 +```php +use plugin\system\storage\StorageAuthorize; + +// 生成上传授权令牌 +$auth = StorageAuthorize::mk()->buildToken([ + 'type' => 'image', + 'xkey' => 'upload_key', + 'xname' => 'filename.jpg' +]); + +// 返回前端使用 +return [ + 'token' => $auth['token'], + 'url' => $auth['url'] +]; +``` + +### 存储配置管理 +```php +use plugin\system\storage\StorageConfig; + +// 获取存储配置 +$config = StorageConfig::get('local'); + +// 保存存储配置 +StorageConfig::save('local', [ + 'root' => './public/upload' +]); +``` + +## 文档更新清单 + +### 已更新的文档 + +1. **readme.md** + - ✅ 删除了独立的 Storage 组件描述 + - ✅ 在 System 组件中增加了存储功能说明 + - ✅ 更新了架构图（删除 Storage 节点） + - ✅ 更新了各组件依赖关系 + - ✅ 更新了许可证列表 + +2. **docs/components-detail.md** + - ✅ 在 System 组件中增加存储功能详细说明 + - ✅ 删除独立的 Storage 章节 + +3. **各插件 `readme.md` / `readme.api.md`** + - ✅ Account: 更新依赖为 System + - ✅ Payment: 更新依赖为 System + - ✅ Wemall: 更新依赖为 System + - ✅ Wuma: 更新依赖为 System + +## 迁移步骤 + +### 对于现有项目 + +1. **更新 composer.json** +```json +{ + "require": { + "zoujingli/think-plugs-system": "^8.0" + // 删除： "zoujingli/think-plugs-storage": "^8.0" + } +} +``` + +2. **更新代码引用** +```php +// 旧代码 +use plugin\storage\storage\StorageManager; + +// 新代码 +use plugin\system\storage\StorageManager; +``` + +3. **重新安装依赖** +```bash +composer update +``` + +4. **验证功能** +```bash +# 测试上传功能 +php think list | grep upload + +# 检查存储配置 +php think config:get storage +``` + +## 优势分析 + +### 架构简化 +- ✅ 减少一个独立组件，降低维护成本 +- ✅ 减少组件间依赖关系 +- ✅ 统一系统核心功能管理 + +### 开发效率 +- ✅ 文件管理和系统管理在同一代码库 +- ✅ 减少跨组件调用 +- ✅ 更清晰的代码组织结构 + +### 性能优化 +- ✅ 减少自动加载文件数量 +- ✅ 减少服务注册数量 +- ✅ 降低系统启动时间 + +## 注意事项 + +1. **命名空间变更** + - 原：`plugin\storage\*` + - 现：`plugin\system\storage\*` + +2. **数据表归属** + - `system_file` 表现在明确归属 System 组件 + - 迁移脚本在 System 的 stc/database 目录 + +3. **配置路径** + - 驱动列表与字段结构：`plugin/think-plugs-system/src/storage/StorageConfig.php` 内 `registryDefinition()` + - 业务侧已保存参数：sysdata，经 `StorageConfig` 读写 + +4. **向后兼容** + - 建议尽快更新代码引用 + - 旧命名空间可能在未来版本移除 + +## 验证清单 + +- [x] Storage 组件目录已删除 +- [x] Storage 功能已合并到 System +- [x] system_file 表归属已更新 +- [x] 所有控制器已迁移到 System +- [x] 所有存储驱动已迁移到 System +- [x] 各插件依赖已更新为 System +- [x] 根 readme 已更新 +- [x] 组件详细文档已更新 +- [x] 架构图已更新 +- [x] 许可证列表已更新 + +## 更新日期 + +2026-03-22 diff --git a/docs/UPDATE_NOTES.md b/docs/UPDATE_NOTES.md new file mode 100644 index 000000000..07c051033 --- /dev/null +++ b/docs/UPDATE_NOTES.md @@ -0,0 +1,205 @@ +# 文档更新说明 + +本次更新根据代码实现同步更新了项目文档，确保文档与实际代码保持一致。 + +## 重要架构变更 + +### Storage 组件已合并到 System + +**重要**: Storage 组件已不再作为独立插件存在，其功能已完全合并到 ThinkPlugsSystem 组件中。 + +#### 变更说明 + +- **原位置**: `plugin/think-plugs-storage/` (已删除) +- **现位置**: `plugin/think-plugs-system/src/storage/` +- **数据表**: `system_file` 现在归属 System 组件 +- **依赖关系**: 所有原依赖 Storage 的插件改为依赖 System + +#### 存储驱动列表 + +System 组件现在包含以下存储驱动： +- LocalStorage (本地存储) +- AliossStorage (阿里云 OSS) +- TxcosStorage (腾讯云 COS) +- QiniuStorage (七牛云 Kodo) +- UpyunStorage (又牛云) +- AlistStorage (Alist 网络存储) + +#### 核心文件 + +- `StorageManager.php` - 存储管理器 +- `StorageAuthorize.php` - 上传授权管理 +- `StorageConfig.php` - 存储配置管理 +- `controller/File.php` - 文件管理控制器 +- `controller/api/Upload.php` - 上传 API 控制器 +- `model/SystemFile.php` - 文件数据模型 + +#### 文档更新 + +详细变更说明请参考：[STORAGE_MERGE.md](./STORAGE_MERGE.md) + +### 废弃模型清理 + +#### SystemConfig 模型已删除 + +**原因**: `SystemConfig` 模型对应的 `system_config` 表从未在生产环境中使用，仅存在于测试代码中。 + +**清理内容**: +- 删除文件：`plugin/think-plugs-system/src/model/SystemConfig.php` +- 该模型无任何生产代码引用 +- 系统配置实际使用 `SystemData` 模型和 `system_data` 表存储 +- 通过 `sysdata()` 和 `sysconf()` 函数访问配置 + +**实际使用的配置存储**: +- 数据表：`system_data` +- 模型：`SystemData` +- 访问方式：`sysdata('system.site')`, `sysconf('site_name')` + +#### Builder 组件已删除 + +**原因**: 动态页面构建功能暂时不需要，移除相关控制器、模型、服务和菜单配置。 + +**清理内容**: +- 删除控制器：`plugin/think-plugs-system/src/controller/Builder.php` (873 行) +- 删除模型：`plugin/think-plugs-system/src/model/SystemBuilder.php` +- 删除服务：`plugin/think-plugs-system/src/service/BuilderService.php` (16.2KB) +- 删除测试：`plugin/think-plugs-system/tests/BuilderControllerTest.php` +- 删除菜单：从 `composer.json` 中移除"动态页面构建"菜单项 + +**影响的菜单**: +- 已移除：系统配置 > 动态页面构建 (`system/builder/index`) + +**保留的功能**: +- `system_data` 表仍然保留，作为系统配置存储使用 +- `sysdata()` 和 `sysconf()` 函数继续使用 `system_data` 表 + +--- + +## 更新内容 + +### 1. 新增组件详细文档 + +创建了 `docs/components-detail.md` 文件，包含： + +- **13 个组件的详细说明**，每个组件包含： + - 包名和定位 + - 核心功能列表 + - 数据表结构 + - 目录结构 + - 使用示例 + - 依赖关系 + - 许可证信息 + +- **架构约定说明**： + - 认证与会话规范 + - 路由与应用约定 + - PHAR 路径约定 + +- **开发工具说明**： + - PHPStan 配置 + - 代码风格工具 + - 测试套件 + +### 2. 更新根 readme.md + +#### 仓库组成部分 +- 为每个组件增加了详细的功能描述 +- 补充了核心工具、扩展能力、全局函数等信息 +- 明确了各组件的许可证类型 +- 增加了组件详细文档的引用链接 + +#### 开发工具部分 +- 增加了测试章节，说明如何运行各类测试 +- 补充了测试覆盖范围说明 +- 简化了 PHPStan 配置说明 + +#### 文档链接部分 +- 修复了所有文档路径（从绝对路径改为相对路径） +- 增加了架构文档子项（插件标准、路由分发、软删除等） +- 新增了组件详细文档的引用 + +#### 许可证部分 +- 明确列出各组件的许可证类型 +- 分组说明：MIT、Apache-2.0、专有授权 +- 增加了商业使用限制说明 + +### 3. 更新 ThinkLibrary readme.md + +#### 核心功能部分 +- 细化了 6 大功能模块的描述 +- 增加了扩展工具的详细说明（FaviconBuilder、ImageSliderVerify、JsonRpc 等） +- 补充了全局函数的分类和说明 + +#### 依赖要求 +- 增加了 fileinfo 扩展要求 +- 增加了 redis 扩展推荐 + +#### 开发规范 +- 增加了具体的命令示例 +- 补充了静态分析说明 +- 增加了测试覆盖范围说明 + +#### 新增章节 +- 认证说明（JWT 令牌、Token Session） +- PHAR 兼容性说明 +- 测试覆盖详细说明 + +## 文档改进点 + +### 描述详细度 +- ✅ 每个组件都有清晰的功能定位 +- ✅ 列出了核心功能清单 +- ✅ 提供了使用示例代码 +- ✅ 明确了数据表和目录结构 + +### 架构清晰度 +- ✅ 分层架构描述清晰 +- ✅ 组件边界明确 +- ✅ 依赖关系清楚 +- ✅ 认证协议统一 + +### 实用性 +- ✅ 提供了完整的命令示例 +- ✅ 包含配置示例代码 +- ✅ 明确了许可证限制 +- ✅ 补充了开发工具使用说明 + +### 一致性 +- ✅ 所有组件使用统一的描述结构 +- ✅ 术语使用一致 +- ✅ 路径格式统一（相对路径） +- ✅ 代码风格统一 + +## 后续建议 + +### 需要补充的内容 +1. **API 接口文档**：已完成，现统一维护在各插件根目录 `readme.api.md` +2. **数据库字典**：每个数据表的字段说明 +3. **事件文档**：系统事件列表和监听器说明 +4. **错误码文档**：统一错误码和异常说明 + +### 需要完善的示例 +1. **完整业务流程示例**：从登录到业务操作的完整流程 +2. **插件开发示例**：如何开发一个新插件 +3. **自定义扩展示例**：如何扩展已有组件 + +## 验证清单 + +- [x] 所有组件描述与实际代码一致 +- [x] 命令示例可以正常运行 +- [x] 配置示例符合实际配置 +- [x] 路径引用使用相对路径 +- [x] 许可证信息准确 +- [x] 依赖关系正确 +- [x] 架构描述清晰 + +## 文档位置 + +- 根 readme：`/readme.md` +- 组件详细文档：`/docs/components-detail.md` +- ThinkLibrary 文档：`/plugin/think-library/readme.md` +- 架构文档：`/docs/architecture/` + +## 更新日期 + +2026-03-22 diff --git a/docs/architecture/auth-token-session.md b/docs/architecture/auth-token-session.md new file mode 100644 index 000000000..35f71cb79 --- /dev/null +++ b/docs/architecture/auth-token-session.md @@ -0,0 +1,149 @@ +# Auth And Token Session + +## 目标 + +当前项目的认证体系只保留“显式 Token + Token Session”这一套主线，不再使用标准 PHP Session 承载登录态。 + +统一原则： + +- 登录态必须由显式 Token 表达 +- 临时用户态必须绑定到 Token 对应的 `sid` +- 业务请求统一使用 `Authorization` +- 后台壳页首跳只允许一次性 `access_key` 引导，不长期在 URL 或 Cookie 中保留认证态 +- 登录来源可以有多种，但认证协议尽量收敛 + +## 标准认证协议 + +### 1. 后台认证 + +- 类型：`system-auth` +- 载体：`Authorization: Bearer ` +- 首屏壳页：允许一次性 `access_key` +- 会话：JWT 内的 `sid` 绑定 `CacheSession` + +适用场景： + +- 后台运营人员 +- 管理员 +- 需要 RBAC 的内部接口 + +### 2. 业务账号认证 + +- 类型：`account-auth` +- 载体：`Authorization: Bearer ` +- 会话：JWT 内的 `sid` 绑定 `CacheSession` + +适用场景： + +- 会员 +- 分销员 +- 商户 +- 店员 +- 任何“业务用户”身份 + +注意： + +- `wap / web / wxapp / wechat / iosapp / android` 是登录来源或终端通道 +- 它们不是独立的认证协议 + +### 3. 设备认证 + +- 当前仅 `wuma` 保留独立设备 token +- 载体：`Authorization: Bearer ` +- 附加头：`X-Device-Code`、`X-Device-Type` +- 这不是 JWT，也不是通用账号协议 + +适用场景： + +- PDA +- 扫码枪 +- 仓库终端 +- 封闭设备接口 + +### 4. 能力令牌 + +- 当前后台上传使用短期能力 token +- 它不是登录态，不参与通用用户会话 + +适用场景： + +- 上传授权 +- 短时能力下放 + +## 请求识别规则 + +统一入口为请求级令牌解析服务： + +- 有 `Authorization` 时，只按请求头判定 +- 后台壳页首次进入时，可通过一次性 `access_key` 引导写入本地 Token +- 不再依赖认证 Cookie 回退 +- 不再混用 `Api-Token`、`Api-Code`、`Api-Type` + +统一请求头： + +```http +Authorization: Bearer +X-Device-Code: +X-Device-Type: +``` + +## Token Session 规则 + +### 核心定义 + +- Token 表达“你是谁” +- Token Session 表达“这次登录上下文里的临时状态” +- Token Session 的主键是 `sid` + +### 存储实现 + +- 服务：`CacheSession` +- 统一入口：`tsession()` +- 存储后端：系统 `cache` +- 支持：`file`、`redis` 等缓存驱动 + +### 配置键 + +- `token_session_expire` +- `token_session_touch` +- `token_session_gc_interval` +- `token_session_store` + +### 使用约束 + +- 默认作用域必须来自当前 Token 的 `sid` +- 未完成 Token 鉴权时，不能直接依赖默认作用域 +- 如需离线或系统级缓存，必须显式传入 `scope` + +### 推荐用法 + +```php +tsession()->write('draft', ['step' => 1]); +$draft = tsession()->read('draft', []); + +tsession()->put(['from' => 'order']); +$all = tsession()->all(); + +tsession()->delete('draft'); +tsession()->clear(); +tsession()->destroy(); +``` + +## 禁止项 + +- 不再使用 `think\Session` +- 不再使用 `think\\facade\\Session` +- 不再使用 `SessionInit` +- 不再使用 `PHPSESSID` +- 不再使用标准 Session 环境变量作为系统登录态配置 + +## 推荐分层 + +如果系统存在多类账号，建议按下面方式分层： + +- `system-auth`：后台人员 +- `account-auth`：所有业务用户 +- `device token`：封闭设备 +- `capability token`：短期能力授权 + +不要按每个终端来源都拆一套新的认证协议。 diff --git a/docs/architecture/doc-comments-report.md b/docs/architecture/doc-comments-report.md new file mode 100644 index 000000000..659f978c4 --- /dev/null +++ b/docs/architecture/doc-comments-report.md @@ -0,0 +1,260 @@ +# 文档与注释补充报告 + +## 概述 + +本次对 ThinkAdminDeveloper 项目的核心 PHP 文件进行了系统的文档审查和注释补充工作，确保所有公共 API 都有清晰的文档说明。 + +## 已完成的工作 + +### 1. 核心基类文档补充 + +#### Helper 基类系列 +- ✅ `helper/Helper.php` - 补充了类说明和构造函数、实例方法的详细注释 +- ✅ `helper/FormBuilder.php` - 补充了 8 个关键方法的详细注释 +- ✅ `helper/QueryHelper.php` - 补充了 6 个关键方法的详细注释 +- ✅ `helper/PageBuilder.php` - 补充了类说明和构造函数注释 +- ✅ `helper/ValidateHelper.php` - 补充了验证方法的详细注释和示例 + +### 2. 文档改进详情 + +#### Helper.php +**改进内容**: +- 类说明：从简单的"控制器助手"扩展为详细说明 +- 增加了功能描述：说明为控制器提供表单、查询、页面构建等辅助功能 +- 添加了 `@package` 和 `@abstract` 标签 + +**修改前**: +```php +/** + * 控制器助手. + * @class Helper + */ +``` + +**修改后**: +```php +/** + * 控制器助手基类 + * + * 为控制器提供通用的辅助功能，包括表单构建、查询构建、页面构建等 + * 所有 Helper 类都继承自此类 + * + * @class Helper + * @package think\admin\helper + * @abstract + */ +``` + +#### FormBuilder.php +**改进的方法注释**: +1. `__construct()` - 构造函数参数详细说明 +2. `mk()` - 增加了返回值说明和参数示例 +3. `setAction()` - 明确了参数用途 +4. `setVariable()` - 增加了参数示例 +5. `setFormAttrs()` - 说明了参数类型 +6. `addScript()` - 明确了参数内容 +7. `validate()` - 详细说明了参数和返回值 +8. `getRequestRules()` - 补充了返回值说明 + +#### QueryHelper.php +**改进的方法注释**: +1. `__call()` - 说明了魔术方法的调用逻辑和返回值规则 +2. `make()` - 详细说明了快捷方法的调用机制 +3. `db()` - 明确了返回值类型 +4. `init()` - 详细说明了各参数的用途 +5. `autoSortQuery()` - 增加了功能说明和异常说明 + +#### ValidateHelper.php +**改进内容**: +- 类说明从"快捷输入验证器"改为"数据验证助手" +- 增加了 `@package` 标签 +- `init()` 方法补充了完整的参数说明、返回值说明和异常说明 +- 保留了使用示例注释 + +### 3. 文档标准 + +本次补充遵循以下 PHPDoc 标准: + +#### 类注释标准 +```php +/** + * 类说明（简短描述） + * + * 详细说明（可选） + * 功能描述、使用场景等 + * + * @class 类名 + * @package 包名 + * @abstract (如果是抽象类) + */ +``` + +#### 方法注释标准 +```php +/** + * 方法说明（简短描述） + * + * 详细说明（可选） + * 功能描述、处理逻辑等 + * + * @param 类型 $参数名 参数说明 + * @param 类型 $参数名 参数说明 + * @return 类型 返回值说明 + * @throws 异常类 异常说明 + */ +``` + +### 4. 已检查但未修改的文件 + +以下文件已有完整的文档注释，无需修改: + +#### ThinkLibrary 核心类 +- ✅ `Command.php` - 已有完整的头部注释和方法注释 +- ✅ `Exception.php` - 已有完整的异常类注释 +- ✅ `Service.php` - 已有完整的服务类注释 +- ✅ `Controller.php` - 已有完整的控制器注释 +- ✅ `Model.php` - 已有完整的模型类注释 +- ✅ `Plugin.php` - 已有完整的插件管理类注释 +- ✅ `Storage.php` - 已有完整的存储门面注释 +- ✅ `Library.php` - 已有完整的库注册类注释 + +#### 服务类 +- ✅ `service/AppService.php` - 已有详细的应用服务注释 +- ✅ `service/JwtToken.php` - 已有完整的 JWT 工具注释 +- ✅ `service/CacheSession.php` - 已有完整的缓存会话注释 +- ✅ `service/NodeService.php` - 已有完整的节点服务注释 +- ✅ `service/QueueService.php` - 已有完整的队列服务注释 +- ✅ `service/RuntimeService.php` - 已有完整的运行时服务注释 + +#### 工具类 +- ✅ `service/FaviconBuilder.php` - 已有完整的 favicon 构建工具注释 +- ✅ `service/ImageSliderVerify.php` - 已有完整的滑块验证码注释 +- ✅ `service/JsonRpcHttpClient.php` - 已有完整的 JSON-RPC 客户端注释 +- ✅ `service/JsonRpcHttpServer.php` - 已有完整的 JSON-RPC 服务端注释 + +#### 扩展工具 +- ✅ `extend/CodeToolkit.php` - 已有完整的编码工具注释 +- ✅ `extend/FileTools.php` - 已有完整的文件工具注释 +- ✅ `extend/HttpClient.php` - 已有完整的 HTTP 客户端注释 +- ✅ `extend/ArrayTree.php` - 已有完整的数组树工具注释 + +### 5. 其他插件检查结果 + +#### ThinkPlugsSystem +- ✅ `Service.php` - 已有完整的系统服务注释 +- ✅ `common.php` - 已有完整的函数注释 +- ✅ `controller/` - 所有控制器已有完整注释 +- ✅ `model/` - 所有模型已有完整注释 +- ✅ `service/` - 所有服务类已有完整注释 +- ✅ `middleware/` - 所有中间件已有完整注释 + +#### ThinkPlugsWorker +- ✅ `Service.php` - 已有完整的 Worker 服务注释 +- ✅ `common.php` - 已有完整的函数注释 +- ✅ `command/` - 所有命令类已有完整注释 +- ✅ `model/` - 所有模型已有完整注释 +- ✅ `service/` - 所有服务类已有完整注释 + +#### System 内置存储中心 +- ✅ `storage/` - 存储驱动、配置和授权类已有完整注释 +- ✅ `controller/Config.php` - 存储配置入口已有完整注释 +- ✅ `controller/File.php` - 文件管理入口已有完整注释 +- ✅ `model/SystemFile.php` - 文件模型已有完整注释 + +## 文档质量评估 + +### 优秀 (无需修改) +- 所有核心基类都有完整的头部版权信息 +- 所有类都有 `@class` 标签说明 +- 大部分公共方法都有参数和返回值注释 +- 关键工具类都有详细的使用示例 + +### 良好 (已补充完善) +- Helper 系列的文档已补充完整 +- 方法注释的参数类型和说明已规范化 +- 返回值说明已补充完整 + +### 建议改进 +- 部分复杂方法可以增加使用示例 +- 部分内部方法可以补充更详细的逻辑说明 +- 可以增加更多代码示例文档 + +## 文档一致性 + +### 已统一的格式 +1. **类说明格式**: 统一使用"类名 + 功能描述"的格式 +2. **包名标签**: 统一添加 `@package` 标签 +3. **参数说明**: 统一使用 `@param 类型 $参数名 说明` 格式 +4. **返回值说明**: 统一使用 `@return 类型 说明` 格式 +5. **异常说明**: 统一使用 `@throws 异常类 说明` 格式 + +### 已修正的问题 +1. 部分类说明过于简单 → 已补充详细功能描述 +2. 部分方法缺少参数类型 → 已补充完整的类型说明 +3. 部分方法缺少返回值说明 → 已补充返回值描述 +4. 部分注释格式不统一 → 已统一格式标准 + +## 覆盖范围统计 + +### 已检查的文件数量 +- **ThinkLibrary**: 30+ 个核心文件 ✅ +- **ThinkPlugsSystem**: 20+ 个文件 ✅ +- **ThinkPlugsWorker**: 15+ 个文件 ✅ +- **System 内置存储中心**: 10+ 个文件 ✅ + +### 已修改的文件数量 +- **Helper 基类系列**: 5 个文件 + - Helper.php + - FormBuilder.php + - QueryHelper.php + - PageBuilder.php + - ValidateHelper.php + +### 修改的注释数量 +- **类注释改进**: 5 处 +- **方法注释改进**: 30+ 处 +- **参数说明补充**: 50+ 处 +- **返回值说明补充**: 20+ 处 + +## 后续建议 + +### 1. 自动化检查 +建议配置 PHPStan 或 PHPDoc 检查工具，确保: +- 所有公共方法都有完整的文档 +- 参数类型和返回值类型正确 +- 文档格式符合标准 + +### 2. 示例代码补充 +建议为以下类补充使用示例: +- FormBuilder 的完整表单示例 +- QueryHelper 的复杂查询示例 +- PageBuilder 的列表页面示例 +- ValidateHelper 的验证规则示例 + +### 3. API 文档生成 +建议使用 phpDocumentor 或 ApiGen 生成完整的 API 文档: +```bash +phpdoc -d plugin/think-library/src -t docs/api +``` + +### 4. 持续维护 +- 新增公共方法时同步补充文档 +- 修改方法签名时更新注释 +- 定期审查文档质量 + +## 总结 + +本次文档补充工作: +- ✅ 审查了 75+ 个核心 PHP 文件 +- ✅ 补充了 5 个 Helper 类的文档 +- ✅ 改进了 30+ 个方法注释 +- ✅ 统一了文档格式标准 +- ✅ 确保了核心 API 都有完整文档 + +所有修改都遵循以下原则: +1. **兼容性优先**: 不改变原有代码逻辑，只补充文档 +2. **循序渐进**: 优先补充公共 API 和核心方法的文档 +3. **标准统一**: 遵循 PHPDoc 和 PSR 标准 +4. **实用导向**: 注重文档的实用性和可读性 + +现在项目的文档完整性已达到较高水平，核心功能都有清晰的文档说明！🎉 diff --git a/docs/architecture/plugin-boundaries.md b/docs/architecture/plugin-boundaries.md new file mode 100644 index 000000000..161f505fc --- /dev/null +++ b/docs/architecture/plugin-boundaries.md @@ -0,0 +1,92 @@ +# Plugin Boundaries + +## 相关文档 + +- [插件标准](./plugin-standard.md) +- [插件优先重构](./plugin-first-refactor.md) + +## 当前分层 + +```mermaid +flowchart TD + L["ThinkLibrary
核心基础设施 / 门面 / 上下文 / Helper"] --> S["ThinkPlugsSystem
后台壳层 / 认证 / 菜单 / 用户 / system_* / 存储中心 / 开发交付工具"] + L --> W["ThinkPlugsWorker
queue / process 运行时实现"] + + S --> W + S --> SF["system_file
存储驱动 / 上传接口"] + S --> HT["plugin\\system\\helper\\*
发布 / 迁移 / 打包工具"] + S --> AC["ThinkPlugsAccount"] + S --> P["ThinkPlugsPayment"] + S --> WC["ThinkPlugsWechatClient"] + S --> WS["ThinkPlugsWechatService"] + S --> WM["ThinkPlugsWemall"] + S --> U["ThinkPlugsWuma"] + + W --> P + W --> WC + W --> U + + AC --> P + AC --> WM + P --> WM + WM --> U +``` + +## 表归属 + +```mermaid +flowchart LR + SYS["ThinkPlugsSystem"] --> SB["system_base"] + SYS --> SD["system_data"] + SYS --> SO["system_oplog"] + SYS --> SA["system_auth"] + SYS --> SAN["system_auth_node"] + SYS --> SM["system_menu"] + SYS --> SU["system_user"] + SYS --> SF["system_file"] + + WK["ThinkPlugsWorker"] --> SQ["system_queue"] +``` + +## Library 内部分层 + +```mermaid +flowchart TD + SV["service
AppService / NodeService / RuntimeService / QueueService / CacheSession / JwtToken"] + RT["runtime
SystemContext / NullSystemContext / RequestContext / RequestTokenService"] + MW["middleware
MultAccess"] + RO["route
Route / Url"] + HP["helper
Query / Form / Save / Delete / Validate / Builder"] + MD["model / extend / contract"] + + MW --> SV + RO --> SV + HP --> RT + HP --> MD + RT --> SV + SV --> MD +``` + +## 关键约束 + +- `ThinkLibrary` 不直接持有 `system_* / system_file / system_queue` 域真实表实现。 +- `ThinkPlugsSystem` 同时承载系统后台壳层、`system_*` 核心数据和存储中心，不再拆分独立 `Admin` / `Storage` 插件。 +- `ThinkPlugsWorker` 提供 `ProcessService / QueueService` 的真实实现，`ThinkLibrary` 只保留门面。 +- `system_file` 迁移、文件管理和上传链路归 `ThinkPlugsSystem`，业务插件只消费 Storage 门面。 +- `FaviconBuilder / ImageSliderVerify / JsonRpcHttpClient / JsonRpcHttpServer` 这类跨组件基础能力保留在 `ThinkLibrary`，业务插件只消费，不重复实现。 + +## 目录规范 + +- 每个业务插件只保留 `src / stc / tests` 三层顶级目录。 +- `src` 下优先使用标准目录：`controller / lang / model / route / service / view`。 +- 只有确实需要命令入口的插件才增加 `command` 目录。 +- `src` 根目录只保留 `Service.php`，以及确实需要全局函数时才保留 `common.php`。 +- 不再新增 `auth / runtime / system / support / integration / queue / storage / handle` 这类职责模糊目录；相关实现统一收敛到 `service` 或更明确的标准目录。 + +## 已有自动化守卫 + +- 代码位置边界：`ArchitectureBoundaryTest` +- 迁移归属边界：`MigrationOwnershipTest` +- Composer 依赖边界：`ComposerDependencyBoundaryTest` + +这些测试已经纳入根 `composer test`。 diff --git a/docs/architecture/plugin-first-refactor.md b/docs/architecture/plugin-first-refactor.md new file mode 100644 index 000000000..e0f65766a --- /dev/null +++ b/docs/architecture/plugin-first-refactor.md @@ -0,0 +1,76 @@ +# Plugin-First Refactor + +## 相关文档 +- [插件标准](./plugin-standard.md) +- [路由调度标准](./route-dispatch-standard.md) +- [软删除标准](./soft-delete-standard.md) + +## 目标 +- `plugin/*` 作为主业务承载目录。 +- `app/*` 仅保留本地多应用和过渡代码。 +- 页面入口统一为 `/{plugin}/...`。 +- 接口入口统一为 `/api/{plugin}/{controller}/{action}`。 +- 路由分发优先命中插件，再命中本地应用，最后回退到默认本地应用。 +- `_plugin` 与 `X-Plugin-App` 只保留为调试开关，默认关闭。 + +## 组件边界 + +### ThinkLibrary +- 提供 `Controller`、`Model`、`Plugin`、`Command` 等基础类型。 +- 负责插件发现、元数据读取、URL 构建、运行时上下文与路由适配。 +- 负责通用会话、JWT、RPC、Storage 门面与标准契约。 +- 不承载后台壳层、守护进程与发布导出能力。 + +### ThinkPlugsSystem +- 负责后台登录、首页、权限菜单、用户、系统配置、日志等后台壳层能力。 +- 持有 `system_auth`、`system_auth_node`、`system_menu`、`system_user`。 +- 持有 `system_data`、`system_base`、`system_oplog`。 +- 承载存储中心能力，负责驱动注册、配置协议、上传授权、上传接口与文件管理。 +- 提供 `system/config/storage`、`system/file/*` 与 `/api/system/upload/*`。 +- 持有 `system_file`。 +- 内置开发交付工具，统一使用 `plugin\system\helper\*` 命名空间。 +- 提供 `xadmin:publish`、`xadmin:package`、`xadmin:helper:*`。 + +### ThinkPlugsWorker +- 负责 Workerman 常驻进程、HTTP 托管、队列调度与运行控制。 +- 提供 `xadmin:worker` 统一入口。 +- 持有 `system_queue`。 + +### 业务插件 +- `ThinkPlugsWechatClient`、`ThinkPlugsWechatService`、`ThinkPlugsPayment`、`ThinkPlugsWemall` 等只承载自己的业务模型、控制器和菜单。 +- 不再把公共基础能力回写到 `app/*` 或 `extend/*`。 + +## 当前状态 +- 插件元数据统一收敛到 `composer.json > extra.xadmin`。 +- `ThinkLibrary` 已支持插件优先分发、本地应用兼容和默认本地应用回退。 +- `ThinkPlugsSystem`、`ThinkPlugsWorker` 的共享表已明确归属；原独立 Storage 与 Helper 已合并到 System。 +- 旧的根级门面与历史兼容目录已逐步收缩到最小集合。 +- 插件中心、存储中心、系统后台都已切换到插件化入口。 + +## 当前约定 + +### 插件注册 +- 每个插件统一使用 `src/Service.php` 作为服务入口。 +- 服务类统一通过 `composer.json > extra.think.services` 注册。 +- 插件编码、前缀、菜单、迁移、说明文档统一写在 `extra.xadmin`。 + +### 运行时 +- 页面链接优先使用 `sysuri()`。 +- 标准接口链接优先使用 `apiuri()`。 +- 根目录全局路由优先使用 `Route::bindApp()`、`Route::bindPlugin()`、`Route::appGroup()`、`Route::pluginGroup()`。 +- 新代码不再依赖旧式三段路由推断目标应用。 + +### 共享表归属 +- `system_auth`、`system_auth_node`、`system_menu`、`system_user` 归 `ThinkPlugsSystem`。 +- `system_data`、`system_base`、`system_oplog` 归 `ThinkPlugsSystem`。 +- `system_file` 归 `ThinkPlugsSystem` 存储中心。 +- `system_queue` 归 `ThinkPlugsWorker`。 + +### 前端脚本变量 +- 系统脚本统一下发 `taSystem`、`taSystemApi`、`taStorage`、`taStorageApi`、`taApiPrefix`。 +- 插件模板、静态脚本、上传脚本和公开预览页都优先消费这组变量。 + +## 后续收尾 +1. 继续清理历史文档和模板中的旧路由示例。 +2. 持续补齐跨平台回归，覆盖 Windows 与 Linux。 +3. 新增插件时严格走 `plugin-standard.md` 中的准入规则。 diff --git a/docs/architecture/plugin-standard.md b/docs/architecture/plugin-standard.md new file mode 100644 index 000000000..f51d7eda5 --- /dev/null +++ b/docs/architecture/plugin-standard.md @@ -0,0 +1,188 @@ +# Plugin Standard + +## 当前结论 +- `app/*` 负责本地多应用与过渡代码。 +- `plugin/*` 负责插件业务实现。 +- 插件分发优先于本地应用分发。 +- 默认本地应用为 `app/index`。 + +插件标准由以下部分共同约束： +- `think\admin\Plugin` +- `think\admin\service\AppService` +- System 内置的 `plugin\system\helper\plugin\PluginMenuService` +- System 内置的 `plugin\system\helper\migration\PhinxExtend` +- `composer.json > extra.xadmin` +- `composer.json > extra.xadmin.publish.copy` +- 架构边界与安装边界测试 + +## 插件包标准 + +### 1. Composer 类型 +- 参与运行时插件分发的组件统一使用 `think-admin-plugin`。 +- 纯开发、交付辅助能力统一内置到 `ThinkPlugsSystem`，不再新增独立工具包。 +- 安装协调组件 `ThinkPlugsInstall` 统一使用 `composer-plugin`，负责接管 Composer 生命周期内的自动发布与按需迁移。 + +### 2. 服务发现 +- 必须通过 `extra.think.services` 注册插件服务类。 +- 标准服务类命名为 `plugin\\{name}\\Service`。 + +### 3. 元数据 +- `extra.xadmin.app` 只描述应用级元数据。 + 必填：`code`、`name` + 可选：`prefix / prefixes / alias / space / document / description / platforms / license / icon / cover / super` +- `version`、`homepage` 等标准包字段继续使用 Composer 顶层定义，不再放到 `extra.xadmin.app`。 +- `extra.xadmin.menu` 按需描述菜单显示、根节点、菜单项与存在性检测。 +- `extra.xadmin.migrate` 按需描述主迁移脚本信息。 +- `extra.xadmin.publish.copy` 按需描述资源发布规则，统一使用 `copy` 清单。 + +运行时插件最小 `composer.json` 骨架： + +```json +{ + "type": "think-admin-plugin", + "name": "vendor/demo-plugin", + "description": "Demo Plugin for ThinkAdmin", + "autoload": { + "psr-4": { + "plugin\\\\demo\\\\": "src" + } + }, + "extra": { + "think": { + "services": [ + "plugin\\\\demo\\\\Service" + ] + }, + "xadmin": { + "app": { + "code": "demo", + "name": "演示插件", + "prefix": "demo" + } + } + } +} +``` + +纯工具组件可按需保留 `type=library`，并省略 `menu / migrate / publish` 等运行时块。 + +## 目录标准 + +### 1. 插件根目录 +- `composer.json` +- `readme.md` +- `readme.api.md` +- `src` +- `stc` +- `tests` + +### 2. 插件文档 +- 每个插件根目录只保留两份说明文档：`readme.md` 与 `readme.api.md`。 +- `readme.md` 只描述插件定位、边界、依赖与入口，不堆放接口明细、迁移细节或大段历史说明。 +- `readme.api.md` 统一描述接口标准与接口列表。 +- HTTP 插件在 `readme.api.md` 中按 `路由 + 请求方式 + 参数 JSONC` 组织，参数字段必须逐项写注释。 +- HTTP 插件的 `readme.api.md` 必须补充标准 JSON 响应结构，至少说明 `code`、`info`、`data` 字段和常用状态码 `200/401/403/404/500`。 +- 命令型或发布型组件在 `readme.api.md` 中按 `命令/配置入口 + 参数 JSONC` 组织，配置字段必须逐项写注释。 +- 插件目录下不再追加第三份功能说明、临时接入文档或历史迁移说明，额外专题文档统一放到仓库 `docs/`。 + +### 3. `src` 根目录 +- 必须保留 `Service.php`。 +- 只有确实需要全局函数时才保留 `common.php`。 +- 不再新增职责模糊的根级文件。 + +### 4. 常用子目录 +- `controller` +- `model` +- `service` +- `view` +- `command` +- `lang` +- `worker` +- `tests` + +## 运行时标准 + +### 1. 路由优先级 +1. 先按插件前缀匹配。 +2. 再按本地应用首段匹配。 +3. 再按根目录全局路由目标声明匹配。 +4. 再按动态插件切换匹配。 +5. 最后回退到默认本地应用。 + +### 2. 标准入口 +- 本地应用页面：`/{app}/{controller}/{action}` +- 插件页面：`/{plugin}/...` +- 插件接口：`/api/{plugin}/{controller}/{action}` + +### 3. 根路由声明 +- 优先使用 `Route::bindApp()` 与 `Route::bindPlugin()`。 +- 分组场景使用 `Route::appGroup()` 与 `Route::pluginGroup()`。 +- 根路由里的目标地址必须写成目标应用内部的相对节点。 + +### 4. 动态切换 +- `_plugin` 与 `X-Plugin-App` 仅作为调试入口。 +- 默认关闭，不作为正式业务路由依赖。 + +### 5. JSON 响应标准 +- HTTP JSON 接口统一返回 HTTP `200`，前后端不再使用 `1/0` 表示成功或失败。 +- 业务状态统一写入 `code` 字段，不再重复返回 `status`。 +- `200` 表示成功，业务数据通过 `data` 返回。 +- `401` 表示未认证、登录过期、令牌无效或会话失效。 +- `403` 表示已认证但无权限、账号禁用或访问被拒绝。 +- `404` 表示接口或资源不存在。 +- `500` 表示服务端异常或未分类业务异常。 + +## 插件服务标准 + +### 1. 基类 +- 参与运行时插件发现、路由或菜单元数据注入的服务统一继承 `think\admin\Plugin`。 +- 纯命令或工具组件如不参与运行时插件装配，可继续继承 `think\Service`。 + +### 2. 职责 +- 注册插件运行时能力。 +- 处理必要的中间件或路由挂载。 +- 承接 `composer.json` 中声明的插件元数据与发布规则。 +- 纯工具组件只承接命令注册或工程化能力，不承担运行时插件装配职责。 + +### 3. 非职责 +- 不在服务类中堆放业务逻辑。 +- 不在服务类中维护大量兼容桥接代码。 +- 不在服务类中声明运行时元数据字段或 `menu()` 之类的旧入口。 + +## 菜单与权限标准 +- 菜单数据统一来自 `composer.json > extra.xadmin.menu.items`。 +- 菜单引用的控制器节点必须真实存在。 +- 叶子节点必须同时声明 `@auth true` 与 `@menu true`。 +- 菜单写入前必须经过 `PluginMenuService::assertMenus()` 校验。 + +## 数据库与发布标准 +- 每个插件只保留一份最终安装迁移脚本。 +- 主迁移脚本以插件内 `stc/database` 为准。 +- 自动迁移开关统一来自 `composer.json > extra.xadmin.migrate`；未声明时只能提示，不能在 Composer 安装链路中强制建表。 +- 发布资源统一来自 `composer.json > extra.xadmin.publish.copy`。 +- 发布规则只保留 `copy`，结构化规则统一使用 `source: { to, force, exclude }` 或 `{ from, to, force, exclude }`。 +- 自动发布与按需迁移统一由 `zoujingli/think-plugs-install` Composer plugin 驱动，根项目需通过 `config.allow-plugins` 显式允许。 +- 首次 Composer 安装只执行发布，不自动建表；后续变更才依据 `extra.xadmin.migrate` 做自动迁移。 +- 根目录 `database/migrations` 视为发布产物，不是主维护源。 +- 共享表必须遵守固定归属，不允许多插件重复持有。 + +## 依赖标准 +- 本地插件依赖统一走 Composer `path` repository。 +- 依赖图必须尽量保持无环。 +- `ThinkPlugsSystem` 可以依赖 `library / static / worker`，并内置 storage 与 helper 能力。 +- 业务插件不应重新把共享基础能力耦回 `system` 或 `library`。 + +## 测试要求 +- 新增插件必须通过安装边界、路由边界、目录边界和迁移边界测试。 +- 菜单、入口、迁移和 URL 规则必须有最小回归覆盖。 + +## 新插件准入清单 +1. 提供独立 `composer.json`。 +2. 提供 `src/Service.php`。 +3. 在 `extra.xadmin.app` 中声明 `code / prefix / name`。 +4. 有后台菜单时，在 `extra.xadmin.menu` 中声明菜单元数据。 +5. 需要发布资源时，在 `extra.xadmin.publish.copy` 中声明规则。 +6. 需要安装表结构时，在 `stc/database` 中保留唯一主迁移脚本，并通过 `extra.xadmin.migrate` 声明主脚本。 +7. 运行时插件服务继承 `think\admin\Plugin`；纯工具组件按需继承 `think\Service`。 +8. 不在 `Service.php` 中声明元数据字段或 `menu()` 兼容入口。 +9. 补齐最小安装与路由测试。 diff --git a/docs/architecture/plugins-detail.md b/docs/architecture/plugins-detail.md new file mode 100644 index 000000000..d6231022c --- /dev/null +++ b/docs/architecture/plugins-detail.md @@ -0,0 +1,774 @@ +# 插件详细说明 + +本文档详细描述每个插件的功能、结构、依赖和使用方式。 + +## 核心组件 + +### ThinkLibrary + +**包名**: `zoujingli/think-library` + +**定位**: 核心基础库，提供整个框架的运行时基础设施 + +**命名空间**: `think\admin\` + +**服务注册**: +```json +{ + "extra": { + "think": { + "services": ["think\admin\Library"] + } + } +} +``` + +**核心功能**: +- **运行时服务**: `RuntimeService`, `AppService`, `NodeService` +- **认证会话**: `JwtToken`, `CacheSession`, `RequestTokenService` +- **路由适配**: `Route`, `Url`, `MultAccess` 中间件 +- **队列契约**: `QueueService` (门面), `QueueServiceInterface` (契约) +- **Storage 门面**: `Storage` 统一存储接口 +- **基础类型**: `Controller`, `Model`, `Command`, `Plugin`, `Service`, `Exception` +- **Helper 工具**: `QueryHelper`, `FormBuilder`, `PageBuilder`, `ValidateHelper` +- **扩展工具**: `CodeToolkit`, `FileTools`, `HttpClient`, `ArrayTree` + +**接口响应约定**: +- HTTP JSON 接口统一返回 HTTP `200` +- 常用业务状态码统一为 `200/401/403/404/500` +- 标准 JSON 字段为 `code`、`info`、`data`，鉴权异常可附加稳定 `error` + +**目录结构**: +``` +think-library/ +├── src/ +│ ├── contract/ # 标准契约接口 +│ ├── extend/ # 扩展工具类 +│ ├── helper/ # 构建器工具 +│ ├── middleware/ # 中间件 +│ ├── model/ # 模型扩展 +│ ├── route/ # 路由相关 +│ ├── runtime/ # 运行时上下文 +│ ├── service/ # 核心服务 +│ ├── common.php # 全局函数 +│ ├── Controller.php # 标准控制器 +│ ├── Model.php # 标准模型 +│ └── Library.php # 服务注册类 +└── tests/ # 单元测试 +``` + +**依赖关系**: +- PHP >= 8.1 +- ThinkPHP 8.1+ +- 扩展：gd, curl, json, zlib, iconv, openssl, mbstring + +--- + +### ThinkPlugsSystem + +**包名**: `zoujingli/think-plugs-system` + +**定位**: 系统后台，提供后台壳层、认证权限和系统运维能力 + +**命名空间**: `plugin\system\` + +**服务注册**: +```json +{ + "extra": { + "think": { + "services": ["plugin\\system\\Service"] + }, + "xadmin": { + "app": { + "code": "system", + "name": "系统管理", + "prefix": "system" + } + } + } +} +``` + +**数据表**: +- `system_base` - 系统基础配置 +- `system_data` - 系统扩展数据 +- `system_oplog` - 系统操作日志 +- `system_file` - 系统文件记录 +- `system_auth` - 系统权限角色 +- `system_auth_node` - 权限节点绑定 +- `system_menu` - 系统菜单管理 +- `system_user` - 系统用户管理 + +**核心功能**: +- **后台壳层**: 登录页面、首页、后台框架 +- **认证授权**: JWT 认证、RBAC 权限、菜单控制 +- **系统用户**: 用户管理、角色管理、权限分配 +- **系统配置**: 参数配置、字典管理、配置缓存 +- **操作日志**: 操作记录、日志审计 +- **任务管理**: 系统任务查看和管理 +- **存储中心**: 文件管理、上传授权、多存储驱动 +- **开发交付工具**: 资源发布、安装包生成、迁移导出、菜单校验 + +**目录结构**: +``` +think-plugs-system/ +├── src/ +│ ├── controller/ # 控制器 +│ ├── helper/ # 开发交付工具（plugin\system\helper\*） +│ ├── lang/ # 语言包 +│ ├── middleware/ # 中间件 (JwtTokenAuth, RbacAccess) +│ ├── model/ # 模型 +│ ├── route/ # 路由 +│ ├── service/ # 服务 +│ │ ├── CaptchaService.php +│ │ ├── SystemAuthService.php +│ │ ├── SystemContext.php +│ │ ├── SystemService.php +│ │ └── UserService.php +│ ├── storage/ # 存储驱动与上传授权 +│ └── view/ # 视图模板 +├── stc/database/ # 数据库迁移 +└── tests/ # 单元测试 +``` + +**依赖**: +- ThinkLibrary +- ThinkPlugsStatic +- ThinkPlugsWorker +- Doctrine/DBAL +- ThinkPHP Migration +- ThinkPHP IDE Helper + +--- + +### ThinkPlugsWorker + +**包名**: `zoujingli/think-plugs-worker` + +**定位**: Workerman 运行时，提供 HTTP 和队列常驻服务 + +**命名空间**: `plugin\worker\` + +**服务注册**: +```json +{ + "extra": { + "think": { + "services": ["plugin\\worker\\Service"] + }, + "xadmin": { + "app": { + "code": "worker", + "name": "运行时服务", + "prefix": "worker" + } + } + } +} +``` + +**数据表**: +- `system_queue` - 系统任务队列 + +**核心功能**: +- **HTTP 服务**: 托管系统 HTTP 服务，支持多进程 +- **队列服务**: 长耗时任务调度、延时任务处理 +- **进程管理**: 跨平台进程控制（start/stop/status/restart） +- **状态监控**: 内存监控、文件监控、健康检查 + +**命令入口**: +```bash +php think xadmin:worker start http -d # 启动 HTTP 服务 +php think xadmin:worker start queue -d # 启动队列服务 +php think xadmin:worker status all # 查看运行状态 +php think xadmin:worker stop http # 停止 HTTP 服务 +php think xadmin:worker restart all # 重启所有服务 +``` + +**跨平台实现**: +- **Linux/macOS**: Workerman 守护进程 + 信号控制（reload/stop） +- **Windows**: console.exe 启动后台 PHP 进程 + 进程扫描 + +**目录结构**: +``` +think-plugs-worker/ +├── src/ +│ ├── command/ # CLI 命令 +│ ├── model/ # 模型 +│ ├── service/ # 服务 +│ │ ├── Server.php +│ │ ├── QueueService.php +│ │ └── ProcessService.php +│ └── common.php # 全局函数 +├── stc/ +│ └── worker.php # 配置文件模板 +└── tests/ # 单元测试 +``` + +**依赖**: +- ThinkLibrary +- Workerman 5.1.9+ +- Symfony/Process 6.0+ + +--- + +### System 内置存储中心 + +**包名**: `zoujingli/think-plugs-system` + +**定位**: System 内置存储中心，统一管理存储驱动和上传授权 + +**命名空间**: `plugin\system\storage\` + +**服务注册**: 随 `plugin\system\Service` 注册，并通过 `StorageManagerInterface` 绑定真实实现。 + +**数据表**: +- `system_file` - 系统文件记录 + +**核心功能**: +- **驱动管理**: 本地存储、OSS、COS、七牛等驱动注册 +- **配置中心**: 存储配置管理、驱动切换 +- **上传授权**: 临时授权、上传令牌、安全校验 +- **文件管理**: 文件列表、下载、删除、统计 + +**目录结构**: +``` +think-plugs-system/ +├── src/ +│ ├── controller/Config.php # 存储配置入口 +│ ├── controller/File.php # 文件管理入口 +│ ├── controller/api/Upload.php # 上传接口 +│ ├── model/SystemFile.php # 文件记录模型 +│ └── storage/ # 存储驱动与授权 +│ ├── StorageConfig.php +│ ├── StorageManager.php +│ ├── StorageAuthorize.php +│ └── LocalStorage.php +└── stc/database/ # system_file 迁移随 System 发布 +``` + +**依赖**: +- ThinkLibrary + +--- + +### System 内置开发交付工具 + +**归属包名**: `zoujingli/think-plugs-system` + +**定位**: 原 ThinkPlugsHelper 已合并到 System，提供迁移、发布、打包等开发交付能力。 + +**命名空间**: `plugin\system\helper\` + +**代码位置**: `plugin/think-plugs-system/src/helper/` + +**服务注册**: +```json +{ + "extra": { + "think": { + "services": ["plugin\\system\\Service", "plugin\\system\\helper\\Service"] + }, + "xadmin": { + "app": { + "code": "system", + "name": "系统管理", + "prefix": "system" + } + } + } +} +``` + +**核心功能**: +- **发布工具**: `xadmin:publish` - 发布配置、静态资源、迁移脚本 +- **打包工具**: `xadmin:package` - 生成安装包 +- **迁移工具**: `xadmin:helper:migrate` - 生成插件迁移脚本 +- **模型工具**: `xadmin:helper:model` - 生成模型文件 +- **菜单工具**: 菜单校验、节点同步 +- **注释工具**: 自动生成代码注释 + +**目录结构**: +``` +think-plugs-system/ +└── src/helper/ + ├── Service.php + ├── command/ # CLI 命令 + │ ├── database/ # 数据库相关命令 + │ ├── project/ # 发布与打包命令 + │ └── system/ # 系统维护命令 + ├── database/ # 数据库工具 + ├── integration/ # 集成服务 + ├── migration/ # 迁移工具 + ├── model/ # 模型工具 + ├── plugin/ # 插件工具 + │ ├── PluginMenuService.php + │ └── PluginRegistry.php + └── service/ # 服务模板 +``` + +**依赖**: +- ThinkLibrary +- ThinkPlugsWorker +- Doctrine/DBAL +- ThinkPHP Migration +- ThinkPHP IDE Helper + +--- + +### ThinkPlugsStatic + +**包名**: `zoujingli/think-plugs-static` + +**定位**: 静态资源和项目骨架组件 + +**特点**: +- 无前缀，不直接访问 +- 通过其他插件间接使用 +- 提供静态资源发布能力 + +**核心功能**: +- **静态资源**: LayUI、jQuery、前端模块等 +- **模板文件**: 后台模板、错误页面、主题样式 +- **项目骨架**: 新项目初始化模板 +- **图标字体**: iconfont 图标库 + +--- + +## 平台插件 + +### ThinkPlugsWechatClient + +**包名**: `zoujingli/think-plugs-wechat-client` + +**定位**: 微信公众号标准平台 + +**命名空间**: `plugin\wechat\` + +**访问前缀**: `wechat` + +**核心功能**: +- 公众号基础配置 +- 菜单管理 +- 消息推送 +- 粉丝管理 +- 素材管理 + +**数据表**: +- 微信配置表 +- 菜单表 +- 消息记录表 +- 粉丝表 +- 素材表 + +--- + +### ThinkPlugsWechatService + +**包名**: `zoujingli/think-plugs-wechat-service` + +**定位**: 微信公众号开放平台（第三方平台托管） + +**命名空间**: `plugin\wechat\service\` + +**访问前缀**: `wechat-service` + +**核心功能**: +- 第三方平台授权 +- 组件配置管理 +- 代公众号实现业务 +- JSON-RPC 接口 + +**数据表**: +- 第三方授权表 +- 组件配置表 +- 预授权码表 + +--- + +## 业务插件 + +### ThinkPlugsAccount + +**包名**: `zoujingli/think-plugs-account` + +**定位**: 多端账号体系管理 + +**命名空间**: `plugin\account\` + +**访问前缀**: `account` + +**许可证**: VIP 授权 + +**数据表**: +- 用户账号表 +- 终端绑定表 +- 短信记录表 +- 其他账号相关表 + +**菜单**: +- 用户管理 + - 用户账号管理 + - 终端账号管理 + - 手机短信管理 + +**依赖**: +- ThinkLibrary +- ThinkPlugsSystem +- ThinkPlugsWechatClient + +--- + +### ThinkPlugsPayment + +**包名**: `zoujingli/think-plugs-payment` + +**定位**: 支付中心 + +**命名空间**: `plugin\payment\` + +**访问前缀**: `payment` + +**许可证**: VIP 授权 + +**数据表**: +- 支付配置表 +- 交易记录表 +- 退款记录表 +- 余额明细表 +- 积分明细表 + +**菜单**: +- 支付管理 + - 支付配置管理 + - 支付行为管理 + - 支付退款管理 + - 余额明细管理 + - 积分明细管理 + +**依赖**: +- ThinkLibrary +- ThinkPlugsSystem +- ThinkPlugsWorker +- ThinkPlugsAccount + +--- + +### ThinkPlugsWemall + +**包名**: `zoujingli/think-plugs-wemall` + +**定位**: 分销商城系统 + +**命名空间**: `plugin\wemall\` + +**访问前缀**: `wemall` + +**许可证**: VIP 授权 + +**数据表**: +- 商品表 +- 订单表 +- 用户表 +- 会员等级表 +- 代理等级表 +- 物流表 +- 其他商城相关表 + +**菜单**: +- 商城配置 + - 数据统计报表 + - 系统通知管理 + - 商城参数管理 + - 推广海报管理 + - 店铺页面装修 + - 快递公司管理 + - 邮费模板管理 +- 用户管理 + - 会员等级管理 + - 会员折扣方案 + - 会员用户管理 + - 创建会员用户 + - 用户余额充值 +- 商城管理 + - 商品数据管理 + - 订单数据管理 + - 订单发货管理 + - 售后订单管理 + - 商品评论管理 +- 代理管理 + - 代理等级管理 + - 代理返佣管理 + - 代理提现管理 +- 帮助咨询 + - 常见问题管理 + - 意见反馈管理 + +**依赖**: +- ThinkLibrary +- ThinkPlugsSystem +- ThinkPlugsAccount +- ThinkPlugsPayment + +--- + +### ThinkPlugsWuma + +**包名**: `zoujingli/think-plugs-wuma` + +**定位**: 一物一码与防伪溯源系统 + +**命名空间**: `plugin\wuma\` + +**访问前缀**: `wuma` + +**许可证**: VIP 授权 + +**数据表**: +- 防伪码表 +- 溯源记录表 +- 其他相关表 + +**依赖**: +- ThinkLibrary +- ThinkPlugsSystem +- ThinkPlugsWorker +- ThinkPlugsWemall + +--- + +## 插件依赖关系图 + +``` +ThinkLibrary (核心基础) + │ + ├─► ThinkPlugsSystem (系统后台) + │ │ + │ ├─► System 内置存储中心 (system_file / upload) + │ ├─► ThinkPlugsWorker (运行时) + │ └─► System 内置 Helper 工具 (plugin\system\helper\*) + │ + ├─► ThinkPlugsWechatClient (公众号) + └─► ThinkPlugsWechatService (开放平台) + +业务插件依赖: +┌─────────────────────────────────────┐ +│ ThinkPlugsAccount (账号) │ +│ 依赖：System, WechatClient │ +└─────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────┐ +│ ThinkPlugsPayment (支付) │ +│ 依赖：Account, System, Worker │ +└─────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────┐ +│ ThinkPlugsWemall (商城) │ +│ 依赖：Account, Payment, System │ +└─────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────┐ +│ ThinkPlugsWuma (一物一码) │ +│ 依赖：Wemall, System, Worker │ +└─────────────────────────────────────┘ +``` + +--- + +## 插件开发标准 + +### 目录规范 + +每个插件必须遵循以下目录结构: + +``` +plugin-name/ +├── src/ +│ ├── controller/ # 控制器（必需） +│ ├── model/ # 模型（可选） +│ ├── service/ # 服务（必需） +│ │ └── Service.php # 服务注册入口 +│ ├── view/ # 视图（可选） +│ ├── lang/ # 语言包（可选） +│ ├── route/ # 路由（可选） +│ ├── middleware/ # 中间件（可选） +│ ├── command/ # CLI 命令（可选） +│ └── common.php # 全局函数（可选） +├── stc/ +│ ├── config/ # 配置发布目录 +│ ├── database/ # 数据库迁移 +│ └── ... # 其他发布资源 +├── tests/ # 单元测试 +├── composer.json # Composer 配置 +├── readme.md # 插件说明 +└── readme.api.md # 接口与参数说明 +``` + +### Composer 配置标准 + +```json +{ + "type": "think-admin-plugin", + "name": "zoujingli/think-plugs-{name}", + "autoload": { + "psr-4": { + "plugin\\{name}\\": "src" + } + }, + "extra": { + "think": { + "services": ["plugin\\{name}\\Service"] + }, + "xadmin": { + "app": { + "code": "{name}", + "name": "{Name}", + "prefix": "{prefix}" + }, + "menu": { ... }, + "migrate": { ... } + } + } +} +``` + +### 服务注册标准 + +运行时插件的 `src/Service.php` 统一继承 `think\admin\Plugin`；纯命令或辅助工具组件可继续继承 `think\Service`。 + +运行时插件服务示例： + +```php +assertTrue(class_exists('plugin\\{name}\\Service')); + } +} +``` + +运行测试: +```bash +vendor/bin/phpunit --filter PluginTest +``` + +--- + +## 插件发布流程 + +### 发布配置 + +```bash +# 显式执行完整安装链路 +php think xadmin:install + +# 发布所有插件配置 +php think xadmin:publish + +# 发布并执行全部已发布迁移 +php think xadmin:publish --migrate +``` + +### 发布流程 + +1. `zoujingli/think-plugs-install` 作为 Composer plugin，在 `composer install / update / remove / dump-autoload` 后自动接管安装链路 +2. 先执行 `service:discover`，再读取各插件 `composer.json` 的 `extra.xadmin.publish.copy` 规则 +3. 按规则同步配置、骨架和静态资源；目标路径前加 `!` 时单项强制覆盖，结构化规则可通过 `exclude` 跳过目录内文件 +4. 同步 `stc/database/` 到 `database/migrations/` +5. 首次 Composer 安装只执行发布，不直接建表；后续只有声明了 `extra.xadmin.migrate` 的变更插件，才会自动执行数据库迁移；未声明时只输出提示 +6. 记录资源发布状态到 `vendor/.published.json`，记录安装快照到 `vendor/.plugin-state.json`，记录迁移发布状态到 `database/migrations/.published.json` + +--- + +## 插件卸载说明 + +**重要提示**: 插件卸载通常不会自动删除: +- 已执行的数据库迁移 +- 历史业务数据 +- 已发布的配置文件 + +如需完全卸载，需要: +1. 手动回滚数据库迁移 +2. 手动删除业务数据 +3. 手动清理配置文件 diff --git a/docs/architecture/route-dispatch-standard.md b/docs/architecture/route-dispatch-standard.md new file mode 100644 index 000000000..bc1b8b4f8 --- /dev/null +++ b/docs/architecture/route-dispatch-standard.md @@ -0,0 +1,118 @@ +# Route Dispatch Standard + +## 目标 + +当前项目的最佳实践不是让根路由“先命中、后猜应用”，而是让根路由先声明目标应用或插件，再进入真实调度。 + +这样可以在分发前就绑定正确的： + +- 应用目录 +- 命名空间 +- `view_path` +- 应用级配置 +- 中间件 +- 语言包 +- 插件入口类型（`web` / `api`） + +否则全局路由虽然能命中，但很容易出现这些问题： + +- 模板从错误目录加载 +- 控制器命名空间错误 +- 插件 API 被当成普通页面入口 +- 本地应用配置和中间件没有生效 + +## 当前标准 + +### 1. 本地与插件模型 + +- `app/*`：本地多应用 +- `plugin/*`：插件应用 +- 默认本地应用：`index` + +### 2. 分发优先级 + +`MultAccess` 当前的标准优先级是： + +1. 显式插件前缀 +2. 显式本地应用前缀 +3. 根路由声明的目标应用/插件 +4. 动态插件切换（兼容入口，默认关闭） +5. 默认本地应用 + +### 3. 标准入口 + +- 本地应用显式入口：`/{app}/{controller}/{action}` +- 默认本地应用：生成 URL 时可省略 `index` +- 插件页面入口：`/{plugin}/{controller}/{action}` +- 插件 API 入口：`/api/{plugin}/{controller}/{action}` + +## 路由注册标准 + +### 1. 单条路由 + +```php +use think\admin\runtime\RequestContext; +use think\facade\Route; + +Route::bindApp('portal', 'home/index', 'index'); +Route::bindPlugin('open-upload', 'api.upload/file', 'system', RequestContext::ENTRY_API); +``` + +约束： + +- `portal`、`open-upload` 是根路由规则 +- `home/index`、`api.upload/file` 是目标应用内部相对路径 +- 不再推荐把目标地址写成带应用前缀的旧三段式 + +### 2. 分组路由 + +```php +use think\admin\runtime\RequestContext; +use think\facade\Route; + +Route::appGroup('member', function () { + Route::get('member-center', 'center/index'); +}); + +Route::pluginGroup('system', function () { + Route::get('quick-upload', 'api.upload/file'); +}, RequestContext::ENTRY_API); +``` + +这适合一批根路由都指向同一个本地应用或插件的场景。 + +### 3. 兼容旧路由 + +以下旧写法仍会尝试做目标推断： + +```php +Route::rule('legacy-demo', 'index/demo/index'); +Route::rule('legacy-login', 'system/login/index'); +``` + +兼容规则只用于过渡： + +- 如果第一段能识别为插件编码，优先按插件处理 +- 否则如果第一段能识别为本地应用编码，按本地应用处理 + +新代码不要继续依赖这种隐式推断。 + +## 为什么这样最好 + +这套机制的关键价值是“先选上下文，再执行路由”。 + +只要目标应用/插件已经在分发前绑定完成，后面的控制器解析、模板加载、配置加载和中间件链都会落在正确目录，不需要再用各种运行时补丁去修视图路径或命名空间。 + +这比单纯在 `MultAccess` 里追加更多 if/else 更稳，因为： + +- 路由语义在注册阶段就是显式的 +- 全局路由不会再偷偷依赖当前默认应用 +- 本地多应用和插件机制可以同时存在 +- 迁移旧路由时有明确新标准和兼容兜底 + +## 推荐约束 + +- 根目录 `route/*.php` 只写跨应用或跨插件的全局路由 +- 应用内部路由放各自 `app/{name}/route` 或 `plugin/*/src/route` +- 根路由一律使用 `bindApp` / `bindPlugin` / `appGroup` / `pluginGroup` +- 如果必须保留旧三段式，后续要逐步迁成显式目标声明 diff --git a/docs/architecture/soft-delete-standard.md b/docs/architecture/soft-delete-standard.md new file mode 100644 index 000000000..e454fff1e --- /dev/null +++ b/docs/architecture/soft-delete-standard.md @@ -0,0 +1,54 @@ +# Soft Delete Standard + +## 当前结论 + +- ORM 软删除字段统一为 `delete_time` +- `delete_time` 是唯一允许继续新增到数据库脚本里的软删除物理字段 +- `deleted`、`deleted_time`、`deleted_at` 不再作为物理字段或兼容迁移保留 +- 不需要软删除的模型，不应再通过 `deleteTime = false` 反向关闭，而应直接使用不带 `SoftDelete` 的普通基类 + +## 当前实现 + +### 1. 模型默认时间字段 + +- 基类 `think\admin\Model` 默认使用 `create_time` 和 `update_time` +- 软删除模型统一使用 `SoftDelete` trait，并把目标字段固定为 `delete_time` + +### 2. 删除执行路径 + +- 使用 `DeleteHelper` 删除模型时： + - 模型启用了 `SoftDelete`，则写入 `delete_time` + - 模型未启用 `SoftDelete`，则执行物理删除 + +### 3. 基类约束 + +- 软删除模型应继承带 `SoftDelete` 的业务基类 +- 非软删除模型应继承普通业务基类 +- 不再推荐在同一个基类体系里通过 `deleteTime = false` 做例外开关 + +## 禁止事项 + +以下写法不再允许继续引入： + +- `deleted` +- `deleted_time` +- `deleted_at` +- `whereRaw('deleted=0')` +- `field(...deleted...)` +- `withoutField('deleted')` + +这些写法都会把代码重新绑回旧字段语义。 + +## 新代码规范 + +1. 新表需要软删除时，只能使用 `delete_time datetime null` +2. 新模型需要软删除时，使用统一软删除基类或显式 `SoftDelete` +3. 新模型不需要软删除时，直接使用普通基类，不再写 `deleteTime = false` +4. 业务状态和软删除必须分开设计，不能混用“作废/取消/失效”字段代替软删除 +5. 数据库脚本、模型注释、测试断言都必须统一使用 `delete_time` + +## 清理结果 + +- 历史兼容软删除迁移已经退化为空迁移占位，不再执行任何字段兼容逻辑 +- 软删除与物理删除模型已经按基类分流 +- 后续如果再出现旧字段名或 `deleteTime = false`，应视为回归 diff --git a/docs/architecture/stability-status.md b/docs/architecture/stability-status.md new file mode 100644 index 000000000..e296ed704 --- /dev/null +++ b/docs/architecture/stability-status.md @@ -0,0 +1,72 @@ +# Stability Status + +## 当前结论 + +截至当前代码状态，系统整体稳定性判断为： + +- 架构稳定性：中高 +- 核心认证链路：中高 +- 运行时回归保障：中高 + +这表示项目已经适合继续作为当前主线架构推进，关键链路已经具备稳定的自动化回归保护。 + +## 已稳定的部分 + +### 1. 认证主线已收敛 + +- 后台与业务账号都统一到显式 Token +- 请求级令牌识别已收敛到统一入口 +- `Authorization` 与 Cookie 的优先级已经明确 +- 旧 `api-token` 已从项目实现层移除 + +### 2. 登录态承载已切换 + +- 标准 Session 不再承载后台和 API 登录态 +- Token Session 已切到 `sid + CacheSession` +- 注销、续期、过期判断已经围绕 `sid` 工作 + +### 3. 插件边界更清晰 + +- `ThinkLibrary` 负责运行时、认证协议、执行协议 +- `System`、`Account`、`Wuma` 的认证场景已能区分 +- 开发型命令已从 `ThinkLibrary` 迁出到 `Helper` + +## 当前主要风险 + +### 1. 设备认证仍是独立分支 + +- `wuma` 仍使用独立设备 token +- 它没有复用通用账号 JWT 和 Token Session +- 这不是错误，但会增加长期维护成本 + +如果未来设备域扩张，这条分支会成为额外复杂度来源。 + +### 2. 浏览器 Cookie 回退依赖配置 + +- 跨域场景仍依赖 `setcookie`、CORS、`credentials` 配置 +- 如果前后端部署策略变化，最先出问题的通常是 Cookie 回退链路 + +因此默认仍建议优先走 `Authorization`。 + +## 当前建议 + +### 优先级 P1 + +- 继续补齐剩余控制器和事件链的 SQLite 集成回归 +- 把“认证成功 / 失效 / 续期 / Cookie 回退”继续保持在固定回归脚本内 + +### 优先级 P2 + +- 继续统一文档入口，避免 README 各写各的 +- 继续收紧插件目录和描述边界，避免旧命名回流 + +### 优先级 P3 + +- 评估 `wuma` 是否继续保留独立设备认证 +- 如果设备端会长期存在，再考虑抽成标准设备认证层 + +## 当前可接受判断 + +如果以“当前主线开发是否可继续”为标准，答案是可以。 + +如果以“是否已经具备强回归保障”为标准，答案是否。 diff --git a/docs/architecture/system-module-refactor-plan.md b/docs/architecture/system-module-refactor-plan.md new file mode 100644 index 000000000..3522eb28a --- /dev/null +++ b/docs/architecture/system-module-refactor-plan.md @@ -0,0 +1,489 @@ +# System Module Refactor Plan + +## 目标 + +- 基于当前 `think-library` 的 `FormBuilder / PageBuilder` 重构 `System` 模块。 +- 以控制器注释为 RBAC 权限源头，数据库只保存同步后的角色、节点、菜单和用户授权关系。 +- 在重构阶段允许直接调整 `System` 主安装脚本字段，并通过新库重建验证结果。 +- 为后续其他插件重构建立统一的数据库脚本命名、Builder 分层和字段命名规范。 + +## 当前结论 + +### 1. Builder 体系 + +- 不恢复旧的动态 Builder 模块。 +- 当前 `System` 模块已经在使用新的 `Controller + Service + Builder` 结构。 +- 现阶段应该继续复用： + - `plugin/think-library/src/builder/form/*` + - `plugin/think-library/src/builder/page/*` + - `plugin/think-plugs-system/src/builder/*` + +### 2. RBAC 体系 + +- 节点来源于控制器注释扫描。 +- 当前约定已经存在： + - `@auth true` 表示权限节点 + - `@menu true` 表示菜单节点 + - `@login true` 表示仅登录可访问 +- 运行时节点解析当前由 `think\admin\service\NodeService` 完成。 + +### 3. 数据库脚本约束 + +- `plugin/think-plugs-system/stc/database/20241010000001_install_system20241010.php` 是 `System` 主维护源。 +- 根目录 `database/migrations/*.php` 视为发布产物，不是主维护源。 +- 每个插件只保留一个主安装脚本，不在重构期间增加多份临时 install 脚本。 + +## 重构范围 + +### 第一批 + +- `Auth` +- `User` +- `Menu` + +### 第二批 + +- `Base` +- `Config` +- `File` + +### 第三批 + +- `Queue` +- `Oplog` +- `Plugin` +- `Index` +- `Login` + +## 统一设计原则 + +### 1. Source of Truth + +- 权限节点来源：控制器注释 +- 插件菜单来源：插件 `composer.json > extra.xadmin.menu` +- 系统菜单来源：数据库中的运行时配置和覆盖 +- 角色授权来源：角色与节点关系表 +- 用户授权来源：用户与角色关系表 + +### 2. 分层职责 + +- `Controller` 只负责输入输出、Builder 响应和异常转换 +- `Service` 负责业务编排、同步逻辑、字段适配和约束校验 +- `Builder` 负责页面结构、表单结构和前端交互装配 +- `Model` 只保留领域对象、关联和必要的属性转换 + +### 3. 命名原则 + +- 外键统一使用 `*_id` +- 时间字段统一使用 `create_time / update_time / delete_time` +- 状态字段统一使用 `status` +- 备注字段统一使用 `remark` +- URL/路由字段区分： + - `route_path` 表示站内路由 + - `link_url` 表示完整外链 +- JSON 字段只存结构化数据，不再混存纯文本和结构对象 + +## 目标数据模型 + +### Phase 1 落地说明 + +第一批 `Auth / User / Menu` 当前采用兼容式字段重命名方案，优先保证现有页面、测试和安装脚本能平滑过渡。 + +第一批优先落地字段： + +- `system_auth.code` +- `system_auth.remark` +- `system_user.base_code` +- `system_user.auth_ids` +- `system_user.remark` + +第一批暂不强制引入新的用户角色关系表，避免一次性改动过大。`system_user_auth` 保留为第二阶段可选增强。 + +### 1. system_auth + +定位：角色定义表 + +建议保留表名，调整字段语义。 + +建议字段： + +- `id` +- `code`：角色编码，唯一 +- `title`：角色名称 +- `remark`：角色说明 +- `sort` +- `status` +- `create_time` +- `update_time` + +当前问题： + +- `utype` 语义不清 +- `desc` 命名不统一 +- 缺少角色编码字段 + +处理建议： + +- 删除或废弃 `utype` +- `desc` 统一为 `remark` +- 新增 `code` + +### 2. system_auth_node + +定位：角色与权限节点关系表 + +建议字段： + +- `id` +- `auth_id` +- `node_code` +- `plugin_code` +- `create_time` + +当前问题： + +- `auth` 命名不清晰 +- `node` 缺少领域表达 +- 无法直接表达插件归属 + +处理建议： + +- `auth -> auth_id` +- `node -> node_code` +- 增加 `plugin_code` + +### 3. system_user + +定位：系统后台用户表 + +建议字段： + +- `id` +- `username` +- `password` +- `nickname` +- `avatar` +- `identity_code` +- `contact_phone` +- `contact_mail` +- `contact_qq` +- `login_ip` +- `login_time` +- `login_num` +- `remark` +- `sort` +- `status` +- `create_time` +- `update_time` +- `delete_time` + +当前问题： + +- `authorize` 用逗号串保存角色编号，扩展性差 +- `headimg`、`describe` 为历史命名 +- `login_at` 当前是字符串时间 +- 缺少 `update_time` + +处理建议： + +- 删除 `authorize`，改为独立关联表 +- `headimg -> avatar` +- `describe -> remark` +- `login_at -> login_time` +- 增加 `update_time` + +### 4. system_user_auth + +定位：用户与角色关系表 + +这是第二阶段可选增强表，不作为第一批强制落地点。 + +建议字段： + +- `id` +- `user_id` +- `auth_id` +- `create_time` + +价值： + +- 替代 `system_user.authorize` 的逗号串模式 +- 便于多角色扩展、审计、筛选和后续插件授权复用 + +### 5. system_menu + +定位：系统后台菜单表 + +建议字段： + +- `id` +- `parent_id` +- `plugin_code` +- `source_type` +- `source_code` +- `title` +- `icon` +- `route_path` +- `link_url` +- `auth_node` +- `query_params` +- `target` +- `sort` +- `status` +- `create_time` +- `update_time` + +当前问题： + +- `pid` 命名是历史风格 +- `url` 同时承载站内路由和外链 +- `node` 与 `url` 职责交叉 +- `params` 只是字符串 + +处理建议： + +- `pid -> parent_id` +- 拆分 `url` 为 `route_path / link_url` +- `node -> auth_node` +- `params -> query_params` +- 增加 `plugin_code / source_type / source_code` + +### 6. system_base + +定位：系统数据字典表 + +建议字段： + +- `id` +- `type` +- `code` +- `name` +- `text_value` +- `meta_json` +- `sort` +- `status` +- `create_time` +- `update_time` +- `delete_time` +- `deleted_by` + +当前问题： + +- `content` 同时保存纯文本和 JSON 元数据 +- 插件归属通过 `content` 间接表达，不利于约束 + +处理建议： + +- 将内容拆分为文本值和元数据 +- 插件归属等扩展信息只进入 `meta_json` + +### 7. system_data + +定位：系统分组配置表 + +建议字段： + +- `id` +- `name` +- `value` +- `create_time` +- `update_time` + +当前结论： + +- 这张表结构可以暂时保留 +- 重点是确保 `value` 只保存结构化 JSON + +### 8. system_file + +定位：系统文件与存储记录表 + +建议字段： + +- `id` +- `storage_type` +- `file_hash` +- `tags` +- `file_name` +- `extension` +- `file_url` +- `storage_key` +- `mime_type` +- `file_size` +- `system_user_id` +- `biz_user_id` +- `is_fast_upload` +- `is_safe` +- `status` +- `create_time` +- `update_time` + +当前问题： + +- `xext / xurl / xkey` 为历史命名 +- `uuid / unid` 不利于理解 +- 字段语义和业务语义脱节 + +处理建议： + +- 历史字段全部改成业务化命名 +- 文件表作为第二批落地 + +### 9. system_oplog + +定位：操作日志表 + +建议字段： + +- `id` +- `node_code` +- `request_ip` +- `action` +- `content` +- `username` +- `create_time` + +当前问题： + +- `geoip` 实际存的是 IP，不是地理信息 + +处理建议： + +- `geoip -> request_ip` + +## RBAC 重构目标 + +### 1. 节点同步 + +- 扫描控制器注释 +- 生成标准节点树 +- 识别插件归属 +- 写入角色节点授权关系 +- 刷新节点缓存 + +### 2. 菜单同步 + +- 插件声明的菜单作为静态源 +- `system_menu` 作为运行时覆盖层 +- 后台手工新增菜单只作为 `custom` 来源处理 + +### 3. 权限判断顺序 + +- 超级管理员直接放行 +- 判断登录态 +- 判断节点是否需要授权 +- 判断用户关联角色 +- 判断角色是否命中节点 + +## Builder 重构目标 + +### 1. 公共 Builder 资产 + +- `SystemListPage` +- `SystemListTabs` +- `SystemTablePreset` +- 公共的模块化表单片段 + +### 2. 第一批要抽离的交互 + +- 权限树筛选与选择 +- 用户角色分组选择 +- 菜单路由/权限节点自动补全 +- 系统配置中的主题选择和存储驱动选择 + +### 3. 输出要求 + +- 保持 HTML 渲染可用 +- 保持 Builder JSON 渲染可用 +- 避免在模板中继续回退到旧式条件模板和拼接式脚本 + +## 实施顺序 + +### Phase 1: 结构冻结 + +- 输出字段改造清单 +- 输出目标表结构 +- 输出脚本命名规范 +- 确认第一批改造对象为 `Auth / User / Menu` + +### Phase 2: 数据库脚本重写 + +- 直接修改 `System` 主安装脚本 +- 第一批先完成兼容式字段替换 +- 更新测试里的 SQLite 建表定义 +- 使用新库重建验证安装结果 + +### Phase 3: 模型与 Service 适配 + +- 更新 `SystemAuth` +- 更新 `SystemUser` +- 更新 `SystemMenu` +- 新增 `SystemUserAuth` +- 把历史字段兼容逻辑收敛到 Service 层 + +### Phase 4: Builder 与控制器重构 + +- 先改 `Auth` +- 再改 `User` +- 再改 `Menu` +- 完成角色、用户、菜单三条链路联调 + +### Phase 5: 第二批模块落地 + +- 重构 `Base` +- 重构 `Config` +- 重构 `File` + +### Phase 6: 收尾 + +- 清理旧字段兼容逻辑 +- 更新文档和测试 +- 重新发布 `database/migrations` + +## 数据库脚本命名规范 + +### 主安装脚本 + +- 目录：`plugin//stc/database/` +- 模式：`{version}_install_{plugin_code}{date}.php` +- `plugin_code` 统一使用 `snake_case` + +示例： + +- `20241010000001_install_system20241010.php` +- `20241010000009_install_wechat_service20241010.php` + +### 当前阶段规则 + +- `System` 模块允许直接修改主 install 脚本 +- 不新增第二份 install 脚本 +- 根目录迁移文件通过发布流程重建 + +## 验收标准 + +- 新库可直接安装 `System` 模块 +- 注释扫描可以生成 RBAC 节点 +- 用户、角色、菜单权限关系闭环可用 +- `Auth / User / Menu` 页面同时支持 HTML 和 Builder JSON +- 第一批模块测试可通过 +- 第二批模块不会继续引入历史字段命名 + +## 下一步 + +第一轮实施直接从下面三项开始： + +1. 改造 `system_auth / system_auth_node / system_user / system_menu` +2. 更新 `System` 主安装脚本与 SQLite 测试表结构 +3. 重做 `Auth / User / Menu` 的 Model、Service、Builder 和控制器适配 + +## 当前进度 + +截至当前工作区状态，第一批已经采用以下字段重命名方向推进： + +- `system_auth.utype -> code` +- `system_auth.desc -> remark` +- `system_user.usertype -> base_code` +- `system_user.authorize -> auth_ids` +- `system_user.describe -> remark` + +并且 `Auth / User / Menu` 相关测试已经可以通过。 diff --git a/docs/components-detail.md b/docs/components-detail.md new file mode 100644 index 000000000..38a734726 --- /dev/null +++ b/docs/components-detail.md @@ -0,0 +1,1023 @@ +# 组件详细说明文档 + +本文档详细描述 ThinkAdminDeveloper 各组件的功能、架构和使用说明。 + +## 核心组件详细说明 + +### 1. ThinkLibrary - 核心基础库 + +**包名**: `zoujingli/think-library` + +**定位**: 核心基础库，为 ThinkAdmin 提供运行时基础设施 + +**核心功能**: + +1. **运行时服务** + - RuntimeService: 运行时环境配置同步，处理 PHAR 兼容、目录初始化 + - AppService: 应用管理、插件发现、服务注册、配置管理 + - NodeService: 节点管理、权限判断、菜单节点处理 + - QueueService: 队列门面服务（真实实现在 Worker 插件） + +2. **认证会话** + - JwtToken: JWT 令牌生成、验证、刷新 + - CacheSession: 基于 Token SID 的缓存会话管理 + - RequestTokenService: 请求级令牌识别服务 + - SystemContext: 系统上下文接口（运行时实现） + - NullSystemContext: 空实现上下文（未认证状态） + +3. **路由适配** + - Route: 自定义路由对象，支持插件路由注册 + - Url: URL 构建工具，支持插件 URL 生成 + - MultAccess: 多应用访问中间件，处理插件前缀切换 + +4. **基础类型** + - Controller: 标准控制器基类，提供通用控制器方法 + - Model: 标准模型基类，扩展软删除、时间戳等能力 + - Command: 标准命令基类，提供命令通用方法 + - Plugin: 插件管理类，处理插件元数据加载 + - Service: 服务基类，提供基础服务方法 + - Exception: 框架异常类，统一异常处理 + +**JSON 响应约定**: +- `Controller::success()` 默认输出 HTTP `200`，并返回 `code = 200` +- `Controller::error()` 默认输出 HTTP `200`，并通过 `code` 输出业务状态码 +- 标准 JSON 字段为 `code`、`info`、`data`，鉴权异常可以附加稳定 `error` 标识 +- 认证链路统一使用 `401/403`，资源缺失统一使用 `404` + +5. **Helper 工具** + - QueryHelper: 数据查询构建器，支持分页、筛选、排序 + - FormBuilder: 表单构建器，支持表单元素快速生成 + - PageBuilder: 列表页面构建器，支持表格、筛选、操作列 + - ValidateHelper: 数据验证器，支持规则验证、错误提示 + +6. **扩展工具** + - CodeToolkit: 编码工具（加密/解密/Base64/Hash） + - FileTools: 文件操作工具（目录创建、文件复制、权限管理） + - HttpClient: HTTP 客户端（cURL 封装、请求构建） + - ArrayTree: 数组树工具（树形结构构建、扁平化） + - FaviconBuilder: 网站图标生成器 + - ImageSliderVerify: 图片滑块验证码 + - JsonRpcHttpClient: JSON-RPC HTTP 客户端 + - JsonRpcHttpServer: JSON-RPC HTTP 服务端 + +**全局函数**: + +- 应用相关：`syspath()`, `runpath()`, `sysconf()`, `sysvar()`, `isOnline()` +- URL 相关：`sysuri()`, `apiuri()`, `plguri()` +- 认证相关：`auth()`, `admin_user()`, `tsession()` +- 工具函数：`xss_safe()`, `str2arr()`, `arr2str()`, `data_save()`, `normalize()` + +**依赖要求**: +- PHP >= 8.1 +- ThinkPHP >= 8.1 +- 扩展：gd, curl, json, zlib, iconv, openssl, mbstring, fileinfo +- 推荐：redis (用于 CacheSession 和缓存驱动) + +**许可证**: MIT License + +--- + +### 2. ThinkPlugsSystem - 系统后台组件 + +**包名**: `zoujingli/think-plugs-system` + +**定位**: 系统后台插件，提供后台壳层、认证权限、菜单用户和系统运维能力 + +**核心功能**: + +1. **后台壳层** + - 登录页面、首页框架、后台布局 + - 面包屑导航、页面模板 + +2. **认证授权** + - JWT 令牌认证中间件 + - RBAC 权限控制 + - 菜单权限判断 + - 节点权限验证 + +3. **系统用户** + - 用户管理（增删改查） + - 角色管理 + - 权限分配 + - 密码修改 + +4. **系统配置** + - 参数配置（分组管理） + - 配置缓存 + - 配置导入导出 + - 字典管理 + +5. **操作日志** + - 操作记录自动记录 + - 日志查询筛选 + - 日志导出 + - 日志清理 + +6. **任务管理** + - 系统任务查看 + - 任务状态管理 + - 任务日志查看 + +7. **开发交付工具** + - 资源发布、迁移发布与安装协同 + - 插件迁移脚本导出和安装包生成 + - 菜单元数据校验、模型注释生成 + - 使用 `plugin\system\helper\*` 命名空间，源码归入 System + +**数据表**: +- `system_auth` - 系统权限角色 +- `system_auth_node` - 权限节点绑定 +- `system_menu` - 系统菜单管理 +- `system_user` - 系统用户管理 +- `system_base` - 系统基础配置（数据字典） +- `system_data` - 系统扩展数据 +- `system_oplog` - 系统操作日志 +- `system_file` - 系统文件管理表 + +**目录结构**: +``` +think-plugs-system/ +├── src/ +│ ├── controller/ # 控制器层 +│ │ ├── Auth.php # 权限管理 +│ │ ├── Base.php # 基础数据 +│ │ ├── Config.php # 系统配置 +│ │ ├── Menu.php # 菜单管理 +│ │ ├── Oplog.php # 操作日志 +│ │ ├── User.php # 用户管理 +│ │ └── ... +│ ├── middleware/ # 中间件层 +│ │ ├── JwtTokenAuth.php +│ │ └── RbacAccess.php +│ ├── helper/ # 开发交付工具（plugin\system\helper\*） +│ │ ├── command/ # 发布、打包、迁移、模型等命令 +│ │ ├── migration/ # PhinxExtend 与迁移导出 +│ │ └── plugin/ # 插件菜单与注册表工具 +│ ├── model/ # 模型层 +│ │ ├── SystemAuth.php +│ │ ├── SystemMenu.php +│ │ ├── SystemUser.php +│ │ └── ... +│ ├── service/ # 服务层 +│ │ ├── SystemAuthService.php +│ │ ├── SystemContext.php +│ │ └── UserService.php +│ ├── storage/ # 存储驱动与上传授权 +│ └── view/ # 视图层 +├── stc/database/ # 迁移脚本 +└── tests/ # 单元测试 +``` + +**依赖**: +- PHP >= 8.1 +- ThinkLibrary +- ThinkPlugsStatic +- ThinkPlugsWorker +- Doctrine/DBAL +- ThinkPHP Migration +- ThinkPHP IDE Helper + +**许可证**: MIT License + +--- + +### 存储中心功能 (已合并到 System) + +Storage 组件已合并到 ThinkPlugsSystem，作为其核心功能之一。 + +**存储驱动管理**: +- LocalStorage: 本地存储驱动 +- AliossStorage: 阿里云 OSS 存储驱动 +- TxcosStorage: 腾讯云 COS 存储驱动 +- QiniuStorage: 七牛云 Kodo 存储驱动 +- UpyunStorage: 又牛云存储驱动 +- AlistStorage: Alist 网络存储驱动 + +**核心文件**: +- `plugin/system/src/storage/StorageManager.php` - 存储管理器 +- `plugin/system/src/storage/StorageAuthorize.php` - 上传授权管理 +- `plugin/system/src/storage/StorageConfig.php` - 存储配置管理 +- `plugin/system/src/controller/File.php` - 文件管理控制器 +- `plugin/system/src/controller/api/Upload.php` - 上传 API 控制器 +- `plugin/system/src/model/SystemFile.php` - 文件数据模型 + +**数据表**: +- `system_file` - 系统文件管理表 + +**功能说明**: +- 统一的 Storage 门面接口 +- 多存储驱动支持和管理 +- 上传授权和临时令牌生成 +- 文件元数据管理 +- 文件上传、删除、清理 +- 文件类型统计和管理 + +**使用示例**: +```php +use plugin\system\storage\StorageManager; + +// 获取存储管理器 +$storage = StorageManager::instance(); + +// 上传文件 +$result = $storage->upload($file, 'local'); + +// 获取上传授权 +$auth = StorageAuthorize::mk()->buildToken([ + 'type' => 'image', + 'xkey' => 'upload_key', + 'xname' => 'filename.jpg' +]); +``` + +--- + +### 3. ThinkPlugsWorker - Workerman 运行时组件 + +**包名**: `zoujingli/think-plugs-worker` + +**定位**: Workerman 运行时插件，提供 HTTP 和队列常驻服务，支持跨平台进程管理 + +**核心功能**: + +1. **HTTP 服务** + - 基于 Workerman 的高性能 HTTP 服务器 + - 支持多进程并发（默认 4 进程） + - 支持文件监控和自动重载（开发环境） + - 内存监控和自动保护 + +2. **队列服务** + - 长耗时任务调度 + - 延时任务处理 + - 任务锁机制 + - 失败重试 + - 历史记录保留 + +3. **进程管理** + - **Linux/macOS**: Workerman 守护进程，信号控制（reload/stop），pidFile 辅助管理 + - **Windows**: console.exe 启动后台 PHP 进程，进程扫描 + 健康检查，不依赖 pidFile + - 命令签名统一：`xadmin:worker serve ` + +4. **状态监控** + - 进程状态查看 + - 内存使用监控 + - 文件变更监控 + - 健康检查 + +**命令入口**: +```bash +# 启动 HTTP 服务 +php think xadmin:worker start http -d + +# 启动队列服务 +php think xadmin:worker start queue -d + +# 查看运行状态 +php think xadmin:worker status all + +# 停止服务 +php think xadmin:worker stop http + +# 重启所有服务 +php think xadmin:worker restart all +``` + +**数据表**: +- `system_queue` - 系统队列任务 + +**配置示例** (`config/worker.php`): +```php +return [ + 'services' => [ + 'http' => [ + 'enabled' => true, + 'label' => 'ThinkAdmin HTTP', + 'driver' => 'http', + 'server' => [ + 'host' => '127.0.0.1', + 'port' => 2346, + ], + 'process' => [ + 'name' => 'ThinkAdminHttp', + 'count' => 4, + ], + ], + 'queue' => [ + 'enabled' => true, + 'label' => 'ThinkAdmin Queue', + 'driver' => 'queue', + 'process' => [ + 'name' => 'ThinkAdminQueue', + 'count' => 2, + ], + 'queue' => [ + 'scan_interval' => 1, // 扫描间隔（秒） + 'batch_limit' => 20, // 每批最多任务数 + 'lock_timeout' => 3600, // 任务锁超时（秒） + 'retain_days' => 7, // 历史记录保留天数 + ], + ], + ], +]; +``` + +**依赖**: +- PHP >= 8.1 +- Workerman >= 5.1.9 +- Symfony/Process >= 6.0 +- ThinkLibrary + +**许可证**: Apache-2.0 License + +--- + +### 4. System 内置开发交付工具 + +**归属包名**: `zoujingli/think-plugs-system` + +**命名空间**: `plugin\system\helper\` + +**代码位置**: `plugin/think-plugs-system/src/helper/` + +**定位**: 原 ThinkPlugsHelper 已合并到 System，作为开发期和交付期使用的内置工具能力，负责迁移导出、安装包生成、发布命令、菜单校验和模型辅助工具。 + +**主要职责**: +- 提供 `xadmin:publish`、`xadmin:package`、`xadmin:helper:*` 等命令 +- 负责插件迁移主脚本识别与导出 +- 负责菜单元数据校验与菜单迁移写入 +- 提供模型注释生成和少量开发辅助工具 + +**常用命令**: +```bash +# 发布配置、静态资源和迁移脚本 +php think xadmin:publish + +# 发布并执行数据库迁移 +php think xadmin:publish --migrate + +# 生成安装包 +php think xadmin:package + +# 生成模型注释 +php think xadmin:helper:model + +# 生成迁移脚本 +php think xadmin:helper:migrate +``` + +**元数据来源**: +- 插件服务：`composer.json > extra.think.services` +- 插件元数据：`composer.json > extra.xadmin.app` +- 菜单元数据：`composer.json > extra.xadmin.menu` +- 迁移元数据：`composer.json > extra.xadmin.migrate` + +**组件边界**: +- 不负责运行时路由、认证和后台页面 +- 不负责常驻进程、队列和存储驱动 +- 依赖 ThinkLibrary 提供基础运行时与元数据读取能力 + +**依赖**: +- PHP >= 8.1 +- ThinkLibrary +- ThinkPlugsWorker +- Doctrine/DBAL +- ThinkPHP Migration +- ThinkPHP IDE Helper + +**许可证**: 随 System 组件发布，工具源码沿原 Apache-2.0 约定 + +--- + +## 平台插件详细说明 + +### 5. System 内置存储中心 + +**包名**: `zoujingli/think-plugs-system` + +**定位**: System 内置存储中心，统一管理存储驱动、上传授权和配置元数据 + +**核心功能**: +- 存储驱动管理（本地存储、OSS、COS 等） +- 上传授权和临时令牌 +- 文件配置元数据管理 +- Storage 门面实现 + +**数据表**: +- `system_file` - 系统文件管理 + +**支持驱动**: +- 本地存储 +- 阿里云 OSS +- 腾讯云 COS +- 七牛云 Kodo +- 其他兼容 Flysystem 的驱动 + +**依赖**: +- PHP >= 8.1 +- ThinkLibrary +- ThinkPlugsSystem + +--- + +### 6. ThinkPlugsWechatClient - 微信公众号标准平台 + +**包名**: `zoujingli/think-plugs-wechat-client` + +**定位**: 公众号标准平台组件，负责公众号配置、粉丝同步、素材图文、菜单、回复规则和微信支付后台能力 + +**核心功能**: +- 公众号参数配置 +- 微信支付参数配置 +- 粉丝同步与标签管理 +- 素材与图文管理 +- 自定义菜单管理 +- 关键词回复与关注自动回复 +- 微信支付行为管理 +- 微信退款管理 + +**后台节点**: +- `wechat-client/config/options` - 公众号配置 +- `wechat-client/config/payment` - 支付配置 +- `wechat-client/fans/index` - 粉丝管理 +- `wechat-client/news/index` - 素材管理 +- `wechat-client/menu/index` - 菜单管理 +- `wechat-client/keys/index` - 关键词回复 +- `wechat-client/payment.record/index` - 支付记录 + +**接口节点**: +- `/api/wechat-client/push/*` - 微信推送 +- `/api/wechat-client/view/*` - 预览页 +- `/api/wechat-client/js/*` - JS SDK +- `/api/wechat-client/login/*` - 网页授权 + +**数据表**: +- `wechat_auto` - 自动回复 +- `wechat_fans` - 粉丝资料 +- `wechat_fans_tags` - 粉丝标签 +- `wechat_keys` - 关键字规则 +- `wechat_media` - 素材库 +- `wechat_news` - 图文主表 +- `wechat_news_article` - 图文文章 +- `wechat_payment_record` - 支付记录 +- `wechat_payment_refund` - 退款记录 + +**命令**: +```bash +# 同步所有粉丝 +php think xadmin:fansall + +# 粉丝消息推送 +php think xadmin:fansmsg + +# 粉丝支付清理 +php think xadmin:fanspay +``` + +**依赖**: +- PHP >= 8.1 +- ThinkLibrary +- ThinkPlugsWorker (推荐) + +**许可证**: MIT License + +--- + +### 7. ThinkPlugsWechatService - 微信公众号开放平台 + +**包名**: `zoujingli/think-plugs-wechat-service` + +**定位**: 公众号开放平台组件，负责第三方平台配置、公众号授权管理和远程 JSON-RPC 服务 + +**核心功能**: +- 微信开放平台参数配置 +- 授权公众号管理 +- 远程 JSON-RPC 服务 +- 推送事件接收 +- 标准平台远程能力代理 + +**后台节点**: +- `wechat-service/config/index` - 开放平台配置 +- `wechat-service/wechat/index` - 授权账号管理 + +**接口节点**: +- `/api/wechat-service/client/jsonrpc` - JSON-RPC 远程调用 +- `/api/wechat-service/push/*` - 推送事件接收 + +**JSON-RPC 地址示例**: +``` +http://example.com/api/wechat-service/client/jsonrpc?token=TOKEN +``` + +**数据表**: +- `wechat_auth` - 微信授权 + +**命令**: +```bash +# 同步微信数据 +php think xsync:wechat +``` + +**依赖**: +- PHP >= 8.1 +- ThinkLibrary + +**许可证**: 专有授权（未授权不可商用） + +--- + +## 业务插件详细说明 + +### 8. ThinkPlugsAccount - 多端账号体系 + +**包名**: `zoujingli/think-plugs-account` + +**定位**: 统一账号组件，负责多端账号模型、登录通道注册、账号绑定关系、接口认证令牌和账号资料管理 + +**核心功能**: +- 多端账号统一管理 +- 微信服务号登录 +- 微信小程序登录 +- 手机短信验证登录 +- 主账号与终端账号绑定解绑 +- 动态注册登录通道 +- 终端资料与主账号资料同步 +- Token 化接口认证 + +**后台节点**: +- `account/master/index` - 主账号管理 +- `account/device/index` - 终端账号管理 +- `account/message/index` - 消息记录管理 + +**接口入口**: +- `/api/account/login/*` - 登录接口 +- `/api/account/auth/*` - 认证接口 +- `/api/account/auth/center/*` - 账号中心 +- `/api/account/wechat/*` - 微信登录 +- `/api/account/wxapp/*` - 小程序登录 + +**数据表**: +- `plugin_account_auth` - 授权配置 +- `plugin_account_bind` - 终端账号 +- `plugin_account_msms` - 短信记录 +- `plugin_account_user` - 主账号资料 + +**使用示例**: +```php +use plugin\account\service\Account; + +$account = Account::mk(Account::WXAPP, TOKEN: ''); +$user = $account->set(['openid' => 'OPENID', 'phone' => '13888888888']); + +$account->set(['extra' => ['desc' => '用户描述', 'sex' => '男']]); +$profile = $account->get(true); + +$bound = $account->bind(['phone' => '13999999999'], ['username' => '会员用户']); +$allBind = $account->allBind(); +``` + +**依赖**: +- PHP >= 8.1 +- ThinkLibrary + +**许可证**: 专有授权（VIP 授权） + +--- + +### 9. ThinkPlugsPayment - 支付中心 + +**包名**: `zoujingli/think-plugs-payment` + +**定位**: 支付中心组件，负责支付配置、支付行为、退款处理、余额积分账本和支付事件分发 + +**核心功能**: +- 支付配置管理 +- 混合支付能力 +- 余额支付与流水 +- 积分支付与流水 +- 线下凭证支付审核 +- 支付行为追踪 +- 退款记录管理 +- 高精度金额计算 + +**后台节点**: +- `payment/config/index` - 支付配置 +- `payment/record/index` - 支付记录 +- `payment/refund/index` - 退款记录 +- `payment/balance/index` - 余额账本 +- `payment/integral/index` - 积分账本 + +**接口节点**: +- `/api/payment/auth/address/*` - 收货地址 +- `/api/payment/auth/balance/*` - 余额支付 +- `/api/payment/auth/integral/*` - 积分支付 + +**支付通知路由**: +``` +/plugin-payment-notify/:vars +``` + +**支付事件**: +- `PluginAccountBind` - 账号绑定 +- `PluginPaymentAudit` - 支付审核 +- `PluginPaymentRefuse` - 支付拒绝 +- `PluginPaymentSuccess` - 支付成功 +- `PluginPaymentCancel` - 支付取消 +- `PluginPaymentConfirm` - 订单确认 + +**数据表**: +- `plugin_payment_address` - 收货地址 +- `plugin_payment_balance` - 余额账本 +- `plugin_payment_config` - 支付配置 +- `plugin_payment_integral` - 积分账本 +- `plugin_payment_record` - 支付记录 +- `plugin_payment_refund` - 退款记录 + +**依赖**: +- PHP >= 8.1 +- ThinkLibrary +- ThinkPlugsAccount + +**许可证**: 专有授权（未授权不可商用） + +--- + +### 10. ThinkPlugsWemall - 分销商城系统 + +**包名**: `zoujingli/think-plugs-wemall` + +**定位**: 分销商城组件，负责商品、订单、售后、会员、分销、海报、报表和商城 API + +**核心功能**: +- 商城参数和页面装修 +- 商品、分类、规格、库存管理 +- 订单、发货、退款、评论管理 +- 会员等级、折扣、创建、充值 +- 分销关系、返佣、提现 +- 海报、通知、报表 +- 帮助中心与意见反馈 +- 面向客户端的商城 API +- 商城开放平台快递查询适配 + +**后台节点**: +- `wemall/base.*/*` - 商城配置 +- `wemall/user.*/*` - 用户管理 +- `wemall/shop.*/*` - 商城管理 +- `wemall/help.*/*` - 帮助中心 + +**接口节点**: +- `/api/wemall/goods/*` - 商品接口 +- `/api/wemall/data/*` - 数据接口 +- `/api/wemall/auth/*` - 认证接口 +- `/api/wemall/help/*` - 帮助接口 + +**命令**: +```bash +# 清理商城数据 +php think xdata:mall:clear + +# 商城数据转换 +php think xdata:mall:trans + +# 商城用户导入 +php think xdata:mall:users +``` + +**事件联动**: +- `PluginAccountBind` - 账号绑定 +- `PluginPaymentAudit/Refuse/Success/Cancel/Confirm` - 支付事件 +- `PluginWemallOrderConfirm` - 订单确认 + +**数据表** (主要): +- 商城配置：`plugin_wemall_config_*` +- 快递与模板：`plugin_wemall_express_*` +- 商品：`plugin_wemall_goods*` +- 订单：`plugin_wemall_order*` +- 帮助中心：`plugin_wemall_help_*` +- 用户行为：`plugin_wemall_user_action_*` +- 会员与返佣：`plugin_wemall_user_*` + +**依赖**: +- PHP >= 8.1 +- ThinkLibrary +- ThinkPlugsAccount +- ThinkPlugsPayment + +**许可证**: 专有授权（未授权不可商用） + +--- + +### 11. ThinkPlugsWuma - 防伪溯源系统 + +**包名**: `zoujingli/think-plugs-wuma` + +**定位**: 防伪溯源组件，负责一物一码、溯源模板、赋码批次、仓储流转、代理库存和扫码验证 + +**核心功能**: +- 一物一码规则管理 +- 防伪验证与溯源展示 +- 生产与赋码批次管理 +- 区块链证书与内容管理 +- 仓库、入库、出库、库存调度 +- 代理库存与调货管理 +- 消费者扫码查询与通知分析 + +**后台节点**: +- `wuma/code/index` - 物码管理 +- `wuma/source.*/*` - 溯源管理 +- `wuma/warehouse*/*` - 仓储管理 +- `wuma/sales.*/*` - 代理销售 +- `wuma/scaner.*/*` - 扫码监控 + +**接口节点**: +- `/api/wuma/base/*` - 基础接口 +- `/api/wuma/coder/*` - 编码接口 +- `/api/wuma/auth/*` - 认证接口 +- `/api/wuma/login/*` - 登录接口 + +**接口请求头规范**: +```http +Authorization: Bearer +X-Device-Code: +X-Device-Type: +``` + +**命令**: +```bash +# 创建物码 +php think xdata:wuma:create +``` + +**数据表** (主要): +- 物码规则：`plugin_wuma_code_rule*` +- 溯源模块：`plugin_wuma_source_*` +- 仓储模块：`plugin_wuma_warehouse*` +- 代理销售：`plugin_wuma_sales_*` + +**依赖**: +- PHP >= 8.1 +- ThinkLibrary +- ThinkPlugsWemall (可联动) + +**许可证**: 专有授权（未授权不可商用） + +--- + +## 交付组件详细说明 + +### 12. ThinkPlugsBuilder - 打包插件 + +**包名**: `zoujingli/think-plugs-builder` + +**定位**: 标准打包插件，用于将当前项目构建为可直接运行的 `admin.phar` + +**核心功能**: +- 使用临时目录中转打包，减少直接扫描项目目录带来的耗时 +- 构建时自动整合项目代码、Composer 依赖和运行入口 +- 首次启动时自动创建 `public`、`runtime` 等运行目录 +- 支持只保留 `.env + admin.phar` 的最小部署形态 +- 支持通过 `php admin.phar xadmin:worker ...` 直接运行 Worker + +**命令**: +```bash +# 使用推荐脚本构建 +composer build:phar + +# 或直接执行命令 +php -d phar.readonly=0 think xadmin:builder --name=admin.phar +``` + +**参数说明**: +- `--name`: 输出的 PHAR 文件名（默认 `admin.phar`） +- `--main`: 包内主入口文件（默认 `think`） +- `--extract`: 首次启动时解压到外部目录的路径 +- `--mount`: 运行时挂载到 PHAR 外部的文件或目录 +- `--exclude`: 额外排除的文件或目录 + +**部署方式**: +最小部署产物只需要两个文件： +``` +release/ +├─ .env +└─ admin.phar +``` + +**运行时自动行为**: +PHAR 首次启动时会自动： +- 如果根目录没有 `.env`，优先用 `.env.example` 自动生成 +- 自动创建 `public` 目录 +- 自动创建 `runtime` 目录 +- 自动同步 `.env` 到 `runtime/.env` +- 如果 `public`、`database` 不存在，则从 PHAR 内解压到外部目录 +- 将 `.env`、`runtime`、`safefile`、`public`、`database` 挂载到 PHAR 外部 + +**路径约定** (PHAR 兼容关键点): +- `syspath()`: 用于读取 **PHAR 包内**资源（只读） +- `runpath()`: 用于读写 **PHAR 外部**文件系统（可写） +- 字体、SQLite、缓存等落盘路径必须使用 `runpath()` +- GD 的 `imagettftext()` 不支持 `phar://` 路径 + +**依赖**: +- PHP >= 8.1 +- Phar 扩展启用 + +--- + +### 13. ThinkPlugsStatic - 静态资源与项目骨架 + +**包名**: `zoujingli/think-plugs-static` + +**定位**: 静态资源和项目骨架组件，负责发布后台前端资源、默认入口文件、基础配置模板和项目初始化骨架 + +**核心功能**: +- 发布 `public/static` 前端资源 +- 发布 `public/index.php`、`public/router.php` 等入口文件 +- 发布基础配置模板与本地多应用骨架（默认 `index` 应用） +- 后台前端统一使用 `LayUI + $.module.use(...)` +- 不再使用 `RequireJS` + +**发布内容**: +主要发布内容包括： +- `.env.example` +- 配置文件：`config/*.php` +- 应用骨架：`app/index/controller/Index.php` +- 路由：`route/.gitkeep` +- 入口文件：`public/index.php`, `public/router.php` +- 静态资源：`public/static/plugs`, `public/static/theme` +- 系统脚本：`public/static/system.js`, `public/static/login.js` +- 自定义扩展：`public/static/extra/style.css`, `public/static/extra/script.js` + +补充说明： +- 发布内容统一来自 `composer.json > extra.xadmin.publish.copy` +- `public/static/theme` 只发布运行时资源，默认排除 `*.less`、`*.css.map`、`package.json` + +**发布命令**: +```bash +# 显式执行完整安装链路 +php think xadmin:install + +# 初始化缺失文件 +php think xadmin:publish + +# 覆盖更新静态资源和骨架 +php think xadmin:publish --force +``` + +**前端约定**: +- 后台只保留 `LayUI` 模块加载机制 +- 统一入口脚本为 `public/static/system.js` 和 `public/static/login.js` +- 自定义脚本建议放到 `public/static/extra` + +**说明**: +- `zoujingli/think-plugs-install` 作为 Composer plugin，会在 `composer install / update / remove / dump-autoload` 后自动执行 `service:discover` 与 `xadmin:publish` +- 首次 Composer 安装只发布资源和迁移脚本，不直接建表 +- 只有声明了 `composer.json > extra.xadmin.migrate` 的插件，才会在后续自动安装链路里执行数据库迁移 +- 后台认证已改为 Token/JWT，不再依赖 Session 保存登录态 +- 用户临时态统一使用基于 Token SID 的 `CacheSession` +- 语言切换默认仅支持 URL 参数与请求头，不再写语言 Cookie + +**依赖**: +- PHP >= 8.1 +- ThinkLibrary + +**许可证**: MIT License + +--- + +## 架构约定 + +### 认证与会话 + +详细规范请参考：[认证与会话规范](./docs/architecture/auth-token-session.md) + +**核心原则**: +- 登录态必须由显式 Token 表达 +- 临时用户态必须绑定到 Token 对应的 `sid` +- 业务请求统一使用 `Authorization` +- 后台壳页首跳只允许一次性 `access_key` 引导 + +**认证协议分层**: +- `system-auth`: 后台人员（JWT） +- `account-auth`: 所有业务用户（JWT） +- `device token`: 封闭设备（wuma 独立实现） +- `capability token`: 短期能力授权（上传等） + +**统一请求头**: +```http +Authorization: Bearer +X-Device-Code: +X-Device-Type: +``` + +**认证异常响应**: +- `401 Unauthorized`：未提供有效凭据、登录已过期、会话失效或令牌无效 +- `403 Forbidden`：已完成认证，但账号被禁用或无权访问当前资源 +- HTTP JSON 接口统一回传 `code`、`info`、`data`，HTTP 状态码固定为 `200` + +**禁止项**: +- 不再使用 `think\Session` +- 不再使用 `think\facade\Session` +- 不再使用 `SessionInit` +- 不再使用 `PHPSESSID` +- 不再使用标准 Session 环境变量作为系统登录态配置 + +### 路由与应用 + +- `app/*` 支持本地多应用，`app/index` 为默认本地应用 +- 本地应用入口：`/{app}/{controller}/{action}`（默认应用可省略首段） +- 插件通过 URL 前缀注册访问入口 +- 请求首段命中插件前缀时切换到插件 +- 未命中插件前缀时回退到本地应用 +- 动态插件切换默认关闭 +- 页面入口统一使用 `/{plugin}/...` +- 接口入口统一使用 `/api/{plugin}/{controller}/{action}` +- 页面链接统一使用 `sysuri()`，接口链接统一使用 `apiuri()` +- 旧 `/{plugin}/api.xxx/...` 只保留兼容，不再作为新代码标准 + +### PHAR 路径约定 + +当使用 `ThinkPlugsBuilder` 构建并以 `admin.phar` 方式运行时： + +- `syspath()`: 读取 **PHAR 包内**只读资源（如 `public/static`、内置模板/数据） +- `runpath()`: 读写 **PHAR 外部**可写目录（如 `runtime/`、`safefile/`、`database/`、`public/upload/`、Worker 的 pid/log/status/stdout 文件） + +更多构建与运行说明请参考：[ThinkPlugsBuilder 文档](./plugin/think-plugs-builder/readme.md) + +--- + +## 开发工具 + +### PHPStan 静态代码分析 + +项目已集成 PHPStan 2.0，用于代码质量检查和静态分析。 + +```bash +# 运行代码分析 +composer analyse + +# 分析结果无错误时输出：[OK] No errors +``` + +配置说明： +- 配置文件：`phpstan.neon` +- 检查级别：`level 3`（已开启更多真实异常检查） +- 检查范围：`app/`, `config/`, `plugin/` +- 通过 `scanFiles` 显式加载 ThinkPHP 与项目公共函数 +- 排除目录：`runtime/`, `vendor/` + +### 代码风格 + +使用 PHP-CS-Fixer 统一代码风格： + +```bash +# 自动修复代码风格 +composer sync +``` + +### 测试 + +运行所有测试： + +```bash +# 运行所有测试 +composer test + +# 仅运行冒烟测试 +composer test:smoke + +# 仅运行单元测试 +composer test:unit +``` + +--- + +## 相关文档 + +- 官网文档：[thinkadmin.top](https://thinkadmin.top) +- 接口文档：[ThinkAdminMobile](https://thinkadmin.apifox.cn) +- 架构文档： + - [插件边界](./docs/architecture/plugin-boundaries.md) + - [插件优先重构](./docs/architecture/plugin-first-refactor.md) + - [认证与会话](./docs/architecture/auth-token-session.md) + - [稳定性评估](./docs/architecture/stability-status.md) + - [插件标准](./docs/architecture/plugin-standard.md) + - [路由分发标准](./docs/architecture/route-dispatch-standard.md) + - [软删除标准](./docs/architecture/soft-delete-standard.md) + +--- + +## 注意事项 + +- 本仓库包含会员插件，未授权不得商用 +- 插件卸载通常不会自动删除已执行迁移和历史数据 +- 自定义前端脚本建议放在 `public/static/extra` +- PHAR 构建仅在调试模式下可用，生产模式不会暴露构建命令 +- 打包前必须先执行 `composer install`，否则缺少 `vendor` 目录无法构建 + +--- + +## 许可证 + +除会员授权插件（Account/Payment/Wemall/Wuma）外，其余组件按各自许可证发布： +- MIT: ThinkLibrary, System, WechatClient, Storage, Static +- Apache-2.0: Worker, Builder, System 内置 Helper 工具 +- 专有授权：Account, Payment, Wemall, Wuma, WechatService diff --git a/readme.md b/readme.md index 708bd8e95..0c959e2f6 100644 --- a/readme.md +++ b/readme.md @@ -1,800 +1,428 @@ -# ThinkAdmin +# ThinkAdminDeveloper for ThinkAdmin -[![Latest Stable Version](https://poser.pugx.org/zoujingli/thinkadmin/v/stable)](https://packagist.org/packages/zoujingli/thinkadmin) -[![Total Downloads](https://poser.pugx.org/zoujingli/thinkadmin/downloads)](https://packagist.org/packages/zoujingli/thinkadmin) -[![Monthly Downloads](https://poser.pugx.org/zoujingli/thinkadmin/d/monthly)](https://poser.pugx.org/zoujingli/thinkadmin) -[![Daily Downloads](https://poser.pugx.org/zoujingli/thinkadmin/d/daily)](https://poser.pugx.org/zoujingli/thinkadmin) -[![License](https://poser.pugx.org/zoujingli/thinkadmin/license)](https://packagist.org/packages/zoujingli/thinkadmin) -[![PHP Version](https://img.shields.io/badge/php-%3E%3D7.1-blue.svg)](https://www.php.net/) -[![ThinkPHP](https://img.shields.io/badge/ThinkPHP-6%20%7C%208-brightgreen.svg)](https://www.thinkphp.cn/) +**ThinkAdminDeveloper** 是基于 ThinkAdmin 8 / ThinkPHP 8.1 的组件化开发仓库，用于维护核心基础库、运行时组件、后台平台插件和业务插件。 -基于 **ThinkPHP 6 & 8** 的现代化后台管理系统，采用 **Composer 插件定制**，提供完整的后台管理解决方案。系统遵循 **MIT** 开源协议，专为快速开发而设计，深度定制 Composer 插件，实现专属插件生态管理架构，可将应用模块封装成独立插件包。 +## 版本基线 -## 项目简介 +- ThinkAdmin `8.x` +- ThinkPHP `8.1+` +- PHP `8.1+` -**ThinkAdmin** 是一个功能强大的后台管理系统，基于最新的 **ThinkPHP 6 & 8** 框架开发，专为简化后台管理流程而设计。系统采用现代化的技术栈，提供丰富的功能模块和插件生态，帮助开发者快速构建企业级后台管理系统。 +## 详细描述 -### 核心优势 +- 这个仓库不是单一应用，而是围绕 ThinkAdmin 8 / ThinkPHP 8.1 组织的一组标准组件，覆盖核心库、运行时、后台平台、业务插件和本地多应用。 +- 目标不是维护旧版多应用项目，而是把系统重构成"插件优先、本地应用兼容、服务注册标准化、组件边界清晰"的结构。 +- 当前所有核心能力都已经按组件拆分：`ThinkLibrary` 提供核心层，`System` 提供系统后台、`system_*` 核心能力、存储中心和开发交付工具，`Worker` 提供常驻运行时，业务插件只承载各自业务域。 +- 因此这个仓库更适合作为组件化开发基线和业务插件宿主，同时支持本地多应用扩展，而不是传统的单仓单应用模板。 -- **🚀 快速开发** - 基于 ThinkPHP 6 & 8 框架，提供完整的后台管理功能，开箱即用 -- **🔌 插件生态** - 支持 Composer 插件管理，可扩展性强，支持热插拔 -- **⚡ 稳定可靠** - 经过多个项目实践验证，系统稳定，性能优异 -- **🛡️ 安全完善** - 内置 RBAC 权限管理、操作日志、数据加密等安全机制 -- **📚 文档齐全** - 提供完整的开发文档和使用指南，学习成本低 -- **🚀 现代化架构** - 支持多应用模式、异步任务、文件存储等现代特性 +## 架构说明 -### 适用场景 +- **本地应用层**：`app/*` 提供本地多应用能力，`app/index` 为默认本地应用，支持按需扩展其他本地应用 +- **核心层**：`ThinkLibrary` 提供运行时、认证、任务契约、菜单节点、模型查询和基础工具。 +- **运行层**：`ThinkPlugsWorker` 用 Workerman 托管 `http` 和 `queue` 两类常驻服务。 +- **系统层**：`ThinkPlugsSystem` 提供后台壳层、认证权限、系统用户、`system_*` 共享配置、字典、扩展数据、操作日志、存储中心和开发交付命令。 +- **业务层**：`ThinkPlugsAccount`、`ThinkPlugsPayment`、`ThinkPlugsWemall`、`ThinkPlugsWuma` 负责各自业务域。 +- **交付层**：System 内置 `plugin\system\helper\*` 负责发布、迁移和安装包，`ThinkPlugsStatic` 负责静态资源和项目骨架。 -- **快速原型开发** - MVP 产品、概念验证、演示系统 -- **企业管理系统** - CRM、ERP、OA、财务系统 -- **SaaS 平台** - 多租户应用、订阅服务、API 管理 -- **学习研究** - 技术学习、框架研究、最佳实践 +```mermaid +flowchart TD + L["ThinkLibrary"] --> S["System"] + L --> W["Worker"] + S --> W + S --> SF["System Storage
system_file / upload"] + S --> HT["System Helper
publish / migrate / package"] + S --> AC["Account"] + S --> P["Payment"] + S --> WC["WechatClient"] + S --> WS["WechatService"] + S --> WM["Wemall"] + S --> U["Wuma"] + AC --> P + AC --> WM + P --> WM + WM --> U +``` -## 在线演示 +## 仓库组成 -- **演示地址**: [https://v6.thinkadmin.top](https://v6.thinkadmin.top) -- **默认账号**: admin -- **默认密码**: admin +详细组件说明请参考：[组件详细文档](./docs/components-detail.md) -## 特性 +### 核心组件 -- 🚀 **快速开发** - 基于 ThinkPHP 6 & 8，开箱即用 -- 🔌 **插件生态** - 支持 Composer 插件管理，热插拔 -- 💾 **文件存储** - 支持多种存储方案，文件秒传 -- 🔐 **权限管理** - 基于注解的 RBAC 权限控制 -- ⚡ **异步任务** - 多进程异步任务处理 -- 🛠️ **开发工具** - 丰富的开发工具和内置函数 -- 📱 **响应式** - 基于 LayUI 2.x，支持多设备 -- 🌐 **多语言** - 支持多语言包管理 -- 🔧 **易扩展** - 支持自定义插件开发 +- **ThinkLibrary** (`zoujingli/think-library`) + 核心基础库，提供运行时、JWT 令牌、任务协议、标准控制器、模型扩展和公共工具。 + - 命名空间：`think\admin\` + - 服务注册：`think\admin\Library` + - 主要功能：插件发现、路由适配、认证会话、队列契约、Storage 门面 + - 核心工具：QueryHelper、FormBuilder、PageBuilder、JwtToken、CacheSession + - 扩展能力：图片滑块验证码、JSON-RPC 客户端/服务端、网站图标生成 + - 全局函数：syspath()、runpath()、sysuri()、apiuri()、tsession() 等 + - 许可证：MIT -## 环境要求 +- **ThinkPlugsSystem** (`zoujingli/think-plugs-system`) + 系统后台组件，提供后台壳层、认证权限、菜单用户、存储中心和开发交付工具。 + - 命名空间：`plugin\system\` + - 服务注册：`plugin\system\Service`，内置开发工具服务 `plugin\system\helper\Service` + - 数据表：`system_auth`, `system_auth_node`, `system_menu`, `system_user`, `system_data`, `system_base`, `system_oplog`, `system_file` + - 默认菜单：系统配置、系统数据、权限管理 + - 核心功能：JWT 认证、RBAC 权限、系统配置、操作日志、任务管理、文件存储、资源发布、迁移导出、菜单校验 + - 开发工具命名空间：统一使用 `plugin\system\helper\*`，源码由 System 包托管 + - 主要命令：`xadmin:publish`, `xadmin:package`, `xadmin:helper:*` + - 中间件：JwtTokenAuth、RbacAccess + - 许可证：MIT -### 基础要求 +- **ThinkPlugsWorker** (`zoujingli/think-plugs-worker`) + Workerman 运行时组件，负责 `http` 和 `queue` 常驻服务，提供跨平台进程管理能力。 + - 命名空间：`plugin\worker\` + - 服务注册：`plugin\worker\Service` + - 数据表：`system_queue` + - 命令入口：`php think xadmin:worker` + - 跨平台：Linux/macOS 使用 Workerman 守护进程，Windows 使用 console.exe + - 核心服务：HTTP 服务（默认 4 进程）、队列服务（任务调度） + - 进程管理：状态监控、内存监控、文件监控、健康检查 + - 许可证：Apache-2.0 -| 组件 | 最低要求 | 推荐版本 | 说明 | -|------|----------|----------|------| -| **PHP** | 7.1+ | 8.0+ | 支持最新 PHP 特性 | -| **Composer** | 2.0+ | 2.5+ | 包管理工具 | -| **数据库** | SQLite 3 | MySQL 8.0+ | 支持多种数据库 | -| **Web 服务器** | PHP 内置 | Nginx/Apache | 生产环境推荐 | -| **内存** | 128MB | 512MB+ | 推荐更大内存 | -| **磁盘空间** | 100MB | 1GB+ | 包含依赖和文件 | +- **ThinkPlugsStatic** (`zoujingli/think-plugs-static`) + 静态资源和项目骨架组件，提供前端静态文件、模板和项目初始化骨架。 + - 无前缀，通过其他插件间接使用 + - 主要功能：静态资源发布、项目骨架生成 + - 发布内容：配置文件、入口文件、LayUI 前端资源、系统脚本 + - 前端约定：只保留 LayUI 模块加载，移除 RequireJS + - 许可证：MIT -### 必需的 PHP 扩展 +### 平台插件 -- `gd` - 图像处理 -- `mbstring` - 多字节字符串处理 -- `openssl` - 加密功能 -- `pdo` - 数据库抽象层 -- `curl` - HTTP 客户端 -- `fileinfo` - 文件类型检测 -- `json` - JSON 处理 -- `zip` - 压缩文件处理 +- **ThinkPlugsWechatClient** (`zoujingli/think-plugs-wechat-client`) + 微信公众号标准平台，提供公众号基础能力、菜单管理、消息推送等。 + - 命名空间：`plugin\wechat\` + - 服务注册：`plugin\wechat\Service` + - 访问前缀：`wechat` + - 数据表：微信配置、粉丝、素材、菜单、关键词回复、支付记录等 + - 核心功能：公众号配置、粉丝同步、素材管理、菜单管理、关键词回复、微信支付 + - 命令：`xadmin:fansall`, `xadmin:fansmsg`, `xadmin:fanspay` + - 许可证：MIT -### 环境检测 +- **ThinkPlugsWechatService** (`zoujingli/think-plugs-wechat-service`) + 微信公众号开放平台，提供第三方平台托管、授权管理和远程 JSON-RPC 服务。 + - 命名空间：`plugin\wechat\service\` + - 服务注册：`plugin\wechat\service\Service` + - 访问前缀：`wechat-service` + - 数据表：第三方授权、组件配置 + - 核心功能：开放平台配置、授权管理、JSON-RPC 远程调用、推送事件接收 + - 命令：`xsync:wechat` + - 许可证：专有授权 -在安装前，请确保您的环境满足以下要求： +### 业务插件 + +- **ThinkPlugsAccount** (`zoujingli/think-plugs-account`) + 多端账号体系，统一管理用户账号、终端设备和短信服务。 + - 命名空间：`plugin\account\` + - 服务注册：`plugin\account\Service` + - 访问前缀：`account` + - 数据表：用户账号、终端绑定、短信记录等 + - 核心功能：多端账号管理、微信登录、短信验证、账号绑定、JWT 认证 + - 接口入口：`/api/account/login/*`, `/api/account/auth/*` + - 依赖：ThinkLibrary, ThinkPlugsSystem + - 许可证：专有授权（VIP） + +- **ThinkPlugsPayment** (`zoujingli/think-plugs-payment`) + 支付中心，统一管理支付配置、交易记录、退款、余额和积分。 + - 命名空间：`plugin\payment\` + - 服务注册：`plugin\payment\Service` + - 访问前缀：`payment` + - 数据表：支付配置、交易记录、退款记录、余额明细、积分明细 + - 核心功能：支付配置、混合支付、余额积分、退款管理、支付事件分发 + - 支付事件：Audit/Refuse/Success/Cancel/Confirm + - 依赖：ThinkLibrary, ThinkPlugsAccount, ThinkPlugsSystem + - 许可证：专有授权（VIP） + +- **ThinkPlugsWemall** (`zoujingli/think-plugs-wemall`) + 分销商城系统，提供完整的电商管理能力。 + - 命名空间：`plugin\wemall\` + - 服务注册：`plugin\wemall\Service` + - 访问前缀：`wemall` + - 数据表：商品、订单、用户、等级、代理、物流等 + - 核心功能：商品管理、订单管理、分销返利、会员等级、商城 API + - 命令：`xdata:mall:clear`, `xdata:mall:trans`, `xdata:mall:users` + - 依赖：ThinkLibrary, ThinkPlugsAccount, ThinkPlugsPayment, ThinkPlugsSystem + - 许可证：专有授权（VIP） + +- **ThinkPlugsWuma** (`zoujingli/think-plugs-wuma`) + 一物一码与防伪溯源系统。 + - 命名空间：`plugin\wuma\` + - 服务注册：`plugin\wuma\Service` + - 访问前缀：`wuma` + - 数据表：防伪码、溯源记录、仓储管理、代理库存等 + - 核心功能：一物一码、溯源管理、仓储流转、代理库存、扫码验证 + - 命令：`xdata:wuma:create` + - 接口请求头：`Authorization`, `X-Device-Code`, `X-Device-Type` + - 依赖：ThinkLibrary, ThinkPlugsWemall, ThinkPlugsSystem + - 许可证：专有授权（VIP） + +## 当前架构约定 + +### 路由与应用 + +- `app/*` 支持本地多应用，`app/index` 为默认本地应用 +- 本地应用入口：`/{app}/{controller}/{action}`（默认应用可省略首段） +- 插件通过 URL 前缀注册访问入口 +- 请求首段命中插件前缀时切换到插件 +- 未命中插件前缀时回退到本地应用 +- 动态插件切换默认关闭 +- 页面入口统一使用 `/{plugin}/...` +- 接口入口统一使用 `/api/{plugin}/{controller}/{action}` +- 页面链接统一使用 `sysuri()`，接口链接统一使用 `apiuri()` +- 旧 `/{plugin}/api.xxx/...` 只保留兼容，不再作为新代码标准 + +### 服务注册 + +- ThinkPHP 服务注册统一使用 `composer.json > extra.think.services` +- 插件运行时元数据统一使用 `composer.json > extra.xadmin.app` +- 菜单元数据统一使用 `composer.json > extra.xadmin.menu` +- 迁移元数据统一使用 `composer.json > extra.xadmin.migrate` + +### 认证 + +- 后台与 API 统一优先使用 `Authorization: Bearer ` +- 不再使用 Session 或认证 Cookie 承载后台登录态 +- 后台壳页首跳允许一次性 `access_key` 引导，后续请求统一落到 `Authorization` +- 用户临时态统一使用基于 Token SID 的 `CacheSession` +- 统一入口为 `tsession()` + +统一请求头约定： + +- 认证令牌：`Authorization: Bearer ` +- 设备接口附加头：`X-Device-Code`、`X-Device-Type` +- 不再使用 `Api-Token`、`Api-Type`、`Api-Code` 这类旧请求头 + +### 接口响应标准 + +- HTTP JSON 接口统一返回 HTTP `200` +- 业务状态统一写入 `code`，常用状态码为 `200/401/403/404/500` +- `200` 表示成功，`401` 表示未认证或登录过期，`403` 表示已认证但无权限，`404` 表示接口或资源不存在，`500` 表示服务端异常 +- 前端判断成功失败时只应以 `code === 200` 为成功，不再使用 `1/0` 语义 +- 各插件 `readme.api.md` 必须同步这一返回结构：`code`、`info`、`data`，鉴权异常可附带 `error` + +### 运行时 + +- 统一命令入口：`php think xadmin:worker` +- `http` 负责托管系统 HTTP 服务 +- `queue` 负责长耗时任务和延时任务调度 +- `ThinkLibrary` 只定义队列契约与调用门面，队列记录由 `ThinkPlugsWorker` 维护 +- 运行时进程统一以 `xadmin:worker serve ` 作为命令签名，CLI 与后台状态管理都围绕该签名进行进程识别 +- `pidFile` 只保留为 Workerman 辅助运行文件，不再作为唯一状态来源；当 pid 文件缺失、脏数据残留或被误删时，会自动回退到进程扫描与健康检查 +- Windows 后台服务统一通过 `plugin/think-plugs-worker/src/service/bin/console.exe` 启动，Linux / macOS 仍保留 Workerman 守护化与 reload 语义 + +### PHAR 路径约定 + +当使用 `ThinkPlugsBuilder` 构建并以 `admin.phar` 方式运行时，请遵循下面约定： + +- `syspath()`：读取 **PHAR 包内**只读资源（如 `public/static`、内置模板/数据） +- `runpath()`：读写 **PHAR 外部**可写目录（如 `runtime/`、`safefile/`、`database/`、`public/upload/`、Worker 的 pid/log/status/stdout 文件） + +更完整的构建与运行说明请参考 `plugin/think-plugs-builder/readme.md`。 + +### 前端 + +- 后台统一使用 `LayUI + $.module.use(...)` +- `RequireJS` 已彻底移除 +- 数据导出统一使用前端 JavaScript 模块 +- 系统脚本统一下发 `taSystem / taSystemApi / taStorage / taStorageApi / taApiPrefix` +- 上传、图标、队列等高频模块优先消费这组变量，不再手工拼 `api.xxx` + +### 双入口示例 + +- 页面：`/system/index/index` +- 页面：`/system/config/storage` +- 接口：`/api/system/plugs/script` +- 接口：`/api/system/upload/file` +- 接口：`/api/wechat/view/news?id=1` +- 接口：`/api/wechat-service/client/jsonrpc?token=TOKEN` + +### 目录 + +- `app/*` 支持本地多应用扩展，实际源码可维护在 `app/*/controller` 或 `plugin/*/src` +- 核心业务源码优先维护在 `plugin/*/src` + +## 开发工具 + +### PHPStan 静态代码分析 + +项目已集成 PHPStan 2.0，用于代码质量检查和静态分析。 ```bash -# 检查 PHP 版本 -php -v +# 运行代码分析 +composer analyse -# 检查 Composer -composer -v - -# 检查 PHP 扩展 -php -m | grep -E "(gd|mbstring|openssl|pdo|curl|fileinfo|json|zip)" +# 分析结果无错误时输出：[OK] No errors ``` -## 快速开始 +配置说明： -### 快速安装体验 +- 配置文件：`phpstan.neon` +- 检查级别：`level 3`（已开启更多真实异常检查） +- 检查范围：`app/`, `config/`, `plugin/` +- 通过 `scanFiles` 显式加载 ThinkPHP 与项目公共函数 +- 排除目录：`runtime/`, `vendor/` + +### 代码风格 + +使用 PHP-CS-Fixer 统一代码风格： ```bash -# 创建项目（需要在英文目录下执行，默认只安装 admin 和 static 模块） -composer create-project zoujingli/thinkadmin - -# 进入项目根目录 -cd thinkadmin - -# 数据库初始化并安装 -# 默认使用 Sqlite 数据库，若使用其他数据库请修改配置后再执行 -php think migrate:run - -# 安装微信管理模块（可选模块） -composer require zoujingli/think-plugs-wechat - -# 🚀 开启 PHP 内置 WEB 服务 -# 默认后台登录账号及密码都是 admin -php think run --host 127.0.0.1 +# 自动修复代码风格 +composer sync ``` -### 访问系统 +### 测试 -安装完成后，打开浏览器访问系统： - -| 访问地址 | 说明 | 默认账号 | -|---------|------|----------| -| `http://127.0.0.1:8000` | 系统首页 | - | -| `http://127.0.0.1:8000/admin` | 后台管理 | admin/admin | -| `http://127.0.0.1:8000/api` | API 接口 | - | - -### 首次使用指南 - -1. **登录后台管理** - - 访问 `http://127.0.0.1:8000/admin` - - 使用默认账号 `admin` / `admin` 登录 - -2. **修改默认密码** - - 进入"系统管理" → "用户管理" - - 修改管理员密码 - -3. **配置系统参数** - - 进入"系统管理" → "系统参数配置" - - 设置网站名称、Logo 等基本信息 - -4. **创建业务模块** - - 使用代码生成器创建 CRUD 功能 - - 开发自定义插件实现业务逻辑 - -### 安装 ThinkLibrary - -ThinkAdmin 基于 ThinkLibrary 核心工具库，如需单独安装： +运行所有测试： ```bash -# 安装 ThinkLibrary -composer require zoujingli/think-library +# 运行所有测试 +composer test -# 确保控制器继承自 think\admin\Controller -class MyController extends \think\admin\Controller { - protected $dbQuery = '数据表名'; - // 使用 ThinkLibrary 提供的功能 -} +# 仅运行冒烟测试 +composer test:smoke + +# 仅运行单元测试 +composer test:unit ``` -## 核心功能 +测试覆盖包括： -### 🚀 自由扩展的组件生态 +- 架构边界测试（插件依赖、迁移归属、Composer 边界） +- 核心功能测试（JWT、CacheSession、Helper 工具） +- 控制器集成测试（System、Account、Payment、Worker） +- 业务集成测试（支付事件、账号绑定） -基于最新 ThinkPHP 框架开发，遵循 Composer 标准管理依赖组件，可自由安装各种开源组件及插件生态程序。系统将功能模块封装为独立的插件包，支持通过 Composer 进行安装和更新，让开发者可以根据项目需求选择性地安装所需的功能模块。 - -### 💾 标准化文件存储引擎 - -支持本地存储、自建 Alist 存储、多种云存储，基于文件 HASH 实现文件秒传，节省服务器空间。提供统一的文件存储引擎，支持多种存储方案，满足不同场景下的数据存储需求。 - -**支持的存储方案**: -- 本地服务器存储 -- 自建 Alist 存储 -- 七牛云空间存储 -- 阿里云 OSS 存储 -- 腾讯云 COS 存储 -- 又拍云 USS 存储 - -### 🔐 注解 RBAC 权限管理 - -通过控制器方法注释实现功能节点自动生成，配合后台权限管理实现最简注解权限控制。系统实现了基于注解的简化 RBAC 权限模型，支持精确到按钮级别的权限控制。 - -**权限系统特点**: -- **注解驱动** - 通过控制器注释自动生成权限节点，简化权限配置 -- **精确控制** - 权限控制精确到按钮级别，提供最大灵活性 -- **自动维护** - 功能节点由系统自动维护，根据控制器代码注释进行刷新 -- **动态菜单** - 根据用户权限动态显示功能菜单，支持三级菜单结构 -- **操作日志** - 完整记录用户操作行为，支持安全审计 - -### 🔧 可升级 Composer 插件微架构 - -深度定制 Composer 插件，实现专属插件生态管理架构，可将应用模块封装成独立插件包。系统强制要求使用插件架构，所有业务功能都必须通过自定义插件实现。 - -### ⚡ 独立进程异步执行任务 - -兼容多平台动态创建 PHP 进程，并列启动多个独立任务进程处理大数据或长时性任务，实时显示执行进度。支持多进程异步任务处理，显著提高任务处理效率。 - -**任务系统特性**: -- **多进程架构** - 支持多进程并发执行任务，提高处理效率 -- **跨平台支持** - 兼容 Windows 和 Linux 系统 -- **自动监控** - 每 0.5 秒扫描任务数据表，自动执行待处理任务 -- **进程管理** - 支持 START、STOP、QUERY、LISTEN 等进程管理指令 -- **进度跟踪** - 支持任务完成状态跟进和进度显示 -- **异常恢复** - 支持自动重启和异常处理 -- **守护进程** - 支持后台守护进程模式运行 - -### 🛠️ 常用操作及工具库封装 - -核心组件封装各种常用 CRUD 操作及工具库，快速实现数据增删改查，后台 UI 基于最新 Layui 构建。基于 ThinkLibrary 核心工具库，提供完整的 CRUD 操作和一系列常用工具。 - -**核心功能模块**: -1. **数据列表展示组件** - 展示数据列表，支持分页、排序和高级搜索 -2. **表单处理模块** - 用于创建、展示和提交表单数据，完善的表单验证和错误处理机制 -3. **数据状态快速处理模块** - 根据业务需求快速更新数据状态，支持多字段同时更新 -4. **数据安全删除模块** - 安全删除数据，支持软删除和硬删除 -5. **文件存储通用组件** - 支持多种文件存储方式，统一接口和配置 -6. **通用数据保存更新模块** - 基于 key 和条件判断数据存在性，进行更新或新增 -7. **通用网络请求模块** - 支持 GET、POST 和 PUT 请求，统一接口 -8. **系统参数配置模块** - 快速配置并保存系统参数 -9. **UTF-8 加密算法支持** - 提供 UTF-8 字符串加密和解密功能 -10. **接口 CORS 跨域支持** - 默认支持跨域请求，输出标准化 JSON 数据 -11. **表单 CSRF 安全验证** - 自动为表单添加 CSRF 安全验证字段 - -## 核心功能详解 - -### 插件生态架构 - -基于 Composer 标准管理依赖组件，支持插件热插拔和在线升级。 - -```php -createTables(); - $this->createMenus(); - } - - public function uninstall() - { - // 卸载插件时的操作 - $this->dropTables(); - $this->removeMenus(); - } -} -``` - -### 注解权限管理 - -通过控制器方法注释实现功能节点自动生成，简化权限配置。 - -```php -title = '用户管理'; - $this->_query('SystemUser') - ->like('username,nickname,phone') - ->equal('status') - ->dateBetween('create_at') - ->order('id desc') - ->page(); - } -} -``` - -### 文件存储系统 - -支持多种存储方案，基于文件 HASH 实现文件秒传。 - -```php -getPathname()); - $exists = $this->checkFileExists($hash); - - if ($exists) { - return $exists['url']; - } - - // 上传文件 - $result = $storage->upload($file); - return $result['url']; - } -} -``` - -### 异步任务系统 - -支持多进程异步任务处理，实时显示执行进度。 - -```php -setQueueProgress('开始发送邮件...', 10.00); - - try { - // 发送邮件逻辑 - $result = $this->sendMail($data['to'], $data['subject'], $data['content']); - - if ($result) { - $this->setQueueProgress('邮件发送成功', 100.00); - $this->setQueueSuccess('邮件发送成功'); - } else { - $this->setQueueError('邮件发送失败'); - } - } catch (\Exception $e) { - $this->setQueueError('邮件发送异常: ' . $e->getMessage()); - } - } -} -``` - -### 开发工具 - -基于 ThinkLibrary 核心工具库，提供完整的 CRUD 操作。 - -```php -title = '商品管理'; - $this->_query($this->dbQuery) - ->like('name,description') - ->equal('category_id,status') - ->dateBetween('create_at') - ->order('id desc') - ->page(); - } - - public function add() - { - $this->title = '添加商品'; - $this->_form($this->dbQuery, 'form'); - } - - public function save() - { - $this->_save($this->dbQuery, $this->_vali([ - 'status.require' => '状态不能为空', - 'status.in:0,1' => '状态值无效' - ])); - } -} -``` - -## 技术栈 - -### 后端技术 - -ThinkAdmin 基于 **ThinkPHP 6 & 8** 框架开发，支持 **PHP 7.1+** 版本，充分利用现代 PHP 特性： - -- **框架版本**: ThinkPHP 6 & 8 (支持最新 PHP 8.x) -- **核心依赖**: ThinkLibrary v6.1+ (核心工具库) -- **插件生态**: ThinkPlugsAdmin v1.0+ (后台管理)、ThinkPlugsWechat v1.0+ (微信管理) -- **数据库支持**: MySQL、PostgreSQL、SQLite、SQL Server -- **ORM 支持**: ThinkORM 2.0+，支持模型关联、查询构建器 -- **缓存系统**: Redis、Memcached、文件缓存 -- **队列系统**: 支持异步任务处理 -- **数据库迁移**: 使用 Phinx 进行版本控制 -- **多语言支持**: 支持全局、应用、动态三种语言包类型 -- **路由管理**: 支持全局路由和应用路由，模块化管理 -- **运行模式**: 支持开发模式和生产模式切换 -- **内置函数**: 提供 20+ 个内置函数，简化开发流程 - -### 前端技术 - -前端采用现代化的技术栈，提供良好的用户体验和开发体验： - -- **UI 框架**: LayUI 2.x (轻量级、响应式) -- **模块管理**: RequireJS (按需加载) -- **图表组件**: ECharts (数据可视化) -- **富文本编辑**: CKEditor (内容编辑) -- **图标字体**: Font Awesome (图标系统) -- **响应式设计**: 支持移动端和桌面端 -- **表格组件**: LayUI Table 组件，支持动态高度、搜索绑定 -- **表单组件**: 支持自动提交、数据验证 -- **弹层组件**: LayUI Layer 弹层组件 -- **工具函数**: 内置 jQuery 扩展和工具函数 - -### 第三方集成 - -系统提供了丰富的第三方服务集成，支持主流云服务和平台： - -- **云存储**: 七牛云、阿里云 OSS、腾讯云 COS、又拍云 USS、自建 Alist 存储 -- **微信生态**: 公众号管理、小程序管理、微信支付、用户管理、素材管理 -- **支付集成**: 微信支付、支付宝等主流支付方式 -- **消息推送**: 邮件发送、短信发送等基础消息推送功能 - -## 插件生态 - -ThinkAdmin 采用 Composer 插件定制架构，提供丰富的插件生态： - -### 核心插件 - -- **ThinkLibrary v6.1+** - 核心工具库，提供完整的 CRUD 操作和一系列常用工具，特别注重多应用支持 -- **ThinkPlugsAdmin v1.0+** - 后台基础管理模块，提供用户、权限、菜单、系统配置等核心功能 -- **ThinkPlugsWechat v1.0+** - 微信平台管理，支持公众号、小程序、微信支付等完整功能 - -### 扩展插件 - -- **ThinkPlugsAccount** - 账号管理插件 -- **ThinkPlugsPayment** - 支付管理插件 -- **ThinkPlugsWorker** - 高性能 Worker 运行插件 -- **ThinkPlugsStatic** - 静态资源管理插件 - -### 插件特点 - -- **热插拔** - 支持插件的动态安装和卸载 -- **统一管理** - 通过 Composer 进行插件依赖管理 -- **本地化开发** - 支持插件本地化定制开发 -- **版本控制** - 支持插件版本管理和更新 - -### 插件开发 - -系统强制要求使用插件架构，所有业务功能都必须通过自定义插件实现。开发者必须基于统一的插件接口规范开发自定义插件来实现具体的业务功能。 - -**插件开发示例**: -```php -createTables(); - $this->createMenus(); - } - - public function uninstall() - { - // 卸载插件时的操作 - $this->dropTables(); - $this->removeMenus(); - } -} -``` - -## 数据库配置 - -### SQLite (默认) -```php -// config/database.php -return [ - 'default' => 'sqlite', - 'connections' => [ - 'sqlite' => [ - 'type' => 'sqlite', - 'database' => 'database/sqlite.db', - ], - ] -]; -``` - -### MySQL -```php -// config/database.php -return [ - 'default' => 'mysql', - 'connections' => [ - 'mysql' => [ - 'type' => 'mysql', - 'hostname' => '127.0.0.1', - 'database' => 'thinkadmin', - 'username' => 'root', - 'password' => 'your_password', - 'hostport' => '3306', - 'charset' => 'utf8mb4', - ], - ] -]; -``` - -## 系统命令 +## 安装与初始化 ```bash -# 启动开发服务器 -php think run --host 127.0.0.1 --port 8000 +# 安装依赖 +composer update --optimize-autoloader -# 数据库迁移 -php think migrate:run +# 显式执行完整安装链路 +php think xadmin:install -# 清除缓存 -php think clear +# 仅发布配置、静态资源和迁移脚本（不执行建表） +php think xadmin:publish -# 异步任务管理 -php think xadmin:queue start # 启动守护进程 -php think xadmin:queue stop # 停止进程 -php think xadmin:queue query # 查询任务 -php think xadmin:queue listen # 监听进程 +# 可选：强制执行所有已发布迁移 +php think xadmin:publish --migrate + +# 可选：检查迁移执行状态 +php think migrate:status + +# 启动 HTTP 服务 +php think xadmin:worker start http -d ``` -## 开发指南 +说明： -### 创建控制器 -```php - config.allow-plugins.zoujingli/think-plugs-install = true` 显式允许该安装插件运行。 +- 当仓库已经存在历史安装快照，且本次变更中包含声明了 `extra.xadmin.migrate` 的插件时，Composer 安装链路会自动切换到 `xadmin:publish --migrate`，直接安装或升级数据库表结构。 +- 首次 `composer install` 只会自动发布资源与迁移脚本，不会直接建表；需要在环境配置完成后显式执行一次 `php think xadmin:install`。 +- 新装或升级的插件如果没有声明 `extra.xadmin.migrate`，Composer 只会输出提示，不会强行执行数据库迁移。 +- `php think xadmin:publish` 只负责发布配置、静态资源并同步各插件 `stc/database` 到根目录 `database/migrations`。 +- `php think xadmin:install` 会显式执行同一条安装链路；当前已安装插件里只要存在 `extra.xadmin.migrate`，就会自动执行迁移；`--migrate` 可强制迁移。 +- `vendor/.plugin-state.json` 用于记录上一次 Composer 自动安装快照，判断哪些插件需要自动迁移。 -use think\admin\Controller; +默认访问地址： -class MyController extends Controller -{ - /** - * 我的页面 - * @auth true - * @menu true - */ - public function index() - { - $this->title = '我的页面'; - $this->fetch(); - } -} -``` +- `http://127.0.0.1:2346`（可通过 `config/worker.php` 修改端口） -### 权限控制 -```php -/** - * 需要权限验证的方法 - * @auth true # 需要权限验证 - * @menu true # 添加到菜单 - * @login true # 需要登录 - */ -public function myMethod() -{ - // 方法内容 -} -``` +## 常用命令 -### 数据操作 -```php -// 查询数据 -$this->_query('user') - ->like('username,email') - ->equal('status') - ->dateBetween('create_time') - ->order('id desc') - ->page(); - -// 表单处理 -$this->_form('user', 'form'); - -// 状态更新 -$this->_save('user', $this->_vali([ - 'status.require' => '状态不能为空', - 'status.in:0,1' => '状态值无效' -])); -``` - -## 常见问题 - -### 安装部署 - -**Q: 安装时提示 Composer 错误怎么办？** - -A: 请检查以下几点： -1. **PHP 版本**: 确保 PHP 版本 ≥ 7.1 -2. **Composer 版本**: 执行 `composer self-update` 更新到最新版本 -3. **网络问题**: 如果网络不稳定，可以配置国内镜像 - -**Q: 数据库初始化失败怎么办？** - -A: 请检查： -1. **数据库配置**: 检查 `config/database.php` 配置是否正确 -2. **数据库权限**: 确保数据库用户有创建表的权限 -3. **数据库连接**: 测试数据库连接是否正常 - -**Q: 无法访问后台管理页面？** - -A: 可能的原因： -1. **URL 路径**: 确保访问的是 `/admin` 或 `/admin.html` -2. **Web 服务器配置**: 检查伪静态规则是否正确配置 -3. **PHP 扩展**: 确保安装了必要的 PHP 扩展 - -### 功能使用 - -**Q: 如何修改后台登录入口？** - -A: 在后台 **系统管理** → **系统参数配置** 中修改： -1. 找到"后台入口地址"配置项 -2. 设置新的入口地址（如：`/myadmin`） -3. 保存配置，原入口将自动失效 - -**Q: 文件上传失败怎么办？** - -A: 检查以下配置： -1. **上传目录权限**: 确保 `public/upload` 目录可写 -2. **PHP 配置**: 检查 `upload_max_filesize` 和 `post_max_size` -3. **系统参数**: 在后台配置正确的文件上传参数 - -**Q: 如何添加自定义菜单？** - -A: 在后台 **系统管理** → **菜单管理** 中： -1. 点击"添加菜单" -2. 填写菜单名称和链接地址 -3. 选择父级菜单 -4. 设置菜单图标和排序 - -### 开发相关 - -**Q: 如何创建新的控制器？** - -A: 在 `app/admin/controller/` 目录下创建控制器文件，继承 `think\admin\Controller`。 - -**Q: 如何添加权限控制？** - -A: 在控制器方法上添加注释：`@auth true`、`@menu true`、`@login true`。 - -**Q: 如何自定义主题样式？** - -A: 可以通过以下方式自定义： -1. **CSS 文件**: 在 `public/static/css/` 目录下添加自定义样式 -2. **系统参数**: 在后台配置主题相关参数 -3. **模板文件**: 修改 `app/admin/view/` 下的模板文件 - -### 插件相关 - -**Q: 如何安装插件？** - -A: 使用 Composer 安装： ```bash -# 安装免费插件 -composer require zoujingli/think-plugs-wechat +# 查看全部命令 +php think list -# 安装付费插件（需要授权） -composer require zoujingli/think-plugs-account +# 启动 HTTP 服务 +php think xadmin:worker start http -d + +# 启动队列服务 +php think xadmin:worker start queue -d + +# 查看运行状态 +php think xadmin:worker status all + +# 代码质量检查 +composer analyse + +# 代码风格修复 +composer sync + +# 生成插件迁移脚本 +php think xadmin:helper:migrate + +# 生成安装包 +php think xadmin:package ``` -**Q: 插件安装后没有显示怎么办？** +## 发布与迁移 -A: 检查以下几点： -1. **插件状态**: 在后台插件管理中查看插件状态 -2. **权限配置**: 确保当前用户有访问插件的权限 -3. **缓存清理**: 清除系统缓存后重新访问 +`xadmin:publish` 由 `ThinkPlugsSystem` 内置的 `plugin\system\helper\*` 工具提供，负责： -**Q: 如何卸载插件？** +- 按插件 `composer.json` 中的 `extra.xadmin.publish.copy` 规则同步资源 +- 同步各插件 `stc/database` 到根目录 `database/migrations` +- 通过 `vendor/.published.json` 跟踪插件已发布资源，并在插件移除或规则收缩后清理失效产物 +- 通过 `database/migrations/.published.json` 清理历史失效或冲突迁移 -A: 使用 Composer 卸载： -```bash -composer remove zoujingli/plugin-name -``` +执行规则： -**注意**: 卸载插件不会自动删除相关数据表，需要手动清理。 +- `zoujingli/think-plugs-install` 作为 Composer plugin，会在 `composer install / update / remove / dump-autoload` 后自动执行发布链路。 +- 自动链路始终先执行 `service:discover`，再执行 `xadmin:publish` 或 `xadmin:publish --migrate`。 +- 只有非首次安装、且本次变更中声明了 `extra.xadmin.migrate` 的插件，才会自动执行数据库迁移；未声明时只输出提示。 +- `php think xadmin:install` 是同一条链路的显式入口，会根据当前已安装插件的 `extra.xadmin.migrate` 自动决定是否迁移。 +- `php think xadmin:publish` 只同步资源和迁移脚本，不执行数据库安装。 +- `php think xadmin:publish --migrate` 会在同步完成后自动调用 `migrate:run`，安装或升级数据库表结构。 +- 根目录 `database/migrations` 是发布产物，真正执行的也是这里的迁移脚本。 -### 性能优化 +当前约定为： -**Q: 系统运行缓慢怎么办？** +- 发布规则以 `copy` 清单为准；目标路径前加 `!` 可对单项启用强制覆盖 +- `copy` 同时支持 `source: target`、`source: { to, force, exclude }`、`{ from, to, force, exclude }` 三种写法 +- 结构化规则支持 `exclude`，可按相对路径或文件名模式跳过目录内的发布文件 +- 目标目录存在 `ignore` 文件时，会跳过该目录下发布文件的自动覆盖和自动删除 +- 每个插件只保留一份最终安装脚本 +- 需要自动建表的插件必须声明 `composer.json > extra.xadmin.migrate`；未声明时 Composer 只提示，不执行数据库迁移 +- Composer 自动迁移依赖 `vendor/.plugin-state.json` 判断是否为首次安装；首次安装只生成发布产物与迁移脚本 +- 根目录 `database/migrations` 视为发布产物，不纳入源码维护 -A: 可以尝试以下优化： -1. **开启缓存**: 在后台切换到生产模式 -2. **数据库优化**: 为常用查询字段添加索引 -3. **文件存储**: 使用云存储提升文件访问速度 -4. **服务器配置**: 优化 PHP 和 Web 服务器配置 +## 平台说明 -**Q: 如何开启生产模式？** +- Windows 兼容 +- Linux 兼容 +- `Worker reload` 仅适用于 Linux / macOS -A: 在后台 **系统管理** → **系统参数配置** 中： -1. 找到"运行模式"配置项 -2. 选择"生产模式" -3. 保存配置并清理缓存 +## 开发文档 -### 错误排查 +- 官网文档：[thinkadmin.top](https://thinkadmin.top) +- 接口文档：[ThinkAdminMobile](https://thinkadmin.apifox.cn) +- 架构文档： + - [插件边界](./docs/architecture/plugin-boundaries.md) + - [插件优先重构](./docs/architecture/plugin-first-refactor.md) + - [认证与会话](./docs/architecture/auth-token-session.md) + - [稳定性评估](./docs/architecture/stability-status.md) + - [插件标准](./docs/architecture/plugin-standard.md) + - [路由分发标准](./docs/architecture/route-dispatch-standard.md) + - [软删除标准](./docs/architecture/soft-delete-standard.md) +- 组件详细文档：[components-detail.md](./docs/components-detail.md) -**Q: 页面显示 500 错误？** +## 注意事项 -A: 检查以下内容： -1. **错误日志**: 查看 `runtime/log/` 目录下的错误日志 -2. **PHP 错误**: 检查 PHP 错误日志 -3. **权限问题**: 确保目录权限正确 -4. **配置问题**: 检查配置文件是否正确 - -**Q: 数据库连接失败？** - -A: 检查数据库配置： -1. **连接参数**: 检查 `config/database.php` 中的连接参数 -2. **数据库服务**: 确保数据库服务正在运行 -3. **网络连接**: 检查网络连接是否正常 -4. **用户权限**: 确保数据库用户有相应权限 - -## 贡献 - -我们欢迎所有形式的贡献，包括但不限于： - -### 如何贡献 - -1. **报告问题** - - 在 [GitHub Issues](https://github.com/zoujingli/ThinkAdmin/issues) 或 [Gitee Issues](https://gitee.com/zoujingli/ThinkAdmin/issues) 报告 Bug - - 提供详细的问题描述和复现步骤 - - 包含系统环境信息 - -2. **提交代码** - - Fork 项目到您的 GitHub 账户 - - 创建功能分支：`git checkout -b feature/AmazingFeature` - - 提交更改：`git commit -m 'Add some AmazingFeature'` - - 推送分支：`git push origin feature/AmazingFeature` - - 创建 Pull Request - -3. **改进文档** - - 完善 README 文档 - - 添加使用示例 - - 翻译文档到其他语言 - -4. **分享经验** - - 分享使用心得 - - 编写教程文章 - - 参与社区讨论 - -### 开发计划 - -- [ ] 支持更多数据库类型 -- [ ] 优化前端界面 -- [ ] 增加更多插件 -- [ ] 完善 API 文档 -- [ ] 支持 Docker 部署 - -### 社区支持 - -- **GitHub**: [https://github.com/zoujingli/ThinkAdmin](https://github.com/zoujingli/ThinkAdmin) -- **Gitee**: [https://gitee.com/zoujingli/ThinkAdmin](https://gitee.com/zoujingli/ThinkAdmin) -- **官方网站**: [https://thinkadmin.top](https://thinkadmin.top) -- **在线演示**: [https://v6.thinkadmin.top](https://v6.thinkadmin.top) -- **技术交流群**: 请访问官网获取群号 - -### 赞助支持 - -如果这个项目对您有帮助，欢迎通过以下方式支持我们： - -- ⭐ Star 项目 -- 🍴 Fork 项目 -- 📢 分享给更多人 -- 💰 赞助开发（请访问官网了解详情） +- 本仓库包含会员插件，未授权不得商用 +- 插件卸载通常不会自动删除已执行迁移和历史数据 +- 自定义前端脚本建议放在 `public/static/extra` ## 许可证 -本项目基于 [MIT](https://mit-license.org) 许可证开源。 +除会员授权插件外，其余组件按各自许可证发布： -## 版权 +- **MIT**: ThinkLibrary, System, WechatClient, Static +- **Apache-2.0**: Worker, Builder, System 内置 Helper 工具 +- **专有授权**: Account, Payment, Wemall, Wuma, WechatService -版权所有 Copyright © 2018-2025 by ThinkAdmin (https://thinkadmin.top) All rights reserved. - -**备案信息**: [粤ICP备16006642号](https://beian.miit.gov.cn) - ---- - -**提示**: 遇到问题时，建议先查看错误日志，大多数问题都能通过日志找到原因。 \ No newline at end of file +未获得授权的插件（Account/Payment/Wemall/Wuma/WechatService）不得用于商业用途。