# 插件控制面 UI 信息架构

## 目标

插件控制面是统一的插件运维后台，不是 Core 主站的复制品。订阅是安装后的业务模块，不是第二个后台系统。界面按任务拆分页面，避免把安装、版本、配置、菜单、订阅和审计动作堆在同一张卡片或同一个长页面中。

## 页面层级

```text
插件管理
├── 概览                         # 控制面总览，不执行高风险操作
├── 已安装插件                   # 插件摘要列表，只保留常用主操作
│   └── 插件详情/:id
│       ├── 运行概况             # 健康、状态、端点、兼容性
│       ├── 版本与升级           # revision、升级、回滚
│       ├── 配置                 # 服务地址、菜单地址、密钥提示
│       ├── 菜单接入             # 预览和应用管理员菜单
│       └── 操作历史             # 当前插件的审计记录
├── 插件市场                     # 受控目录元数据和入库入口
└── 操作记录                     # 全局操作审计和操作详情

已安装并启用的业务模块
└── 订阅管理                     # 复用控制面会话，不提供第二个登录页
    ├── 概览
    ├── 套餐
    ├── 用户订阅
    └── 操作记录
```

页面使用 hash 路由，便于刷新、复制链接和从 Core 自定义菜单直接打开：

```text
#/overview
#/plugins
#/plugins/{plugin_id}/overview
#/plugins/{plugin_id}/revisions
#/plugins/{plugin_id}/config
#/plugins/{plugin_id}/menu
#/plugins/{plugin_id}/operations
#/marketplace
#/operations
#/modules/subscription/overview
#/modules/subscription/plans
#/modules/subscription/subscriptions
#/modules/subscription/audit
```

hash 只表达页面位置，不承载凭据、Core JWT、Admin Key 或服务密钥。

## 一级页面职责

### 概览

只展示已登记、运行中、待启用和需要关注的数量，以及最近操作和生命周期提示。概览不直接承载上传、启停、回滚或卸载按钮，避免误操作；通过“管理插件”和“查看全部”进入专门页面。

### 已安装插件

每个插件条目只显示名称、版本、状态、Core 兼容性、活动 revision 和更新时间。条目保留一个生命周期主操作（启用或停用）和“查看详情”；升级、回滚、菜单和卸载进入“更多操作”菜单，防止按钮挤压或误触。

### 插件详情

详情页的每个二级页签只有一个任务：

- **运行概况**：判断当前是否健康、是否已配置、是否可以启用；错误仅展示脱敏后的最近错误。
- **版本与升级**：查看 revision、活动版本和校验时间；上传升级包、选择回滚版本。
- **配置**：读取和保存服务/菜单地址；敏感配置仍由服务端加密，页面不回显原值。
- **菜单接入**：查看声明的菜单元数据，先预览再应用，不把菜单操作混在生命周期按钮中。
- **操作历史**：只看当前插件关联的操作，操作 ID 可以打开详情。

### 插件市场

市场只显示受控索引提供的名称、版本、发布者、兼容性、发布时间和归档哈希。安装动作的语义是“下载并校验后入库”，完成后插件处于待启用状态；已经登记的插件跳转到版本页，不在市场卡片上直接覆盖现有版本。

### 操作记录

提供按插件和操作类型筛选的全局审计视图。列表展示操作、插件、结果和时间；操作 ID 进入详情弹窗，详情中包含请求 ID、状态和脱敏错误。

### 订阅业务模块

订阅模块只有在 `qiu.subscription-admin` 安装、启用并通过健康检查后才出现在导航中。它沿用 Plugin Admin 的管理员会话、CSRF、主题和响应式 Shell；模块页面不显示登录表单、不创建 Cookie，也不重复调用 Core 登录。套餐、用户订阅和余额数据仍从模块 BFF 读取，Core 继续是权威来源。

## 导航与响应式规则

- 桌面端使用左侧一级导航，内容区只显示当前路由页面；导航项同时显示页面名称和一句职责提示。
- 移动端（宽度不超过 760px）将一级导航变为抽屉，通过“菜单”按钮打开；打开导航不会改变页面宽度，也不会让整个页面依赖横向滚动。
- 详情页签只允许页签条自身横向滚动，内容区和页面主体始终保持 `scrollWidth <= innerWidth`。
- 桌面端统计卡片四列，中等宽度两列，手机端仍使用两列但缩小内边距；内容面板在中等宽度以下改为单列。
- 列表卡片的次要动作进入操作菜单；移动端按钮按可用宽度换行，不使用固定宽度挤压文字。
- 审计表格在手机端保留最小可读列宽，仅表格容器横向滚动，页面本身不横向溢出。
- 页面、卡片和表单使用统一 4px/6px 圆角、36px 控件高度和统一边距；页面不会用额外的局部颜色覆盖 Core 主题。

## 数据加载与权限

- 页面数据按路由按需加载：概览加载插件和审计，市场加载插件和市场索引，操作记录加载插件和审计，详情加载指定插件和审计；订阅模块只在启用后加载自己的数据。
- 所有请求继续通过插件后端会话和 CSRF；浏览器不会直接调用 Core，也不会收到 Core token 或 Admin Key。
- 订阅模块请求只能沿用控制面会话，不允许出现第二个登录 endpoint 或模块级会话。
- 页面上的按钮隐藏只改善交互，真正的管理员权限、生命周期状态和幂等校验仍由插件后端负责。
- mutation 返回 operation ID 后，前端短暂读取操作详情，再刷新当前路由；操作记录页面始终保留最终审计结果。

## 验收标准

1. 登录后默认进入概览，导航可进入控制面页面和已启用的业务模块，浏览器刷新后 hash 路由不丢失。
2. 已安装列表不再展示所有生命周期按钮；插件详情的五个二级页签分别承担单一职责。
3. 市场入库、配置、启停、升级、回滚、菜单和卸载接口行为与现有后端契约一致。
4. 425px、900px、1440px 视口没有页面级横向溢出；移动端导航、详情页签和操作菜单可触达。
5. 页面 DOM、JSON 响应、URL、错误提示和操作详情不出现 Core JWT、Admin Key、密码或服务密钥。