补齐超时响应唯一 timeoutCode 与智能体按码查询，并增强报价模板预览与解析落库。

Co-authored-by: Cursor <cursoragent@cursor.com>

inquiry-backend/YTD-README.md

@@ -25,7 +25,7 @@ pnpm run dev
 | 机器人回复语 | `inquiry/botReply/index` |
 | 账号管理 | `inquiry/account/index` |
 | 角色管理 | `inquiry/role/index` |
-| 系统设置 | `inquiry/systemSetting/index` |
+| 超时响应 | `inquiry/systemSetting/index` |
 
 菜单由后端 `sys_permission` 种子下发（见 `deploy/sql/inquiry_admin_menu_seed_v1.sql`）。登录后刷新权限即可看到询价菜单。
 

inquiry-backend/src/layouts/inquiry/index.vue

@@ -49,7 +49,7 @@
     {
       title: '系统配置',
       items: [
-        { key: '/inquiry-sys/system-setting', label: '系统设置', icon: 'clock' },
+        { key: '/inquiry-sys/system-setting', label: '超时响应', icon: 'clock' },
         { key: '/inquiry-sys/user', label: '账号管理', icon: 'account' },
         { key: '/inquiry-sys/role', label: '角色管理', icon: 'role' },
       ],

inquiry-backend/src/store/modules/permission.ts

@@ -46,7 +46,7 @@ const INQUIRY_LEAVES: InquiryLeaf[] = [
     path: '/inquiry-sys/system-setting',
     name: 'inquiry-system-setting',
     component: 'inquiry/systemSetting/index',
-    title: '系统设置',
+    title: '超时响应',
   },
   { path: '/inquiry-sys/user', name: 'inquiry-sys-user', component: 'inquiry/account/index', title: '账号管理' },
   { path: '/inquiry-sys/role', name: 'inquiry-sys-role', component: 'inquiry/role/index', title: '角色管理' },
@@ -102,8 +102,9 @@ function ensureInquiryHandwrittenRoutes(routeList: AppRouteRecordRaw[]) {
         const comp = String((existing as any).component || '');
         if (!comp.includes(leaf.component) && !comp.includes(leaf.component.replace(/\/index$/, ''))) {
           (existing as any).component = leaf.component;
-          existing.meta = { ...(existing.meta || {}), title: leaf.title, ignoreKeepAlive: true };
         }
+        // 侧栏/页题以手写清单为准（例：系统设置 → 超时响应）
+        existing.meta = { ...(existing.meta || {}), title: leaf.title, ignoreKeepAlive: true };
         continue;
       }
       const node: AppRouteRecordRaw = {

inquiry-backend/src/views/inquiry/mock/templates.ts

@@ -28,8 +28,11 @@ export type TemplateRow = {
   currentVersion?: number;
   parseMessage?: string;
   unmappedRequired?: string[];
+  unmappedLabels?: string[];
   /** 表上有、对照清单未映射上的中文说明（智能体 mappingGaps） */
   mappingGaps?: string[];
+  /** 列表提示：未解析条数（主账合并口径） */
+  unparsedHintCount?: number;
   objectKey?: string;
 };
 
@@ -61,7 +64,9 @@ export function mapApiRow(raw: any): TemplateRow {
     currentVersion: raw.currentVersion,
     parseMessage: raw.parseMessage,
     unmappedRequired: Array.isArray(raw.unmappedRequired) ? raw.unmappedRequired.map(String) : [],
+    unmappedLabels: Array.isArray(raw.unmappedLabels) ? raw.unmappedLabels.map(String) : [],
     mappingGaps: Array.isArray(raw.mappingGaps) ? raw.mappingGaps.map(String) : [],
+    unparsedHintCount: Number(raw.unparsedHintCount || 0),
     objectKey: raw.objectKey,
   };
 }

inquiry-backend/src/views/inquiry/systemSetting/index.vue

@@ -1,7 +1,9 @@
 <script setup>
 /**
- * 系统设置：响应超时小时配置。
- * 海运 / 空运 / 陆运同页分三块展示，只允许改超时小时；无增删、无 Tab。
+ * 超时响应：响应超时小时配置。
+ * 海运 / 空运 / 陆运同页自上而下分块展示，只允许改超时小时；无增删、无 Tab。
+ * 「编码」= timeoutCode，每条唯一（如 sea_sales / land_hk_express），供智能体单码调用；只读。
+ * roleCode（销售/产品）仅为角色维度，可重复，不是调用主键。
  * 不展示线路类别（维度仍在主账，仅后台列表隐藏）。
  * 数据来自主账 inq_response_timeout；本页不做工单超时判定。
  */
@@ -50,6 +52,12 @@ function displayOrDash(v) {
   return s || '—';
 }
 
+/** 唯一业务编码；缺省时提示需迁移 */
+function timeoutCodeOf(row) {
+  const c = String(row.timeoutCode || '').trim();
+  return c || '—';
+}
+
 async function loadList() {
   loading.value = true;
   try {
@@ -105,7 +113,7 @@ async function commitHours(row) {
 <template>
   <div class="sys-setting-page">
     <div class="toolbar-bar">
-      <span class="hint">固定规则，仅可改超时小时；失焦或回车保存</span>
+      <span class="hint">固定规则，仅可改超时小时；编码唯一只读，供智能体调用；失焦或回车保存</span>
     </div>
 
     <div v-if="loading" style="padding: 24px; color: #94a3b8">加载中…</div>
@@ -120,16 +128,22 @@ async function commitHours(row) {
             <thead>
               <tr>
                 <th style="width: 88px">角色</th>
+                <th style="width: 160px" title="每条唯一；智能体用此码取超时小时">编码</th>
                 <th>运输类型</th>
                 <th style="width: 140px">超时设置（小时）</th>
               </tr>
             </thead>
             <tbody>
               <tr v-if="!block.rows.length">
-                <td colspan="3" style="color: #94a3b8">暂无配置</td>
+                <td colspan="4" style="color: #94a3b8">暂无配置</td>
               </tr>
               <tr v-for="row in block.rows" :key="row.id">
                 <td>{{ roleLabel(row.roleCode) }}</td>
+                <td>
+                  <code class="role-code" :title="'智能体调用编码：' + timeoutCodeOf(row)">{{
+                    timeoutCodeOf(row)
+                  }}</code>
+                </td>
                 <td>{{ displayOrDash(row.transportType) }}</td>
                 <td>
                   <div class="hours-cell">
@@ -202,4 +216,16 @@ async function commitHours(row) {
   color: #667085;
   font-weight: 600;
 }
+
+.role-code {
+  display: inline-block;
+  padding: 2px 6px;
+  border-radius: 4px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 11px;
+  font-weight: 600;
+  color: #344054;
+  background: #f2f4f7;
+  border: 1px solid #e4e7ec;
+}
 </style>

inquiry-backend/src/views/inquiry/systemSetting/systemSetting.api.ts

@@ -1,6 +1,7 @@
 /**
- * 系统设置 · 响应超时配置 API。
+ * 超时响应配置 API。
  * 对接主账 /inquiry/responseTimeout；仅 listAll + 改小时数。
+ * timeoutCode 每条唯一（如 sea_sales），智能体 POST /inquiry/agent/responseTimeout/byCode 单码查询。
  */
 import { defHttp } from '/@/utils/http/axios';
 
@@ -11,6 +12,8 @@ enum Api {
 
 export type ResponseTimeoutRow = {
   id: string;
+  /** 唯一业务编码，智能体调用主键 */
+  timeoutCode?: string;
   transportMode: string;
   roleCode: string;
   routeCategory?: string;

inquiry-backend/src/views/inquiry/template/index.vue

@@ -3,7 +3,8 @@
  * 报价模板页：对接主账 /inquiry/quoteTemplate。
  * - 上传按钮只在顶栏一处；弹窗用原生 overlay
  * - 版式由上传 Excel 决定；列表展示「映射点数」而非假占位符
- * - 预览：原表截图（LibreOffice 转图），不是 AI 画格子
+ * - 预览：原表截图（LibreOffice 转图）
+ * - 解析状态列可点：弹窗看已解析 / 未解析清单
  */
 import { computed, onMounted, onUnmounted, reactive, ref } from "vue";
 import { Modal, message } from "ant-design-vue";
@@ -17,9 +18,15 @@ import {
   enableTemplate,
   fetchTemplateSnapshotBlob,
   getTemplateList,
+  getTemplateVersion,
   reparseTemplate,
   uploadTemplate,
 } from "/@/views/inquiry/template/template.api";
+import {
+  FIELD_LABELS,
+  summarizeMappingParse,
+  type MappingParseSummary,
+} from "/@/views/inquiry/template/previewSample";
 
 // buildTemplateFileUrl 已由 downloadTemplateFile 替代（鉴权 blob 下载）
 
@@ -45,7 +52,17 @@ const formOpen = ref(false);
 const editing = ref<TemplateRow | null>(null);
 const previewOpen = ref(false);
 const previewRow = ref<TemplateRow | null>(null);
-/** 原表截图预览状态 */
+/** 空映射摘要 */
+const emptyMappingSummary = (): MappingParseSummary => ({
+  fields: [],
+  regions: [],
+  gaps: [],
+  unmappedRequired: [],
+  unmappedLabels: [],
+  pointCount: 0,
+});
+
+/** 原表截图预览状态（不含映射清单） */
 const previewState = reactive({
   loading: false,
   error: "",
@@ -54,6 +71,34 @@ const previewState = reactive({
   mappedCount: 0,
   fileName: "",
 });
+
+/** 列表「解析状态」点击弹窗：已解析 / 未解析 */
+const parseDetailOpen = ref(false);
+const parseDetailRow = ref<TemplateRow | null>(null);
+const parseDetailState = reactive({
+  loading: false,
+  mappedCount: 0,
+  mapping: emptyMappingSummary() as MappingParseSummary,
+});
+
+/** 未解析清单：优先 mappingGaps，其次 AI 自报项 */
+const parseDetailUnparsed = computed(() => {
+  const m = parseDetailState.mapping;
+  const list: string[] = [];
+  for (const g of m.gaps || []) {
+    if (g) list.push(g);
+  }
+  if (!list.length) {
+    for (const c of m.unmappedRequired || []) {
+      list.push(`字段未映射：${FIELD_LABELS[c] || c}`);
+    }
+    for (const lab of m.unmappedLabels || []) {
+      if (lab) list.push(`表标签未落点：${lab}`);
+    }
+  }
+  return list;
+});
+
 const fileInputRef = ref<HTMLInputElement | null>(null);
 const pendingFile = ref<File | null>(null);
 
@@ -98,7 +143,7 @@ function revokePreviewUrl() {
 }
 
 /**
- * 打开预览：读取上传后已缓存的截图（未就绪则现转）。
+ * 打开预览：仅原表截图。
  * 副作用：HTTP 读 previewSnapshot；本地 blob URL；不写库。
  */
 async function openPreview(row: TemplateRow) {
@@ -132,6 +177,57 @@ async function openPreview(row: TemplateRow) {
   }
 }
 
+/**
+ * 列表点「解析状态」：弹窗展示已解析 / 未解析清单。
+ * 副作用：HTTP 读 version.mappingJson；不写库。
+ */
+async function openParseDetail(row: TemplateRow) {
+  if (row.parseStatus === "解析中" || row.parseStatus === "未上传") {
+    message.info(row.parseStatus === "解析中" ? "解析中，请稍候再看" : "请先上传模板文件");
+    return;
+  }
+  if (!row.versionId) {
+    message.warning("无可用版本");
+    return;
+  }
+  parseDetailRow.value = row;
+  parseDetailOpen.value = true;
+  parseDetailState.loading = true;
+  parseDetailState.mappedCount = row.mappingPointCount || 0;
+  parseDetailState.mapping = emptyMappingSummary();
+  try {
+    const ver: any = await getTemplateVersion(row.versionId);
+    const mappingJson = ver?.mappingJson ?? ver?.result?.mappingJson ?? null;
+    let summary = summarizeMappingParse(mappingJson);
+    if (!summary.gaps.length && row.mappingGaps?.length) {
+      summary = { ...summary, gaps: [...row.mappingGaps] };
+    }
+    if (!summary.unmappedRequired.length && row.unmappedRequired?.length) {
+      summary = { ...summary, unmappedRequired: [...row.unmappedRequired] };
+    }
+    parseDetailState.mapping = summary;
+    if (summary.pointCount > 0) {
+      parseDetailState.mappedCount = summary.pointCount;
+    }
+  } catch {
+    parseDetailState.mapping = {
+      ...emptyMappingSummary(),
+      gaps: listMappingGaps(row),
+      unmappedRequired: row.unmappedRequired || [],
+      pointCount: row.mappingPointCount || 0,
+    };
+  } finally {
+    parseDetailState.loading = false;
+  }
+}
+
+function closeParseDetail() {
+  parseDetailOpen.value = false;
+  parseDetailRow.value = null;
+  parseDetailState.loading = false;
+  parseDetailState.mapping = emptyMappingSummary();
+}
+
 function closeForm() {
   formOpen.value = false;
 }
@@ -281,13 +377,23 @@ function openEdit(row: TemplateRow) {
   formOpen.value = true;
 }
 
-/** 运营可见的未解析项：优先 mappingGaps，其次 AI 自报 unmappedRequired */
+/** 运营可见的未解析项：优先 mappingGaps，其次标签/必填未映射 */
 function listMappingGaps(row: TemplateRow): string[] {
   if (row.mappingGaps?.length) return [...row.mappingGaps];
-  if (row.unmappedRequired?.length) {
-    return row.unmappedRequired.map((c) => `字段未映射：${c}`);
+  const list: string[] = [];
+  for (const lab of row.unmappedLabels || []) {
+    if (lab) list.push(`表标签未落点：${lab}`);
   }
-  return [];
+  for (const c of row.unmappedRequired || []) {
+    if (c) list.push(`字段未映射：${c}`);
+  }
+  return list;
+}
+
+/** 列表角标条数 */
+function unparsedCount(row: TemplateRow): number {
+  if (row.unparsedHintCount && row.unparsedHintCount > 0) return row.unparsedHintCount;
+  return listMappingGaps(row).length;
 }
 
 function normalizeKeywordItems(items: string[]): string[] {
@@ -543,24 +649,29 @@ async function downloadPreviewOrOriginal() {
               {{ formatKeywords(row.keywords) || "—" }}
             </td>
             <td
-              class="qt-col-muted"
+              class="qt-col-muted qt-parse-cell-click"
               :class="{
                 'qt-parse-fail': row.parseStatus === '失败' || row.parseStatus === '映射未完成',
-                'qt-parse-gaps': listMappingGaps(row).length > 0 && row.parseStatus === '已解析',
+                'qt-parse-gaps': unparsedCount(row) > 0 && row.parseStatus === '已解析',
               }"
-              :title="row.parseMessage || row.parseStatus"
+              :title="
+                unparsedCount(row) > 0
+                  ? `有 ${unparsedCount(row)} 项未解析，点击查看`
+                  : '点击查看已解析 / 未解析内容'
+              "
+              @click.stop="openParseDetail(row)"
             >
-              <span>{{ row.parseStatus }}</span>
-              <span v-if="listMappingGaps(row).length" class="qt-gap-badge">
-                未解析 {{ listMappingGaps(row).length }}
-              </span>
+              <div class="qt-parse-status-row">
+                <span class="qt-parse-status-link">{{ row.parseStatus }}</span>
+                <span v-if="unparsedCount(row) > 0" class="qt-gap-badge">未解析 {{ unparsedCount(row) }}</span>
+              </div>
+              <div v-if="unparsedCount(row) > 0" class="qt-parse-gap-hint">有未解析内容，点击查看</div>
               <div
-                v-if="
+                v-else-if="
                   row.parseMessage &&
                   (row.parseStatus === '失败' ||
                     row.parseStatus === '映射未完成' ||
-                    row.parseStatus === '解析中' ||
-                    listMappingGaps(row).length > 0)
+                    row.parseStatus === '解析中')
                 "
                 class="qt-parse-msg"
               >
@@ -830,6 +941,86 @@ async function downloadPreviewOrOriginal() {
     </div>
   </Teleport>
 
+  <!-- 解析状态弹窗：已解析 / 未解析清单 -->
+  <Teleport to="body">
+    <div
+      v-if="parseDetailOpen && parseDetailRow"
+      class="modal-overlay"
+      role="dialog"
+      aria-modal="true"
+      @click.self="closeParseDetail"
+    >
+      <div class="modal-dialog qt-parse-detail-dialog" @click.stop>
+        <div class="qt-modal-head">
+          <div class="qt-modal-title-row">
+            <div class="qt-modal-icon qt-modal-icon--green">
+              <ProtoIcon name="fileSpreadsheet" :size="16" />
+            </div>
+            <div>
+              <div class="qt-modal-sub">解析结果</div>
+              <div class="qt-modal-title">{{ parseDetailRow.name }}</div>
+            </div>
+          </div>
+          <button type="button" class="btn btn-ghost" aria-label="关闭" @click="closeParseDetail">
+            <ProtoIcon name="x" :size="18" />
+          </button>
+        </div>
+
+        <div class="qt-preview-modal-body">
+          <div class="qt-preview-tags">
+            <span class="tag" :class="bizTag(parseDetailRow.bizType)">{{ parseDetailRow.bizType }}</span>
+            <span class="tag tag-green">已解析 {{ parseDetailState.mappedCount }} 项</span>
+            <span v-if="parseDetailUnparsed.length" class="tag tag-amber"
+              >未解析 {{ parseDetailUnparsed.length }} 项</span
+            >
+          </div>
+
+          <div class="qt-parse-panels">
+            <div class="qt-parse-panel qt-parse-panel--ok">
+              <div class="qt-parse-panel-title">已解析内容</div>
+              <div v-if="parseDetailState.loading" class="qt-parse-panel-empty">加载映射中…</div>
+              <template
+                v-else-if="parseDetailState.mapping.fields.length || parseDetailState.mapping.regions.length"
+              >
+                <ul class="qt-parse-panel-list">
+                  <li v-for="f in parseDetailState.mapping.fields" :key="'f-' + f.code">
+                    <span class="qt-parse-name">{{ f.label }}</span>
+                    <code class="qt-parse-code">{{ f.code }}</code>
+                    <span class="qt-parse-cell">{{ f.cell }}</span>
+                  </li>
+                  <li v-for="r in parseDetailState.mapping.regions" :key="'r-' + r.kind + r.id">
+                    <span class="qt-parse-name"
+                      >{{ r.kind === "fee" ? "费用区" : "线路区" }} · {{ r.title }}</span
+                    >
+                    <code v-if="r.id" class="qt-parse-code">{{ r.id }}</code>
+                  </li>
+                </ul>
+              </template>
+              <div v-else class="qt-parse-panel-empty">暂无已映射字段（解析中或未完成）</div>
+            </div>
+            <div
+              class="qt-parse-panel"
+              :class="parseDetailUnparsed.length ? 'qt-parse-panel--gap' : 'qt-parse-panel--ok'"
+            >
+              <div class="qt-parse-panel-title">未解析内容</div>
+              <div v-if="parseDetailState.loading" class="qt-parse-panel-empty">加载映射中…</div>
+              <ul v-else-if="parseDetailUnparsed.length" class="qt-parse-panel-list">
+                <li v-for="(g, i) in parseDetailUnparsed" :key="'g-' + i">{{ g }}</li>
+              </ul>
+              <div v-else class="qt-parse-panel-empty">
+                暂无未解析项。若刚升级功能，可点「重新解析」刷新缺口清单。
+              </div>
+            </div>
+          </div>
+        </div>
+
+        <div class="qt-preview-modal-footer">
+          <button type="button" class="btn btn-secondary" @click="closeParseDetail">关闭</button>
+        </div>
+      </div>
+    </div>
+  </Teleport>
+
   <!-- 截图放大灯箱：1:1 比例，仅关灯箱不关预览弹窗 -->
   <Teleport to="body">
     <div
@@ -855,6 +1046,95 @@ async function downloadPreviewOrOriginal() {
   max-width: min(96vw, 980px) !important;
   width: min(96vw, 980px);
 }
+.qt-parse-detail-dialog {
+  max-width: min(96vw, 720px) !important;
+  width: min(96vw, 720px);
+}
+.qt-parse-cell-click {
+  cursor: pointer;
+}
+.qt-parse-cell-click:hover .qt-parse-status-link {
+  color: #155eef;
+  text-decoration: underline;
+}
+.qt-parse-status-link {
+  font-weight: 700;
+}
+.qt-parse-panels {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 10px;
+  margin: 0;
+}
+@media (max-width: 800px) {
+  .qt-parse-panels {
+    grid-template-columns: 1fr;
+  }
+}
+.qt-parse-panel {
+  border-radius: 8px;
+  border: 1px solid #e4e7ec;
+  background: #f9fafb;
+  padding: 10px 12px;
+  min-height: 88px;
+  max-height: min(50vh, 360px);
+  overflow: auto;
+}
+.qt-parse-panel--ok {
+  border-color: #abefc6;
+  background: #f0fdf4;
+}
+.qt-parse-panel--gap {
+  border-color: #fec84b;
+  background: #fffaeb;
+}
+.qt-parse-panel-title {
+  font-size: 12px;
+  font-weight: 800;
+  color: #344054;
+  margin-bottom: 6px;
+}
+.qt-parse-panel--gap .qt-parse-panel-title {
+  color: #b54708;
+}
+.qt-parse-panel-empty {
+  font-size: 11px;
+  color: #98a2b3;
+  line-height: 1.4;
+}
+.qt-parse-panel-list {
+  margin: 0;
+  padding-left: 16px;
+  font-size: 11px;
+  color: #344054;
+  line-height: 1.45;
+}
+.qt-parse-panel-list li {
+  margin-bottom: 4px;
+}
+.qt-parse-name {
+  font-weight: 700;
+  margin-right: 6px;
+}
+.qt-parse-code {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 10px;
+  color: #475467;
+  background: #fff;
+  border: 1px solid #e4e7ec;
+  border-radius: 3px;
+  padding: 0 4px;
+  margin-right: 6px;
+}
+.qt-parse-cell {
+  color: #667085;
+  font-size: 10px;
+}
+.tag-amber {
+  background: #fffaeb;
+  color: #b54708;
+  border: 1px solid #fec84b;
+}
 .qt-col-name {
   font-weight: 800;
   color: #0f172a;
@@ -875,9 +1155,21 @@ async function downloadPreviewOrOriginal() {
 .qt-parse-gaps {
   color: #b45309;
 }
+.qt-parse-status-row {
+  display: inline-flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+.qt-parse-gap-hint {
+  margin-top: 3px;
+  font-size: 10px;
+  font-weight: 700;
+  color: #b54708;
+  line-height: 1.3;
+}
 .qt-gap-badge {
   display: inline-block;
-  margin-left: 6px;
   padding: 1px 6px;
   border-radius: 999px;
   font-size: 10px;

inquiry-backend/src/views/inquiry/template/previewSample.ts

@@ -1,6 +1,6 @@
 /**
  * 报价模板预览：Excel 样式网格（上传原文），辅以映射摘要。
- * 主数据来自 /previewSheet；mappingJson 仅用于未映射必填提示。
+ * 主数据来自 /previewSheet；mappingJson 用于已映射/未映射清单。
  */
 
 /** 系统字段 code → 中文标签 */
@@ -27,8 +27,131 @@ export const FIELD_LABELS: Record<string, string> = {
   weight_kg: "重量",
   volume_cbm: "体积",
   total_amount: "报价合计",
+  chargeable_weight_kg: "计费重",
+  delivery_address: "送货地址",
+  pickup_address: "提货地址",
+  transit_time: "运输时效",
+  cargo_value: "货值",
+  hs_code: "HS编码",
+  oil_elec_mag: "油电磁",
+  has_battery: "是否带电",
+  on_board_date: "开船日",
+  special_remarks: "特殊备注",
+  eta_request: "要求到港",
+  sailing_schedule: "船期",
+  shipping_line: "船公司",
+  flight_no: "航班号",
+  transfer_airport: "中转机场",
+  effective_date: "生效日期",
+  fuel_surcharge_rate: "燃油附加费率",
+  tax_rate: "税率",
+  has_oil: "是否含油",
+  has_magnet: "是否含磁",
+  vehicle_qty: "车型/数量",
 };
 
+/** 解析结果摘要：供预览弹窗展示「已解析 / 未解析」 */
+export type MappingFieldItem = {
+  code: string;
+  label: string;
+  cell: string;
+};
+
+export type MappingRegionItem = {
+  kind: "fee" | "route";
+  id: string;
+  title: string;
+};
+
+export type MappingParseSummary = {
+  fields: MappingFieldItem[];
+  regions: MappingRegionItem[];
+  gaps: string[];
+  unmappedRequired: string[];
+  unmappedLabels: string[];
+  pointCount: number;
+};
+
+function asMappingObject(mappingJson: unknown): Record<string, any> | null {
+  if (!mappingJson) return null;
+  if (typeof mappingJson === "object") return mappingJson as Record<string, any>;
+  if (typeof mappingJson === "string") {
+    try {
+      const obj = JSON.parse(mappingJson);
+      return obj && typeof obj === "object" ? obj : null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * 从 mappingJson 拆出运营可读的已映射 / 未映射清单。
+ * 不打接口；mappingGaps 为空时（旧版解析）仍可看 fields 与 unmapped*。
+ */
+export function summarizeMappingParse(mappingJson: unknown): MappingParseSummary {
+  const obj = asMappingObject(mappingJson);
+  const empty: MappingParseSummary = {
+    fields: [],
+    regions: [],
+    gaps: [],
+    unmappedRequired: [],
+    unmappedLabels: [],
+    pointCount: 0,
+  };
+  if (!obj) return empty;
+
+  const fieldsObj = obj.fields && typeof obj.fields === "object" ? obj.fields : {};
+  const fields: MappingFieldItem[] = Object.keys(fieldsObj)
+    .filter((k) => fieldsObj[k])
+    .map((code) => ({
+      code,
+      label: FIELD_LABELS[code] || code,
+      cell: String(fieldsObj[code] || ""),
+    }))
+    .sort((a, b) => a.label.localeCompare(b.label, "zh"));
+
+  const regions: MappingRegionItem[] = [];
+  const feeRegions = Array.isArray(obj.feeRegions) ? obj.feeRegions : [];
+  for (const r of feeRegions) {
+    if (!r || typeof r !== "object") continue;
+    regions.push({
+      kind: "fee",
+      id: String(r.id || ""),
+      title: String(r.title || r.id || "费用区"),
+    });
+  }
+  const routeRegions = Array.isArray(obj.routeRegions) ? obj.routeRegions : [];
+  for (const r of routeRegions) {
+    if (!r || typeof r !== "object") continue;
+    regions.push({
+      kind: "route",
+      id: String(r.id || ""),
+      title: String(r.title || r.id || "线路区"),
+    });
+  }
+
+  const gaps = Array.isArray(obj.mappingGaps)
+    ? obj.mappingGaps.map((x: any) => String(x)).filter(Boolean)
+    : [];
+  const unmappedRequired = Array.isArray(obj.unmappedRequired)
+    ? obj.unmappedRequired.map((x: any) => String(x)).filter(Boolean)
+    : [];
+  const unmappedLabels = Array.isArray(obj.unmappedLabels)
+    ? obj.unmappedLabels.map((x: any) => String(x)).filter(Boolean)
+    : [];
+
+  return {
+    fields,
+    regions,
+    gaps,
+    unmappedRequired,
+    unmappedLabels,
+    pointCount: fields.length + regions.length,
+  };
+}
+
 export type SheetPreviewCell = {
   addr: string;
   text: string;