diff --git a/.agents/rules/ulthon-database-design.md b/.agents/rules/ulthon-database-design.md new file mode 100644 index 0000000..440e902 --- /dev/null +++ b/.agents/rules/ulthon-database-design.md @@ -0,0 +1,76 @@ +# 表结构设计规范 + +## 特殊字段 + +| 字段名 | 用途 | 说明 | +|--------|------|------| +| `status` | 默认开关字段 | - | +| `create_time` | 创建时间 | 尽量 NOT NULL，默认值 0（TP 会自动填充） | +| `update_time` | 更新时间 | 尽量 NOT NULL，默认值 0（TP 会自动填充） | +| `delete_time` | 删除时间 | 尽量 NOT NULL，默认值 0；CURD 默认开启软删除，删除标志为 0 | + +## 字段后缀约定 + +以特殊字符结尾的字段会自动识别为对应类型： + +| 后缀 | 类型 | +|------|------| +| `image`、`logo`、`photo`、`icon` | 单图片 | +| `images`、`photos`、`icons` | 多图片 | +| `file` | 单文件 | +| `files` | 多文件 | + +## 注释语法 + +字段注释支持通过特殊格式定义表单类型和数据集： + +``` +名称 {类型} (数据集) +``` + +- **类型**：用 `{}` 包起来，例如 `{radio}` +- **数据集**：用 `()` 包起来，例如 `(1:男, 2:女, 0:未知)` +- 数据集索引可以用数字或英文单词，不要使用其他字符和空格 + +示例：`性别 {radio} (1:男, 2:女, 0:未知)` + +## 类型大全 + +| 类型 | 说明 | 是否需要数据集 | 注释案例 | +|------|------|----------------|----------| +| text | 普通文本框 | 否 | `店铺名称 {text}`（一般不需要写 text） | +| image | 单图片 | 否 | `店铺logo {image}` | +| images | 多图片 | 否 | `店铺环境 {images}`，分隔符默认为竖线 | +| file | 单文件 | 否 | `演示资料 {file}` | +| files | 多文件 | 否 | `演示资料 {files}`，默认分隔符为竖线 | +| date | 时间组件 | 是 | `生日 {date} (datetime)` | +| editor | 富文本 | 否 | `店铺详情 {editor}` | +| textarea | 多行文本 | 否 | `店铺简介 {textarea}` | +| select | 下拉选择 | 是 | `版本 {select} (trial:免费版,office:正式版)` | +| switch | 开关组件 | 是 | `状态 {switch} (0:关闭,1:开启)` | +| checkbox | 多选框 | 是 | `功能权限 {checkbox} (mall:商城,blog:博客)` | +| radio | 单选框 | 是 | `状态 {radio} (0:未审核,1:审核中)` | +| relation | 关联表 | 是（格式见下） | `标签 {relation} (table:tag,relationBindSelect:title)` | +| table | 表格选择器 | 是（格式见下） | `商品标签 {table} (table:mall_tag,type:checkbox,valueField:id,fieldName:title)` | +| city | 城市选择器 | 是 | `仓库 {city} (level:city)` | + +## 关联表注释参数 + +| 参数 | 说明 | 备注 | +|------|------|------| +| `table` | 关联表名 | 必填 | +| `primaryKey` | 关联表主键 | 非必填 | +| `modelFilename` | 模型文件 | 非必填，不建议指定，可自动生成 | +| `onlyFileds` | 列表页显示字段 | 可指定，用竖线分割 | +| `relationBindSelect` | 表单下拉关联字段 | 必填 | + +完整写法示例： + +``` +标签 {relation} (table:tag,relationBindSelect:title,primaryKey:id,onlyFileds:title|titme_image|username|phone) +``` + +## 其他细节 + +- 设计时尽量设置默认值。例如 `status` 默认值为 1，添加数据时表单会自动将 radio 选中"1:启用" +- 分隔符默认为竖线 `|` diff --git a/.agents/rules/ulthon-naming-convention.md b/.agents/rules/ulthon-naming-convention.md new file mode 100644 index 0000000..2a16bdb --- /dev/null +++ b/.agents/rules/ulthon-naming-convention.md @@ -0,0 +1,13 @@ +# 命名规范 + +## 目录命名 + +- 一个单词的目录用小写，例如 `service/` +- 多个单词的目录用大驼峰，例如 `AdminService/`、`UserService/` + +## PHP 文件命名 + +- `app/common` 目录下已有单独的规范说明（见 `ulthon-source-directory.md`） +- 其他各应用目录下： + - **service 模块**需要写后缀，例如 `AdminService`，而不是 `admin` + - **除了 service 模块**，其他文件不需要写后缀，不论是 controller、model、traits、config、middleware 等 diff --git a/AGENTS.md b/AGENTS.md index fd88095..7e9513a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,10 +16,10 @@ ### 通用基础规范（所有开发者必须遵守） - 技术栈：ThinkPHP 8.x；PHP 8+；MySQL 8+；Layui 2.x；模板引擎：ThinkPHP 内置模板引擎 -- 命名规范（必读）： -- 代码风格（必读，遵循 `.php-cs-fixer.php`）： -- 表结构设计规范（必读）： -- 项目文档主页： +- 命名规范（必读）：[ulthon-naming-convention.md](./.agents/rules/ulthon-naming-convention.md) +- 代码风格（必读）：遵循项目根目录 `.php-cs-fixer.php` +- 表结构设计规范（必读）：[ulthon-database-design.md](./.agents/rules/ulthon-database-design.md) +- 项目文档主页（在线）： ### 代码分层铁律（不可协商） @@ -81,6 +81,8 @@ | 规则文件 | 作用域 | 说明 | |---------|--------|------| +| [ulthon-naming-convention.md](./.agents/rules/ulthon-naming-convention.md) | 命名规范 | 目录命名与 PHP 文件命名约定 | +| [ulthon-database-design.md](./.agents/rules/ulthon-database-design.md) | 数据库设计 | 表结构设计：特殊字段、字段后缀、注释语法、类型大全 | | [ulthon-controller-url.md](./.agents/rules/ulthon-controller-url.md) | 控制器路由 | URL 与控制器/方法的映射规则 | | [ulthon-deploy-environment.md](./.agents/rules/ulthon-deploy-environment.md) | 部署与命令执行 | 部署栈模式与 Docker/宿主机命令判断 | | [ulthon-source-directory.md](./.agents/rules/ulthon-source-directory.md) | source/ 目录 | 子项目/多端代码的目录约定与安全要求 |