ulthon_admin/CODERULE.md

# Ulthon Admin 项目开发规则

## 1. 框架技术栈

- **核心框架**: ThinkPHP 8.0
- **开发语言**: PHP 8+
- **数据库**: MySQL 8+
- **前端框架**: Layui 2.8.6
- **模板引擎**: ThinkPHP 内置模板引擎
- **代码生成器**: 自定义命令行工具

## 2. 项目架构设计

### 2.1 双层架构设计

Uthon Admin 采用独特的双层架构设计，将系统功能分为核心基础层和业务应用层，便于开发者进行二次开发和功能扩展：

- **基础核心层 (`extend/base/`)**: 
  - 包含系统内置的所有核心功能代码
  - 提供标准化的类和方法接口
  - 不可直接修改，确保系统稳定性
  - 示例：`extend/base/controller/Base.php`、`extend/base/model/BaseModel.php`

- **业务应用层 (`application/`)**: 
  - 基于基础核心层扩展开发的具体业务代码
  - 所有业务类必须继承基础核心层的对应类
  - 开发者可自由修改和扩展，不会影响核心功能
  - 示例：`application/admin/controller/User.php` 继承 `base\controller\Base`
 
### 2.2 继承重写机制

**注意**：继承重写机制主要针对 ulthon-admin 自身的内置功能（如管理员管理、菜单、权限等），用于扩展或修改框架内置功能。

- 对于 ulthon-admin 内置功能，通过继承基础核心类（位于 `extend/base/`），可以获得内置功能并进行扩展
- 需要修改内置功能时，在业务类中重写对应方法，保持方法签名一致
- 支持调用父类方法：`parent::methodName()`

**用户自定义代码**：
- 用户自己的业务代码不需要遵守该继承规则
- 生成的代码直接位于 `application/` 目录下
- 可以直接在 `application/` 目录下进行开发和修改

## 3. 开发流程

### 3.1 标准开发步骤

1. **设计数据库表结构**
   - 按照业务需求设计合理的表结构
   - 必须为所有字段编写清晰、完整的注释
   - 遵循命名规范：表名小写，使用下划线分隔

2. **生成基础代码**
   - 使用内置命令行工具生成代码
   - 支持生成到临时目录，避免覆盖已定制代码
   - 生成内容包括：控制器、模型、视图、验证器、菜单配置

3. **代码定制**
   - 基于生成的代码进行业务定制
   - 仅修改 `application/` 目录下的文件
   - 使用继承重写机制扩展基础功能

4. **测试与验证**
   - 测试所有功能是否正常工作
   - 确保数据完整性和安全性
   - 检查代码规范和性能

### 3.2 代码生成命令

CURD命令大全

ulthon_admin框架以内置快速生成CURD的命令, 包括控制器、视图、模型、JS文件。能够使开发者效率得到进一步提升。

> 备注：在进行CURD命令行之前, 请按照规范设计表结构, 请参考表结构规范模块说明。

**常用命令**
```
# 生成ul_test_goods表的CURD
php think curd -t test_goods

# 生成ul_test_goods表的CURD到临时目录
php think curd -t test_goods -r

# 生成ul_test_goods表的CURD, 文件冲突时强制覆盖
php think curd -t test_goods -f

# 删除ul_test_goods表的CURD
php think curd -t test_goods -d

# 生成ul_test_goods表的CURD, 控制器在目录demo下的Goods.php文件
# 原路径：  `controller\text\Goods.php`，
# 此时路径：`controller\demo\Goods.php`
# 不建议指定该参数
php think curd -t test_goods -c demo/Goods

# 生成ul_test_goods表的CURD, 模型在目录demo下的Goods.php文件
# 原路径：  `model\MallCate.php`
# 此时路径: `model\demo\Goods.php`
# 不建议指定该参数
php think curd -t test_goods -m demo/Goods
```

**参数介绍**

| 短参  |  长参 |说明| 
| ------------ | ------------ | ------|
|  -t |  `--table=VALUE` | 主表名 |
| -c  |  `--controllerFilename=VALUE` | 控制器文件名 |
|-m| `--modelFilename=VALUE` |主表模型文件名|
|-f| `--force`|强制覆盖模式 |
|-d| `--delete`|删除模式 |
|-r |`--runtime`|生成到临时目录|

**官方命令行文档**: [https://doc.ulthon.com/read/augushong/ulthon_admin/619efc929565f/zh-cn/2.x.html](https://doc.ulthon.com/read/augushong/ulthon_admin/619efc929565f/zh-cn/2.x.html)

**CURD 文档地址**: [https://doc.ulthon.com/read/augushong/ulthon_admin/619efc816472e/zh-cn/2.x.html](https://doc.ulthon.com/read/augushong/ulthon_admin/619efc816472e/zh-cn/2.x.html)

### 3.3 表结构设计规范

**官方表结构规范文档**: [https://doc.ulthon.com/read/augushong/ulthon_admin/619efc9d7af62/zh-cn/2.x.html](https://doc.ulthon.com/read/augushong/ulthon_admin/619efc9d7af62/zh-cn/2.x.html)

> 以官方在线文档为准，包含详细的表结构设计规范，包括表名规则、特殊字段、数据类型定义等。

## 4. 命名规范

**官方命名规范文档**: [https://doc.ulthon.com/read/augushong/ulthon_admin/64fbcf8830640/zh-cn/2.x.html](https://doc.ulthon.com/read/augushong/ulthon_admin/64fbcf8830640/zh-cn/2.x.html)

> 以官方在线文档为准，包含详细的命名规范说明。

## 5. 代码规范

**官方代码规范文档**: [https://doc.ulthon.com/read/augushong/ulthon_admin/64360c249d66a/zh-cn/2.x.html](https://doc.ulthon.com/read/augushong/ulthon_admin/64360c249d66a/zh-cn/2.x.html)

> 以官方在线文档为准，包含 PHP-CS-Fixer 配置和详细的代码规范说明。

### 5.1 前端文件组织规范

**视图与JS文件对应规则**：后台的所有视图，每个HTML文件都会搭配一个对应的JS文件，文件结构示例：

```
goods          
├─ add.html    
├─ add.js      
├─ edit.html   
├─ edit.js     
├─ index.html  
├─ index.js    
├─ read.html   
├─ read.js     
└─ _common.js  
```

- 每个功能页面的HTML和JS文件名保持一致
- `_common.js` 用于存放该模块通用的JS代码
- JS文件中应包含对应页面的业务逻辑、事件绑定等
- 这种结构便于维护和扩展，确保前端代码的组织性

## 7. 二次开发注意事项

- 不要修改 `extend/base/` 目录下的任何文件
- 所有业务逻辑都应放在 `application/` 目录下
- 扩展功能时优先考虑继承重写机制
- 保持代码结构清晰，便于维护
- 定期备份代码和数据库
- 遵循版本控制规范，提交信息清晰

---

以上规则是 Ulthon Admin 项目开发的基本规范，所有开发者必须严格遵守。遵循这些规则可以提高代码质量，减少开发成本，便于系统维护和扩展。