127 lines
6.4 KiB
Markdown
127 lines
6.4 KiB
Markdown
# AGENTS.md — SentCMS
|
||
|
||
## 项目概述
|
||
|
||
SentCMS 是基于 **ThinkPHP 6.x** 的 PHP CMS 系统。采用**单应用**架构（非 ThinkPHP 多应用模式），4 个"模块"（`admin`、`front`、`user`、`api`）是控制器命名空间，不是独立的 ThinkPHP 应用。
|
||
|
||
- **PHP** >= 7.1，**MySQL**，网站根目录 = `public/`
|
||
- 许可证：Apache-2.0
|
||
|
||
## 环境搭建
|
||
|
||
```bash
|
||
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`，分两层：
|
||
|
||
1. **静态路由** — `Route::group('admin', ...)`、`Route::group('user', ...)`、`Route::group('api', ...)` 及前台路由。
|
||
2. **动态模型路由** — `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 应用，静态资源直接对外服务。
|
||
|
||
## 常见任务
|
||
|
||
### 新增后台控制器
|
||
|
||
1. 创建 `app/controller/admin/{Name}.php`，继承 `app\controller\admin\Base`。
|
||
2. 创建视图目录 `view/admin/{name}/`。
|
||
3. 路由自动匹配：`admin/{name}/{action}`。
|
||
4. 在 `auth_menu` 表中添加菜单项以显示在后台侧边栏。
|
||
|
||
### 新增 API 接口
|
||
|
||
1. 在 `app/controller/api/{Name}.php` 中添加方法，继承 `app\controller\api\Base`。
|
||
2. 路由自动匹配：`api/{name}/{action}`。
|
||
3. 默认启用 JWT 认证（`login`/`register` 除外）。
|
||
|
||
### 新增内容模型
|
||
|
||
1. 通过后台管理界面创建模型 → 自动注册动态路由。
|
||
2. 内容路由映射到 `admin.Content`、`front.Content`、`user.Content`、`api.Content`。
|
||
3. 模型属性定义存储在数据库（`model_attribute` 表）中。
|
||
|
||
### 新增插件
|
||
|
||
1. 创建 `addons/{name}/` 目录，包含 `controller/Admin.php`、可选的 `controller/Index.php` 和 `view/` 模板。
|
||
2. 在 `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` 常量 — 在所有后台控制器中可用。
|