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

.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` 配置为准（不假设本机已安装相关工具）。
+

.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. 系统会自动识别并完成身份认证。
+

.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`
+

.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`，并尽量将变更限制在最小范围。
+

.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）不生效。
+

.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`）跳过交互确认。