koishi-plugin-media-luna 0.0.1

package/client/README.md

@@ -0,0 +1,558 @@
+# Media Luna WebUI 前端需求
+
+基于 Koishi Console 的 WebUI 前端，使用 Vue 3 + TypeScript。
+
+## 技术栈
+
+- Vue 3 Composition API
+- TypeScript
+- @koishijs/client（Console 客户端库）
+- Element Plus（可选，Koishi Console 自带基础组件）
+- 样式必须能支持Koishi自带的主题切换
+## 页面结构
+
+```text
+client/
+├── index.ts                 # 前端入口
+├── components/              # 公共组件
+│   ├── TagInput.vue         # 标签输入组件
+│   ├── JsonEditor.vue       # JSON 编辑器
+│   ├── StatusBadge.vue      # 状态徽章
+│   └── ConfirmDialog.vue    # 确认对话框
+└── pages/
+    ├── index.vue            # 生成面板（主页）
+    ├── channels.vue         # 渠道管理
+    ├── presets.vue          # 预设管理
+    ├── tasks.vue            # 任务中心
+    ├── middlewares.vue      # 中间件配置
+    └── settings.vue         # 全局设置
+```
+
+---
+
+## 页面详细需求
+
+### 1. 生成面板 (index.vue)
+
+**功能**：在 WebUI 中直接生成图片。
+
+**UI 布局**：
+```
+┌─────────────────────────────────────────────────────────┐
+│  渠道选择: [下拉框]        预设选择: [下拉框]             │
+├─────────────────────────────────────────────────────────┤
+│  ┌───────────────────────────────────────────────────┐  │
+│  │                    提示词输入                      │  │
+│  │                   (textarea)                      │  │
+│  └───────────────────────────────────────────────────┘  │
+├─────────────────────────────────────────────────────────┤
+│  附件上传: [拖拽区域 / 点击上传]                         │
+│  已上传: [图片预览1] [图片预览2] [×删除]                 │
+├─────────────────────────────────────────────────────────┤
+│  高级参数: [展开/收起]                                  │
+│  ├─ 参数1: [输入框]                                    │
+│  └─ 参数2: [输入框]                                    │
+├─────────────────────────────────────────────────────────┤
+│               [ 预览参数 ]    [ 生成 ]                   │
+├─────────────────────────────────────────────────────────┤
+│  生成结果:                                              │
+│  ┌─────────┐ ┌─────────┐                               │
+│  │  图片1   │ │  图片2   │                              │
+│  └─────────┘ └─────────┘                               │
+│  耗时: 3.2s  任务ID: 123                                │
+└─────────────────────────────────────────────────────────┘
+```
+
+**交互逻辑**：
+1. 渠道选择后，根据渠道标签筛选可用预设（调用 `presets/matching`）
+2. 选择预设后，预设的 `promptTemplate` 显示在提示词区域（`{{userText}}` 高亮）
+3. 点击"预览参数"调用 `generate/preview`，显示最终 prompt
+4. 点击"生成"调用 `generate`，显示 loading，完成后展示图片
+5. 生成失败时显示错误信息
+
+**API 调用**：
+- `media-luna/channels/list` - 获取渠道列表
+- `media-luna/presets/matching` - 获取匹配预设
+- `media-luna/connectors/fields` - 获取连接器参数定义（用于高级参数）
+- `media-luna/generate/preview` - 预览
+- `media-luna/generate` - 执行生成
+
+---
+
+### 2. 渠道管理 (channels.vue)
+
+**功能**：CRUD 渠道配置。
+
+**UI 布局**：
+```
+┌─────────────────────────────────────────────────────────┐
+│  [ + 新建渠道 ]    搜索: [______]    标签筛选: [多选]     │
+├─────────────────────────────────────────────────────────┤
+│  ┌─────────────────────────────────────────────────────┐│
+│  │ 表格                                                ││
+│  │ ┌────┬────────┬──────────┬──────┬────────┬───────┐ ││
+│  │ │启用│  名称   │  连接器   │ 标签 │ 创建时间 │ 操作  │ ││
+│  │ ├────┼────────┼──────────┼──────┼────────┼───────┤ ││
+│  │ │ ✓  │ dalle3 │ DALL-E   │ img  │ 12-01  │编辑|删除││
+│  │ │ ✗  │ sd-xl  │ Stable.. │ img  │ 12-02  │编辑|删除││
+│  │ └────┴────────┴──────────┴──────┴────────┴───────┘ ││
+│  └─────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────┘
+```
+
+**编辑对话框**：
+```
+┌─────────────────────────────────────────────┐
+│  新建/编辑渠道                         [×]  │
+├─────────────────────────────────────────────┤
+│  基本信息                                   │
+│  ├─ 名称*: [____________] (唯一标识)        │
+│  ├─ 显示名称: [____________]                │
+│  ├─ 启用: [开关]                            │
+│  └─ 标签: [标签输入组件]                    │
+├─────────────────────────────────────────────┤
+│  连接器配置                                 │
+│  ├─ 连接器*: [下拉选择] → 动态加载字段      │
+│  ├─ API URL*: [____________]                │
+│  ├─ API Key*: [____________]                │
+│  └─ Model: [下拉选择]                       │
+├─────────────────────────────────────────────┤
+│  中间件覆盖 [展开/收起]                     │
+│  ├─ 计费: { ... }                          │
+│  └─ 预设: { ... }                          │
+├─────────────────────────────────────────────┤
+│                     [取消]  [保存]          │
+└─────────────────────────────────────────────┘
+```
+
+**交互逻辑**：
+1. 表格支持快速切换启用状态（调用 `channels/toggle`）
+2. 选择连接器后，动态加载该连接器的字段定义（`connectors/fields`）
+3. 删除前弹出确认对话框
+4. 表格支持按标签筛选
+
+**API 调用**：
+- `media-luna/channels/list`
+- `media-luna/channels/create`
+- `media-luna/channels/update`
+- `media-luna/channels/delete`
+- `media-luna/channels/toggle`
+- `media-luna/channels/tags`
+- `media-luna/connectors/list`
+- `media-luna/connectors/fields`
+
+---
+
+### 3. 预设管理 (presets.vue)
+
+**功能**：管理 prompt 预设模板。
+
+**UI 布局**：
+```
+┌─────────────────────────────────────────────────────────┐
+│  [ + 新建预设 ]    来源: [全部|用户|API]    标签: [多选] │
+├─────────────────────────────────────────────────────────┤
+│  卡片网格布局                                           │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
+│  │  🎨 写实风格   │  │  ✨ 动漫风格  │  │  🖼 油画风格  │  │
+│  │  ────────────│  │  ────────────│  │  ────────────│  │
+│  │  realistic.. │  │  anime sty.. │  │  oil paint.. │  │
+│  │  ────────────│  │  ────────────│  │  ────────────│  │
+│  │  [用户] [img] │  │  [API] [img] │  │  [用户] [art] │  │
+│  │  [编辑][复制] │  │  [只读][复制] │  │  [编辑][删除] │  │
+│  └──────────────┘  └──────────────┘  └──────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+**编辑对话框**：
+```
+┌─────────────────────────────────────────────┐
+│  新建/编辑预设                         [×]  │
+├─────────────────────────────────────────────┤
+│  名称*: [____________]                      │
+│  显示名称: [____________]                   │
+│  启用: [开关]                               │
+│  标签: [标签输入组件]                       │
+├─────────────────────────────────────────────┤
+│  提示词模板*:                               │
+│  ┌─────────────────────────────────────────┐│
+│  │ realistic photo, {{userText}}, high    ││
+│  │ quality, 8k                             ││
+│  └─────────────────────────────────────────┘│
+│  提示: 使用 {{userText}} 作为用户输入占位符  │
+├─────────────────────────────────────────────┤
+│  参考图片:                                  │
+│  [拖拽上传区域]                             │
+│  [图片1] [图片2] [×]                        │
+├─────────────────────────────────────────────┤
+│  参数覆盖 (JSON):                           │
+│  ┌─────────────────────────────────────────┐│
+│  │ { "steps": 30, "cfg_scale": 7 }        ││
+│  └─────────────────────────────────────────┘│
+├─────────────────────────────────────────────┤
+│                     [取消]  [保存]          │
+└─────────────────────────────────────────────┘
+```
+
+**交互逻辑**：
+1. API 来源的预设只能查看和复制，不能编辑/删除
+2. 复制预设后自动打开编辑对话框（来源改为 user）
+3. 卡片显示预设的 promptTemplate 预览（截断显示）
+4. 支持按来源和标签筛选
+
+**API 调用**：
+- `media-luna/presets/list`
+- `media-luna/presets/create`
+- `media-luna/presets/update`
+- `media-luna/presets/delete`
+- `media-luna/presets/toggle`
+- `media-luna/presets/copy`
+- `media-luna/presets/tags`
+
+---
+
+### 4. 任务中心 (tasks.vue)
+
+**功能**：查看生成任务历史和统计。
+
+**UI 布局**：
+```
+┌─────────────────────────────────────────────────────────┐
+│  统计概览                                               │
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
+│  │  总任务  │  │  成功    │  │  失败    │  │ 成功率   │   │
+│  │  1234   │  │  1100   │  │  134    │  │ 89.1%   │   │
+│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
+├─────────────────────────────────────────────────────────┤
+│  筛选: 状态[全部▼] 渠道[全部▼]   [ 清理旧任务 ]          │
+├─────────────────────────────────────────────────────────┤
+│  任务列表                                               │
+│  ┌─────────────────────────────────────────────────────┐│
+│  │ #123 | dalle3 | "a cat..." | ✓成功 | 3.2s | 12:30  ││
+│  │ #122 | sd-xl  | "sunset.." | ✗失败 | -    | 12:28  ││
+│  │ #121 | dalle3 | "dog..."   | ●处理中| -   | 12:25  ││
+│  └─────────────────────────────────────────────────────┘│
+├─────────────────────────────────────────────────────────┤
+│  分页: [上一页] 1 2 3 ... [下一页]   共 50 条           │
+└─────────────────────────────────────────────────────────┘
+```
+
+**任务详情对话框**：
+```
+┌─────────────────────────────────────────────┐
+│  任务详情 #123                         [×]  │
+├─────────────────────────────────────────────┤
+│  状态: ✓ 成功                               │
+│  渠道: dalle3                               │
+│  耗时: 3.2s                                 │
+│  创建时间: 2024-12-16 12:30:00              │
+├─────────────────────────────────────────────┤
+│  原始提示词:                                │
+│  a cute cat playing with yarn               │
+├─────────────────────────────────────────────┤
+│  最终提示词:                                │
+│  realistic photo, a cute cat playing        │
+│  with yarn, high quality, 8k                │
+├─────────────────────────────────────────────┤
+│  生成结果:                                  │
+│  ┌─────────┐                               │
+│  │  [图片]  │                               │
+│  └─────────┘                               │
+├─────────────────────────────────────────────┤
+│  中间件日志:                                │
+│  billing: { charged: 100, currency: "点数" }│
+│  preset: { name: "写实", applied: true }   │
+├─────────────────────────────────────────────┤
+│                              [删除]  [关闭] │
+└─────────────────────────────────────────────┘
+```
+
+**交互逻辑**：
+1. 点击任务行展开详情
+2. 支持按状态、渠道筛选
+3. 分页加载（默认 50 条/页）
+4. "清理旧任务"弹出对话框选择保留天数
+5. 失败任务显示错误信息
+
+**API 调用**：
+- `media-luna/tasks/list`
+- `media-luna/tasks/get`
+- `media-luna/tasks/delete`
+- `media-luna/tasks/stats`
+- `media-luna/tasks/cleanup`
+
+---
+
+### 5. 中间件配置 (middlewares.vue)
+
+**功能**：查看和配置中间件。
+
+**UI 布局**：
+```
+┌─────────────────────────────────────────────────────────┐
+│  执行顺序预览                                           │
+│  [prepare] → [billing-pre] → [preset] → [request]      │
+│           → [billing-post] → [task-recorder] → [end]   │
+├─────────────────────────────────────────────────────────┤
+│  中间件列表                                             │
+│  ┌─────────────────────────────────────────────────────┐│
+│  │ ☑ billing-pre     │ 预扣费     │ prepare  │ [配置] ││
+│  │ ☑ preset          │ 预设处理   │ pre-req  │ [配置] ││
+│  │ ☑ billing-post    │ 计费结算   │ finalize │ [配置] ││
+│  │ ☑ task-recorder   │ 任务记录   │ finalize │ [配置] ││
+│  └─────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────┘
+```
+
+**配置对话框**：
+```
+┌─────────────────────────────────────────────┐
+│  配置: billing-pre (预扣费)            [×]  │
+├─────────────────────────────────────────────┤
+│  启用: [开关]                               │
+├─────────────────────────────────────────────┤
+│  配置项（根据 configSchema 动态渲染）:       │
+│  ├─ mode: [pre ▼]                          │
+│  ├─ refundOnFail: [开关]                   │
+│  └─ provider: [koishi-monetary ▼]          │
+├─────────────────────────────────────────────┤
+│           [重置默认]  [取消]  [保存]         │
+└─────────────────────────────────────────────┘
+```
+
+**交互逻辑**：
+1. 执行顺序预览展示拓扑排序结果
+2. 可并行的中间件用同一层显示
+3. 切换启用状态立即生效
+4. 配置表单根据 `configSchema` 动态生成
+
+**API 调用**：
+- `media-luna/middlewares/list`
+- `media-luna/middlewares/get`
+- `media-luna/middlewares/update`
+- `media-luna/middlewares/reset`
+- `media-luna/middlewares/execution-order`
+
+---
+
+### 6. 全局设置 (settings.vue)
+
+**功能**：插件全局配置。
+
+**UI 布局**：
+```
+┌─────────────────────────────────────────────────────────┐
+│  全局设置                                               │
+├─────────────────────────────────────────────────────────┤
+│  计费配置                                               │
+│  ├─ 计费模式: [预扣费 ▼]                               │
+│  ├─ 失败退款: [开关]                                   │
+│  └─ 货币提供者: [koishi-monetary ▼]                    │
+├─────────────────────────────────────────────────────────┤
+│  任务设置                                               │
+│  ├─ 启用任务记录: [开关]                               │
+│  ├─ 自动清理: [开关]                                   │
+│  └─ 保留天数: [30]                                     │
+├─────────────────────────────────────────────────────────┤
+│  预设 API                                              │
+│  ├─ 启用远程预设: [开关]                               │
+│  ├─ API URL: [____________]                            │
+│  └─ 刷新间隔: [3600] 秒                                │
+├─────────────────────────────────────────────────────────┤
+│                                      [保存设置]         │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 公共组件
+
+### TagInput.vue
+
+标签输入组件，支持：
+- 输入框 + 回车添加
+- 标签显示 + 删除按钮
+- 自动补全（基于已有标签）
+
+```vue
+<TagInput v-model="tags" :suggestions="allTags" />
+```
+
+### StatusBadge.vue
+
+状态徽章，根据状态显示不同颜色：
+- `pending` - 灰色
+- `processing` - 蓝色
+- `success` - 绿色
+- `failed` - 红色
+
+```vue
+<StatusBadge :status="task.status" />
+```
+
+### JsonEditor.vue
+
+简易 JSON 编辑器：
+- 语法高亮
+- 格式化
+- 错误提示
+
+```vue
+<JsonEditor v-model="config" :schema="configSchema" />
+```
+
+### ConfirmDialog.vue
+
+确认对话框：
+
+```vue
+<ConfirmDialog
+  v-model:visible="showConfirm"
+  title="确认删除"
+  content="删除后无法恢复，确定要删除吗？"
+  @confirm="handleDelete"
+/>
+```
+
+---
+
+## 入口文件 (index.ts)
+
+```typescript
+import { Context } from '@koishijs/client'
+import Index from './pages/index.vue'
+import Channels from './pages/channels.vue'
+import Presets from './pages/presets.vue'
+import Tasks from './pages/tasks.vue'
+import Middlewares from './pages/middlewares.vue'
+import Settings from './pages/settings.vue'
+
+export default (ctx: Context) => {
+  ctx.page({
+    name: '生成',
+    path: '/media-luna',
+    component: Index,
+  })
+
+  ctx.page({
+    name: '渠道',
+    path: '/media-luna/channels',
+    component: Channels,
+  })
+
+  ctx.page({
+    name: '预设',
+    path: '/media-luna/presets',
+    component: Presets,
+  })
+
+  ctx.page({
+    name: '任务',
+    path: '/media-luna/tasks',
+    component: Tasks,
+  })
+
+  ctx.page({
+    name: '中间件',
+    path: '/media-luna/middlewares',
+    component: Middlewares,
+  })
+
+  ctx.page({
+    name: '设置',
+    path: '/media-luna/settings',
+    component: Settings,
+  })
+}
+```
+
+---
+
+## API 调用封装
+
+建议创建 `api.ts` 封装所有 API 调用：
+
+```typescript
+import { send } from '@koishijs/client'
+
+// 通用响应类型
+interface ApiResponse<T> {
+  success: boolean
+  data?: T
+  error?: string
+}
+
+// 封装调用
+async function call<T>(event: string, params?: any): Promise<T> {
+  const result = await send(event, params) as ApiResponse<T>
+  if (!result.success) {
+    throw new Error(result.error || '请求失败')
+  }
+  return result.data!
+}
+
+// 渠道 API
+export const channelApi = {
+  list: () => call<ChannelConfig[]>('media-luna/channels/list'),
+  get: (id: number) => call<ChannelConfig>('media-luna/channels/get', { id }),
+  create: (data: Partial<ChannelConfig>) => call<ChannelConfig>('media-luna/channels/create', data),
+  update: (id: number, data: Partial<ChannelConfig>) => call<ChannelConfig>('media-luna/channels/update', { id, data }),
+  delete: (id: number) => call<void>('media-luna/channels/delete', { id }),
+  toggle: (id: number, enabled: boolean) => call<void>('media-luna/channels/toggle', { id, enabled }),
+  tags: () => call<string[]>('media-luna/channels/tags'),
+}
+
+// 预设 API
+export const presetApi = {
+  list: (enabledOnly?: boolean) => call<PresetData[]>('media-luna/presets/list', { enabledOnly }),
+  get: (id: number) => call<PresetData>('media-luna/presets/get', { id }),
+  create: (data: Partial<PresetData>) => call<PresetData>('media-luna/presets/create', data),
+  update: (id: number, data: Partial<PresetData>) => call<PresetData>('media-luna/presets/update', { id, data }),
+  delete: (id: number) => call<void>('media-luna/presets/delete', { id }),
+  toggle: (id: number, enabled: boolean) => call<void>('media-luna/presets/toggle', { id, enabled }),
+  copy: (id: number) => call<PresetData>('media-luna/presets/copy', { id }),
+  matching: (channelId: number) => call<PresetData[]>('media-luna/presets/matching', { channelId }),
+}
+
+// 任务 API
+export const taskApi = {
+  list: (params?: TaskListParams) => call<TaskListResult>('media-luna/tasks/list', params),
+  get: (id: number) => call<TaskData>('media-luna/tasks/get', { id }),
+  delete: (id: number) => call<void>('media-luna/tasks/delete', { id }),
+  stats: (channelId?: number) => call<TaskStats>('media-luna/tasks/stats', { channelId }),
+  cleanup: (days?: number) => call<CleanupResult>('media-luna/tasks/cleanup', { days }),
+}
+
+// 中间件 API
+export const middlewareApi = {
+  list: () => call<MiddlewareInfo[]>('media-luna/middlewares/list'),
+  get: (name: string) => call<MiddlewareDetail>('media-luna/middlewares/get', { name }),
+  update: (name: string, data: MiddlewareUpdateData) => call<void>('media-luna/middlewares/update', { name, data }),
+  reset: (name: string) => call<void>('media-luna/middlewares/reset', { name }),
+  executionOrder: () => call<ExecutionLevel[]>('media-luna/middlewares/execution-order'),
+}
+
+// 连接器 API
+export const connectorApi = {
+  list: () => call<ConnectorInfo[]>('media-luna/connectors/list'),
+  get: (id: string) => call<ConnectorDetail>('media-luna/connectors/get', { id }),
+  fields: (id: string) => call<FieldDefinition[]>('media-luna/connectors/fields', { id }),
+}
+
+// 生成 API
+export const generateApi = {
+  generate: (params: GenerateParams) => call<GenerationResult>('media-luna/generate', params),
+  preview: (params: PreviewParams) => call<PreviewResult>('media-luna/generate/preview', params),
+}
+```
+
+---
+
+## 注意事项
+
+1. **响应式更新**：操作完成后刷新列表数据
+2. **错误处理**：统一 toast 提示错误信息
+3. **加载状态**：异步操作显示 loading
+4. **表单验证**：必填字段、格式校验
+5. **确认操作**：删除等危险操作需二次确认
+6. **权限控制**：API 来源预设不可编辑/删除（前端禁用按钮）