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/ 目录下的任何文件。
• 业务隔离: 所有业务逻辑必须放在 app/ 目录下。

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

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

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

3. 标准开发流程

1. 设计/调整表结构

   • 严格遵循【第一部分：通用基础规范】中的数据库设计规范。
   • 优先通过 Scheme 机制在 app/admin/scheme/ 代码化维护表结构。

2. 同步并确保一致

   • 以代码为准：scheme:sync
   • 以数据库为准：scheme:make -t {table}
   • 注意：生成 CURD 前，Scheme 与数据库结构必须完全一致，否则会被拒绝。

3. 生成基础代码（CURD）

   • 推荐先生成到临时目录确认：php think curd -t {table} -r
   • 确认无误后再正式生成/覆盖：php think curd -t {table} / php think curd -t {table} -f

4. 业务代码定制

   • 在生成代码基础上进行修改，仅操作 app/ 目录。

5. 测试与验证

   • 功能测试、数据完整性检查、代码规范检查（遵循项目 PHP-CS-Fixer 配置）。

4. 常用开发工具

4.1 代码生成命令 (CURD)

文档: CURD 命令详解

更完整的命令组合与参数说明，优先以在线文档为准；仓库内的工作流摘要可参考 .trae/skills/ulthon-scheme-curd-workflow/。

5. 前端开发规范

5.1 文件组织

每个视图 HTML 文件应搭配一个同名的 JS 文件，并按模块维护 _common.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 参考资料

• 标准工作流摘要：.trae/skills/ulthon-scheme-curd-workflow/SKILL.md