mirror of
https://gitee.com/ulthon/ulthon_information.git
synced 2026-07-07 07:12:47 +08:00
351808bf07
添加 AGENTS.md 和 app/AGENTS.md 两个知识库文档，分别记录项目整体架构和应用模块详情。文档包含项目结构、代码映射、开发约定和反模式说明，便于新开发者快速了解系统。
91 lines
4.3 KiB
Markdown
91 lines
4.3 KiB
Markdown
# 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/ 空目录**: 未使用的响应封装层
|