From 28267ff1c0564368a79219967811d22c3b0bbc7d Mon Sep 17 00:00:00 2001
From: augushong <augushong@163.com>
Date: Sun, 1 Feb 2026 13:13:03 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E6=9E=84=E9=A1=B9=E7=9B=AE?=
 =?UTF-8?q?=E8=A7=84=E5=88=99=E4=B8=8E=E6=8A=80=E8=83=BD=E6=96=87=E6=A1=A3?=
 =?UTF-8?q?=E7=BB=93=E6=9E=84=E5=B9=B6=E6=9B=B4=E6=96=B0=E5=BC=80=E5=8F=91?=
 =?UTF-8?q?=E6=8C=87=E5=8D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .trae/rules/project_rules.md                  | 28 +++++++
 .../skills/ulthon-auth-session-token/SKILL.md | 28 +++++++
 .../ulthon-core-extend-pattern/SKILL.md       | 33 ++++++++
 .trae/skills/ulthon-db-tools-debug/SKILL.md   | 35 +++++++++
 .../skills/ulthon-page-api-dual-mode/SKILL.md | 32 ++++++++
 .../ulthon-scheme-curd-workflow/SKILL.md      | 75 ++++++++++++++++++
 AGENTS.md                                     | 77 +++++--------------
 CODERULE.md                                   | 71 +++++------------
 8 files changed, 272 insertions(+), 107 deletions(-)
 create mode 100644 .trae/rules/project_rules.md
 create mode 100644 .trae/skills/ulthon-auth-session-token/SKILL.md
 create mode 100644 .trae/skills/ulthon-core-extend-pattern/SKILL.md
 create mode 100644 .trae/skills/ulthon-db-tools-debug/SKILL.md
 create mode 100644 .trae/skills/ulthon-page-api-dual-mode/SKILL.md
 create mode 100644 .trae/skills/ulthon-scheme-curd-workflow/SKILL.md

diff --git a/.trae/rules/project_rules.md b/.trae/rules/project_rules.md
new file mode 100644
index 0000000..cbf7de3
--- /dev/null
+++ b/.trae/rules/project_rules.md
@@ -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` 配置为准（不假设本机已安装相关工具）。
+
diff --git a/.trae/skills/ulthon-auth-session-token/SKILL.md b/.trae/skills/ulthon-auth-session-token/SKILL.md
new file mode 100644
index 0000000..296bfae
--- /dev/null
+++ b/.trae/skills/ulthon-auth-session-token/SKILL.md
@@ -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. 系统会自动识别并完成身份认证。
+
diff --git a/.trae/skills/ulthon-core-extend-pattern/SKILL.md b/.trae/skills/ulthon-core-extend-pattern/SKILL.md
new file mode 100644
index 0000000..4304380
--- /dev/null
+++ b/.trae/skills/ulthon-core-extend-pattern/SKILL.md
@@ -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`
+
diff --git a/.trae/skills/ulthon-db-tools-debug/SKILL.md b/.trae/skills/ulthon-db-tools-debug/SKILL.md
new file mode 100644
index 0000000..7f5c58d
--- /dev/null
+++ b/.trae/skills/ulthon-db-tools-debug/SKILL.md
@@ -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`，并尽量将变更限制在最小范围。
+
diff --git a/.trae/skills/ulthon-page-api-dual-mode/SKILL.md b/.trae/skills/ulthon-page-api-dual-mode/SKILL.md
new file mode 100644
index 0000000..e24f888
--- /dev/null
+++ b/.trae/skills/ulthon-page-api-dual-mode/SKILL.md
@@ -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）不生效。
+
diff --git a/.trae/skills/ulthon-scheme-curd-workflow/SKILL.md b/.trae/skills/ulthon-scheme-curd-workflow/SKILL.md
new file mode 100644
index 0000000..d16fa23
--- /dev/null
+++ b/.trae/skills/ulthon-scheme-curd-workflow/SKILL.md
@@ -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`）跳过交互确认。
diff --git a/AGENTS.md b/AGENTS.md
index 0e25911..66f3590 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -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`）跳过交互确认。
diff --git a/CODERULE.md b/CODERULE.md
index ea2aeac..f2edc56 100644
--- a/CODERULE.md
+++ b/CODERULE.md
@@ -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`