后台开发规范

后台页面要保持一致的菜单、权限、列表、表单和交互方式，避免每个模块各写一套管理体验。

一、菜单声明

模块或插件菜单应在自身 manifest 中声明，核心只负责读取、合并和显示。

{
  "menus": [
    {
      "top": "content",
      "group": "content.demo",
      "group_title": "示例模块",
      "group_icon": "file",
      "id": "module.demo.item",
      "title": "示例数据",
      "url": "modules/demo/items",
      "permission": "module.demo.item",
      "sort": 10
    }
  ]
}

二、权限命名

权限命名按来源分组：

module.demo.item
module.demo.item.create
module.demo.item.update
module.demo.item.delete

plugin.demo.settings
plugin.demo.settings.update

页面权限控制入口，动作权限控制保存、删除、排序和状态切换。

三、列表接口

列表接口返回结构化 JSON：

return response()->json([
    'code' => 0,
    'msg' => '',
    'count' => $page->total(),
    'data' => $page->items(),
]);

列表只返回当前页需要的轻字段。详情、正文、大 JSON 和附件组进入编辑接口或详情接口再读取。

四、编辑页

复杂编辑推荐使用独立编辑页，列表页只负责新增、编辑、删除、排序和状态。

独立编辑页适合：

• Markdown 文档。
• 富文本内容。
• 多 Tab 表单。
• 复杂配置。
• 需要预览的页面。

五、保存接口

保存接口必须做验证：

$data = $request->validate([
    'title' => ['required', 'string', 'max:120'],
    'sort' => ['nullable', 'integer', 'min:0'],
    'status' => ['nullable', 'boolean'],
]);

不要信任前端传入的 ID、权限、排序字段和状态值。

六、状态和排序

状态开关和排序保存属于高频操作，应单独提供轻量接口。保存后如果会影响前台输出、菜单或模板标签结果，应清理对应缓存。

七、资源引用

模块后台资源发布到：

public/assets/modules/{code}/

插件后台资源发布到：

public/assets/plugins/{code}/

源码仍保留在模块或插件目录，不把 public 发布目录当源码维护入口。

八、禁止事项

• 不在后台页面直接输出未转义用户输入。
• 不绕过管理员认证和权限校验。
• 不把模块业务页面模板放进核心后台模板目录。
• 不为单个模块改公共后台 JS，除非是在补通用能力。
• 不让插件禁用后后台菜单仍指向不可用控制器。