AGENTS.md — SentCMS

项目概述

SentCMS 是基于 ThinkPHP 6.x 的 PHP CMS 系统。采用单应用架构（非 ThinkPHP 多应用模式），4 个"模块"（admin、front、user、api）是控制器命名空间，不是独立的 ThinkPHP 应用。

PHP >= 7.1，MySQL，网站根目录 = public/
许可证：Apache-2.0

环境搭建

composer install              # 安装依赖
cp .example.env .env          # 然后编辑数据库配置、JWT 密钥、rootuid

网站文档根目录必须指向 public/。
必须开启 URL 伪静态（public/ 下已包含 Apache .htaccess）。
首次安装：访问 http://域名/install.php，自动建表并写入 install.lock。
index.php 在缺少 .env 或 install.lock 时会重定向到 install.php。

架构说明

app/controller/{admin,front,user,api}/   ← 4 个控制器分组，各有独立 Base
app/http/middleware/                      ← Admin, Api, ApiAuth, Validate
app/http/validate/{admin,api}/           ← 按控制器自动加载的验证器
app/http/form/                           ← 自定义表单引擎
app/model/{addons,ads,auth,client,form,link,module,system,wechat}/
app/services/{module/,system/}           ← 业务逻辑服务
app/common.php                           ← 全局辅助函数（is_login, is_administrator 等）
config/                                  ← ThinkPHP 配置（database, auth, view, addons, jwt 等）
extend/com/                              ← 自定义类库（Database, Datatable, Sent 标签库, Version）
extend/doc/                              ← 文档注释解析器（用于后台页面标题）
addons/{devteam,sitestat,syslogin,systeminfo}/  ← 插件系统
view/admin/                              ← 后台管理模板
public/template/                         ← 前台主题模板
public/static/                           ← 静态资源
route/app.php                            ← 所有路由定义

路由系统

路由定义在 route/app.php，分两层：

静态路由 — Route::group('admin', ...)、Route::group('user', ...)、Route::group('api', ...) 及前台路由。
动态模型路由 — ModuleService::registerRoute() 从数据库读取内容模型，动态注册路由，如 /admin/{模型名}/:function → admin.Content/:function，/{模型名}/detail-:id → front.Content/detail 等。

重要：内容模型没有独立的控制器文件，全部映射到 admin.Content、front.Content、user.Content、api.Content，并附加 name 和 model_id 参数。

中间件链

模块	中间件	认证机制
admin	`Validate` → `Admin`	Session（`adminInfo`），RBAC 权限通过 `sent\auth\Auth` 校验
api	`Validate` → `ApiAuth` → `Api`	JWT（`sent\jwt\JWTAuth`）
user	控制器层无中间件	`user\Base::initialize()` 中 Session 检查
front	无	公开访问

Admin 中间件对 AJAX 请求自动将响应转为 JSON。
Validate 中间件在 POST 请求时自动加载 app\http\validate\{控制器} 对应的验证器，且仅在对应场景（scene）存在时才执行校验。

模板系统

后台视图：view/admin/{控制器}/{操作}.html
前台视图：public/template/{主题名}/ — 主题通过系统配置（pc_themes、mobile_themes）切换
前台控制器模板名使用 _ 作为分隔符：如 front.content → 模板 front_content/action.html
自定义 ThinkPHP 标签库 com\Sent 已预加载（定义在 extend/com/Sent.php）
模板路径常量：__static__、__img__、__css__、__js__、__plugins__、__public__

关键约定

超级管理员：由环境变量 rootuid 决定（默认 1），通过 app/common.php 中的 is_administrator() 检查。
权限表：auth_group、auth_group_access、auth_rule（可在 config/auth.php 中配置表名）。
钩子/事件：插件钩子使用缓存（sentcms_hooks 缓存键），在基础控制器构造函数中通过 Event::listenEvents() 注册。
数据库表前缀：通过 .env 中的 DATABASE.PREFIX 设置。
本项目无测试、无 CI、无 Lint 工具配置。
无构建步骤 — 传统 PHP 应用，静态资源直接对外服务。

常见任务

新增后台控制器

创建 app/controller/admin/{Name}.php，继承 app\controller\admin\Base。
创建视图目录 view/admin/{name}/。
路由自动匹配：admin/{name}/{action}。
在 auth_menu 表中添加菜单项以显示在后台侧边栏。

新增 API 接口

在 app/controller/api/{Name}.php 中添加方法，继承 app\controller\api\Base。
路由自动匹配：api/{name}/{action}。
默认启用 JWT 认证（login/register 除外）。

新增内容模型

通过后台管理界面创建模型 → 自动注册动态路由。
内容路由映射到 admin.Content、front.Content、user.Content、api.Content。
模型属性定义存储在数据库（model_attribute 表）中。

新增插件

创建 addons/{name}/ 目录，包含 controller/Admin.php、可选的 controller/Index.php 和 view/ 模板。
在 addons 配置和数据库表中注册。

环境变量（.env）

关键变量（参见 .example.env）：

APP_DEBUG — 调试模式
VERSION — 后台显示的版本号
rootuid — 超级管理员用户 ID
DATABASE.* — MySQL 连接（type, hostname, database, username, password, hostport, charset, prefix）
JWT.SECRET — JWT 签名密钥

注意事项

勿删 install.lock — 它阻止安装程序被重复访问。
勿提交 .env — 已在 .gitignore 中忽略。
composer.lock 同样已忽略 — 每次 composer install 重新生成。
runtime/ 目录需要对 Web 服务器可写（缓存、日志、会话、备份）。
public/uploads/ 目录需可写以支持文件上传。
前台主题模板在 public/template/，不在 view/ — 这点容易搞混。
项目根目录的 view/ 仅存放后台模板和插件视图。
内容模型控制器是虚拟的（全部路由到 Content 控制器）——不要去找按模型名命名的控制器文件。
后台 Base 控制器在 initialize() 中定义了 IS_ROOT 常量 — 在所有后台控制器中可用。

6.4 KiB Raw Blame History Unescape Escape