EXCEL2JSON/demands/DEMAND-字典映射.md

这次更新加入了 “字典映射 (Dictionary Mapping)” 功能，允许用户对有限的枚举值进行转换（如“是/否”转“Y/N”）。

我特别在文档中强调了**“自动扫描”**功能——让 UI 自动读取 Excel 列中的前几十行去重数据，自动列出所有可能的选项，用户只需要填右边的目标值即可，极大提升体验。

---

复制下面的内容发送给 Claude：

---

Role: 资深前端架构师 (Svelte 5 + TypeScript)

Project Context: 我们正在开发 "Excel2JSON ETL Blueprint Generator"。 前端负责解析 Excel、配置映射规则（含静态重命名、字典转换、动态 API）、生成预览，并最终导出包含 [处理后的基础数据 + API 执行逻辑] 的 job_bundle.json。

Current Task: 我们需要在 v2.0 (API Enrichment) 的基础上，新增 v2.1 (Dictionary/Enum Mapping) 功能。

Phase 2.1: 字典映射与高级 ETL 配置需求文档

1. 核心功能变更

在静态字段映射（Static Mapping）阶段，新增 "值映射 (Value Map)" 功能。

• 场景: Excel 中某列是状态词（如 "开/关", "男/女"），目标 JSON 需要代码（如 1/0, M/F）。
• 逻辑: 解析 Excel -> 字典替换 -> 类型转换 -> 生成基础 JSON -> (后续由 Python 处理 API).

2. 用户界面与交互 (UI/UX)

2.1 列配置面板升级

点击 Excel 表头配置时，除了修改 Target Key 和 Data Type，新增一个 "Value Mapping" (值映射) 开关/折叠面板。

面板内容：

1. 自动扫描 (Auto-Scan):

• UI 自动读取该列的前 50 行数据，提取所有唯一值 (Unique Values)。
• 显示一个“映射表”：左侧是 Source Value (Excel 原值)，右侧是 Target Value (输入框)。

2. 手动添加: 允许用户手动增加新的映射对（防止前 50 行没覆盖到所有情况）。
3. 默认值 (Fallback):

• 如果单元格的值不在映射表中，怎么处理？
• 选项: Keep Original (保留原值) / Set to Null / Custom Value (自定义默认值)。

2.2 预览逻辑 (Preview Logic)

• 右侧 JSON 预览必须实时反映字典映射的结果。
• 示例: 用户在左侧把 "是" 映射为 true (Boolean)，右侧预览中原本的 "是" 应立即变为 true。

3. 核心数据结构 (Updated Interfaces)

请更新 TypeScript 接口以支持新的映射逻辑：

// 字典映射项
interface ValueMapItem {
  source: string | number; // Excel 里的原始值 (e.g., "是")
  target: any;             // JSON 里的目标值 (e.g., true, "Y", 1)
}

// 静态映射规则 (升级版)
interface StaticRule {
  type: 'static';
  source_column: string;      // Excel 原表头
  target_key: string;         // JSON 目标 Key
  data_type: 'string' | 'number' | 'boolean' | 'date' | 'array'; // 目标类型
  
  // v2.1 新增: 字典映射配置
  use_dictionary: boolean;    // 是否启用字典映射
  value_mapping?: ValueMapItem[]; 
  mapping_fallback?: 'keep' | 'null' | any; // 没匹配到时的默认值
  
  // v2.0 已有
  format?: string;            // 日期格式
  separator?: string;         // 数组分隔符
}

// 动态 API 规则 (保持 v2.0 不变)
interface ApiEnrichmentRule {
  type: 'api_fetch';
  target_key: string;
  url_template: string;       // "https://api.com/{{id}}"
  method: 'GET' | 'POST';
  headers?: Record<string, string>;
  body_template?: string;
  response_path: string;      // "data.result"
}

// 提交配置 (保持 v2.0 不变)
interface SubmissionConfig {
  target_url: string;
  method: 'POST' | 'PUT';
  batch_size: number;
}

// 最终导出的 Job Bundle
interface JobBundle {
  meta: { version: string; generated_at: string };
  config: {
    // static_rules 仅用于前端回显，Python 脚本其实只需要 enrichment 和 submission
    // 但为了以后能在前端重新导入编辑，建议保留完整配置
    static_rules: StaticRule[]; 
    enrichment_rules: ApiEnrichmentRule[];
    submission: SubmissionConfig;
  };
  // 注意: source_data 是前端已经应用了 "StaticRule" (包括字典映射) 后的干净数据
  source_data: Record<string, any>[]; 
}

4. 处理流程 (Processing Pipeline)

前端在生成 source_data 时，必须严格按照以下顺序处理每一单元格：

1. Extract: 读取 Excel 单元格原始值。
2. Map (字典映射):

• 如果启用了 use_dictionary：查找映射表。
• 找到 -> 替换为 Target Value。
• 没找到 -> 应用 mapping_fallback 策略。

3. Cast (类型转换):

• 将上一步的结果转换为 data_type 指定的类型 (e.g., String -> Boolean, String -> Number)。
• 注意: 如果字典映射的目标值已经是正确的类型（如 true），则跳过此步或确保不会再次转为字符串 "true"。

4. Format: (如果是日期或数组) 应用格式化规则。

5. 开发任务清单

1. 组件开发:

• 修改 ColumnConfigPanel.svelte (或类似组件)。
• 新增 DictionaryMapper 子组件：包含“自动扫描”按钮和“键值对”编辑表格。

2. 逻辑核心:

• 更新 processRow 函数，在类型转换前插入字典查找逻辑。
• 实现 scanUniqueValues(columnData) 函数，用于快速提取 Excel 列的去重值。

3. 预览同步: 确保右侧 JSON 预览能实时响应字典配置的变更。
4. 导出验证: 导出 job_bundle.json，检查 source_data 中的值是否已成功转换为映射后的值（例如 "Y" 而不是 "是"）。

---

给 AI 的提示 (Prompt Tip)

• 性能注意: 自动扫描 scanUniqueValues 时，如果 Excel 数据量极大（>10万行），不要全量扫描。只扫描前 1000 行即可，并提示用户“仅扫描了前 1000 行，如有遗漏请手动添加”。
• 交互细节: 字典映射的 Target Value 输入框，应该能智能识别类型。如果用户输入 true，应该被识别为 Boolean 而不是字符串 "true"。

---

执行步骤

请先基于上述文档，更新 数据类型定义 (Interfaces) 和 核心处理逻辑 (processRow 函数)。