第一个业务模块
本例从建表到打开 Admin 列表,演示「业务工单」模块。所有写操作在独立开发环境完成;生产部署接收经验证的源码与构建产物。
1. 建表与开发开关
使用 mysql --default-character-set=utf8mb4 -u USER -p DATABASE 连接开发库,执行下面 SQL。USER / DATABASE 替换为实际值;如果配置了 DB_PREFIX,物理表名也需加上前缀。
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. 预览并生成
从项目根执行:
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。仅首次导入,不要重复执行。
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 buildDocker 请用 容器生成后流程 中的命令,不能把宿主机 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 并重启服务。继续修改表结构或升级模板时,使用 增量更新,不要删除文件再生成。