mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-09-05 23:35:31 +08:00
docs(rules): 新增文件级覆盖机制规则并修正索引职责互斥
- 新增 ulthon-file-override-mechanism.md:阐述 app/ 覆盖 extend/base/ 的三类机制(视图模板、include 标签、app_file_path)与不支持覆盖的反例清单 - ulthon-base-app-architecture:升格原孤立描述为独立小节"5. 文件级覆盖机制" - ulthon-timer:在 app_file_path 覆盖说明处增加规则引用 - AGENTS.md:登记新规则到框架内置规则索引 - ulthon-rules-manager:修订索引职责(AGENTS.md 仅 ulthon-、PROJECT.md 仅 project-,互斥不重复维护);索引格式从 4 列改为 3 列与项目实际一致;维护规则补充对称约束;泛化"迁移现有内容"章节
This commit is contained in:
@@ -87,13 +87,24 @@ description: "详细说明了 Base/App 双层架构的设计理念、三层结
|
||||
- **辅助函数**:放在 `extend/base/helper.php`,通过 `app/common.php` 引入。
|
||||
- **初始化数据**:放在 `extend/base/adminInitData/`(带 @internal-framework 注解标记)。
|
||||
- **版本更新代码**:放在 `extend/base/adminUpdateCodeData/`(带 @internal-framework 注解标记)。
|
||||
- 静态文件/模板/配置支持分层加载:优先加载 `app/`,不存在时再回落到框架默认实现(例如 `app_file_path`)。
|
||||
|
||||
### 4. 核心层维护原则
|
||||
|
||||
- 稳定性优先:保证向下兼容
|
||||
- 通用性优先:不引入具体业务逻辑
|
||||
|
||||
### 5. 文件级覆盖机制
|
||||
|
||||
除"类继承覆盖"外,框架还支持**文件级覆盖**:在 `app/` 下放置与 `extend/base/` 同路径同名的视图、模板、配置数组或 PHP 钩子文件,运行时会优先加载 app 版本。该能力覆盖三类文件:
|
||||
|
||||
- 视图模板(控制器 `fetch()` 渲染时三级回退:`app/<module>/view/` → `extend/base/<module>/view/` → `<root>/view/`)
|
||||
- 模板内 `{include}` 标签(与视图同源的三级查找)
|
||||
- `app_file_path()` 辅助函数显式加载的文件(两级回退:`app/<相对路径>` → `extend/base/<相对路径>`)
|
||||
|
||||
注意:文件级覆盖只对**特定类型**的文件生效。命令、语言包、路由、`config/*`、`public/static/*`、`AdminInitServiceBase::requireData()` 等均**不支持**——业务侧在 `app/` 下放同名文件不会生效。
|
||||
|
||||
完整的机制说明、7 处已知调用点清单与反例,见规则:[ulthon-file-override-mechanism](../../rules/ulthon-file-override-mechanism.md)。
|
||||
|
||||
---
|
||||
|
||||
## 三、架构参考资料
|
||||
|
||||
Reference in New Issue
Block a user