ulthon_admin/CODERULE.md

Ulthon Admin 开发规则手册

本文档分为三部分：

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

---

第一部分：通用基础规范

适用对象：所有开发者（必须遵守）

1. 技术栈标准

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

2. 命名与代码规范

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

• 命名规范: 官方命名规范文档
  • 涵盖：类名、方法名、变量名、目录名等。
• 代码风格: 官方代码规范文档 (PHP-CS-Fixer)
  • 统一使用 PSR 标准，建议配置自动格式化工具。

3. 数据库设计规范

• 设计文档: 官方表结构设计规范
• 核心要求:
  • 表名小写，使用下划线分隔。
  • 按照前缀、模块、功能的顺序命名，例如：ul_mall_goods。
  • 必须为所有字段编写清晰、完整的注释。
  • 严格遵循文档中的字段类型定义。

4.在线文档

• 项目文档: Ulthon Admin 项目文档

---

第二部分：框架开发规则

适用对象：框架作者、核心贡献者

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 命令详解

常用命令示例:

# 生成表 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 文件，结构如下：

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 常用命令

# 将数据库表 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} 生成业务代码。