# Ulthon Admin 开发规则手册

本文档分为三部分：
1. **通用基础规范**：所有开发者（框架作者与业务开发者）均需遵守的基础准则。
2. **框架开发规则**：针对框架本身的维护者和贡献者。
3. **业务开发规则**：针对使用框架开发具体业务系统的开发者。

---

## 第一部分：通用基础规范
> 适用对象：所有开发者（必须遵守）

### 1. 技术栈标准

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

### 2. 命名与代码规范

所有代码（无论是核心框架还是业务代码）必须严格遵守以下规范：

- **命名规范**: [官方命名规范文档](https://doc.ulthon.com/read/augushong/ulthon_admin/64fbcf8830640/zh-cn/2.x.html)
  - 涵盖：类名、方法名、变量名、目录名等。
- **代码风格**: [官方代码规范文档 (PHP-CS-Fixer)](https://doc.ulthon.com/read/augushong/ulthon_admin/64360c249d66a/zh-cn/2.x.html)
  - 统一使用 PSR 标准，建议配置自动格式化工具。

### 3. 数据库设计规范

- **设计文档**: [官方表结构设计规范](https://doc.ulthon.com/read/augushong/ulthon_admin/619efc9d7af62/zh-cn/2.x.html)
- **核心要求**:
  - 表名小写，使用下划线分隔。
  - 按照前缀、模块、功能的顺序命名，例如：`ul_mall_goods`。
  - 必须为所有字段编写清晰、完整的注释。
  - 严格遵循文档中的字段类型定义。

### 4.在线文档

- **项目文档**: [Ulthon Admin 项目文档](https://doc.ulthon.com/read/augushong/ulthon_admin/home/zh-cn/2.x.html)

---

## 第二部分：框架开发规则
> 适用对象：框架作者、核心贡献者

### 1. 架构设计理念

#### 1.1 双层架构核心
Ulthon Admin 采用独特的双层架构设计，其中 **基础核心层 (`extend/base/`)** 是框架的基石：

- **职责**: 存放系统内置的所有核心功能代码，提供标准化的类和接口。
- **原则**: 保持高度稳定，**严禁依赖具体的业务逻辑**。
- **框架代码写到 `extend/base/` 目录下**。但所有的调用都是从app目录下开始的。即便是纯框架要用到的代码，也是从app目录下开始调用的。
  - 比如base层有一个 AuthServiceBase 类，在app目录下有一个 AuthService 类，它继承了 AuthServiceBase 类。实际调用时，是从app目录下调用 AuthService 类的方法，而不是从base目录下调用 AuthServiceBase 类的方法。
  - 这样做的好处是，业务代码可以根据需要自由扩展和定制，而不会受到框架核心的影响。

### 2. 核心层维护原则

- **稳定性优先**: 核心层的任何修改都必须保证向下兼容。
- **通用性**: 核心代码应具有高度的抽象性，不应包含特定项目的业务逻辑。

---

## 第三部分：业务系统开发规则
> 适用对象：业务功能开发者

### 1. 开发红线与原则

- **核心保护**: 严禁修改 `extend/base/` 目录下的任何文件。
- **业务隔离**: 所有业务逻辑必须放在 `application/` 目录下。

### 2. 扩展机制：继承与重写

当需要修改或扩展框架内置功能（如管理员管理、菜单权限）时，请遵循以下机制：

- **继承**: 业务类继承 `extend/base/` 中的基础类。
- **重写**: 在业务类中重写父类方法，保持方法签名一致。
- **调用父类**: 使用 `parent::methodName()` 复用原有逻辑，或者从父类复制代码重新实现。
- **注意**: 全新开发的业务模块不受此限制，直接在 `application/` 下开发即可。

### 3. 标准开发流程

1. **设计数据库表结构**
   - 严格遵循【第一部分：通用基础规范】中的数据库设计规范。
   - 可以直接在数据库中创建表，也可以使用 Scheme 层代码化创建。

2. **生成基础代码 (CURD)**
   - 使用 `php think curd` 命令生成控制器、模型、视图等。
   - 推荐先生成到临时目录 (`-r`) 确认无误。

3. **业务代码定制**
   - 在生成的代码基础上进行修改。
   - 仅操作 `application/` 目录。

4. **测试与验证**
   - 功能测试、数据完整性检查、代码规范检查。

### 4. 常用开发工具

#### 4.1 代码生成命令 (CURD)
> 文档: [CURD 命令详解](https://doc.ulthon.com/read/augushong/ulthon_admin/curd-command/zh-cn/2.x.html)

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

# 生成到临时目录 (推荐)
php think curd -t test_goods -r

# 强制覆盖
php think curd -t test_goods -f

# 删除生成的 CURD
php think curd -t test_goods -d
```

### 5. 前端开发规范

#### 5.1 文件组织
每个视图 HTML 文件应搭配一个同名的 JS 文件，结构如下：

```text
goods/          
├── add.html    <-- 视图
├── add.js      <-- 对应逻辑
├── index.html  
├── index.js    
└── _common.js  <-- 模块通用逻辑
```

这种结构确保了逻辑与视图的解耦，便于维护。

### 6. Scheme 机制（数据库代码化）

Ulthon Admin 引入了 Scheme 层，实现了数据库结构与 PHP 代码的双向同步，便于版本控制和快速迁移。

#### 6.1 核心概念
- **Code to DB (`scheme:sync`)**: 通过编写 PHP 类定义表结构，自动同步到数据库（支持备份原表）。
- **DB to Code (`scheme:make`)**: 读取现有数据库表结构，反向生成 PHP Scheme 类。

#### 6.2 目录规范
- **业务 Scheme**: `app/admin/scheme/` (所有生成的业务表结构类存放在此)

#### 6.3 常用命令
```bash
# 将数据库表 ul_test_goods 反向生成为 PHP 代码
php think scheme:make -t test_goods

# 将 app/admin/scheme/ 下的代码同步到数据库 (自动备份原表)
php think scheme:sync
```

#### 6.4 标准 CURD 开发工作流
Scheme 机制是 CURD 生成的前置依赖，开发流程如下：

1. **设计表结构**：
   - 方式 A：手动创建/修改数据库表结构。
   - 方式 B：手动编写/修改 `app/admin/scheme/` 下的 Scheme 类。（推荐）

2. **同步结构（确保一致性）**：
   - 若采用方式 A，执行 `php think scheme:make -t {table}` 将变更同步到 Scheme。
   - 若采用方式 B，执行 `php think scheme:sync` 将变更同步到数据库。
   - **注意**：生成 CURD 前，Scheme 与数据库结构必须完全一致，否则会被拒绝。

3. **生成 CURD**：
   - 执行 `php think curd -t {table}` 生成业务代码。