From 351808bf07f47522738046e848e61d318e1b43c5 Mon Sep 17 00:00:00 2001 From: augushong Date: Sun, 26 Apr 2026 22:31:20 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E7=9F=A5=E8=AF=86=E5=BA=93=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 添加 AGENTS.md 和 app/AGENTS.md 两个知识库文档，分别记录项目整体架构和应用模块详情。文档包含项目结构、代码映射、开发约定和反模式说明，便于新开发者快速了解系统。 --- AGENTS.md | 148 ++++++++++++++++++++++++++++++++++++++++++++++++++ app/AGENTS.md | 90 ++++++++++++++++++++++++++++++ 2 files changed, 238 insertions(+) create mode 100644 AGENTS.md create mode 100644 app/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c5ad204 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,148 @@ +# PROJECT KNOWLEDGE BASE + +**Generated:** 2026-04-26 +**Commit:** df6b22d +**Branch:** master + +## OVERVIEW + +基于 ThinkPHP 6 的企业官网内容管理系统(CMS)，项目名 `ulthon_admin`，最低支持 PHP 7.1。多应用架构(admin/index/api)，layui 前端，支持 MySQL + SQLite 双数据库。 + +## STRUCTURE + +``` +ulthon_information/ +├── app/ # 应用核心(多应用模式) +│ ├── admin/controller/ # 后台管理(15个控制器) +│ ├── index/controller/ # 前台展示(5个控制器) +│ ├── api/controller/ # API接口(微信/文件/验证码) +│ ├── model/ # 全局模型(17个，非各应用内) +│ ├── common/ # 跨应用共享层(tools/traits/model) +│ └── middleware/ # 中间件(ConfigInit/AdminLog/PermissionRecord) +├── config/ # 框架配置(16个，含2个自定义) +├── database/migrations/ # Phinx迁移(16个表) +├── database/seeds/ # 种子数据(3个) +├── extend/think/ # PSR-0自定义扩展(Htmx响应/DebugMysql日志) +├── public/ # Web根目录 +│ └── static/lib/ # 前端库(layui/wangeditor/quill等，直接提交) +├── route/app.php # 全局路由(sitemap/rss/atom) +├── view/ # 模板文件(admin/index/common) +├── source/font/ # 思源黑体(水印用) +└── think # CLI入口 +``` + +## WHERE TO LOOK + +| 任务 | 位置 | 备注 | +|------|------|------| +| 添加后台功能 | `app/admin/controller/` | 继承 `admin\controller\Common` | +| 添加前台页面 | `app/index/controller/` | 继承 `index\controller\Common` | +| 添加API接口 | `app/api/controller/` | 直接继承 `app\BaseController` | +| 添加数据模型 | `app/model/` | 继承 `common\model\Base`，使用 `AutoClearCache` | +| 添加数据库表 | `database/migrations/` | 用 `ColumnFormat` 辅助类定义列 | +| 修改全局函数 | `app/common.php` | json_message/geturl/check_permission等 | +| 修改配置 | `config/` | 自定义: `upload_type.php`/`view_type.php` | +| 添加前端库 | `public/static/lib/` | 直接提交源码(无npm) | +| SEO相关 | `app/common/tools/Sitemap.php`/`Rss.php` | 通过 `route/app.php` 注册 | +| 上传文件逻辑 | `app/UploadFiles.php` | 静态服务类，支持多编辑器适配 | +| 权限控制 | `app/common.php` -> `check_permission()` | admin_id=1 为超级管理员 | +| 模板渲染 | `view/` | ThinkPHP `{}` 标签，默认过滤 `ua_htmlentities` | + +## CODE MAP + +### 控制器继承链 + +``` +app\BaseController (abstract: validate/success/error/redirect) + +-- admin\controller\Common (Session鉴权) -> 15个子控制器 + +-- index\controller\BaseController (域名跳转/HTTPS) -> Common -> 3个子控制器 + +-- api\controller\* (直接继承 BaseController) -> 3个控制器 +``` + +### 响应格式 + +``` +JSON: { code: 0(成功)/500(失败), msg: '', data: {} } +AJAX请求 -> JSON; 普通请求 -> 模板页面(common@tpl/success|error) +辅助: json_message() / htmx() / $this->success() / $this->error() +``` + +### 数据库表关系 + +``` +Post --(M:N)--> Category (通过 post_category) +Post --(M:N)--> Tag (通过 post_tag) +Post --(1:N)--> PostComment, PostVisit +Admin --(N:1)--> AdminGroup --(权限列表)--> AdminPermission +表前缀: ul_，时间戳: int(10)，软删除: delete_time字段 +``` + +## CONVENTIONS + +- **代码风格**: PSR-12 (见 `.php-cs-fixer.php`)，单引号，后置自增，import按字母排序 +- **自动加载**: PSR-4 `app\` -> `app/`，PSR-0 `extend/` +- **时间戳**: 统一 int(10) 整数，非 datetime +- **软删除**: `delete_time` 字段(int)，值=0表示未删除 +- **缓存**: 模型变更后自动清缓存(AutoClearCache trait) +- **数据库迁移**: 仅 `change()` 方法(不可逆)，用 `ColumnFormat` 辅助类 +- **密码哈希**: `md5(password + salt)` (已知安全问题，但项目内一致使用) +- **视图过滤**: 默认 `ua_htmlentities` (null安全) +- **多应用URL**: 默认路径前缀 `/index/`/`/admin/`/`/api/`，README描述了域名绑定但配置中未启用 +- **Session**: 7天过期 +- **CLI模式**: 缓存强制用 file 驱动(防Redis连接失败) + +## ANTI-PATTERNS (THIS PROJECT) + +- **md5密码哈希**: 全项目使用 `md5(password+salt)`，未使用 `password_hash()`。涉及 Login/Admin/User/ResetPassword +- **批量赋值无保护**: `Model::create($post_data)` 未使用 `$fillable` 白名单 +- **SSL验证禁用**: `geturl()`/`posturl()` 中 `CURLOPT_SSL_VERIFYPEER=false` +- **调试残留**: `WxOpen::test()` 含 `dump()` 和硬编码微信AppID +- **.env 含生产凭据**: 数据库密码明文，已提交Git +- **.vscode/sftp.json**: 含服务器root密码 +- **.user.ini 硬编码路径**: `open_basedir` 指向 `/www/wwwroot/phpreturn.com/` +- **目录权限0777**: `File.php` 中 `mkdir` 使用 0777 +- **中间件已禁用**: AdminLog/PermissionRecord 被注释掉 + +## UNIQUE STYLES + +- **HTMX支持**: `extend/think/response/Htmx.php` 自定义响应类型，`htmx()` 全局函数 +- **DebugMysql日志**: `extend/think/log/driver/DebugMysql.php` 将日志写入数据库 +- **图片水印**: `common/tools/Image.php` 用 Intervention/Image + 思源黑体 +- **防采集**: `common/tools/PostShow.php` 用 phpQuery 注入版权文字到HTML +- **UA解析**: PostVisit 用 DeviceDetector 解析访问者设备信息 +- **UserHub SSO**: 通过 `ulthon/user_hub_client` 包实现OAuth单点登录 +- **HTML转Markdown**: admin/Post 控制器支持 HTML -> Markdown 转换 +- **多编辑器适配**: UploadFiles 支持 wangEditor/editorMD/base64/URL 多种上传方式 +- **view_type.php**: 分类/文章的视图模板映射(产品/案例/关于变体/动态) +- **upload_type.php**: 上传文件业务类型枚举 + +## COMMANDS + +```bash +# 安装 +composer install + +# 数据库 +php think migrate:run # 执行迁移 +php think seed:run # 填充种子数据 + +# 开发服务器 +php think run -p 8010 # 内置服务器(必须带index.php) + +# 代码风格 +vendor/bin/php-cs-fixer fix # 运行 PHP-CS-Fixer + +# 维护 +php think reset_password # 重置admin密码为123456 +``` + +## NOTES + +- 默认数据库驱动为 SQLite(`ul.db`)，生产通过 `.env` 切换为 MySQL +- `app/command/spider/` 和 `app/common/response/` 为空目录(废弃/未实现) +- `.travis.yml` 是 ThinkPHP 框架的CI配置，非本项目CI +- 前端库(`public/static/lib/`)未使用包管理器，直接提交源码 +- 日志默认通道为 `debug_mysql`，需确保对应表存在 +- `cacheAlways()` 方法非TP6内置，可能来自 composer 依赖扩展 +- `app_default_doamin` 在 config/app.php 中拼写错误(应为 domain) +- 域名绑定规则: www->前台, admin->后台, api->接口 (需Web服务器配合) diff --git a/app/AGENTS.md b/app/AGENTS.md new file mode 100644 index 0000000..e042aba --- /dev/null +++ b/app/AGENTS.md @@ -0,0 +1,90 @@ +# APP MODULE KNOWLEDGE BASE + +**Generated:** 2026-04-26 + +## OVERVIEW + +多应用架构核心层，包含三个 ThinkPHP 应用(admin/index/api)、全局模型、共享工具和中间件。 + +## STRUCTURE + +``` +app/ +├── BaseController.php # 抽象基类(validate/success/error/redirect) +├── Request.php # 自定义Request(空过滤器) +├── ExceptionHandle.php # 异常处理器 +├── UploadFiles.php # 文件上传静态服务类(非控制器) +├── common.php # 全局辅助函数(18个) +├── middleware.php # 全局中间件注册(CORS/Session/ConfigInit) +├── provider.php # 容器绑定 +├── event.php # 事件定义(全部为空) +├── command/ResetPassword.php # CLI: 重置admin密码 +├── admin/ # 后台管理应用 +│ ├── controller/ # 15个控制器 +│ ├── middleware.php # AdminLog/PermissionRecord(已注释) +│ └── route/index.php # 空(自动路由) +├── index/ # 前台展示应用 +│ ├── controller/ # 5个控制器(含BaseController/Common中间层) +│ └── route/index.php # 文章详情+分类列表路由 +├── api/ # API接口应用 +│ └── controller/ # WxOpen/Files/Captcha +├── model/ # 全局模型(17个) +├── common/ # 跨应用共享层 +│ ├── model/Base.php # 模型基类(use AutoClearCache) +│ ├── traits/ # AutoClearCache trait +│ ├── tools/ # Sitemap/Rss/Image/PostShow/PostBlock/Site +│ ├── Bootstrap.php # 自定义分页URL生成 +│ ├── ColumnFormat.php # 迁移列辅助类 +│ └── TextFormat.php # 文本格式化 +├── middleware/ # ConfigInit(启用) / AdminLog(禁用) / PermissionRecord(禁用) +``` + +## WHERE TO LOOK + +| 任务 | 位置 | 备注 | +|------|------|------| +| 添加后台CRUD | `admin/controller/` | 继承 `admin\controller\Common`，Session自动鉴权 | +| 添加前台页面 | `index/controller/` | 继承 `index\controller\Common`，自动加载导航/分类 | +| 添加API | `api/controller/` | 继承 `app\BaseController`，无额外中间件 | +| 添加模型 | `model/` | 继承 `common\model\Base`，声明 `$autoClearCache` | +| 添加业务工具 | `common/tools/` | 纯PHP类，无框架约束 | +| 修改上传逻辑 | `UploadFiles.php` | 静态方法，多编辑器适配入口 | +| 修改权限逻辑 | `common.php` -> `check_permission()` | admin_id=1 超管 | +| 添加全局函数 | `common.php` | ThinkPHP 自动加载 | +| 添加CLI命令 | `command/` | 需在 `config/console.php` 注册 | + +## 模型关系 + +``` +Post (SoftDelete, AutoClearCache) + |-- hasMany -> PostCategory -> belongsTo -> Category (树形, AutoClearCache) + |-- hasMany -> PostTag -> belongsTo -> Tag + |-- hasMany -> PostComment + |-- hasMany -> PostVisit (JSON: client/client_os/client_bot) + +Admin -> AdminGroup (SoftDelete) -> AdminPermission +Admin -> AdminLog (SoftDelete) + +Nav (AutoClearCache, 多type: 导航/轮播/友链/平台) +UploadFiles (SoftDelete, 状态: 未使用/已使用/已删除/已清除) +SystemConfig (name-value键值对) +User (SoftDelete) +TempImg / WxPublicAccount +``` + +## CONVENTIONS + +- **控制器响应**: AJAX -> `json_message()`，普通请求 -> `$this->success()`/`$this->error()` 渲染模板 +- **模型缓存**: 继承 `common\model\Base` 自动获得 `AutoClearCache`，需声明 `$autoClearCache = ['cache_key']` +- **无Validate类**: 全部行内验证 `$this->validate($data, $rules)` +- **无独立Service层**: 业务逻辑直接在Controller中 +- **事件系统未使用**: `event.php` 所有监听器为空数组 +- **路由**: admin 自动路由，index 有自定义路由(短URL格式)，api 自动路由 + +## ANTI-PATTERNS + +- **UploadFiles.php 位置不当**: 静态服务类放在 `app/` 根命名空间，应在 `common/` 或 `service/` +- **admin 中间件全部禁用**: AdminLog/PermissionRecord 被注释，操作审计和权限记录不工作 +- **common.php 职责过多**: 347行混合了HTTP/权限/文件/URL/时间/缓存等多种职责 +- **command/spider/ 空目录**: 废弃的爬虫功能未清理 +- **common/response/ 空目录**: 未使用的响应封装层