# BuildAdmin ThinkPHP → Webman 迁移执行提示词

> 将以下内容作为提示词，指导 AI 或开发者执行从 ThinkPHP 8 到 Webman 的迁移工作。

---

## 一、项目背景

当前项目为 **BuildAdmin**，基于 **ThinkPHP 8.1.4** 开发，包含以下核心特性：

- **多应用**：api、admin、common 三个应用
- **路由**：使用 pathinfo 自动路由，无显式路由文件
- **依赖**：think-orm、think-multi-app、think-throttle、think-migration
- **控制器**：约 32 个，继承链为 BaseController → Api → Backend/Frontend
- **中间件**：AllowCrossDomain、AdminLog、LoadLangPack
- **扩展**：extend/ba 目录、modules 模块化系统

---

## 二、迁移目标

将后端从 ThinkPHP 8（PHP-FPM 模式）迁移至 **Webman**（常驻内存模式），要求：

1. 保持现有 API 接口路径和返回格式不变，确保前端无需改动
2. 业务逻辑、模型、验证器尽量复用
3. 迁移后需通过功能测试验证

---

## 三、执行步骤（按顺序执行）

### 步骤 1：初始化 Webman 项目

1. 在项目根目录同级或指定目录创建 webman 项目：`composer create-project workerman/webman dafuweng-webman`
2. 安装 think-orm：`composer require webman/think-orm`
3. 安装 think-validate（如需）：`composer require topthink/think-validate`
4. 配置 `config/thinkorm.php`，从 `config/database.php` 迁移数据库配置

### 步骤 2：迁移配置文件

1. 将 `config/database.php` 转为 webman 的 `config/thinkorm.php` 格式
2. 将 `config/buildadmin.php`、`config/upload.php`、`config/cache.php` 等迁移至 `config/` 目录
3. 配置 `.env` 支持（webman 需安装 vlucas/phpdotenv 或使用 config 读取）

### 步骤 3：梳理并定义路由

1. 扫描 `app/api/controller/`、`app/admin/controller/` 下所有控制器及方法
2. 根据 ThinkPHP pathinfo 规则（应用/控制器/方法）生成 webman 路由
3. 在 `config/route.php` 中定义，格式示例：
   ```php
   Route::get('/api/index/index', [\app\api\controller\Index::class, 'index']);
   Route::any('/admin/auth/admin/index', [\app\admin\controller\auth\Admin::class, 'index']);
   ```
4. 保持 URL 路径与现有前端调用一致（如 `/api/xxx`、`/admin/xxx`）

### 步骤 4：改造控制器基类

1. 创建 `app/support/BaseController.php`，适配 webman 的 Request 注入
2. 方法签名改为：`public function xxx(Webman\Http\Request $request)`，第一个参数必须为 Request
3. 将 `$this->error()`、`$this->success()` 改为 `return response()->json(...)` 或封装为返回 Response 的方法
4. 移除对 `think\App` 的依赖，用 `$request` 替代 `$this->request`

### 步骤 5：改造 Api 与 Backend 基类

1. `app/common/controller/Api.php`：迁移 `initialize()` 中的数据库检查、ip_check、set_timezone、语言包加载逻辑
2. `app/common/controller/Backend.php`：迁移 Auth 鉴权、权限校验、`Event::trigger('backendInit')` 等逻辑
3. 将 `$this->app->request->controllerPath` 改为从路由或 Request 中获取

### 步骤 6：迁移中间件

1. `AllowCrossDomain`：改写为 webman 中间件格式，在 `config/middleware.php` 中注册
2. `AdminLog`：同上
3. `LoadLangPack`：使用 webman 的国际化插件或自行实现
4. 原控制器中间件逻辑迁移至路由组中间件

### 步骤 7：替换 Facade 与助手函数

1. `Config::get()` → `config('xxx.yyy')` 或 `config_get('xxx', 'yyy')`
2. `Db::` → 使用 think-orm 的 `Db` 类（webman/think-orm 已适配）
3. `Lang::get()` → 使用 webman 的 `__()` 或国际化组件
4. `Event::trigger()`、`Event::listen()` → 使用 webman 事件插件或观察者模式
5. `request()` → 通过方法参数传入 `$request` 或使用 `request()` 助手（需在 webman 中实现）

### 步骤 8：迁移 extend/ba 扩展

1. 将 `extend/ba/` 下类中依赖的 `think\Request`、`think\facade\*` 替换为 webman 兼容实现
2. 保持 `extend/` 的 PSR 自动加载，在 composer.json 或 webman 中配置

### 步骤 9：迁移模块系统

1. `app/common/service/moduleService.php` 中的模块加载逻辑迁移至 webman 的 `config/bootstrap.php` 或进程启动回调
2. 确保 modules 目录下的模块能在 webman 启动时正确加载

### 步骤 10：迁移公共函数

1. `app/common.php` 中的 `get_sys_config`、`get_auth_token`、`full_url`、`ip_check`、`set_timezone` 等
2. 将 `request()` 调用改为接收 `$request` 参数或实现 webman 的 request 助手
3. 将 `config()` 调用改为 webman 的 config 函数

### 步骤 11：入口与部署

1. **入口**：Webman 使用 `php start.php start` 启动，默认端口 8787，无需 `public/index.php`
2. **静态资源**：将原 `public/` 下的 `install/`、`robots.txt` 等复制到 `dafuweng-webman/public/`
3. **Nginx**：root 指向 `public` 目录，`try_files $uri @proxy` 代理动态请求到 8787
4. 详细说明见 [webman部署说明.md](./webman部署说明.md)，Nginx 示例见 [nginx.conf.example](../dafuweng-webman/docs/nginx.conf.example)

---

## 四、注意事项

1. **不要使用类型强制转换**（如 `(int)`、`(string)`），遵循项目规范
2. **保持 API 响应格式**：`{ code, msg, time, data }` 结构不变
3. **Token 鉴权**：`get_auth_token()` 逻辑需完整迁移，支持 header、param、server 多种获取方式
4. **数据权限**：Backend 中的 `dataLimit`、`getDataLimitAdminIds` 等逻辑需保留
5. **异常处理**：配置 webman 的异常处理器，统一返回 JSON 格式错误

---

## 五、验证清单

迁移完成后，请逐项验证：

- [ ] 管理员登录、登出、Token 刷新
- [ ] 后台 CRUD 列表、添加、编辑、删除
- [ ] 权限校验（noNeedLogin、noNeedPermission）
- [ ] 跨域请求正常
- [ ] 上传、配置、语言包加载
- [ ] 前端已编译项目能正常调用所有 API

---

## 六、参考资源

- [Webman 官方文档](https://www.workerman.net/doc/webman/)
- [从 ThinkPHP6 移植到 Webman 的技术经验](https://workerman.net/a/1402)
- [webman/think-orm 使用说明](https://www.workerman.net/doc/webman/db/orm.html)