开发者总览

TanzCMS 的二次开发首先要判断能力归属。不要一遇到新需求就改核心控制器，也不要把可选能力做成一方模块。

能力归属

能力	推荐归属
内容、栏目、字段、模板、会员、权限、上传、缓存	核心或一方模块
官方业务域，例如内容、会员、订单、支付、文档	modules/{code}
可选增强，例如登录方式、短信通道、存储驱动、SEO 工具	plugins/{code}
页面结构、列表卡片、会员中心视觉	themes/{theme}
前台数据读取和循环展示	模板标签或主题模板
第三方系统读取站点数据	Open API
第三方平台主动通知	统一回调入口

目录边界

app/                         核心壳和平台基础能力
modules/{code}/              一方业务模块
plugins/{code}/              可安装插件
themes/{theme}/              前台、会员和模板覆盖
public/assets/modules/{code} 模块发布后的静态资源
public/assets/plugins/{code} 插件发布后的静态资源

public/assets/modules 和 public/assets/plugins 只放发布后的静态资源，不放 PHP 源码、迁移或业务逻辑。

开发原则

• 前台和会员模板使用 TanzCMS .html 模板语法，不使用 Blade。
• 控制器只做请求校验、权限检查和服务调用。
• 页面结构优先放到主题模板，不在 PHP 中拼整块 HTML。
• 模板标签传声明式参数，不接收 SQL 片段、任意表名或未校验字段名。
• 新增后台接口必须有页面权限和功能权限。
• 插件禁用或卸载后，核心系统不能依赖插件服务才能正常运行。
• 上传、附件、缓存、权限、日志和回调要走系统统一能力。

开发验收

开发完成后至少检查：

1. 目录是否符合核心、模块、插件、主题边界。
2. 是否新增了不必要的硬编码栏目、模板、URL 或主题名。
3. 是否保持 .html 模板语法和默认安全输出。
4. 后台接口是否有权限校验和 CSRF 边界。
5. 插件公开回调是否有签名、幂等和日志。
6. 数据库表是否使用当前站点表前缀规则。
7. 模块或插件启停后是否清理模板、配置和路由缓存。
8. 发布包是否排除了开发文档、测试、临时文件、日志和运行时上传文件。