插件把平台之外的 Web 页面接入为侧栏入口。平台以 iframe 加载插件地址，并在地址后追加 api 查询参数（值为平台自身地址）；插件页面据此调用平台接口。插件的鉴权与数据访问由插件页面自身实现，平台按角色与项目控制入口的可见范围。
使用前提
| 项 | 内容 |
|---|
| 菜单入口 | 管理 → 插件 |
| 路由 | /plugins |
| 页面权限 | 「查看插件」 |
| 接口权限 | 「查看插件」（列表与详情）、「管理插件」（创建、编辑、删除） |
| 角色 | 管理员与项目经理可创建、编辑；删除按钮仅管理员可见 |
| 依赖 | 插件页面已部署为可通过地址访问的独立页面 |
插件配置与机制
插件字段
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|
| 插件名称 | 文本 | 是 | 无 | 唯一；作为侧栏入口名称 |
| 插件描述 | 文本 | 否 | 空 | 最大 500 字符 |
| 插件地址 | 文本 | 是 | 无 | 完整地址，如 https://example.com/plugin |
| 菜单组 | 枚举 | 是 | 数据 | 数据、模型、管理三组 |
| 激活 | 开关 | 否 | 开启 | 关闭后入口从侧栏移除，页面提示已停用 |
| 对所有项目开放 | 开关 | 否 | 关闭 | 开启后所有项目可见 |
| 项目权限 | 多选 | 条件 | 空 | 未开启全局时必填，仅在所选项目内可见 |
| 角色权限 | 多选 | 否 | 空 | 入口仅对所选角色显示，为空时任何角色都看不到入口 |
插件类型
插件按两个维度分类。
| 维度 | 取值 | 作用范围 |
|---|
| 菜单组 | 数据、模型、管理 | 决定入口出现在侧栏的哪个分组 |
| 项目范围 | 全局、项目 | 全局对所有项目开放；项目仅在所选项目内可见 |
插件机制
| 环节 | 行为 |
|---|
| 菜单入口生成 | 插件同时满足「激活」「角色包含当前用户」「全局或所属项目在用户可见项目内」时，入口出现在对应菜单组 |
| 打开方式 | 点击侧栏入口打开 /plugins/{id}，平台以 iframe 加载插件地址 |
| 参数传递 | 平台在插件地址后追加 api=<平台地址>，插件页面读取该参数作为接口基址 |
| 停用行为 | 插件停用后入口从侧栏移除；已打开页面提示「该插件已停用」 |
自主开发
插件是独立部署的 Web 页面，开发与发布在平台之外完成。
- 实现一个可通过 HTTPS 访问的页面，作为插件页面。
- 读取地址栏的
api 查询参数，作为平台接口基址。
- 以该基址调用平台 RESTful 接口，并在跨域请求中携带会话凭据。
- 在插件管理中创建插件，填写页面地址、菜单组、角色与项目范围，保存并启用。
约束与限制
| 项 | 取值 | 说明 |
|---|
| 名称唯一 | 同名插件不可重复创建 | 保存时校验 |
| 描述长度 | ≤ 500 字符 | 超长拒绝保存 |
| 地址格式 | 必须为合法完整地址 | 校验失败拒绝保存 |
| 角色权限为空 | 入口对任何角色都不显示 | 至少选择一个角色 |
| 项目范围 | 非全局插件需至少一个项目 | 否则用户看不到入口 |
| 删除方式 | 软删除 | 管理员操作 |
| 菜单更新 | 修改插件后刷新当前会话；其他用户重新登录后生效 | 入口按会话生成 |
失败处理
| 现象 | 可能原因 | 处置 | 责任方 |
|---|
| 插件列表为空 | 无插件，或当前账号无可见项目 | 创建插件，或将插件设为对所有项目开放 | 管理员、项目经理 |
| 保存提示名称已存在 | 插件名称重复 | 更换名称 | 管理员、项目经理 |
| 保存提示地址格式不正确 | 地址不完整或缺少协议 | 填写包含协议的完整地址 | 管理员、项目经理 |
| 创建后侧栏不显示入口 | 未激活、角色权限为空，或项目范围不含当前项目 | 检查激活状态、角色权限与项目权限 | 管理员、项目经理 |
| 打开提示「该插件已停用」 | 插件处于停用状态 | 启用插件 | 管理员、项目经理 |
| 页面空白或加载失败 | 插件页面不可达，或页面禁止被 iframe 嵌入 | 确认插件页面可访问并允许被嵌入 | 插件开发者、管理员 |
相关页面
| 页面 | 用途 |
|---|
| 模块权限 | 配置 「查看插件」 与 「管理插件」 |
| 项目 | 维护插件可见的项目 |
| 用户 | 分配角色与模块权限 |
| 系统设置 | 系统参数与菜单相关配置 |