ulthon_admin/.agents/skills/ulthon-scheme-curd-workflow/SKILL.md

name, description

name	description
ulthon-scheme-curd-workflow	指导使用 Scheme 与 CURD 的标准开发流程。需要新增/调整表结构并生成模块基础代码时调用。

Scheme + CURD 标准工作流

何时调用

• 新增业务表、调整字段、补充索引/注释，并希望保持“代码 <-> 数据库”一致。
• 准备生成控制器/模型/视图等基础 CRUD 代码。

关键原则

• CURD 生成前，Scheme 与数据库表结构必须完全一致，否则会被拒绝。
• 业务 Scheme 代码统一放在 app/admin/scheme/。
• 表结构设计遵循项目数据库规范：表名小写下划线、字段注释完整、避免 ENUM。
• CURD 命令中的 {table} 参数应为不含前缀的下划线格式（例如：数据库表 ul_user_profile 对应的参数为 user_profile）。
• CURD 生成的页面脚本（index.js / add.js / edit.js / read.js / _common.js）默认与视图文件放在同一目录：app/admin/view/<模块路径>/，不提供“输出到其他 JS 目录”的配置项。
• 一旦你开始在生成代码上做业务改造，就应默认“正式目录不可被覆盖”，后续结构变更需要走“临时生成 + 按需合并”。

CURD 命令参数说明

参数	简写	说明
--table	-t	主表名（支持带前缀或不带前缀）
--force	-f	强制覆盖模式（谨慎使用）
--delete	-d	删除模式（删除生成的文件，不是数据库操作）
--runtime	-r	临时生成模式（推荐用于预览）

参数使用建议

1. 首次生成：直接使用 -t 生成到项目目录
2. 已有业务代码：使用 -r 生成到临时目录，对比并手动合并新增字段/逻辑
3. 删除文件：-d 用于清理已生成的文件，不影响数据库

推荐流程

A. 首次生成（代码未做业务改造）

1. 在 app/admin/scheme/ 新建或修改对应表的 Scheme 类。
2. 仅查看差异（不改库），确认当前 Scheme 与 DB 的不一致点：

php think scheme:sync --dry-run

3. 执行同步，将代码结构同步到数据库：

php think scheme:sync

4. 生成 CURD（先生成到临时目录确认更稳妥，{table} 需使用下划线格式）：

php think curd -t {table} -r

5. 确认无误后正式生成：

php think curd -t {table}

也可以直接使用 -f 强制覆盖（首次生成或确认无需保留时）。

B. 以数据库为准

1. 在数据库中创建/修改表结构。
2. 反向生成 Scheme 代码（{table} 需使用下划线格式）：

php think scheme:make -t {table}

3. 再执行 CURD：

php think curd -t {table} -r

已有业务代码时如何安全重新生成（核心能力）

框架的 CURD 机制支持在任何阶段安全地重新生成代码。这是与其他很多系统的关键区别：其他系统要么不推荐重新生成，要么重新生成会直接覆盖已有改动。

场景

你已经基于 CURD 生成的代码做了业务定制（改过控制器逻辑、视图布局、JS 交互等），现在需要新增或调整字段。

错误做法

直接 curd -t {table} -f 强制覆盖 -- 会丢失所有业务改动。

正确做法（临时生成 + 按需合并）

1. 先修改 Scheme 并同步结构（确保 Scheme 与 DB 一致）：

php think scheme:sync

2. 生成到临时目录（不影响正式代码）：

php think curd -t {table} -r

3. 对比临时目录与正式目录的差异，仅将结构性变更按需合并回正式代码：

   • 新增字段对应的列表列、表单项、校验规则
   • 新增字段在模型中的属性声明
   • 其他自动生成的配置（如关联关系、组件类型）

4. 合并后做一次功能自测，重点验证新增字段在新增/编辑/列表/详情中的完整链路。

临时目录位置

使用 -r 参数时，生成的文件会输出到 runtime/curd/ 目录下，按表名组织，可直接与 app/ 下的正式代码对比。

业务定制（生成后必做）

CURD 生成的代码是标准化骨架，实际业务几乎都需要在此基础上调整。所有修改仅在 app/ 目录进行。

生成物说明

一次 CURD 会生成以下文件（路径以 app/admin/ 为基准）：

类型	路径	说明
控制器	controller/<模块路径>.php	列表/新增/编辑/详情/删除等动作
模型	model/<表名>.php	字段定义、关联、获取器等
视图	view/<模块路径>/index.html 等	列表页、新增/编辑/详情页
JS 脚本	view/<模块路径>/index.js 等	与视图同名配对的页面脚本
公共脚本	view/<模块路径>/_common.js	模块级公共逻辑

逐页检查清单

1. 列表页（index）：列展示字段、搜索项、行操作按钮（编辑/删除/详情等）、顶部工具栏按钮（新增等）
2. 新增/编辑页（add/edit）：表单字段、校验规则、默认值、关联数据加载
3. 详情页（read）：展示字段与格式
4. 公共逻辑（_common.js）：模块级事件绑定与共享函数

接口需求

如需让页面同时支持 JSON 输出（供移动端/前端调用），使用"页面/接口同体机制"，详见 ulthon-page-api-dual-mode。

验证与交付

功能验证

用 tools:http:call 在命令行模拟已登录管理员请求，验证增删改查链路：

# 列表
php think tools:http:call --url="/admin/<模块路径>/index" --method=GET
# 新增
php think tools:http:call --url="/admin/<模块路径>/add" --method=POST --data='{"title":"测试"}'
# 编辑
php think tools:http:call --url="/admin/<模块路径>/edit" --method=POST --data='{"id":1,"title":"修改后"}'
# 详情
php think tools:http:call --url="/admin/<模块路径>/read?id=1" --method=GET
# 删除
php think tools:http:call --url="/admin/<模块路径>/delete" --method=POST --data='{"id":1}'

异常时用 php think tools:log:* 追踪，详见 ulthon-tools-http-call。

功能配套

• 菜单：用 admin:menu:* 新增/调整菜单，与页面路径/节点保持一致。详见 ulthon-admin-menu-cli。
• 权限：用 admin:permission:nodes 生成/核对节点，为角色分配节点并为用户分配角色。详见 ulthon-permission-cli。
• 数据库排错：必要时用 tools:db:* 做只读检查，详见 ulthon-db-tools-debug。

交付检查

• 后台页面：列表/表单/详情/删除等核心路径可用
• 命令行验证：增删改查已通过 tools 命令跑通
• 代码规范：按仓库根目录 .php-cs-fixer.php 约束自查
• 菜单与权限：已配置且符合预期

交互提示

• 命令行工具通常支持 --force-force（-ff）跳过交互确认。