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:
augushong
2026-07-19 00:30:05 +08:00
parent 073172473b
commit 46f0d62852
5 changed files with 130 additions and 14 deletions

View File

@@ -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)。
---
## 三、架构参考资料