ulthon/ulthon_admin
1
0
Fork 0
mirror of https://gitee.com/ulthon/ulthon_admin.git synced 2026-07-01 15:32:48 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: 重构项目规则与技能文档结构并更新开发指南

Browse Source
This commit is contained in:
augushong
2026-02-01 13:13:03 +08:00
parent 180d9291a3
commit 28267ff1c0
8 changed files with 272 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
.trae/rules/project_rules.md Normal file
View File

@@ -0,0 +1,28 @@
## Ulthon Admin（ThinkPHP 8）项目级规则（Agent 必须遵守）
### 核心红线
- 严禁修改 `extend/base/` 下任何文件。
- 所有业务逻辑必须放在 `app/` 下（优先 `app/admin/`），通过继承与重写扩展框架能力。
- 即使是框架层能力，也必须从 `app/` 下入口类调用（业务类继承 base 层基础类），不得直接从 `extend/base/` 调用。
### 环境与配置
- 不自行安装/变更基础环境（Docker、MySQL、Redis 等），除非用户明确要求。
- 不修改环境配置文件（如 `.env`）；发现配置缺失或不合理时，仅提示需要由开发者补齐。
- 不主动启动或常驻运行项目（由开发者提前运行以便调试）；仅在用户明确要求时执行相关命令。
### 数据库与结构
- 设计表结构优先采用 Scheme 机制（`app/admin/scheme/`），确保 Code 与 DB 一致后再生成 CURD。
- 一般不要使用枚举类型（ENUM）；优先使用 `tinyint/int` + 注释/字典表等方式表达状态。
- 调试数据库数据可以使用内置 tools:db 命令，但不要用它来“设计表结构”（临时调试改动需注意还原）。
### 前端与视图组织
- 遵循视图与脚本同名配对：每个视图 `*.html` 配套同名 `*.js`，并按模块维护 `_common.js`。
### 代码风格与命名
- 严格遵循项目命名规范与 PSR 风格；需要格式化时以仓库根目录的 `.php-cs-fixer.php` 配置为准（不假设本机已安装相关工具）。

28
.trae/skills/ulthon-auth-session-token/SKILL.md Normal file
View File

@@ -0,0 +1,28 @@
---
name: "ulthon-auth-session-token"
description: "解释并指导 Session+Token 登录认证的使用方式。需要实现接口鉴权或联调移动端请求时调用。"
---
# 登录认证（Session + Token）
## 何时调用
- 编写/联调需要登录态的接口。
- 需要在非浏览器环境（移动端、小程序、跨域脚本）调用后台接口。
## 机制概览
- Session：主要用于浏览器环境，依赖 Cookie。
- Token：用于接口与无 Cookie 场景，通过 Header 传递完成认证。
## 使用方式
1. 登录成功后，接口会返回 `token` 数据。
2. 后续请求在 Header 携带：
```text
Authorization: Bearer <token>
```
3. 系统会自动识别并完成身份认证。

33
.trae/skills/ulthon-core-extend-pattern/SKILL.md Normal file
View File

@@ -0,0 +1,33 @@
---
name: "ulthon-core-extend-pattern"
description: "指导如何在不修改 extend/base 的前提下扩展功能。需要新增/改造框架内置能力（权限、菜单、管理员等）时调用。"
---
# 核心层扩展模式（继承与重写）
## 何时调用
- 需要修改或扩展框架内置模块（如管理员、菜单、权限、上传等）行为。
- 看到代码位于 `extend/base/`，但业务需要调整其逻辑或返回数据。
## 必须遵守
- 不修改 `extend/base/` 下任何文件。
- 业务实现放在 `app/` 下，并通过继承覆盖 base 层实现。
- 所有调用从 `app/` 下入口类开始，不直接 new/调用 `extend/base/` 类。
## 推荐做法
1. 在 `extend/base/` 找到对应基础类（通常以 `*Base.php` 结尾）。
2. 在 `app/` 下找到或创建同职责的业务类（不带 Base 后缀），让其继承基础类。
3. 在业务类中重写需要变更的方法：
- 方法签名保持一致
- 能复用就 `parent::methodName()`，必要时复制父类逻辑后改造
4. 保持对外调用点不变：控制器/服务统一调用 `app/` 下的类。
## 示例定位思路
- 控制器：`extend/base/admin/controller/*/*Base.php` ↔ `app/admin/controller/*/*.php`
- 模型：`extend/base/admin/model/*Base.php` ↔ `app/admin/model/*.php`
- 服务：`extend/base/admin/service/*Base.php` ↔ `app/admin/service/*.php`

35
.trae/skills/ulthon-db-tools-debug/SKILL.md Normal file
View File

