docs: 更新框架文档并新增技能说明

2026-07-01 15:32:48 +08:00 · 2026-02-02 21:54:06 +08:00
parent 28267ff1c0
commit 7ee9e102a5
4 changed files with 173 additions and 3 deletions
--- a/.trae/skills/tp-controller-url-rules/SKILL.md
+++ b/.trae/skills/tp-controller-url-rules/SKILL.md
@@ -0,0 +1,52 @@
+---
+name: "tp-controller-url-rules"
+description: "解释 ThinkPHP 8 多级控制器与大驼峰控制器的 URL 访问规则。当用户询问如何访问控制器、URL 报错或需要配置路由时调用。"
+---
+
+# ThinkPHP 8 控制器 URL 访问规则
+
+本 Skill 指导如何在 ThinkPHP 8 框架中正确访问多级控制器以及采用大驼峰命名的控制器和方法。
+
+## 1. 大驼峰命名转换规则
+
+ThinkPHP 8 默认开启了 URL 自动转换（`url_convert`）。大驼峰命名（CamelCase）的控制器和方法在 URL 中会被转换为小写+下划线（snake_case）。
+
+- **控制器类名**：`UserGroup` → URL：`user_group`
+- **操作方法名**：`public function editInfo()` → URL：`edit_info`
+
+**示例：**
+控制器 `app\admin\controller\UserGroup.php` 中的 `editInfo` 方法：
+访问路径：`/admin/user_group/edit_info`
+
+## 2. 多级控制器访问规则
+
+当控制器存放在子目录中时，URL 访问需要使用 `.`（点号）来连接目录名和控制器名。
+
+- **目录结构**：`app/admin/controller/system/Config.php`
+- **访问路径**：`/admin/system.config/index`
+
+**注意：**
+- 子目录名建议使用全小写。
+- 如果子目录名也是大驼峰，同样遵循转换规则（取决于具体配置，但通常建议目录名保持简单）。
+
+## 3. 混合使用示例
+
+结合多级目录和大驼峰命名的复杂情况：
+
+| 控制器文件路径 | 类名 | 方法名 | 对应 URL 路径 |
+| :--- | :--- | :--- | :--- |
+| `controller/Index.php` | `Index` | `index` | `/admin/index/index` |
+| `controller/UserGroup.php` | `UserGroup` | `add` | `/admin/user_group/add` |
+| `controller/system/Admin.php` | `Admin` | `login` | `/admin/system.admin/login` |
+| `controller/mall/GoodsCate.php` | `GoodsCate` | `getList` | `/admin/mall.goods_cate/get_list` |
+
+## 4. 常见问题排查
+
+- **404 错误**：检查是否漏掉了多级控制器的 `.` 分隔符。
+- **大小写敏感**：如果 URL 无法识别下划线，检查 `config/route.php` 中的 `url_convert` 是否被设置为 `false`。
+- **多应用影响**：在多应用模式下，URL 的第一段通常是应用名（如 `admin`），后续才是控制器和方法。
+
+## 5. 开发者建议
+
+- **统一风格**：在代码中使用大驼峰命名类和方法，但在前端请求、模板链接（如 `{:url('...')}`）中建议明确指向转换后的路径或使用系统助手函数自动生成。
+- **路由定义**：对于复杂的 URL，建议在 `route/*.php` 中手动定义路由规则，以提供更友好的访问地址。
--- a/.trae/skills/ulthon-scheme-curd-workflow/SKILL.md
+++ b/.trae/skills/ulthon-scheme-curd-workflow/SKILL.md
@@ -15,6 +15,7 @@ description: "指导使用 Scheme 与 CURD 的标准开发流程。需要新增/
 - CURD 生成前，Scheme 与数据库表结构必须完全一致，否则会被拒绝。
 - 业务 Scheme 代码统一放在 `app/admin/scheme/`。
 - 表结构设计遵循项目数据库规范：表名小写下划线、字段注释完整、避免 ENUM。
+- CURD 命令中的 `{table}` 参数应为**不含前缀的下划线**格式（例如：数据库表 `ul_user_profile` 对应的参数为 `user_profile`）。
 - 一旦你开始在生成代码上做业务改造，就应默认“正式目录不可被覆盖”，后续结构变更需要走“临时生成 + 按需合并”。

 ## 推荐流程
