mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-09-05 07:15:31 +08:00
docs(agents): 落实按主题单一文档原则，合并规则到对应技能
- AGENTS.md 代码分层铁律精简为入口摘要，链接指向技能详情 - 合并 ulthon-timer-multi-node 规则到 ulthon-timer 技能（多节点协调章节） - 合并 ulthon-database-design 规则到 ulthon-scheme-definition 技能（含字段约定、组件类型） - 合并 ulthon-testing 规则到 ulthon-testing 技能（含设计哲学、决策树、测试约束） - rules-manager 边界原则从规则/技能二分改为按主题单一文档 - AGENTS.md 通用基础规范中表结构规范链接改向技能 - 工作流索引中三个技能描述扩充（明确承载原规则内容）
This commit is contained in:
augushong
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: "ulthon-scheme-definition"
|
||||
description: "指导编写 Ulthon Admin 的 Scheme 架构定义文件。当需要新增表结构、修改字段定义或配置组件显示时调用。"
|
||||
description: "指导编写 Ulthon Admin 的 Scheme 文件，定义数据库表结构与后台管理界面组件。涵盖注解方式（scheme:sync：代码 → DB）与字段注释方式（scheme:make：DB → 代码）。"
|
||||
---
|
||||
|
||||
# Ulthon Scheme 定义指南
|
||||
@@ -9,7 +9,13 @@ description: "指导编写 Ulthon Admin 的 Scheme 架构定义文件。当需
|
||||
|
||||
参考文档：[表结构-ulthon_admin](https://doc.ulthon.com/read/augushong/ulthon_admin/619efc9d7af62/zh-cn/2.x.html)
|
||||
|
||||
## 基本结构
|
||||
## 何时调用
|
||||
|
||||
- 新增表结构、修改字段定义或配置后台管理界面组件呈现方式
|
||||
- 通过字段注释反向生成 Scheme 代码（`scheme:make`，DB → 代码）
|
||||
- 通过 Scheme 类正向同步到数据库（`scheme:sync`，代码 → DB）
|
||||
|
||||
## Scheme 类基本结构
|
||||
|
||||
Scheme 文件是一个 PHP 类，继承自 `BaseScheme`，并使用 PHP 8 注解（Attribute）来描述元数据。
|
||||
|
||||
@@ -51,18 +57,18 @@ class YourClassName extends BaseScheme
|
||||
|
||||
## 注解详解
|
||||
|
||||
### 1. #[Table] (类注解)
|
||||
### #[Table] (类注解)
|
||||
- `name`: 数据库表名（建议以 `ul_` 开头）。
|
||||
- `comment`: 表注释。
|
||||
- `engine`: 存储引擎，默认 `InnoDB`。
|
||||
- `charset`: 字符集，默认 `utf8mb4`。
|
||||
|
||||
### 2. #[Index] (类注解，可重复)
|
||||
### #[Index] (类注解，可重复)
|
||||
- `columns`: 索引列，字符串或数组（如 `['cate_id', 'status']`）。
|
||||
- `name`: 索引名称。
|
||||
- `type`: 索引类型：`NORMAL`, `UNIQUE`, `FULLTEXT`。
|
||||
|
||||
### 3. #[Field] (属性注解)
|
||||
### #[Field] (属性注解)
|
||||
- `type`: 字段类型 (e.g., `int`, `bigint`, `char`, `varchar`, `text`, `decimal`, `tinyint`)。
|
||||
- `length`: 长度 (对于 char/varchar/int)。
|
||||
- `precision`: 精度 (对于 decimal)。
|
||||
@@ -74,45 +80,100 @@ class YourClassName extends BaseScheme
|
||||
- `autoIncrement`: 是否自增 (bool)。
|
||||
- `primary`: 是否为主键 (bool)。
|
||||
|
||||
### 4. #[Component] (属性注解，可选)
|
||||
定义在后台管理页面中该字段使用的 UI 组件。
|
||||
- `type`: 组件类型。常用值：
|
||||
- `text`: 普通文本框（默认）。
|
||||
- `image`: 单图片上传。
|
||||
- `images`: 多图片上传（默认分隔符为 `|`）。
|
||||
- `file`: 单文件上传。
|
||||
- `files`: 多文件上传（默认分隔符为 `|`）。
|
||||
- `date`: 时间/日期组件。需配合 `options` 指定格式，如 `datetime` 或 `date`。
|
||||
- `editor`: 富文本编辑器。
|
||||
- `textarea`: 文本域。
|
||||
- `select`: 下拉选择框（需配合 `options`）。
|
||||
- `switch`: 开关组件（需配合 `options`，如 `['0' => '关闭', '1' => '开启']`）。
|
||||
- `checkbox`: 复选框（需配合 `options`）。
|
||||
- `radio`: 单选框（需配合 `options`）。
|
||||
- `relation`: 关联表下拉选择。`options` 需包含：
|
||||
- `table`: 关联表名。
|
||||
- `relationBindSelect`: 显示的字段名。
|
||||
- `primaryKey`: 关联表主键（可选）。
|
||||
- `onlyFileds`: 列表页显示的字段（可选，用 `|` 分隔）。**注意：键名是 `onlyFileds`（而非 `onlyFields`），需与 `extend/base/common/command/CurdBase.php` 解析逻辑保持一致；写错键名会导致列表字段配置静默失效。**
|
||||
- `table`: 表格选择器。`options` 需包含：
|
||||
- `table`: 关联表名。
|
||||
- `type`: 选择模式 (`checkbox`/`radio`)。
|
||||
- `valueField`: 值字段名。
|
||||
- `fieldName`: 显示字段名。
|
||||
- `city`: 城市选择器。`options` 需包含：
|
||||
- `level`: 层级 (`province`/`city`/`area`)。
|
||||
- `options`: 选项数据。支持索引数组 `['禁用', '启用']` 或关联数组 `['1' => '男', '2' => '女']`，对于 `relation`/`table`/`city` 类型，则是配置参数数组。
|
||||
### #[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` 用）
|
||||
|
||||
```php
|
||||
#[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. **字段后缀约定**: 框架会根据字段名后缀自动推断部分组件类型（若未显式指定 `#[Component]`）：
|
||||
- `image`, `logo`, `photo`, `icon`: 默认为单图片。
|
||||
- `images`, `photos`, `icons`: 默认为多图片。
|
||||
- `file`: 默认为单文件。
|
||||
- `files`: 默认为多文件。
|
||||
|
||||
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. **分隔符**：多图片/多文件类型默认分隔符为竖线 `|`。
|
||||
|
||||
Reference in New Issue
Block a user