dafuweng-buildadmin/docs/webman迁移执行提示词.md

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 中定义，格式示例：

   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，Nginx 示例见 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 官方文档
• 从 ThinkPHP6 移植到 Webman 的技术经验
• webman/think-orm 使用说明