ThinkAdmin/readme.md

# ThinkAdmin

**ThinkAdmin** 是基于 ThinkAdmin 8 / ThinkPHP 8.1 的组件化开发仓库，用于维护核心基础库、运行时组件、后台平台插件和业务插件。

## 版本基线

- ThinkAdmin `8.x`
- ThinkPHP `8.1+`
- PHP `8.1+`

## 详细描述

- 这个仓库不是单一应用，而是围绕 ThinkAdmin 8 / ThinkPHP 8.1 组织的一组标准组件，覆盖核心库、运行时、后台平台、业务插件和本地多应用。
- 目标不是维护旧版多应用项目，而是把系统重构成"插件优先、本地应用兼容、服务注册标准化、组件边界清晰"的结构。
- 当前所有核心能力都已经按组件拆分：`ThinkLibrary` 提供核心层，`System` 提供系统后台、`system_*` 核心能力、存储中心和开发交付工具，`Worker` 提供常驻运行时，业务插件只承载各自业务域。
- 因此这个仓库更适合作为组件化开发基线和业务插件宿主，同时支持本地多应用扩展，而不是传统的单仓单应用模板。

## 架构说明

- **本地应用层**：`app/*` 提供本地多应用能力，`app/index` 为默认本地应用，支持按需扩展其他本地应用
- **核心层**：`ThinkLibrary` 提供运行时、认证、任务契约、菜单节点、模型查询和基础工具。
- **运行层**：`ThinkPlugsWorker` 用 Workerman 托管 `http` 和 `queue` 两类常驻服务。
- **系统层**：`ThinkPlugsSystem` 提供后台壳层、认证权限、系统用户、`system_*` 共享配置、字典、扩展数据、操作日志、存储中心和开发交付命令。
- **业务层**：`ThinkPlugsAccount`、`ThinkPlugsPayment`、`ThinkPlugsWemall`、`ThinkPlugsWuma` 负责各自业务域。
- **交付层**：System 内置 `plugin\system\helper\*` 负责发布、迁移和安装包，`ThinkPlugsStatic` 负责静态资源和项目骨架。

```mermaid
flowchart TD
    L["ThinkLibrary"] --> S["System"]
    L --> W["Worker"]
    S --> W
    S --> SF["System Storage<br/>system_file / upload"]
    S --> HT["System Helper<br/>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
```

## 仓库组成

详细组件说明请参考：[组件详细文档](./docs/components-detail.md)

### 核心组件

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

- **ThinkPlugsStatic** (`zoujingli/think-plugs-static`)
  静态资源和项目骨架组件，提供前端静态文件、模板和项目初始化骨架。
    - 无前缀，通过其他插件间接使用
    - 主要功能：静态资源发布、项目骨架生成
    - 发布内容：配置文件、入口文件、LayUI 前端资源、系统脚本
    - 前端约定：只保留 LayUI 模块加载，移除 RequireJS
    - 许可证：MIT

### 平台插件

- **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 <JWT>`
- 不再使用 Session 或认证 Cookie 承载后台登录态
- 后台壳页首跳允许一次性 `access_key` 引导，后续请求统一落到 `Authorization`
- 用户临时态统一使用基于 Token SID 的 `CacheSession`
- 统一入口为 `tsession()`

统一请求头约定：

- 认证令牌：`Authorization: Bearer <token>`
- 设备接口附加头：`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 <service>` 作为命令签名，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
# 运行代码分析
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
```

测试覆盖包括：

- 架构边界测试（插件依赖、迁移归属、Composer 边界）
- 核心功能测试（JWT、CacheSession、Helper 工具）
- 控制器集成测试（System、Account、Payment、Worker）
- 业务集成测试（支付事件、账号绑定）

## 安装与初始化

```bash
# 安装依赖
composer update --optimize-autoloader

# 显式执行完整安装链路
php think xadmin:install

# 仅发布配置、静态资源和迁移脚本（不执行建表）
php think xadmin:publish

# 可选：强制执行所有已发布迁移
php think xadmin:publish --migrate

# 可选：检查迁移执行状态
php think migrate:status

# 启动 HTTP 服务
php think xadmin:worker start http -d
```

说明：

- `zoujingli/think-plugs-install` 现在是 Composer plugin，`composer install / update / remove / dump-autoload` 完成后会自动执行 `service:discover` 与 `xadmin:publish`。
- 根项目通过 `composer.json > 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 自动安装快照，判断哪些插件需要自动迁移。

默认访问地址：

- `http://127.0.0.1:2346`（可通过 `config/worker.php` 修改端口）

## 常用命令

```bash
# 查看全部命令
php think list

# 启动 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
```

## 发布与迁移

`xadmin:publish` 由 `ThinkPlugsSystem` 内置的 `plugin\system\helper\*` 工具提供，负责：

- 按插件 `composer.json` 中的 `extra.xadmin.publish.copy` 规则同步资源
- 同步各插件 `stc/database` 到根目录 `database/migrations`
- 通过 `vendor/.published.json` 跟踪插件已发布资源，并在插件移除或规则收缩后清理失效产物
- 通过 `database/migrations/.published.json` 清理历史失效或冲突迁移

执行规则：

- `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` 是发布产物，真正执行的也是这里的迁移脚本。

当前约定为：

- 发布规则以 `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` 视为发布产物，不纳入源码维护

## 平台说明

- Windows 兼容
- Linux 兼容
- `Worker reload` 仅适用于 Linux / macOS

## 开发文档

- 官网文档：[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)

## 注意事项

- 本仓库包含会员插件，未授权不得商用
- 插件卸载通常不会自动删除已执行迁移和历史数据
- 自定义前端脚本建议放在 `public/static/extra`

## 许可证

除会员授权插件外，其余组件按各自许可证发布：

- **MIT**: ThinkLibrary, System, WechatClient, Static
- **Apache-2.0**: Worker, Builder, System 内置 Helper 工具
- **专有授权**: Account, Payment, Wemall, Wuma, WechatService

未获得授权的插件（Account/Payment/Wemall/Wuma/WechatService）不得用于商业用途。