最小全栈插件

exp_issue_demo/                           # 工作区根，以下命令均在这里运行
├── package.json
├── packages.json
└── exp_issue_demo/                       # 能力工程目录
    ├── capabilities.json
    ├── frontend/exp_issue_demo_frontend/
    │   ├── fh2-plugin.json
    │   ├── public/icons/issue-board.svg
    │   └── src/
    │       ├── plugin.ts
    │       ├── shared/backend.ts
    │       └── views/issue-panel/{contract.ts,index.ts,IssuePanel.vue}
    ├── frontend/exp_issue_demo_issues/    # 生成的另一示例，本页保留不改
    ├── backend/exp_issue_demo_backend/
    │   ├── fh2-plugin.json
    │   ├── schema.sql
    │   ├── handlers/issue/{create.ts,list.ts,acknowledge.ts,resolve.ts}
    │   ├── events/photo-created.ts
    │   ├── fixtures/photo-created.body.json # 正式消息体示意，不用于本地模拟器成功验收
    │   ├── types/                       # generate 生成，勿手改
    │   └── tsconfig.json
    └── mock/
        ├── fixtures/default.json
        └── events/photo-created.json    # 独立本地注入信封，当前消费仍受阻

{
  "pluginId": "exp_issue_demo_backend",
  "name": "现场问题示例后端",
  "version": "0.1.0",
  "allowlist": ["data:read", "data:write"],
  "flows": [],
  "connections": [],
  "scripts": [],
  "events": [
    {
      "type": "media.photo_created",
      "consumer": [ { "handler": "events/photo-created.ts", "entry": "onPhotoCreated" } ]
    }
  ]
}

// exp_issue_demo/backend/exp_issue_demo_backend/handlers/issue/create.ts
import type { HandlerCtx } from 'fh2-plugin-sdk/backend'

interface RecordInput { readonly [key: string]: unknown }

export function create (input: RecordInput, _ctx: HandlerCtx) {
  const title = String(input.title || '').trim()
  if (!title) {
    throw { code: 'INVALID_ARGUMENT', message: 'title 不能为空' }
  }
  const severity = ['low', 'medium', 'high'].indexOf(String(input.severity)) >= 0 ? String(input.severity) : 'medium'

  // 按标题去重：重复提交不会产生第二条记录，返回已有记录
  // created_at 由平台自动维护，不要自己写（它是保留字段）
  const saved = store.createIfAbsent('issue', {
    title: title,
    description: String(input.description || ''),
    severity: severity,
    status: 'new',
    evidence_file_id: ''
  }, ['title'])

  if (!saved.ok) {
    throw saved.error
  }
  return { id: saved.data.record.id, created: saved.data.created }
}

// exp_issue_demo/backend/exp_issue_demo_backend/handlers/issue/list.ts
import type { HandlerCtx } from 'fh2-plugin-sdk/backend'

interface RecordInput { readonly [key: string]: unknown }

export function list (input: RecordInput, _ctx: HandlerCtx) {
  // 不传状态时保留全部状态，使已签收记录仍可在界面点完成
  const status = String(input.status || '').trim()
  const result = store.query('issue', status ? { status: { eq: status } } : {},
    { orderBy: [{ field: 'createdAt', dir: 'desc' }], limit: 20 })
  if (!result.ok) {
    throw result.error
  }
  return { list: result.data.list, total: result.data.total }
}

// exp_issue_demo/backend/exp_issue_demo_backend/handlers/issue/acknowledge.ts
import type { HandlerCtx } from 'fh2-plugin-sdk/backend'

interface RecordInput { readonly [key: string]: unknown }

export function acknowledge (input: RecordInput, _ctx: HandlerCtx) {
  const id = String(input.id || '').trim()
  if (!id) {
    throw { code: 'INVALID_ARGUMENT', message: 'id 不能为空' }
  }

  // 条件更新：只有还是 new 才允许签收，affected === 1 才算成功
  const updated = store.update('issue',
    { id: { eq: id }, status: { eq: 'new' } },
    { status: 'acknowledged' })
  if (!updated.ok) {
    throw updated.error
  }
  if (updated.data.affected === 0) {
    throw { code: 'NOT_FOUND', message: '问题不存在或已被签收' }
  }
  return { id: id, status: 'acknowledged' }
}

// exp_issue_demo/backend/exp_issue_demo_backend/handlers/issue/resolve.ts
import type { HandlerCtx } from 'fh2-plugin-sdk/backend'

interface RecordInput { readonly [key: string]: unknown }

