foucui 1.0.1

package/components/QiuBadge/components/BadgeLibraryPanel.vue

@@ -0,0 +1,182 @@
+<template>
+  <div class="badge-library-panel">
+    <qiu-card shadow="never" class="toolbar-card">
+      <label class="upload-btn">
+        <input
+          type="file"
+          accept="image/jpeg,image/png,image/gif,image/webp,image/bmp"
+          class="upload-input"
+          @change="onFileChange"
+        />
+        <qiu-button type="primary" tag="span">上传图片</qiu-button>
+      </label>
+      <span class="hint">上传后可在模板编辑器的「图片库」中选用。</span>
+    </qiu-card>
+
+    <qiu-card v-qiu-loading="loading" shadow="never">
+      <div class="lib-grid">
+        <div v-for="it in list" :key="it.id" class="lib-cell">
+          <img :src="fullUrl(it.url)" alt="" class="thumb" loading="lazy" />
+          <div class="meta" :title="it.orig_name">{{ it.orig_name || '未命名' }}</div>
+          <div class="sub">{{ formatSize(it.size) }} · {{ it.create_time }}</div>
+          <qiu-button type="danger" link size="small" @click="remove(it)">删除</qiu-button>
+        </div>
+      </div>
+      <qiu-empty v-if="!loading && !list.length" description="暂无图片" />
+      <div v-if="total > pageSize" class="pager">
+        <qiu-pagination
+          v-model:current-page="page"
+          :page-size="pageSize"
+          layout="total, prev, pager, next"
+          :total="total"
+          @current-change="load"
+        />
+      </div>
+    </qiu-card>
+
+    <qiu-dialog v-model="deleteConfirmVisible" title="删除确认" width="400px">
+      <p>确定删除「{{ deleteTarget?.orig_name || '该图片' }}」？</p>
+      <template #footer>
+        <qiu-button @click="deleteConfirmVisible = false">取消</qiu-button>
+        <qiu-button type="danger" @click="doRemove">删除</qiu-button>
+      </template>
+    </qiu-dialog>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import { qiuMsg } from '../../QiuMsg'
+import { getBadgeLibraryImages, uploadBadgeLibraryImage, deleteBadgeLibraryImage } from '../api/index'
+import { resolveAssetUrl } from '../shared/assetUrl'
+
+const loading = ref(false)
+const list = ref<any[]>([])
+const total = ref(0)
+const page = ref(1)
+const pageSize = ref(40)
+const deleteConfirmVisible = ref(false)
+const deleteTarget = ref<{ id: number; orig_name?: string } | null>(null)
+
+function fullUrl(path: string) {
+  return resolveAssetUrl(path)
+}
+
+function formatSize(n: unknown) {
+  const b = Number(n) || 0
+  if (b < 1024) return `${b} B`
+  if (b < 1024 * 1024) return `${(b / 1024).toFixed(1)} KB`
+  return `${(b / 1024 / 1024).toFixed(2)} MB`
+}
+
+async function load() {
+  loading.value = true
+  try {
+    const res: any = await getBadgeLibraryImages({ page: page.value, page_size: pageSize.value })
+    list.value = res.data?.list ?? []
+    total.value = Number(res.data?.total ?? 0)
+  } catch {
+    list.value = []
+    total.value = 0
+  } finally {
+    loading.value = false
+  }
+}
+
+async function onFileChange(e: Event) {
+  const input = e.target as HTMLInputElement
+  const file = input.files?.[0]
+  input.value = ''
+  if (!file) return
+  try {
+    await uploadBadgeLibraryImage(file)
+    qiuMsg.success('已上传')
+    page.value = 1
+    await load()
+  } catch {
+    /* */
+  }
+}
+
+function remove(it: { id: number; orig_name?: string }) {
+  deleteTarget.value = it
+  deleteConfirmVisible.value = true
+}
+
+async function doRemove() {
+  const it = deleteTarget.value
+  if (!it) return
+  deleteConfirmVisible.value = false
+  try {
+    await deleteBadgeLibraryImage(Number(it.id))
+    qiuMsg.success('已删除')
+    await load()
+  } catch {
+    /* */
+  }
+}
+
+onMounted(() => load())
+
+defineExpose({ load })
+</script>
+
+<style scoped>
+.badge-library-panel .toolbar-card {
+  margin-bottom: 16px;
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  flex-wrap: wrap;
+}
+.upload-btn {
+  position: relative;
+  display: inline-flex;
+  cursor: pointer;
+}
+.upload-input {
+  position: absolute;
+  width: 0;
+  height: 0;
+  opacity: 0;
+  pointer-events: none;
+}
+.hint {
+  font-size: 13px;
+  color: #909399;
+}
+.lib-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(160px, 1fr));
+  gap: 12px;
+}
+.lib-cell {
+  border: 1px solid #ebeef5;
+  border-radius: 8px;
+  padding: 10px;
+}
+.thumb {
+  width: 100%;
+  height: 120px;
+  object-fit: contain;
+  background: #f5f7fa;
+  border-radius: 6px;
+}
+.meta {
+  font-size: 13px;
+  margin-top: 8px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.sub {
+  font-size: 12px;
+  color: #909399;
+  margin: 4px 0 8px;
+}
+.pager {
+  margin-top: 16px;
+  display: flex;
+  justify-content: flex-end;
+}
+</style>

package/components/QiuBadge/composables/useTableHostHeight.ts

@@ -0,0 +1,53 @@
+import { ref, watch, onUnmounted, nextTick } from 'vue'
+
+/** 测量容器高度供 qiu-table 的 `height` 使用，使表格占满剩余区域。
+ * 使用 ResizeObserver（宿主为表格外层 div，非表格根节点）+ window resize，避免仅靠窗口尺寸遗漏侧栏折叠等变化。 */
+export function useTableHostHeight(minHeight = 160) {
+  const hostRef = ref<HTMLElement | null>(null)
+  const tableHeight = ref(Math.max(minHeight, 200))
+  let raf = 0
+  let ro: ResizeObserver | null = null
+  let removeWindowListener: (() => void) | null = null
+
+  const measure = () => {
+    const el = hostRef.value
+    if (!el) return
+    cancelAnimationFrame(raf)
+    raf = requestAnimationFrame(() => {
+      const h = Math.floor(el.getBoundingClientRect().height)
+      const next = Math.max(minHeight, h)
+      if (Math.abs(next - tableHeight.value) > 1) {
+        tableHeight.value = next
+      }
+    })
+  }
+
+  const cleanup = () => {
+    removeWindowListener?.()
+    removeWindowListener = null
+    ro?.disconnect()
+    ro = null
+  }
+
+  watch(
+    hostRef,
+    (el) => {
+      cleanup()
+      if (!el) return
+      nextTick(() => measure())
+      const onWinResize = () => measure()
+      window.addEventListener('resize', onWinResize, { passive: true })
+      removeWindowListener = () => window.removeEventListener('resize', onWinResize)
+      ro = new ResizeObserver(() => measure())
+      ro.observe(el)
+    },
+    { flush: 'post' }
+  )
+
+  onUnmounted(() => {
+    cleanup()
+    cancelAnimationFrame(raf)
+  })
+
+  return { hostRef, tableHeight, recalcTableHeight: measure }
+}

package/components/QiuBadge/index.ts

@@ -0,0 +1,18 @@
+/**
+ * QiuBadge — 证件 / 桌签制作插件
+ * 源码迁自 zhihui web-admin + shared，先落地再调。
+ */
+/** 编辑器真源在 QiuCanvasKit；此入口保持兼容 */
+export { default as QiuBadgeTemplateEditor } from '../QiuCanvasKit/QiuCanvasEditor.vue'
+export { default as QiuBadgeTemplateList } from './views/BadgeTemplateListView.vue'
+export { default as QiuBadgeManage } from './views/BadgeManageView.vue'
+export { default as QiuBadgeLibrary } from './views/BadgeLibraryView.vue'
+export { default as QiuDeskLabel } from './views/DeskLabelView.vue'
+export { default as QiuDeskLabelTemplateList } from './views/DeskLabelTemplateListView.vue'
+export { default as QiuBadgeTemplateRenderer } from './shared/BadgeTemplateRenderer.vue'
+export { default as QiuBadgeImagePickerDialog } from './components/BadgeImagePickerDialog.vue'
+export { default as QiuBadgeLibraryManagerDialog } from './components/BadgeLibraryManagerDialog.vue'
+export { default as QiuBadgeLibraryPanel } from './components/BadgeLibraryPanel.vue'
+export * from './shared/badgeTemplate'
+export * from './shared/assetUrl'
+export * as QiuBadgeApi from './api/index'

package/components/QiuBadge/shared/BadgeTemplateRenderer.vue

@@ -0,0 +1,32 @@
+<script setup lang="ts">
+/**
+ * 兼容旧名：委托 QiuCanvasRenderer
+ * @author qiuye
+ * @email yjk150@qq.com
+ * @date 2026-08-16
+ */
+import QiuCanvasRenderer from '../../QiuCanvasKit/QiuCanvasRenderer.vue'
+import type { BadgeTemplateDoc } from './badgeTemplate'
+import type { MergeContext } from '../../QiuCanvasKit/types'
+
+defineOptions({ name: 'QiuBadgeTemplateRenderer' })
+
+withDefaults(
+  defineProps<{
+    doc: BadgeTemplateDoc | null
+    mergeData?: MergeContext | Record<string, string>
+    screenScale?: number
+    enableLinks?: boolean
+  }>(),
+  { screenScale: 1, mergeData: () => ({}), enableLinks: false }
+)
+</script>
+
+<template>
+  <QiuCanvasRenderer
+    :doc="(doc as any)"
+    :merge-data="mergeData"
+    :screen-scale="screenScale"
+    :enable-links="enableLinks"
+  />
+</template>

package/components/QiuBadge/shared/assetUrl.ts

@@ -0,0 +1,26 @@
+export function resolveAssetUrl(src: string | null | undefined): string {
+  const value = String(src || '').trim()
+  if (!value) return ''
+  if (/^data:/i.test(value) || /^blob:/i.test(value)) return value
+  if (/^(https?:)?\/\//i.test(value)) {
+    try {
+      const parsed = new URL(value, window.location.origin)
+      if (parsed.pathname.startsWith('/uploads/')) {
+        // Always prefer same-origin uploads path so html2canvas/jsPDF can render images
+        // without being blocked by cross-origin resource restrictions in production.
+        return `${parsed.pathname}${parsed.search}${parsed.hash}`
+      }
+    } catch {}
+    return value
+  }
+  if (value.startsWith('/uploads/')) {
+    return value
+  }
+
+  const raw = import.meta.env.VITE_API_BASE_URL
+  const apiBase = typeof raw === 'string' ? raw.trim().replace(/\/$/, '') : ''
+  if (!apiBase) return value.startsWith('/') ? value : `/${value}`
+
+  const staticBase = apiBase.replace(/\/api$/i, '')
+  return `${staticBase}${value.startsWith('/') ? value : `/${value}`}`
+}

package/components/QiuBadge/shared/badgeTemplate.ts

@@ -0,0 +1,309 @@
+/** 与后端 BadgeData 及 allowedBadgePlaceholderKeys 一致 */
+export const BADGE_PLACEHOLDER_KEYS = [
+  'competition_name',
+  'student_name',
+  'competition_no',
+  'school_name',
+  'school_short_name',
+  'age_group',
+  'competition_room',
+  'seat_no',
+  'floor',
+  'teacher_name',
+  'date',
+  'session',
+  'enroll_teacher_name',
+  'teacher_phone',
+  'signup_teacher_name',
+  'signup_teacher_phone',
+  'signup_teacher_department',
+  'signup_teacher_position',
+  'signup_teacher_id_card',
+  'signup_teacher_email',
+  'signup_teacher_username',
+  'venue_name',
+  'venue_address',
+  'competition_daily_start',
+  'competition_daily_end',
+] as const
+
+export type BadgePlaceholderKey = (typeof BADGE_PLACEHOLDER_KEYS)[number]
+
+export const BADGE_PLACEHOLDER_LABELS: Record<string, string> = {
+  competition_name: '比赛名称',
+  student_name: '学生姓名',
+  competition_no: '参赛编号',
+  school_name: '学校',
+  school_short_name: '学校简称',
+  age_group: '年龄段',
+  competition_room: '考场/教室',
+  seat_no: '座位号',
+  floor: '楼层',
+  teacher_name: '监考教师',
+  date: '比赛日期',
+  session: '场次',
+  enroll_teacher_name: '报名/带队教师（扩展）',
+  teacher_phone: '教师手机（扩展）',
+  signup_teacher_name: '报名教师姓名',
+  signup_teacher_phone: '报名教师手机',
+  signup_teacher_department: '报名教师部门',
+  signup_teacher_position: '报名教师职务',
+  signup_teacher_id_card: '报名教师身份证',
+  signup_teacher_email: '报名教师邮箱',
+  signup_teacher_username: '报名教师账号',
+  venue_name: '场地名称',
+  venue_address: '场地地址',
+  competition_daily_start: '比赛当天开始时间',
+  competition_daily_end: '比赛当天结束时间',
+}
+
+export interface BadgeTemplateCanvas {
+  widthMm: number
+  heightMm: number
+  background?: string
+  backgroundImage?: string
+  /** 是否绘制画布边框（编辑/预览/打印一致） */
+  showBorder?: boolean
+  borderColor?: string
+  /** 边框宽度（mm） */
+  borderWidthMm?: number
+}
+
+export interface BadgeCanvasRegion {
+  id: string
+  name: string
+  xMm: number
+  yMm: number
+  wMm: number
+  hMm: number
+  background?: string
+  backgroundImage?: string
+}
+
+/** 元素跳转链接（Banner 热区 / 按钮形态） */
+export type BadgeElementLink = {
+  href: string
+  target?: '_blank' | '_self'
+}
+
+export interface BadgeTextElement {
+  id: string
+  type: 'text'
+  zIndex: number
+  xMm: number
+  yMm: number
+  wMm: number
+  hMm: number
+  rotation?: number
+  flipX?: boolean
+  flipY?: boolean
+  groupId?: string
+  regionId?: string
+  align?: string
+  text: string
+  fontSize: number
+  fontFamily: string
+  color: string
+  textDirection?: 'horizontal' | 'vertical'
+  link?: BadgeElementLink
+}
+
+export interface BadgeImageElement {
+  id: string
+  type: 'image' | 'seal'
+  zIndex: number
+  xMm: number
+  yMm: number
+  wMm: number
+  hMm: number
+  rotation?: number
+  flipX?: boolean
+  flipY?: boolean
+  groupId?: string
+  regionId?: string
+  align?: string
+  src: string
+  clipboardSource?: 'clipboard'
+  clipboardUploadState?: 'pending' | 'uploaded'
+  clipboardUploadKey?: string
+  clipboardImageId?: number
+  clipboardOrigName?: string
+  link?: BadgeElementLink
+}
+
+export interface BadgeShapeElement {
+  id: string
+  type: 'shape'
+  shape: 'rect' | 'circle' | 'triangle' | 'line' | 'polygon' | 'trapezoid'
+  zIndex: number
+  xMm: number
+  yMm: number
+  wMm: number
+  hMm: number
+  rotation?: number
+  flipX?: boolean
+  flipY?: boolean
+  groupId?: string
+  regionId?: string
+  background?: string
+  lockAspectRatio?: boolean
+  showStroke?: boolean
+  strokeColor?: string
+  strokeWidthMm?: number
+  opacity?: number
+  polygonSides?: number
+  link?: BadgeElementLink
+}
+
+export type BadgeElement = BadgeTextElement | BadgeImageElement | BadgeShapeElement
+
+export interface BadgeGuideLine {
+  id: string
+  axis: 'horizontal' | 'vertical'
+  offsetMm: number
+}
+
+export interface BadgeTemplateDoc {
+  version: number
+  canvas: BadgeTemplateCanvas
+  elements: BadgeElement[]
+  guides?: BadgeGuideLine[]
+  regions?: BadgeCanvasRegion[]
+  /** 可选：画布级数据模块（与 QiuCanvasKit 对齐） */
+  dataModules?: Array<{
+    id: string
+    label: string
+    fields: Array<{ key: string; label: string; type?: string }>
+    sample?: Record<string, string>
+    builtin?: boolean
+    enabled?: boolean
+  }>
+}
+
+export function mergeBadgeText(text: string, data: Record<string, string>) {
+  return text.replace(/\{\{\s*([a-zA-Z0-9_.]+)\s*\}\}/g, (_, k: string) => {
+    if (k.includes('.')) {
+      const [mod, field] = k.split('.')
+      const nested = (data as Record<string, unknown>)[mod]
+      if (nested && typeof nested === 'object') {
+        const v = (nested as Record<string, string>)[field]
+        if (v != null && v !== '') return String(v)
+      }
+    }
+    const v = data[k]
+    return v != null && v !== '' ? String(v) : ''
+  })
+}
+
+/** 将接口返回的一条证件（参赛证/工作证等）记录转为占位符合并表 */
+export function flattenBadgeForMerge(
+  b: Record<string, unknown>,
+  competitionNameFallback?: string
+): Record<string, string> {
+  const cn =
+    (b.competition_name != null ? String(b.competition_name) : '') ||
+    (competitionNameFallback ?? '')
+  const schoolName = String(b.school_name ?? '')
+  const schoolShortName =
+    String(b.school_short_name ?? b.school_name_short ?? '').trim() || deriveSchoolShortName(schoolName)
+  return {
+    competition_name: cn,
+    student_name: String(b.student_name ?? ''),
+    competition_no: String(b.competition_no ?? ''),
+    school_name: schoolName,
+    school_short_name: schoolShortName,
+    age_group: String(b.age_group ?? ''),
+    competition_room: String(b.competition_room ?? ''),
+    seat_no: String(b.seat_no ?? ''),
+    floor: String(b.floor ?? ''),
+    teacher_name: String(b.teacher_name ?? ''),
+    date: String(b.date ?? b.competition_date ?? ''),
+    session: String(b.session ?? b.competition_session ?? ''),
+    enroll_teacher_name: String(b.enroll_teacher_name ?? ''),
+    teacher_phone: String(b.teacher_phone ?? ''),
+    signup_teacher_name: String(b.signup_teacher_name ?? ''),
+    signup_teacher_phone: String(b.signup_teacher_phone ?? ''),
+    signup_teacher_department: String(b.signup_teacher_department ?? ''),
+    signup_teacher_position: String(b.signup_teacher_position ?? ''),
+    signup_teacher_id_card: String(b.signup_teacher_id_card ?? ''),
+    signup_teacher_email: String(b.signup_teacher_email ?? ''),
+    signup_teacher_username: String(b.signup_teacher_username ?? ''),
+    venue_name: String(b.venue_name ?? ''),
+    venue_address: String(b.venue_address ?? ''),
+    competition_daily_start: String(b.competition_daily_start ?? ''),
+    competition_daily_end: String(b.competition_daily_end ?? ''),
+  }
+}
+
+function deriveSchoolShortName(schoolName: string): string {
+  let name = String(schoolName ?? '').trim()
+  if (!name) return ''
+
+  name = name.replace(/\s+/g, '')
+  name = name.replace(/^[中国中华人民共和國共和国]+/, '')
+
+  const adminPrefix =
+    /^(?:[^省特别行政区]+省|内蒙古自治区|广西壮族自治区|宁夏回族自治区|新疆维吾尔自治区|西藏自治区|北京市|天津市|上海市|重庆市|香港特别行政区|澳门特别行政区|台湾省|[^市]+市|[^区县旗]+区|[^区县旗]+县|[^区县旗]+旗|[^镇乡街道]+镇|[^镇乡街道]+乡|[^镇乡街道]+街道)/
+
+  let stripped = true
+  while (stripped && name) {
+    stripped = false
+    const next = name.replace(adminPrefix, '')
+    if (next !== name) {
+      name = next
+      stripped = true
+    }
+  }
+
+  return name || schoolName.trim()
+}
+
+export function sortBadgeElements(els: BadgeElement[]): BadgeElement[] {
+  return [...els].sort((a, b) => (a.zIndex ?? 0) - (b.zIndex ?? 0))
+}
+
+/** 桌面贴模板可用占位符：与参赛证保持一致，实际值由 DeskLabels 接口尽量补齐 */
+export const DESK_LABEL_PLACEHOLDER_KEYS = BADGE_PLACEHOLDER_KEYS
+
+export type DeskLabelPlaceholderKey = BadgePlaceholderKey
+
+export const DESK_LABEL_PLACEHOLDER_LABELS: Record<string, string> = BADGE_PLACEHOLDER_LABELS
+
+/** 单条桌面贴数据 → 与证件模板相同的合并表（未用字段留空，便于复用 BadgeTemplateRenderer） */
+export function flattenDeskLabelForMerge(
+  row: Record<string, unknown>,
+  competitionNameFallback?: string
+): Record<string, string> {
+  const cn =
+    (row.competition_name != null ? String(row.competition_name) : '') || (competitionNameFallback ?? '')
+  const schoolName = String(row.school_name ?? '')
+  const schoolShortName =
+    String(row.school_short_name ?? row.school_name_short ?? '').trim() || deriveSchoolShortName(schoolName)
+  return {
+    competition_name: cn,
+    student_name: String(row.student_name ?? ''),
+    competition_no: String(row.competition_no ?? ''),
+    school_name: schoolName,
+    school_short_name: schoolShortName,
+    age_group: String(row.age_group ?? ''),
+    competition_room: String(row.competition_room ?? ''),
+    seat_no: String(row.seat_no ?? ''),
+    floor: String(row.floor ?? ''),
+    teacher_name: String(row.teacher_name ?? ''),
+    date: String(row.date ?? row.competition_date ?? ''),
+    session: String(row.session ?? row.competition_session ?? ''),
+    enroll_teacher_name: String(row.enroll_teacher_name ?? ''),
+    teacher_phone: String(row.teacher_phone ?? ''),
+    signup_teacher_name: String(row.signup_teacher_name ?? ''),
+    signup_teacher_phone: String(row.signup_teacher_phone ?? ''),
+    signup_teacher_department: String(row.signup_teacher_department ?? ''),
+    signup_teacher_position: String(row.signup_teacher_position ?? ''),
+    signup_teacher_id_card: String(row.signup_teacher_id_card ?? ''),
+    signup_teacher_email: String(row.signup_teacher_email ?? ''),
+    signup_teacher_username: String(row.signup_teacher_username ?? ''),
+    venue_name: String(row.venue_name ?? ''),
+    venue_address: String(row.venue_address ?? ''),
+    competition_daily_start: String(row.competition_daily_start ?? ''),
+    competition_daily_end: String(row.competition_daily_end ?? ''),
+  }
+}

package/components/QiuBadge/utils/chinaAreaData.ts

@@ -0,0 +1,44 @@
+/**
+ * 省市区树数据（替代 element-china-area-data）
+ * 与旧包 API 对齐：regionData + codeToText，供 QiuBadge 赛区树使用。
+ * 使用本地 pca-code.json，避免 Vite 解析 china-division 包入口失败。
+ *
+ * @author qiuye
+ * @email yjk150@qq.com
+ * @date 2026-08-16
+ */
+import pcaCJson from './pca-code.json'
+
+export interface ChinaAreaNode {
+  value: string
+  label: string
+  children?: ChinaAreaNode[]
+}
+
+interface PcaCodeNode {
+  code: string | number
+  name: string
+  children?: PcaCodeNode[]
+}
+
+function mapNode(n: PcaCodeNode): ChinaAreaNode {
+  return {
+    value: String(n.code),
+    label: String(n.name || ''),
+    children: n.children?.length ? n.children.map(mapNode) : undefined,
+  }
+}
+
+/** 与 element-china-area-data 的 regionData 同形 */
+export const regionData: ChinaAreaNode[] = (pcaCJson as PcaCodeNode[]).map(mapNode)
+
+/** code → 中文名 */
+export const codeToText: Record<string, string> = {}
+
+function walk(nodes: ChinaAreaNode[]) {
+  for (const n of nodes) {
+    codeToText[n.value] = n.label
+    if (n.children?.length) walk(n.children)
+  }
+}
+walk(regionData)

package/components/QiuBadge/utils/hostRegion.ts

@@ -0,0 +1,22 @@
+/** host_region 存省市区 code 的 JSON 数组字符串，如 ["110000","110100","110105"]；旧数据为纯文本则原样展示 */
+
+export function parseHostRegionCodes(raw: unknown): string[] {
+  if (raw == null) return []
+  const s = String(raw).trim()
+  if (!s) return []
+  try {
+    const a = JSON.parse(s)
+    if (Array.isArray(a)) return a.map(String).filter(Boolean)
+  } catch {
+    /* 旧版手填 */
+  }
+  return []
+}
+
+export function formatHostRegionLabel(raw: unknown, codeToText: Record<string, string>): string {
+  const codes = parseHostRegionCodes(raw)
+  if (codes.length) {
+    return codes.map((c) => codeToText[c] || c).filter(Boolean).join(' / ')
+  }
+  return String(raw ?? '').trim()
+}