后台页面开发手册

后台页面优先复用 TanzCMS 通用组件。模块和插件只声明页面字段、接口和少量差异逻辑，不为每个页面重新写表格、分页、弹窗和消息提示。

页面类型

类型	推荐实现
记录列表	通用 CRUD
长表单编辑	独立编辑页，列表配置 editorPage
系统设置	设置页组件
插件配置	插件页复用后台面板和 CRUD
复杂业务页	页面专用 JS/CSS，但仍复用通用弹窗、上传和消息

列表页结构

后台列表页使用统一结构：

<section class="tanz-crud-page">
  <div class="tanz-crud">
    <form class="layui-form tanz-crud-toolbar">
      <div class="tanz-crud-actions"></div>
      <div class="tanz-crud-search"></div>
    </form>
    <div class="tanz-table-wrap">
      <table></table>
    </div>
    <div class="tanz-pagination-host"></div>
  </div>
</section>

不要为单个列表单独写分页、复选框半选、搜索栏和批量删除逻辑。

独立编辑页

长内容、栏目配置、Markdown 文档等复杂表单应使用独立编辑页，不放进弹窗。

通用 CRUD 支持 editorPage：

{
  key: 'docs.pages',
  editorPage: true
}

列表继续复用搜索、分页和状态切换；新增和编辑跳转到独立页面。

权限

后台权限分为页面权限和功能权限：

module.docs.page
module.docs.page.create
module.docs.page.update
module.docs.page.delete

规则：

• 菜单权限控制页面访问。
• 功能权限控制新增、编辑、删除、状态切换等接口。
• 前端隐藏按钮不是安全边界，后端接口必须校验。
• 设置页也要区分进入页面和保存设置权限。

接口规范

后台接口应返回 JSON：

{
  "message": "保存成功",
  "data": {}
}

失败时返回合适 HTTP 状态码，例如 422 表单验证失败、403 无权限、404 记录不存在。

资源加载

页面专用 JS/CSS 直接在页面片段中引用。稳定复用两个以上页面后，再提升为通用资源。

模块资源发布到：

public/assets/modules/{code}/

插件资源发布到：

public/assets/plugins/{code}/

不要把模块或插件页面资源写进全局后台外壳。

弹窗和消息

业务弹窗：

layer.open({
  skin: 'admin-layer'
});

确认弹窗：

layer.confirm(message, {
  skin: 'admin-layer admin-confirm-layer',
  btn: ['确定', '取消']
});

提示消息：

layer.msg('<span class="admin-message-content">保存成功</span>', {
  skin: 'admin-message-layer is-success'
});

不要直接使用无皮肤的 layer.msg 或 layer.confirm。

UI 边界

• 后台说明文字要短，复杂说明进入帮助文档。
• 常规按钮、搜索框、分页按钮优先使用 32px 高度。
• 主题色统一使用 --admin-primary。
• 状态开关、复选框、分页当前页和弹窗主按钮都要适配主题色。
• 删除统一优先走批量操作，行内只保留明确单项动作。
• 功能配置型数据不随意提供删除。