export function resolve (input: RecordInput, _ctx: HandlerCtx) {
  const id = String(input.id || '').trim()
  if (!id) {
    throw { code: 'INVALID_ARGUMENT', message: 'id 不能为空' }
  }
  const updated = store.update('issue',
    { id: { eq: id }, status: { eq: 'acknowledged' } },
    { status: 'resolved' })
  if (!updated.ok) {
    throw updated.error
  }
  if (updated.data.affected === 0) {
    throw { code: 'NOT_FOUND', message: '问题不存在或当前状态不可完成' }
  }
  return { id: id, status: 'resolved' }
}

// exp_issue_demo/backend/exp_issue_demo_backend/events/photo-created.ts
import type { EventCtx } from 'fh2-plugin-sdk/backend'

interface RecordInput { readonly [key: string]: unknown }

export function onPhotoCreated (input: RecordInput, _ctx: EventCtx) {
  const fileId = String(input.file_id || '').trim()
  if (!fileId) {
    // 契约错误：消息进死信，不重投
    throw { code: 'INVALID_ARGUMENT', message: 'file_id 不能为空' }
  }

  // 找最新一条已签收的问题
  const found = store.query('issue', { status: { eq: 'acknowledged' } },
    { orderBy: [{ field: 'createdAt', dir: 'desc' }], limit: 1 })
  if (!found.ok) {
    throw found.error
  }
  const issue = found.data.list[0]
  if (issue === undefined) {
    // 没有进行中的问题：消息按正常处理，不挂载
    return { attached: false }
  }

  // 更新条件里带旧值（evidence_file_id 为空）：消息重复投递时第二次 affected=0，不会重复覆盖
  const updated = store.update('issue',
    { id: { eq: issue.id }, evidence_file_id: { eq: '' } },
    { evidence_file_id: fileId })
  if (!updated.ok) {
    throw updated.error
  }
  if (updated.data.affected === 0) {
    // 已经绑过照片（重复投递），幂等命中
    return { attached: false, issue_id: issue.id }
  }
  return { attached: true, issue_id: issue.id }
}

// exp_issue_demo/frontend/exp_issue_demo_frontend/src/shared/backend.ts
import { isPluginError } from 'fh2-plugin-sdk'
import type { JsonValue, PluginContext } from 'fh2-plugin-sdk'

// 注意：这里填后端清单里的 pluginId，不是前端的 id
const BACKEND_PLUGIN_ID = 'exp_issue_demo_backend'

export async function invoke<T> (
  ctx: Pick<PluginContext, 'apiCall'>,
  handler: string,
  input: Record<string, JsonValue>,
  idempotencyKey?: string,
): Promise<T> {
  try {
    const res = await ctx.apiCall<{ code: number; message: string; data: JsonValue }>('/plugin/invoke', {
      method: 'POST',
      body: { pluginId: BACKEND_PLUGIN_ID, handler, input },
      ...(idempotencyKey ? { idempotencyKey } : {}),
    })
    // 只有网关返回 code === 0 才会走到这里
    return res.data as T
  } catch (error) {
    if (isPluginError(error) && error.code === 'PLUGIN_GATEWAY_ERROR') {
      // 本地与目标网关的非零数字码在 detail.gatewayCode；网络或格式错误可能没有该字段
      const detail = (error.detail ?? {}) as { gatewayCode?: number; gatewayMessage?: string }
      throw new Error(`[网关 ${detail.gatewayCode ?? '?'}] ${detail.gatewayMessage ?? error.message}`)
    }
    throw error
  }
}

// exp_issue_demo/frontend/exp_issue_demo_frontend/src/plugin.ts
import { createViewState, definePlugin } from 'fh2-plugin-sdk'
import { issuePanelView } from './views/issue-panel/contract'
import { invoke } from './shared/backend'

export interface IssuePanelState {
  readonly list: Array<{ id: string; title: string; severity: string; status: string }>;
  readonly busy: boolean;
  readonly error: string;
}