@@ -0,0 +1,35 @@
---
name: "ulthon-db-tools-debug"
description: "封装 tools:db 命令的使用方法。需要快速查询/执行 SQL 或查看表信息进行调试时调用。"
---
# 内置数据库调试命令（tools:db）
## 何时调用
- 需要快速查看数据、验证 SQL、检查表结构（字段/索引/行数）用于排错。
- 需要在不写临时代码的情况下做一次性查询或数据检查。
## 必须注意
- 这些命令用于“调试数据”，不要用来“设计表结构”。
- 如果为了排错临时改了表结构或数据，需要在任务结束前确保影响可控并记录变更点。
## 常用命令
```bash
php think tools:db:query
php think tools:db:execute
php think tools:db:table
php think tools:db:count
php think tools:db:info
php think tools:db:desc
```
通过 `--help` 查看每个命令参数说明。
## 使用建议
- 优先用 `query/desc/info/table/count` 做只读检查。
- 需要变更数据时再用 `execute`，并尽量将变更限制在最小范围。

32
.trae/skills/ulthon-page-api-dual-mode/SKILL.md Normal file
View File

@@ -0,0 +1,32 @@
---
name: "ulthon-page-api-dual-mode"
description: "指导控制器实现“页面/接口同体”。需要同一路由同时返回 HTML 与 JSON 时调用。"
---
# 页面 / 接口同体（Controller Dual Mode）
## 何时调用
- 希望同一个控制器方法既能渲染页面（HTML），也能作为接口返回 JSON。
- 需要让现有页面接口在移动端/脚本调用时返回结构化数据。
## 触发与认证
- 触发：请求头 `Accept` 包含 `application/json`。
- 认证：Header 传 `Authorization: Bearer <tokenContent>`。
## 实现要点
- 控制器方法必须调用 `$this->fetch()`，不要使用 `View::fetch()`。
- 无论使用 `$this->assign()` 还是 `View::assign()`，其数据都会被转换为 JSON 返回。
- 若不希望某个 assign 字段出现在 JSON 中，可使用：
```php
$this->assign('name', 'value', -1);
```
## 特殊行为
- `index` 方法 GET 默认返回分页数据；如果需要返回 assign 数据，URL 增加参数 `get_page_data=1`。
- 仅在控制器模式（Controller Mode）生效；路由模式（Route Mode）不生效。

75
.trae/skills/ulthon-scheme-curd-workflow/SKILL.md Normal file
View File

@@ -0,0 +1,75 @@
---
name: "ulthon-scheme-curd-workflow"
description: "指导使用 Scheme 与 CURD 的标准开发流程。需要新增/调整表结构并生成模块基础代码时调用。"
---
# Scheme + CURD 标准工作流
## 何时调用
- 新增业务表、调整字段、补充索引/注释，并希望保持“代码 <-> 数据库”一致。
- 准备生成控制器/模型/视图等基础 CRUD 代码。
## 关键原则
- CURD 生成前，Scheme 与数据库表结构必须完全一致，否则会被拒绝。
- 业务 Scheme 代码统一放在 `app/admin/scheme/`。
- 表结构设计遵循项目数据库规范：表名小写下划线、字段注释完整、避免 ENUM。
- 一旦你开始在生成代码上做业务改造，就应默认“正式目录不可被覆盖”，后续结构变更需要走“临时生成 + 按需合并”。
## 推荐流程
### A. 以代码为准（推荐）
1. 在 `app/admin/scheme/` 新建或修改对应表的 Scheme 类。
2. 执行同步，将代码结构同步到数据库：
```bash
php think scheme:sync
```
3. 生成 CURD（先生成到临时目录确认更稳妥）：
```bash
php think curd -t {table} -r
```
4. 初次接入（代码还未做业务改造）可选择正式生成或覆盖：
```bash
php think curd -t {table}
php think curd -t {table} -f
```
### A2. 已经做过业务改造时的推荐做法（临时生成 + 按需合并）
适用场景：你已经修改过 CURD 生成的控制器/模型/视图/JS 等代码，此时再次 `-f` 覆盖会丢失业务改动。
1. 先完成结构同步（`scheme:sync` 或 `scheme:make`），确保与数据库一致。
2. 始终生成到临时目录：
```bash
php think curd -t {table} -r
```
3. 对比临时目录与正式目录的差异，仅把“新增字段/新增校验/新增表单项/新增列表列”等结构性变更按需合并回正式代码。
4. 合并后再做一次功能自测，重点验证新增字段的新增/编辑/列表/详情与校验链路。
### B. 以数据库为准
1. 在数据库中创建/修改表结构。
2. 反向生成 Scheme 代码：
```bash
php think scheme:make -t {table}
```
3. 再执行 CURD：
```bash
php think curd -t {table} -r
```
## 交互提示
- 命令行工具通常支持 `--force-force`（`-ff`）跳过交互确认。

