开发手册

本文汇总 TanzCMS 二次开发、模块开发、插件开发、主题制作和发布运维相关规范。开发时优先遵守目录边界、模板边界和可安装可升级原则。

一、阅读顺序

手册	重点
开发者总览	先了解核心、模块、插件、主题和应用市场的边界
PHP 开发规范	控制器、服务、数据库、异常、安全和模板边界
数据库与迁移规范	表前缀、迁移位置、模块表、插件表和备份恢复
后台开发规范	菜单、权限、CRUD、状态、排序和独立编辑页
API 开发规范	鉴权、scope、响应格式、分页、错误码和回调
模板标签开发进阶	标签处理器、结构化数据、缓存和参数校验
主题开发完整手册	主题目录、模板选择、资源路径和覆盖规则
安全开发规范	CSRF、权限、上传、XSS、SQL 注入和敏感信息
缓存与性能开发规范	元数据缓存、模板缓存、页面缓存和失效规则
应用市场打包规范	核心包、模块包、插件包和主题包边界
排错手册	404、模板不生效、菜单不显示、资源 404 和数据库导入异常
测试与验收手册	安装、升级、发布包、路由、权限和健康检查
代码示例合集	最小模块、插件、标签、后台页、API 和回调示例

二、总原则

• 核心负责平台能力，模块负责一方业务，插件负责可选扩展，主题负责展示。
• 前台、会员中心和主题模板使用 TanzCMS .html 模板语法，不使用 Blade。
• PHP 提供结构化数据、权限、URL、状态和低层通用小片段，不为单个栏目或主题拼整页 HTML。
• 模块包、插件包和主题包不得覆盖核心 app/、config/ 和公共后台脚本。
• 线上安装和升级文档使用通用命令，不写本地机器路径。

三、最小闭环

一个新能力至少要同时考虑：

1. 数据表和迁移放在哪里。
2. 菜单、权限和路由如何注册。
3. 前台模板或后台页面如何引用资源。
4. 启用、禁用、卸载和升级时如何清缓存。
5. 如何导入初始数据，如何避免覆盖站点已有数据。
6. 发布包是否排除了本地文档、测试文件、私有插件、上传文件和运行时文件。