Skip to content

第一个业务模块 ​

本例从建表到打开 Admin 列表,演示「业务工单」模块。所有写操作在独立开发环境完成;生产部署接收经验证的源码与构建产物。

1. 建表与开发开关 ​

使用 mysql --default-character-set=utf8mb4 -u USER -p DATABASE 连接开发库,执行下面 SQL。USER / DATABASE 替换为实际值;如果配置了 DB_PREFIX,物理表名也需加上前缀。

sql
SET NAMES utf8mb4;
CREATE TABLE `biz_tickets` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `title` varchar(200) NOT NULL COMMENT '工单标题',
  `content` text NULL COMMENT '工单内容',
  `status` tinyint NOT NULL DEFAULT 1 COMMENT '状态',
  `created_by` int unsigned NULL COMMENT '创建人',
  `created_at` datetime NULL,
  `updated_at` datetime NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='业务工单';

设置 server/.env 的 APP_DEBUG=true。手动部署在 server/ 执行 php start.php restart;Docker 在项目根执行 docker compose -f docker/docker-compose.yml restart webman。这是真实功能开关;只 reload 不代替环境配置重启。

2. 预览并生成 ​

从项目根执行:

bash
cd server
php webman make:crud biz_tickets --module=biz --model=BizTicket --comment="业务工单" --preview
php webman make:crud biz_tickets --module=biz --model=BizTicket --comment="业务工单"
cd ..

模块名 biz 为独立业务分组,模型名为 BizTicket。system、article、business 等是保留名,完整名单见 代码生成器。

生成共 11 个文件:后端分层与资源类、中英文语言包、Admin API/列表/表单、菜单 SQL。只生成后端和 Admin;不会自动执行 SQL 或 build。

3. 菜单、路由与前端构建 ​

以下仍在项目根执行,先审核 SQL;需要挂到已有目录时先调整 parent_id。仅首次导入,不要重复执行。

bash
mysql --default-character-set=utf8mb4 -u USER -p DATABASE < server/database/generated/biz-biz_ticket-menu.sql
(cd server && php start.php reload)
pnpm --dir admin build

Docker 请用 容器生成后流程 中的命令,不能把宿主机 PHP reload 当作容器 reload。pnpm build 在宿主机或 CI 执行,把新页面编译至 server/public/admin/;只修改源码不会改变当前静态后台。

4. 授权与验收 ​

菜单导入后,超管拥有 * 权限,重新登录即能看到菜单;普通角色需在角色管理中勾选该菜单和新增、编辑、删除、状态按钮,然后重新登录。前端权限和服务端权限都需要具备。

页面使用 history 地址 /admin/biz/biz-ticket,不加 #。确认列表、按标题筛选、新增、详情、编辑、状态切换、删除与批量删除均正常;对应 API 前缀为 /adminapi/biz/biz-ticket。

  • 菜单不见:检查 SQL、角色授权、菜单状态、重新登录。
  • 页面 404:检查 Admin build 及菜单 component=biz/biz-ticket/index。
  • API 404:检查运行中的 Webman 是否 reload。
  • 中文乱码:检查客户端 utf8mb4 和原始 COMMENT,修复后还需更新已经生成的标签。

完成开发后恢复 APP_DEBUG=false 并重启服务。继续修改表结构或升级模板时,使用 增量更新,不要删除文件再生成。

基于 MIT 许可发布