77
AGENTS.md
View File

@@ -1,63 +1,26 @@
## Agent 工作约束（Ulthon Admin）
本仓库的开发规范以两类信息为准：
1. **规则（必须始终遵守）**：见 [.trae/rules/project_rules.md](./.trae/rules/project_rules.md) 与 [CODERULE.md](./CODERULE.md)。
2. **技能（按场景调用的工作流）**：见 `.trae/skills/*/SKILL.md`。
在线文档（参考）：https://doc.ulthon.com/read/augushong/ulthon_admin/home/zh-cn/2.x.html
## 不应该做的事情
1. 一般而言你不需要直接修改开发环境，除了安装composer依赖或其他开发相关的资源。但你不应该自己安装docker、mysql、redis等基础环境，这些由开发者提前维护好。
2. 一般而言你不需要修改环境配置文件（如 `.env`），这些由开发者提前维护好，如果你发现错误应当提示开发者完善相关的配置。
3. 你不需要自己运行项目程序，开发者会提前运行好，以便你直接在开发过程中调试。
1. 一般不需要直接修改开发环境（除非安装 composer 依赖或开发相关资源）。不要自行安装 Docker、MySQL、Redis 等基础环境，这些由开发者维护。
2. 一般不需要修改环境配置文件（如 `.env`）。发现配置缺失或错误时，应提示开发者完善相关配置。
3. 一般不需要自行启动或常驻运行项目程序（开发者会提前运行以便调试）；除非用户明确要求执行运行/调试命令。
## 框架内置能力速查
## 需要遵守的规则
本段只保留入口与触发条件，细节以对应技能为准：
基本规则参考 [CODERULE.md](./CODERULE.md);
更多规则参考在线文档 https://doc.ulthon.com/read/augushong/ulthon_admin/home/zh-cn/2.x.html
- 扩展内置能力（不改 base）：[ulthon-core-extend-pattern](./.trae/skills/ulthon-core-extend-pattern/SKILL.md)
- Scheme + CURD 工作流：[ulthon-scheme-curd-workflow](./.trae/skills/ulthon-scheme-curd-workflow/SKILL.md)
- 数据库调试命令（tools:db）：[ulthon-db-tools-debug](./.trae/skills/ulthon-db-tools-debug/SKILL.md)
- 页面 / 接口同体（同一控制器 HTML+JSON）：[ulthon-page-api-dual-mode](./.trae/skills/ulthon-page-api-dual-mode/SKILL.md)
- 登录认证（Session + Token）：[ulthon-auth-session-token](./.trae/skills/ulthon-auth-session-token/SKILL.md)
## 框架工具
### 数据库操作
项目内置了数据库操作工具，可以直接在命令行中执行数据库操作。命令是：
```bash
php think tools:db:execute
php think tools:db:query
php think tools:db:table
php think tools:db:count
php think tools:db:info
php think tools:db:desc
```
通过 --help 可以查看每个命令的详细说明。
该功能的作用是快捷调试数据库的数据，不要通过这个方式设计表结构，（临时调试修改表结构等可以使用，但要注意还原，关于表结构设计有专门的方案规范）。
### 命令行交互
所有命令行工具均支持使用 `--force-force` (简写 `-ff`) 全局参数来跳过交互确认。
### 理解和设计表结构
项目内置SCHEME机制，参考 [CODERULE.md](./CODEGUIDE.md)的 Scheme 机制 部分。通过scheme可以获得所有表结构，也可以用于设计数据库结构。
### 开发流程
项目内置CURD机制，基本流程在[CODERULE.md](./CODERULE.md)的 CURD 部分，详细说明需要查看在线文档。
### 页面接口同体机制
系统支持页面和接口同体，即同一个控制器方法既可以返回 HTML 页面，也可以返回 JSON 接口数据。
- **触发方式**：在请求头（Header）中设置 `Accept` 包含 `application/json`。
- **认证方式**：支持在 Header 中传入 `Authorization: Bearer tokenContent` 进行接口认证。
- **实现要求**：控制器方法必须调用 `$this->fetch()` 而非 `View::fetch()`。
- **数据输出**：
- 无论是 `$this->assign()` 还是 `View::assign()` 的数据都会被转换为 JSON。
- 如果不希望某个数据出现在 JSON 中，可以使用 `$this->assign('name', 'value', -1)`（第三个参数设为 -1）。
- **特殊处理**：`index` 方法GET方式默认返回分页数据。若需获取 `assign` 的数据，需在 URL 中添加参数 `get_page_data=1`。
- **生效范围**：仅在控制器模式（Controller Mode）中生效，路由模式（Route Mode）不生效。
### 登录认证机制
系统登录时会同时启用 **Session** 和 **Token** 机制。
- **Session 机制**：主要用于传统的浏览器环境，依赖 Cookie。
- **Token 机制**：专门为接口开发和无法使用 Cookie 的场景（如移动端、小程序、跨域请求等）设计。
- **使用方法**：
- 登录成功后，接口会返回 `token` 数据。
- 前端在后续请求中，需将此 token 放入请求头：`Authorization: Bearer <token>`。
- 系统会自动识别并完成身份认证。
命令行通用参数：多数命令支持 `--force-force`（`-ff`）跳过交互确认。

