blackteay/ThinkAdmin
1
0
Fork 0
mirror of https://gitee.com/zoujingli/ThinkAdmin.git synced 2026-06-06 20:18:10 +08:00
Code Issues Projects Releases Wiki Activity

docs(architecture): 完善 v8 架构与迁移说明

Browse Source 
补充 v8 重构后的架构文档、组件说明和迁移记录，方便后续维护者理解插件边界。

主要内容：

- 更新根 README，说明 v8 插件分层、系统模块、交付命令和验证流程。

- 新增组件明细、插件边界、路由分发、软删除和稳定性文档。

- 记录 Storage 合并到 System、旧 View 移除和 Helper 并入 System 的决策。

- 补充文档注释报告和后续重构计划，便于持续演进。
This commit is contained in:
Anyon 2026-05-08 15:31:22 +08:00
parent 4e2b7ab2fc
commit 6f4056f64d
14 changed files with 4138 additions and 730 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

280
docs/STORAGE_MERGE.md Normal file
View File

@ -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

205
docs/UPDATE_NOTES.md Normal file
View File

@ -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

149
docs/architecture/auth-token-session.md Normal file
View File

@ -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 <JWT>`
- 首屏壳页：允许一次性 `access_key`
- 会话：JWT 内的 `sid` 绑定 `CacheSession`
适用场景：
- 后台运营人员
- 管理员
- 需要 RBAC 的内部接口
### 2. 业务账号认证
- 类型：`account-auth`
- 载体：`Authorization: Bearer <JWT>`
- 会话：JWT 内的 `sid` 绑定 `CacheSession`
适用场景：
- 会员
- 分销员
- 商户
- 店员
- 任何“业务用户”身份
注意：
- `wap / web / wxapp / wechat / iosapp / android` 是登录来源或终端通道
- 它们不是独立的认证协议
### 3. 设备认证
- 当前仅 `wuma` 保留独立设备 token
- 载体：`Authorization: Bearer <token>`
- 附加头：`X-Device-Code`、`X-Device-Type`
- 这不是 JWT，也不是通用账号协议
适用场景：
- PDA
- 扫码枪
- 仓库终端
- 封闭设备接口
### 4. 能力令牌
- 当前后台上传使用短期能力 token
- 它不是登录态，不参与通用用户会话
适用场景：
- 上传授权
- 短时能力下放
## 请求识别规则
统一入口为请求级令牌解析服务：
- 有 `Authorization` 时，只按请求头判定
- 后台壳页首次进入时，可通过一次性 `access_key` 引导写入本地 Token
- 不再依赖认证 Cookie 回退
- 不再混用 `Api-Token`、`Api-Code`、`Api-Type`
统一请求头：
```http
Authorization: Bearer <token>
X-Device-Code: <device-code>
X-Device-Type: <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`：短期能力授权
不要按每个终端来源都拆一套新的认证协议。

260
docs/architecture/doc-comments-report.md Normal file
View File

@ -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. **实用导向**: 注重文档的实用性和可读性
现在项目的文档完整性已达到较高水平，核心功能都有清晰的文档说明！🎉

92
docs/architecture/plugin-boundaries.md Normal file
View File

@ -0,0 +1,92 @@
# Plugin Boundaries
## 相关文档
- [插件标准](./plugin-standard.md)
- [插件优先重构](./plugin-first-refactor.md)
## 当前分层
```mermaid
flowchart TD
L["ThinkLibrary<br/>核心基础设施 / 门面 / 上下文 / Helper"] --> S["ThinkPlugsSystem<br/>后台壳层 / 认证 / 菜单 / 用户 / system_* / 存储中心 / 开发交付工具"]
L --> W["ThinkPlugsWorker<br/>queue / process 运行时实现"]
S --> W
S --> SF["system_file<br/>存储驱动 / 上传接口"]
S --> HT["plugin\\system\\helper\\*<br/>发布 / 迁移 / 打包工具"]
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<br/>AppService / NodeService / RuntimeService / QueueService / CacheSession / JwtToken"]
RT["runtime<br/>SystemContext / NullSystemContext / RequestContext / RequestTokenService"]
MW["middleware<br/>MultAccess"]
RO["route<br/>Route / Url"]
HP["helper<br/>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`。

76
docs/architecture/plugin-first-refactor.md Normal file
View File

@ -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` 中的准入规则。

188
docs/architecture/plugin-standard.md Normal file
View File

@ -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. 补齐最小安装与路由测试。

774
docs/architecture/plugins-detail.md Normal file
View File

@ -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
<?php
namespace plugin\{name};
use think\admin\Plugin;
class Service extends Plugin
{
public function boot(): void
{
// 插件启动逻辑
}
public function register(): void
{
// 插件注册逻辑
}
}
```
### 接口文档标准
- HTTP 插件必须在根目录 `readme.api.md` 中说明标准 JSON 响应结构
- 文档中的 `code` 必须使用 `200/401/403/404/500` 语义，不再使用 `1/0`
- 前端与调用方只能以 `code === 200` 视为成功，其他状态码按对应业务语义处理
### 菜单元数据标准
菜单配置在 `composer.json` 的 `extra.xadmin.menu` 中:
```json
{
"menu": {
"show": true,
"root": {
"name": "菜单根名称",
"sort": 100
},
"items": [
{
"name": "一级菜单",
"subs": [
{
"name": "二级菜单",
"icon": "layui-icon xxx",
"node": "plugin/controller/action"
}
]
}
]
}
}
```
### 迁移元数据标准
迁移配置在 `composer.json` 的 `extra.xadmin.migrate` 中:
```json
{
"migrate": {
"file": "20241010000001_install_{name}20241010.php",
"class": "Install{Name}20241010",
"name": "{Name}Plugin"
}
}
```
---
## 插件测试标准
每个插件必须包含单元测试:
```php
<?php
namespace plugin\{name}\tests;
use PHPUnit\Framework\TestCase;
class PluginTest extends TestCase
{
public function testPluginExists(): void
{
$this->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. 手动清理配置文件

118
docs/architecture/route-dispatch-standard.md Normal file
View File

@ -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`
- 如果必须保留旧三段式，后续要逐步迁成显式目标声明

54
docs/architecture/soft-delete-standard.md Normal file
View File

@ -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`，应视为回归

72
docs/architecture/stability-status.md Normal file
View File

@ -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` 是否继续保留独立设备认证
- 如果设备端会长期存在，再考虑抽成标准设备认证层
## 当前可接受判断
如果以“当前主线开发是否可继续”为标准，答案是可以。
如果以“是否已经具备强回归保障”为标准，答案是否。

489
docs/architecture/system-module-refactor-plan.md Normal file
View File

@ -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/<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` 相关测试已经可以通过。

1023
docs/components-detail.md Normal file
View File

File diff suppressed because it is too large Load Diff

1088
readme.md
View File

File diff suppressed because it is too large Load Diff