export default definePlugin({
  async activate (ctx) {
    if (ctx.host.id !== 'cockpit')
      return

    const state = createViewState<IssuePanelState>({ list: [], busy: false, error: '' })

    async function loadRecords () {
      const data = await invoke<{ list: IssuePanelState['list'] }>(ctx, 'issue.list', {})
      state.update(current => ({ ...current, list: data.list }))
    }

    async function runAction (action: () => Promise<void>): Promise<void> {
      state.update(current => ({ ...current, busy: true, error: '' }))
      try {
        await action()
      } catch (error) {
        state.update(current => ({ ...current, error: error instanceof Error ? error.message : '请求失败' }))
      } finally {
        state.update(current => ({ ...current, busy: false }))
      }
    }

    await issuePanelView.handle(ctx, {
      state,
      methods: {
        refresh: () => runAction(loadRecords),
        createIssue: (input: { title: string; description: string; severity: string }) => runAction(async () => {
          const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify([input.title, input.description])))
          const key = Array.from(new Uint8Array(hash), byte => byte.toString(16).padStart(2, '0')).join('')
          await invoke(ctx, 'issue.create', input, `issue-create:${key}`)
          await loadRecords()
        }),
        acknowledge: (input: { id: string }) => runAction(async () => {
          await invoke(ctx, 'issue.acknowledge', { id: input.id }, `issue-ack:${input.id}`)
          await loadRecords()
        }),
        resolve: (input: { id: string }) => runAction(async () => {
          await invoke(ctx, 'issue.resolve', { id: input.id }, `issue-resolve:${input.id}`)
          await loadRecords()
        }),
      },
    })

    await ctx.extensions.contribute('issue-panel', {
      visible: true,
      label: '现场问题',
      icon: 'issue-board', // 图标必须在插件清单 contributes.icons 里声明，否则渲染为空
      render: () => issuePanelView.get(ctx),
    })
  },
})

import { describe, expect, it, vi } from 'vitest'
import type { PluginContext } from 'fh2-plugin-sdk'
import plugin from '../src/plugin'

const captured = vi.hoisted(() => ({ session: undefined as any }))
vi.mock('../src/views/issue-panel/contract', () => ({ issuePanelView: {
  handle: async (_ctx: unknown, session: unknown) => {
    captured.session = session
  },
  get: () => ({}),
} }))

describe('请求失败反馈', () => {
  it('刷新、签收和完成失败均写入状态并退出忙碌，不向 Vue 事件抛未处理拒绝', async () => {
    const apiCall = vi.fn().mockRejectedValue(new Error('请求失败'))
    await plugin.activate({ host: { id: 'cockpit' }, apiCall, extensions: { contribute: vi.fn().mockResolvedValue({}) } } as unknown as PluginContext)
    await expect(captured.session.methods.refresh()).resolves.toBeUndefined()
    expect(captured.session.state.get()).toMatchObject({ busy: false, error: '请求失败' })
    await expect(captured.session.methods.acknowledge({ id: 'test' })).resolves.toBeUndefined()
    await expect(captured.session.methods.resolve({ id: 'test' })).resolves.toBeUndefined()
    expect(captured.session.state.get()).toMatchObject({ busy: false, error: '请求失败' })
  })
})

{
  "id": "exp_issue_demo_frontend",
  "name": "现场问题示例",
  "version": "0.1.0",
  "entry": "./plugin.js",
  "permissions": ["platform:http"],
  "extensions": [
    { "id": "hello-action", "point": "cockpit.ui.toolbar-actions" },
    { "id": "hello-panel", "point": "cockpit.ui.left-panel" },
    { "id": "issue-panel", "point": "cockpit.ui.left-panel" }
  ],
  "views": {
    "hello-panel": { "entry": "./views/hello-panel.js" },
    "issue-panel": { "entry": "./views/issue-panel.js" }
  },
  "contributes": {
    "icons": [{ "id": "issue-board", "src": "./icons/issue-board.svg" }]
  }
}

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="5" y="3" width="14" height="18" rx="2"/><path d="M9 8h6M9 12h6M9 16h4"/></svg>

import { definePluginView } from 'fh2-plugin-sdk/view'
import type { PluginViewClient } from 'fh2-plugin-sdk/view'
import type { IssuePanelState } from '../../plugin'

interface IssuePanelContract {
  state: IssuePanelState;
  methods: {
    refresh: () => Promise<void>;
    createIssue: (input: { title: string; description: string; severity: string }) => Promise<void>;
    acknowledge: (input: { id: string }) => Promise<void>;
    resolve: (input: { id: string }) => Promise<void>;
  };
}

export const issuePanelView = definePluginView<IssuePanelContract>('issue-panel')
export type IssuePanelClient = PluginViewClient<IssuePanelContract>

import { createApp } from 'vue'
import { defineView } from 'fh2-plugin-sdk/view'
import { issuePanelView } from './contract'
import IssuePanel from './IssuePanel.vue'

export default defineView({
  mount (ctx) {
    const client = issuePanelView.client(ctx.port)
    const app = createApp(IssuePanel, { client })
    app.mount(ctx.mountElement)
    return {
      dispose () {
        app.unmount()
        client.dispose()
      },
    }
  },
})