71
CODERULE.md
View File

@@ -70,7 +70,7 @@ Ulthon Admin 采用独特的双层架构设计，其中 **基础核心层 (`exte
### 1. 开发红线与原则
- **核心保护**: 严禁修改 `extend/base/` 目录下的任何文件。
- **业务隔离**: 所有业务逻辑必须放在 `application/` 目录下。
- **业务隔离**: 所有业务逻辑必须放在 `app/` 目录下。
### 2. 扩展机制：继承与重写
@@ -79,49 +79,40 @@ Ulthon Admin 采用独特的双层架构设计，其中 **基础核心层 (`exte
- **继承**: 业务类继承 `extend/base/` 中的基础类。
- **重写**: 在业务类中重写父类方法，保持方法签名一致。
- **调用父类**: 使用 `parent::methodName()` 复用原有逻辑，或者从父类复制代码重新实现。
- **注意**: 全新开发的业务模块不受此限制，直接在 `application/` 下开发即可。
- **注意**: 全新开发的业务模块不受此限制，直接在 `app/` 下开发即可。
### 3. 标准开发流程
1. **设计数据库表结构**
1. **设计/调整表结构**
- 严格遵循【第一部分：通用基础规范】中的数据库设计规范。
- 可以直接在数据库中创建表，也可以使用 Scheme 层代码化创建。
- 优先通过 Scheme 机制在 `app/admin/scheme/` 代码化维护表结构。
2. **生成基础代码 (CURD)**
- 使用 `php think curd` 命令生成控制器、模型、视图等。
- 推荐先生成到临时目录 (`-r`) 确认无误。
2. **同步并确保一致**
- 以代码为准：`scheme:sync`
- 以数据库为准：`scheme:make -t {table}`
- **注意**：生成 CURD 前，Scheme 与数据库结构必须完全一致，否则会被拒绝。
3. **业务代码定制**
- 在生成的代码基础上进行修改。
- 仅操作 `application/` 目录。
3. **生成基础代码（CURD）**
- 推荐先生成到临时目录确认：`php think curd -t {table} -r`
- 确认无误后再正式生成/覆盖：`php think curd -t {table}` / `php think curd -t {table} -f`
4. **测试与验证**
- 功能测试、数据完整性检查、代码规范检查。
4. **业务代码定制**
- 在生成代码基础上进行修改，仅操作 `app/` 目录。
5. **测试与验证**
- 功能测试、数据完整性检查、代码规范检查（遵循项目 PHP-CS-Fixer 配置）。
### 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
```
更完整的命令组合与参数说明，优先以在线文档为准；仓库内的工作流摘要可参考 `.trae/skills/ulthon-scheme-curd-workflow/`。
### 5. 前端开发规范
#### 5.1 文件组织
每个视图 HTML 文件应搭配一个同名的 JS 文件，结构如下：
每个视图 HTML 文件应搭配一个同名的 JS 文件，并按模块维护 `_common.js`，结构示例：
```text
goods/
@@ -136,7 +127,7 @@ goods/
### 6. Scheme 机制（数据库代码化）
Ulthon Admin 引入了 Scheme 层，实现了数据库结构与 PHP 代码的双向同步，便于版本控制和快速迁移。
Ulthon Admin 引入了 Scheme 层，实现数据库结构与 PHP 代码的双向同步，便于版本控制和快速迁移。
#### 6.1 核心概念
- **Code to DB (`scheme:sync`)**: 通过编写 PHP 类定义表结构，自动同步到数据库（支持备份原表）。
@@ -145,26 +136,6 @@ Ulthon Admin 引入了 Scheme 层，实现了数据库结构与 PHP 代码的双
#### 6.2 目录规范
- **业务 Scheme**: `app/admin/scheme/` (所有生成的业务表结构类存放在此)
#### 6.3 常用命令
```bash
# 将数据库表 ul_test_goods 反向生成为 PHP 代码
php think scheme:make -t test_goods
#### 6.3 参考资料
# 将 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}` 生成业务代码。
- 标准工作流摘要：`.trae/skills/ulthon-scheme-curd-workflow/SKILL.md`