@@ -28,7 +29,7 @@ description: "指导使用 Scheme 与 CURD 的标准开发流程。需要新增/
 php think scheme:sync
 ```

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

 ```bash
 php think curd -t {table} -r
@@ -58,7 +59,7 @@ php think curd -t {table} -r
 ### B. 以数据库为准

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

 ```bash
 php think scheme:make -t {table}
--- a/.trae/skills/ulthon-scheme-definition/SKILL.md
+++ b/.trae/skills/ulthon-scheme-definition/SKILL.md
@@ -0,0 +1,117 @@
+---
+name: "ulthon-scheme-definition"
+description: "指导编写 Ulthon Admin 的 Scheme 架构定义文件。当需要新增表结构、修改字段定义或配置组件显示时调用。"
+---
+
+# Ulthon Scheme 定义指南
+
+本技能指导如何在 `app/admin/scheme/` 目录下编写 Scheme 文件，这些文件定义了数据库表结构以及后台管理界面的组件呈现方式。
+
+参考文档：[表结构-ulthon_admin](https://doc.ulthon.com/read/augushong/ulthon_admin/619efc9d7af62/zh-cn/2.x.html)
+
+## 基本结构
+
+Scheme 文件是一个 PHP 类，继承自 `BaseScheme`，并使用 PHP 8 注解（Attribute）来描述元数据。
+
+```php
+<?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;
+}
+```
+
+## 注解详解
+
+### 1. #[Table] (类注解)
+- `name`: 数据库表名（建议以 `ul_` 开头）。
+- `comment`: 表注释。
+- `engine`: 存储引擎，默认 `InnoDB`。
+- `charset`: 字符集，默认 `utf8mb4`。
+
+### 2. #[Index] (类注解，可重复)
+- `columns`: 索引列，字符串或数组（如 `['cate_id', 'status']`）。
+- `name`: 索引名称。
+- `type`: 索引类型：`NORMAL`, `UNIQUE`, `FULLTEXT`。
+
+### 3. #[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)。
+
+### 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`: 关联表主键（可选）。
+    - `onlyFields`: 列表页显示的字段（可选，用 `|` 分隔）。
+  - `table`: 表格选择器。`options` 需包含：
+    - `table`: 关联表名。
+    - `type`: 选择模式 (`checkbox`/`radio`)。
+    - `valueField`: 值字段名。
+    - `fieldName`: 显示字段名。
+  - `city`: 城市选择器。`options` 需包含：
+    - `level`: 层级 (`province`/`city`/`area`)。
+- `options`: 选项数据。支持索引数组 `['禁用', '启用']` 或关联数组 `['1' => '男', '2' => '女']`，对于 `relation`/`table`/`city` 类型，则是配置参数数组。
+
+## 编写建议
+
+1. **命名规范**: 文件名采用大驼峰（PascalCase），且必须与类名一致。
+2. **基础字段**: 建议所有业务表都包含 `id`, `create_time`, `update_time` 字段。如果需要软删除，增加 `delete_time`。
+   - `create_time`, `update_time`, `delete_time` 建议设置为 `int` 类型，默认 `0`，非空。
+3. **状态表达**: 避免使用 MySQL ENUM 类型。优先使用 `int` 或 `tinyint` 配合 `#[Component(type: 'radio')]` 或 `#[Component(type: 'switch')]`。
+4. **注释约定**: `Field` 的 `comment` 会直接同步到数据库字段注释，同时也作为后台表单的 Label。
+5. **字段后缀约定**: 框架会根据字段名后缀自动推断部分组件类型（若未显式指定 `#[Component]`）：
+   - `image`, `logo`, `photo`, `icon`: 默认为单图片。
+   - `images`, `photos`, `icons`: 默认为多图片。
+   - `file`: 默认为单文件。
+   - `files`: 默认为多文件。
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,7 +15,7 @@

 ## 框架内置能力速查

-本段只保留入口与触发条件，细节以对应技能为准：
+本段只保留入口与触发条件，细节以对应技能为准，包括但不限于以下内容：

 - 扩展内置能力（不改 base）：[ulthon-core-extend-pattern](./.trae/skills/ulthon-core-extend-pattern/SKILL.md)
 - Scheme + CURD 工作流：[ulthon-scheme-curd-workflow](./.trae/skills/ulthon-scheme-curd-workflow/SKILL.md)