mirror of https://gitee.com/ulthon/ulthon_admin.git synced 2026-10-29 08:58:22 +08:00

Files

augushong e54c772868 feat(admin): 菜单快照对齐迁移，存量库自动补齐运行管理与XHProf菜单

对齐迁移是菜单快照进入数据库的唯一途径（新装与存量库同路径）；缺失行按显式 id 补插，框架结构行仅对齐 pid+sort，软删/用户分组跳过；新增规则文件与索引；清理 status 模块孤儿占位文件。

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

2026-09-09 14:37:56 +00:00

6.8 KiB

Raw Blame History

智能体协作规范（Ulthon Admin）

上方「项目信息」由本项目开发者维护，下方为框架规则。进入项目先看项目信息。

项目信息

项目概述：ulthon_admin 框架本身（框架作者开发模式，非下游业务项目）
运行方式：使用框架内置 docker-dev 栈（source/stack/docker-dev/）。启动：cd source/stack/docker-dev && docker compose up -d
命令执行方式：php think 一律在容器内执行，不在宿主机直接执行。模式目录内：docker compose exec ulthon_admin php think ...；仓库根目录：docker compose -f source/stack/docker-dev/docker-compose.yaml exec ulthon_admin php think ...
端口：应用 8000、MySQL 13306（容器内 3306，root/root，库名 ulthon）、Redis 16379、phpMyAdmin 18888
访问地址：http://localhost:8000/admin（后台，默认账号 admin / 123456）
注意：宿主机 docker compose exec 默认以 root 执行，产生的 runtime 文件 www-data 不可写；遇到 runtime 权限问题时 chmod -R a+rwX runtime（模式目录内 exec 可加 --user www-data 规避）

代码分层铁律（Base/App 双层架构）

框架采用 Base/App 双层架构：extend/base/ 是框架内核（*Base 类），app/ 是业务代码入口，两者目录路径一一对应。

严禁修改 extend/base/ 下任何文件，所有开发只在 app/ 进行
扩展框架内置能力时只改 app/ 下对应入口类（必要时 extends 对应 *Base，保持方法签名一致）
app/ 可文件级覆盖 extend/base/ 的三类文件（见 ulthon-file-override-mechanism.md）
默认身份是框架使用者；仅当任务明确涉及 extend/base/ 时切换为框架作者身份
完整规则、目录映射与项目结构总览：ulthon-base-app-architecture

其他框架规则

技术栈：ThinkPHP 8.x / PHP 8.1+ / MySQL 5.7+ / Layui 2.x；代码风格遵循根目录 .php-cs-fixer.php
命名规范（必读）：ulthon-naming-convention.md
表结构设计（必读）：ulthon-scheme-definition；表结构优先 Scheme（app/admin/scheme/），避免 ENUM；tools:db 仅用于调试，不用于设计表结构
前端：视图与脚本同名配对（*.html + 同名 *.js），按模块维护 _common.js
权限：基于 auth 注解动态扫描节点与鉴权，以角色为中心管理（CLI 见 ulthon-permission-cli）
临时文件统一输出到 runtime/agents/（可按任务再分子目录），不放仓库根目录
调试与验证优先框架内置命令行工具（见下方快速命令），不借助外部数据库 MCP 或临时脚本
项目运行方式未在上方说明时，执行命令前先按 ulthon-deploy-environment.md 判断环境（如根目录有 Docker 编排文件则勿直接宿主机执行 php think）
在线文档：https://doc.ulthon.com/read/augushong/ulthon_admin/home/zh-cn/2.x.html

规则与技能

.agents/rules/（零散规则）与 .agents/skills/（场景技能）按前缀区分维护者：ulthon- 为框架分发，project- 为本项目自建
涉及具体模块/场景前，先查对应目录是否有专属文件
新增零散规则的操作流程见 ulthon-rules-manager

框架规则速览（一行一条，完整内容见文件）：

规则文件	说明
ulthon-naming-convention.md	目录与 PHP 文件命名约定
ulthon-controller-url.md	URL 与控制器/方法映射
ulthon-controller-response-throw.md	success/error/result/redirect 是 throw 不是 return
ulthon-deploy-environment.md	部署栈模式与运行环境判断
ulthon-source-directory.md	source/ 目录约定与安全要求
ulthon-file-override-mechanism.md	app/ 覆盖 extend/base/ 的三类文件
ulthon-system-config.md	sysconfig 的存储/读取/扩展
ulthon-init-data-migration.md	初始化数据变更必须同提交配套数据型 migration

标准开发流程（Scheme + CURD）

步骤	对应技能
1. 初始化环境（依赖、`.env`、数据库、`php think` 可用）	-
2. 设计表结构（`app/admin/scheme/`）	ulthon-scheme-definition
3. 同步 Scheme 与 DB（`scheme:sync` / `scheme:make`，生成前必须一致）	ulthon-scheme-curd-workflow
4. 生成 CURD（`curd -t {table}`，字段变更可 `-r` 安全重生成）	ulthon-scheme-curd-workflow
5. 业务定制（仅改 `app/`）	ulthon-admin-table、ulthon-page-api-dual-mode
6. 功能验证	ulthon-tools-http-call
7. 功能配套（菜单/权限/角色）	ulthon-admin-menu-cli、ulthon-permission-cli
8. 最终检查（页面可用、命令行验证、规范自查）	-

快速命令

场景	命令
同步表结构（代码→DB）	`php think scheme:sync`
生成 Scheme（DB→代码）	`php think scheme:make -t {table}`
CURD 代码生成	`php think curd -t {table}`
模拟 HTTP 请求	`php think tools:http:call`
查看日志	`php think tools:log:show`
数据库查询	`php think tools:db:query "SELECT ..."`
查看权限节点	`php think admin:permission:nodes`
菜单管理	`php think admin:menu:*`
框架更新	`php think admin:update`

6.8 KiB Raw Blame History Unescape Escape