ThinkAdmin/docs/components-detail.md

组件详细说明文档

本文档详细描述 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 门面接口
• 多存储驱动支持和管理
• 上传授权和临时令牌生成
• 文件元数据管理
• 文件上传、删除、清理
• 文件类型统计和管理

使用示例:

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

4. 状态监控

   • 进程状态查看
   • 内存使用监控
   • 文件变更监控
   • 健康检查

命令入口:

# 启动 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):

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:* 等命令
• 负责插件迁移主脚本识别与导出
• 负责菜单元数据校验与菜单迁移写入
• 提供模型注释生成和少量开发辅助工具

常用命令:

# 发布配置、静态资源和迁移脚本
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 - 退款记录

命令:

# 同步所有粉丝
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 - 微信授权

命令:

# 同步微信数据
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 - 主账号资料

使用示例:

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/* - 帮助接口

命令:

# 清理商城数据
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/* - 登录接口

接口请求头规范:

Authorization: Bearer <token>
X-Device-Code: <device-code>
X-Device-Type: <device-type>

命令:

# 创建物码
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

命令:

# 使用推荐脚本构建
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

发布命令:

# 显式执行完整安装链路
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

---

架构约定

认证与会话

详细规范请参考：认证与会话规范

核心原则:

• 登录态必须由显式 Token 表达
• 临时用户态必须绑定到 Token 对应的 sid
• 业务请求统一使用 Authorization
• 后台壳页首跳只允许一次性 access_key 引导

认证协议分层:

• system-auth: 后台人员（JWT）
• account-auth: 所有业务用户（JWT）
• device token: 封闭设备（wuma 独立实现）
• capability token: 短期能力授权（上传等）

统一请求头:

Authorization: Bearer <token>
X-Device-Code: <device-code>
X-Device-Type: <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 文档

---

开发工具

PHPStan 静态代码分析

项目已集成 PHPStan 2.0，用于代码质量检查和静态分析。

# 运行代码分析
composer analyse

# 分析结果无错误时输出：[OK] No errors

配置说明：

• 配置文件：phpstan.neon
• 检查级别：level 3（已开启更多真实异常检查）
• 检查范围：app/, config/, plugin/
• 通过 scanFiles 显式加载 ThinkPHP 与项目公共函数
• 排除目录：runtime/, vendor/

代码风格

使用 PHP-CS-Fixer 统一代码风格：

# 自动修复代码风格
composer sync

测试

运行所有测试：

# 运行所有测试
composer test

# 仅运行冒烟测试
composer test:smoke

# 仅运行单元测试
composer test:unit

---

相关文档

• 官网文档：thinkadmin.top
• 接口文档：ThinkAdminMobile
• 架构文档：
  • 插件边界
  • 插件优先重构
  • 认证与会话
  • 稳定性评估
  • 插件标准
  • 路由分发标准
  • 软删除标准

---

注意事项

• 本仓库包含会员插件，未授权不得商用
• 插件卸载通常不会自动删除已执行迁移和历史数据
• 自定义前端脚本建议放在 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