DEVELOPMENT
开发文档
GPL-3.0 开源，代码所见即所得。以下是二次开发的核心约定，完整手册随安装包附赠（README.md）。
兼容性基线
| 项 | 约定 |
|---|
| PHP 版本 | 代码以 PHP 7.4 为兼容基线，不使用 8.0+ 专属语法（联合类型、match、?->、enum、readonly 等）——目的是让 7.4 的老虚拟主机也能部署；7.4 兼容语法在 PHP 8.x 上向前兼容可正常运行 |
| 编码 | UTF-8 无 BOM；PHP / JS / CSS 保留文件头作者注释块 |
| 测试 | 改动后跑 run_tests.php（352 项断言）；改视图 DOM 前先 grep 跨标签子串断言 |
目录结构速览
| 路径 | 说明 |
|---|
public/ | ★ Web 根（唯一暴露目录）：index.php 前台入口 / admin.php 后台 / assets / uploads |
app/Core/ | 框架核：App 容器、Router、Database、View、Auth、Csrf、Schema（32 张表）、License（授权哨兵）、helpers |
app/Controllers/ | Home / Music / Member / Wallet / Creator / Forum / Album / Pay / Auth / Points + Admin/* |
app/Services/ | LedgerService（★ 资金账本唯一入口）、PayService、MediaConverter、WaveformService、PluginManager、ThemeManager、UpdateService… |
app/Views/themes/cyberdeck/ | 唯一完整模板，也是缺失模板时的回退主题 |
plugins/ themes/ | 内置 7 插件与 4 套薄皮肤 |
storage/ config/ | ★ Web 根之外：数据库、转码产物、备份、日志；安装后生成的配置 |
二次开发铁律
| 铁律 | 说明 |
|---|
| 资金 | 任何余额变动必须走 LedgerService，禁止直接 UPDATE users.balance |
| 加字段 | 同改 Schema.php + migrate.php；新增表还要进 migrate 的 $newTables 白名单 |
| 后台表单 | form action 归属：site.php → SiteController、settings.php → SettingsController，写错 = 保存无效 |
| 静态资源 | 改 app/Views/themes/cyberdeck/assets/ 后必须同步 public/assets/（app.js / app.css 有回归 md5 断言） |
| 全局函数 | 新助手函数放 app/Core/helpers.php（url() / e() / money_fmt() / dur_fmt() 等） |
| 打包边界 | 运行数据（config/ storage/ uploads/）不进包；开发件（run_tests.php tests/）不随安装包分发 |
插件开发
plugins/{slug}/
├── plugin.json # slug / name / version / hooks / slots / settings
├── Plugin.php # 命名空间 Plugins\{slug}，钩子方法名 = 钩子名 "."→"_"
└── admin.php # 可选：放这里后台自动出现「设置」按钮
| 可用钩子 | 触发时机 |
|---|
register_routes | 路由注册期（index.php 末尾，可注册自己的路由） |
music.uploaded | 曲目上传 / 审核 / 补救成功（auto_post 插件即用它发新作速报） |
forum.topic_created | 论坛发帖成功 |
media.saved / media.deleted | 媒体文件落库 / 清理（qiniu、r2 云存储插件用它转存与同步删除） |
提示：插槽需同时在 plugin.json 的 slots 声明并实现 slot_{name}() 方法，否则不渲染；可用插槽：notice / top_bar / home_top / music_side / player_bar / forum_side / footer / footer_links。
主题系统
- 解析顺序：
app/Views/themes/{激活}/ → themes/{激活}/ → app/Views/themes/cyberdeck/（逐文件回退）
- 薄主题 =
theme.json + layouts/main.php（覆盖配色与形状），业务模板回退 cyberdeck
- 改 cyberdeck 的业务模板等于五主题同时生效；输出一律
<?= e($x) ?> 转义