<template>
  <section class="issue-panel" data-plugin-view="issue-panel">
    <h2>现场问题</h2>
    <form @submit.prevent="submit">
      <input v-model="title" aria-label="问题标题" placeholder="问题标题">
      <input v-model="description" aria-label="问题描述" placeholder="问题描述">
      <select v-model="severity" aria-label="严重程度">
        <option value="low">
          低
        </option>
        <option value="medium">
          中
        </option>
        <option value="high">
          高
        </option>
      </select>
      <button type="submit" :disabled="state.busy">
        上报问题
      </button>
      <button type="button" @click="client.refresh()">
        刷新列表
      </button>
    </form>
    <p v-if="state.error" class="error" role="alert">
      {{ state.error }}
    </p>
    <p v-if="state.list.length === 0" class="empty">
      暂无现场问题
    </p>
    <ul>
      <li v-for="issue in state.list" :key="issue.id" :data-issue-id="issue.id" :data-issue-status="issue.status">
        <strong>{{ issue.title }}</strong>
        <small>{{ statusLabel[issue.status] ?? issue.status }}</small>
        <button v-if="issue.status === 'new'" type="button" @click="client.acknowledge({ id: issue.id })">
          签收
        </button>
        <button v-if="issue.status === 'acknowledged'" type="button" @click="client.resolve({ id: issue.id })">
          完成
        </button>
      </li>
    </ul>
  </section>
</template>

<script setup lang="ts">
import { onMounted, onUnmounted, ref } from 'vue'
import type { IssuePanelState } from '../../plugin'
import type { IssuePanelClient } from './contract'

const props = defineProps<{ client: IssuePanelClient }>()
const client = props.client
const state = ref<IssuePanelState>({ list: [], busy: false, error: '' })
const title = ref('')
const description = ref('')
const severity = ref('medium')
const statusLabel: Record<string, string> = { new: '待签收', acknowledged: '处理中', resolved: '已完成' }
const subscription = client.state.subscribe((next) => {
  state.value = next
})
onUnmounted(() => subscription.dispose())
onMounted(() => {
  void client.refresh()
})

function submit () {
  void client.createIssue({ title: title.value.trim(), description: description.value.trim(), severity: severity.value })
}
</script>

<style scoped>
.issue-panel { box-sizing: border-box; width: 100%; padding: 16px; color: #fff; background: #1f1f1f; font: 13px/1.5 "PingFang SC", sans-serif; }
h2 { margin: 0 0 12px; font-size: 16px; }
form { display: flex; flex-wrap: wrap; gap: 8px; }
input, select { box-sizing: border-box; min-width: 0; width: 100%; padding: 6px 8px; color: #fff; background: #2c2c2c; border: 1px solid #555; border-radius: 4px; }
button { padding: 6px 10px; color: #fff; background: #0075ff; border: 0; border-radius: 4px; cursor: pointer; }
button:disabled { opacity: .5; cursor: default; }
ul { padding: 0; list-style: none; }
li { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; padding: 10px 0; border-bottom: 1px solid #444; }
li strong { overflow-wrap: anywhere; }
small, .empty { color: #aaa; }
.error { color: #ff8a92; }
</style>

import { readdirSync } from 'node:fs'
import { resolve } from 'node:path'
import { describe, expect, it } from 'vitest'
import { loadManifest } from 'fh2-plugin-toolchain'

const manifest = loadManifest(resolve('fh2-plugin.json'))

describe('现场问题插件契约', () => {
  it('清单界面与源目录一致', () => {
    const directories = readdirSync(resolve('src/views'), { withFileTypes: true })
      .filter(entry => entry.isDirectory())
      .map(entry => entry.name)
      .sort()
    expect(Object.keys(manifest.views ?? {}).sort()).toEqual(directories)
  })

  it('声明左侧面板、HTTP 权限和实际图标', () => {
    expect(manifest.extensions).toContainEqual({ id: 'issue-panel', point: 'cockpit.ui.left-panel' })
    expect(manifest.views).toHaveProperty('issue-panel.entry', './views/issue-panel.js')
    expect(manifest.permissions).toContain('platform:http')
    expect(manifest.contributes?.icons).toContainEqual({ id: 'issue-board', src: './icons/issue-board.svg' })
    expect(manifest).not.toHaveProperty('manifestVersion')
  })
})

{
  "event_id": "photo-event-001",
  "file_id": "photo-demo-001"
}

{
  "id": "photo-event-001",
  "type": "media.photo_created",
  "data": { "file_id": "photo-demo-001" }
}

{ "entities": { "issue": [] } }

{
  "code": 40006,
  "message": "INVALID_ARGUMENT: file_id 不能为空",
  "data": null
}