ulthon_admin/.agents/skills/ulthon-scheme-definition/SKILL.md

name, description

name	description
ulthon-scheme-definition	指导编写 Ulthon Admin 的 Scheme 文件，定义数据库表结构与后台管理界面组件。涵盖注解方式（scheme:sync：代码 → DB）与字段注释方式（scheme:make：DB → 代码）。

Ulthon Scheme 定义指南

本技能指导如何在 app/admin/scheme/ 目录下编写 Scheme 文件，这些文件定义了数据库表结构以及后台管理界面的组件呈现方式。

参考文档：表结构-ulthon_admin

何时调用

• 新增表结构、修改字段定义或配置后台管理界面组件呈现方式
• 通过字段注释反向生成 Scheme 代码（scheme:make，DB → 代码）
• 通过 Scheme 类正向同步到数据库（scheme:sync，代码 → DB）

Scheme 类基本结构

Scheme 文件是一个 PHP 类，继承自 BaseScheme，并使用 PHP 8 注解（Attribute）来描述元数据。

<?php

namespace app\admin\scheme;

use app\common\scheme\BaseScheme;
use app\common\scheme\attribute\Table;
use app\common\scheme\attribute\Field;
use app\common\scheme\attribute\Component;
use app\common\scheme\attribute\Index;

#[Table(name: 'ul_your_table_name', comment: '表注释')]
#[Index(columns: ['field1'], name: 'idx_field1', type: 'NORMAL')]
class YourClassName extends BaseScheme
{
    #[Field(type: 'int', length: 11, nullable: false, unsigned: true, autoIncrement: true, primary: true)]
    public $id;

    #[Field(type: 'char', length: 100, default: '', comment: '标题')]
    public $title;

    #[Field(type: 'int', length: 11, default: '1', comment: '状态', unsigned: true)]
    #[Component(type: 'radio', options: ['禁用', '启用'])]
    public $status;

    #[Field(type: 'int', length: 11, default: '0', comment: '创建时间', unsigned: true)]
    public $create_time;

    #[Field(type: 'int', length: 11, default: '0', unsigned: true)]
    public $update_time;

    #[Field(type: 'int', length: 11, default: '0', unsigned: true)]
    public $delete_time;
}

注解详解

#[Table] (类注解)

• name: 数据库表名（建议以 ul_ 开头）。
• comment: 表注释。
• engine: 存储引擎，默认 InnoDB。
• charset: 字符集，默认 utf8mb4。

#[Index] (类注解，可重复)

• columns: 索引列，字符串或数组（如 ['cate_id', 'status']）。
• name: 索引名称。
• type: 索引类型：NORMAL, UNIQUE, FULLTEXT。

#[Field] (属性注解)

• type: 字段类型 (e.g., int, bigint, char, varchar, text, decimal, tinyint)。
• length: 长度 (对于 char/varchar/int)。
• precision: 精度 (对于 decimal)。
• scale: 小数位数 (对于 decimal)。
• nullable: 是否允许为空 (bool)。
• default: 默认值 (mixed)。
• comment: 字段注释。
• unsigned: 是否无符号 (bool)。
• autoIncrement: 是否自增 (bool)。
• primary: 是否为主键 (bool)。

#[Component] (属性注解，可选)

定义在后台管理页面中该字段使用的 UI 组件。详见下方「组件类型清单」。

特殊字段约定

字段名	用途	说明
status	默认开关字段	设计建议默认值为 1（启用），添加数据时表单会自动选中"启用"
create_time	创建时间	尽量 NOT NULL，默认值 0（TP 自动填充）
update_time	更新时间	尽量 NOT NULL，默认值 0（TP 自动填充）
delete_time	删除时间	尽量 NOT NULL，默认值 0；存在此字段时模型自动启用软删除，删除标志为 0

字段后缀约定（自动推断组件类型）

字段名以特殊字符结尾时会自动识别为对应类型（若未显式指定 #[Component]）：

后缀	类型
image、logo、photo、icon	单图片
images、photos、icons	多图片
file	单文件
files	多文件

组件类型清单

适用于 #[Component] 注解（scheme:sync：代码 → DB）与数据库字段注释（scheme:make：DB → 代码）两种场景。

类型	说明	是否需要数据集
text	普通文本框（默认，一般不需要写）	否
image	单图片	否
images	多图片（默认分隔符 |）	否
file	单文件	否
files	多文件（默认分隔符 |）	否
date	时间组件	是（datetime / date）
editor	富文本	否
textarea	多行文本	否
select	下拉选择	是
switch	开关组件	是（如 0:关闭,1:开启）
checkbox	多选框	是
radio	单选框	是
relation	关联表下拉选择	是（参数见下）
table	表格选择器	是（参数见下）
city	城市选择器	是（level: province/city/area）

注解方式（推荐，scheme:sync 用）

#[Component(type: 'radio', options: ['1' => '男', '2' => '女'])]
public $gender;

options 支持索引数组 ['禁用', '启用'] 或关联数组 ['1' => '男', '2' => '女']；对于 relation/table/city 类型，则是配置参数数组。

字段注释方式（scheme:make 用）

通过字段注释语法在数据库层声明组件：

名称 {类型} (数据集)

• 类型用 {} 包起来，例如 {radio}
• 数据集用 () 包起来，例如 (1:男, 2:女, 0:未知)
• 数据集索引可用数字或英文单词，不要使用其他字符和空格

示例：性别 {radio} (1:男, 2:女, 0:未知)

关联表（relation）参数

relation 类型用于关联表下拉选择，options 需包含：

参数	说明	备注
table	关联表名	必填
relationBindSelect	表单下拉关联字段	必填
primaryKey	关联表主键	非必填
modelFilename	模型文件	非必填，不建议指定，可自动生成
onlyFields	列表页显示字段	可指定，用 | 分隔。写错键名会导致列表字段配置静默失效。

字段注释完整写法示例：

标签 {relation} (table:tag,relationBindSelect:title,primaryKey:id,onlyFields:title|time_image|username|phone)

table 类型（表格选择器）参数类似，options 需包含：table、type（checkbox/radio）、valueField、fieldName。

编写规范

1. 命名规范：文件名采用大驼峰（PascalCase），且必须与类名一致。
2. 时间字段：统一使用 int 存储 Unix 时间戳，默认 0，非空。不要使用 datetime/timestamp。
3. 软删除：delete_time 字段（int，默认 0）存在时，模型自动启用软删除机制。查询时不要手写 delete_time 条件。
4. 状态表达：避免使用 MySQL ENUM 类型。优先使用 int 或 tinyint 配合 #[Component(type: 'radio')] 或 #[Component(type: 'switch')]。
5. 注释约定：Field 的 comment 会直接同步到数据库字段注释，同时也作为后台表单的 Label。
6. 默认值约定：设计时尽量设置默认值。
7. 分隔符：多图片/多文件类型默认分隔符为竖线 |。