Skip to main content

fast_excel/
header.rs

1//! 动态表头适配
2//!
3//! 目标:同一份业务模型能接住"各种版本 / 各种人改过列名"的 Excel。匹配顺序:
4//!
5//! 1. **精确**:归一化后与标准表头一致;
6//! 2. **别名**:命中 [`ColumnDef::aliases`];
7//! 3. **模糊**:互相包含(`报价(USD)(单价)` 命中 `报价(USD)`),按差异最小的列优先;
8//! 4. **列序回退**:表头缺失时按声明顺序落到第 N 列(需显式开启)。
9//!
10//! 归一化会去掉所有空白、`*` 必填标记,统一全角/半角与中英文括号、冒号。
11
12use std::collections::HashMap;
13
14use serde::Serialize;
15
16use crate::column::{ColumnDef, ColumnKind};
17use crate::value::normalize_text;
18
19/// 表头定位与匹配选项
20#[derive(Debug, Clone)]
21pub struct HeaderOptions {
22    /// 表头所在行(0 基,允许前面有标题行 / 说明行)
23    pub row_index: u32,
24    /// 表头占几行(多行表头按列纵向拼接,如 `报价\n(USD)`)
25    pub row_span: u32,
26    /// 是否启用模糊匹配(互相包含)
27    pub fuzzy: bool,
28    /// 是否归一化(去空白/全角半角/必填标记)
29    pub normalize: bool,
30    /// 未匹配到的文件列是否忽略(false = 收集到 `unknown` 由业务侧决定)
31    pub ignore_unknown: bool,
32    /// 表头完全缺失时按声明顺序回退到同序列
33    pub allow_index_fallback: bool,
34    /// 单元格文本是否 trim
35    pub trim: bool,
36}
37
38impl Default for HeaderOptions {
39    fn default() -> Self {
40        Self {
41            row_index: 0,
42            row_span: 1,
43            fuzzy: true,
44            normalize: true,
45            ignore_unknown: true,
46            allow_index_fallback: false,
47            trim: true,
48        }
49    }
50}
51
52impl HeaderOptions {
53    /// 严格模式:只认精确表头(不做模糊、不许回退)
54    pub fn strict() -> Self {
55        Self {
56            fuzzy: false,
57            allow_index_fallback: false,
58            ..Default::default()
59        }
60    }
61
62    pub fn row_index(mut self, row_index: u32) -> Self {
63        self.row_index = row_index;
64        self
65    }
66
67    pub fn row_span(mut self, span: u32) -> Self {
68        self.row_span = span.max(1);
69        self
70    }
71
72    pub fn strict_match(mut self) -> Self {
73        self.fuzzy = false;
74        self
75    }
76
77    pub fn index_fallback(mut self, enable: bool) -> Self {
78        self.allow_index_fallback = enable;
79        self
80    }
81
82    pub fn normalize_enabled(mut self, enable: bool) -> Self {
83        self.normalize = enable;
84        self
85    }
86}
87
88/// 匹配方式
89#[derive(Debug, Clone, Copy, PartialEq, Eq)]
90pub enum MatchKind {
91    /// 与标准表头精确一致
92    Exact,
93    /// 命中别名
94    Alias,
95    /// 模糊包含
96    Fuzzy,
97    /// 按列序回退
98    IndexFallback,
99    /// 缺失(该列在本文件里没有对应列)
100    Missing,
101}
102
103impl MatchKind {
104    pub fn as_str(self) -> &'static str {
105        match self {
106            MatchKind::Exact => "exact",
107            MatchKind::Alias => "alias",
108            MatchKind::Fuzzy => "fuzzy",
109            MatchKind::IndexFallback => "index",
110            MatchKind::Missing => "missing",
111        }
112    }
113}
114
115/// 一个声明列的解析结果
116#[derive(Debug, Clone)]
117pub struct ResolvedColumn {
118    /// 在声明列表中的下标
119    pub order: usize,
120    pub header: String,
121    pub required: bool,
122    pub kind: ColumnKind,
123    /// 命中的文件列(0 基);缺失为 `None`
124    pub file_index: Option<u16>,
125    /// 命中的文件表头原文
126    pub file_header: Option<String>,
127    pub matched_by: MatchKind,
128}
129
130impl ResolvedColumn {
131    pub fn is_matched(&self) -> bool {
132        self.file_index.is_some()
133    }
134}
135
136/// 表头解析结果
137#[derive(Debug, Clone)]
138pub struct HeaderMap {
139    /// 按声明顺序对齐的列(含缺失列)
140    pub columns: Vec<ResolvedColumn>,
141    /// 文件表头原文(按列序,多行表头已拼接)
142    pub file_headers: Vec<String>,
143    /// 文件名里没被任何声明列用到的列
144    pub unmapped: Vec<(u16, String)>,
145    /// 实际使用的表头行(0 基)
146    pub header_row: u32,
147    /// 表头占几行
148    pub header_span: u32,
149}
150
151impl HeaderMap {
152    /// 声明列 → 文件列索引
153    pub fn index_of(&self, header: &str) -> Option<u16> {
154        self.columns
155            .iter()
156            .find(|c| c.header == header && c.file_index.is_some())
157            .and_then(|c| c.file_index)
158    }
159
160    pub fn resolved(&self, header: &str) -> Option<&ResolvedColumn> {
161        self.columns.iter().find(|c| c.header == header)
162    }
163
164    /// 文件列 → 文件表头
165    pub fn file_header(&self, col: u16) -> Option<&str> {
166        self.file_headers.get(col as usize).map(|s| s.as_str())
167    }
168
169    /// 缺哪些必填列
170    pub fn missing_required(&self) -> Vec<String> {
171        self.columns
172            .iter()
173            .filter(|c| c.required && !c.is_matched())
174            .map(|c| c.header.clone())
175            .collect()
176    }
177
178    /// 未匹配的文件列
179    pub fn unknown_columns(&self) -> Vec<String> {
180        self.unmapped.iter().map(|(_, h)| h.clone()).collect()
181    }
182
183    /// 表头自适应报告(预览接口直接返回给前端)
184    pub fn analysis(&self) -> HeaderAnalysis {
185        HeaderAnalysis {
186            header_row: self.header_row + 1,
187            header_span: self.header_span,
188            total_columns: self.file_headers.len(),
189            matched: self
190                .columns
191                .iter()
192                .filter(|c| c.is_matched())
193                .map(|c| MatchedColumn {
194                    header: c.header.clone(),
195                    file_header: c.file_header.clone().unwrap_or_default(),
196                    excel_column: excel_column_name(c.file_index.unwrap_or(0)),
197                    matched_by: c.matched_by.as_str().to_string(),
198                })
199                .collect(),
200            missing: self.missing_required(),
201            unknown: self.unknown_columns(),
202        }
203    }
204
205    /// 完全动态:不声明列,文件的每一列都收下来
206    pub fn dynamic(file_headers: Vec<String>) -> Self {
207        let columns = file_headers
208            .iter()
209            .enumerate()
210            .map(|(i, h)| ResolvedColumn {
211                order: i,
212                header: h.clone(),
213                required: false,
214                kind: ColumnKind::Any,
215                file_index: Some(i as u16),
216                file_header: Some(h.clone()),
217                matched_by: MatchKind::Exact,
218            })
219            .collect();
220        Self {
221            columns,
222            file_headers,
223            unmapped: Vec::new(),
224            header_row: 0,
225            header_span: 1,
226        }
227    }
228}
229
230/// 表头自适应报告(返回给前端的"列匹配结果")
231#[derive(Debug, Clone, Serialize)]
232#[serde(rename_all = "camelCase")]
233pub struct HeaderAnalysis {
234    /// 表头行号(1 基,前端展示用)
235    pub header_row: u32,
236    pub header_span: u32,
237    pub total_columns: usize,
238    pub matched: Vec<MatchedColumn>,
239    /// 缺失的必填列
240    pub missing: Vec<String>,
241    /// 文件中未识别的列(可作为"多出来的列"提示)
242    pub unknown: Vec<String>,
243}
244
245#[derive(Debug, Clone, Serialize)]
246#[serde(rename_all = "camelCase")]
247pub struct MatchedColumn {
248    /// 模型字段对应的标准表头
249    pub header: String,
250    /// 文件里的实际表头
251    pub file_header: String,
252    /// Excel 列号(A/B/AA...)
253    pub excel_column: String,
254    /// exact / alias / fuzzy / index
255    pub matched_by: String,
256}
257
258/// 表头归一化
259pub fn normalize_header(raw: &str) -> String {
260    let t = normalize_text(raw);
261    let mut out = String::with_capacity(t.len());
262    for c in t.chars() {
263        match c {
264            ' ' | '\t' | '\r' | '\n' | '\u{3000}' | '\u{00a0}' => {}
265            // 必填标记 / 常见装饰
266            '*' | '★' | '☆' | '●' | '▲' => {}
267            '(' => out.push('('),
268            ')' => out.push(')'),
269            ':' => out.push(':'),
270            ',' | '、' => out.push(','),
271            '/' => out.push('/'),
272            '-' | '—' | '–' => out.push('-'),
273            c => out.push(c.to_ascii_lowercase()),
274        }
275    }
276    // 去掉尾部冒号
277    while out.ends_with(':') || out.ends_with('(') {
278        out.pop();
279    }
280    out
281}
282
283/// 列索引 → Excel 列号(0 → A,25 → Z,26 → AA)
284pub fn excel_column_name(index: u16) -> String {
285    let mut n = index as u32;
286    let mut out = String::new();
287    loop {
288        let r = (n % 26) as u8;
289        out.insert(0, (b'A' + r) as char);
290        if n < 26 {
291            break;
292        }
293        n = n / 26 - 1;
294    }
295    out
296}
297
298/// 按声明列动态解析文件表头
299pub fn resolve_headers(
300    file_headers: &[String],
301    defs: &[ColumnDef],
302    opts: &HeaderOptions,
303) -> HeaderMap {
304    let norm: Vec<String> = file_headers
305        .iter()
306        .map(|h| normalize_key(h, opts))
307        .collect();
308    let mut claimed = vec![false; file_headers.len()];
309    let mut columns = Vec::with_capacity(defs.len());
310
311    for (order, def) in defs.iter().enumerate() {
312        if !def.is_importable() {
313            continue;
314        }
315        let target = normalize_key(&def.header, opts);
316        let alias_keys: Vec<String> = def.aliases.iter().map(|a| normalize_key(a, opts)).collect();
317
318        let mut matched: Option<(usize, MatchKind)> = None;
319
320        // 1) 标准表头精确
321        if let Some(i) = find_exact(&norm, &claimed, std::slice::from_ref(&target)) {
322            matched = Some((i, MatchKind::Exact));
323        }
324        // 2) 别名
325        if matched.is_none() {
326            if let Some(i) = find_exact(&norm, &claimed, &alias_keys) {
327                matched = Some((i, MatchKind::Alias));
328            }
329        }
330        // 3) 模糊包含(差异最小的优先)
331        if matched.is_none() && opts.fuzzy {
332            let mut keys = vec![target.clone()];
333            keys.extend(alias_keys.iter().cloned());
334            if let Some(i) = find_fuzzy(&norm, &claimed, &keys) {
335                matched = Some((i, MatchKind::Fuzzy));
336            }
337        }
338        // 4) 列序回退
339        if matched.is_none() && opts.allow_index_fallback && order < norm.len() && !claimed[order] {
340            matched = Some((order, MatchKind::IndexFallback));
341        }
342
343        match matched {
344            Some((i, kind)) => {
345                claimed[i] = true;
346                columns.push(ResolvedColumn {
347                    order,
348                    header: def.header.clone(),
349                    required: def.required,
350                    kind: def.kind,
351                    file_index: Some(i as u16),
352                    file_header: Some(file_headers[i].clone()),
353                    matched_by: kind,
354                });
355            }
356            None => columns.push(ResolvedColumn {
357                order,
358                header: def.header.clone(),
359                required: def.required,
360                kind: def.kind,
361                file_index: None,
362                file_header: None,
363                matched_by: MatchKind::Missing,
364            }),
365        }
366    }
367
368    let unmapped: Vec<(u16, String)> = file_headers
369        .iter()
370        .enumerate()
371        .filter(|(i, _)| !claimed[*i])
372        .map(|(i, h)| (i as u16, h.clone()))
373        .collect();
374
375    HeaderMap {
376        columns,
377        file_headers: file_headers.to_vec(),
378        unmapped,
379        header_row: opts.row_index,
380        header_span: opts.row_span.max(1),
381    }
382}
383
384fn normalize_key(raw: &str, opts: &HeaderOptions) -> String {
385    if opts.normalize {
386        normalize_header(raw)
387    } else {
388        raw.trim().to_ascii_lowercase()
389    }
390}
391
392fn find_exact(norm: &[String], claimed: &[bool], keys: &[String]) -> Option<usize> {
393    keys.iter().find_map(|k| {
394        if k.is_empty() {
395            return None;
396        }
397        norm.iter()
398            .enumerate()
399            .find(|(i, h)| !claimed[*i] && h.as_str() == k.as_str())
400            .map(|(i, _)| i)
401    })
402}
403
404/// 模糊匹配:互相包含,取差异最小(最贴近)的未占用列
405fn find_fuzzy(norm: &[String], claimed: &[bool], keys: &[String]) -> Option<usize> {
406    let mut best: Option<(usize, usize)> = None;
407    for key in keys {
408        if key.chars().count() < 2 {
409            continue;
410        }
411        for (i, h) in norm.iter().enumerate() {
412            if claimed[i] || h.is_empty() {
413                continue;
414            }
415            if h.contains(key.as_str()) || key.contains(h.as_str()) {
416                let diff = h.chars().count().abs_diff(key.chars().count());
417                if best.map(|(_, d)| diff < d).unwrap_or(true) {
418                    best = Some((i, diff));
419                }
420            }
421        }
422    }
423    best.map(|(i, _)| i)
424}
425
426/// 便捷:声明列名 → 声明的 [`ColumnDef`] 列表(默认 `Any` 类型、非必填)
427pub fn simple_columns<I, S>(headers: I) -> Vec<ColumnDef>
428where
429    I: IntoIterator<Item = S>,
430    S: Into<String>,
431{
432    headers.into_iter().map(ColumnDef::new).collect()
433}
434
435/// 便捷:把文件表头映射成 `声明表头 → 文件列索引`
436pub fn index_map(map: &HeaderMap) -> HashMap<String, u16> {
437    map.columns
438        .iter()
439        .filter_map(|c| c.file_index.map(|i| (c.header.clone(), i)))
440        .collect()
441}
442
443#[cfg(test)]
444mod tests {
445    use super::*;
446
447    fn headers(v: &[&str]) -> Vec<String> {
448        v.iter().map(|s| s.to_string()).collect()
449    }
450
451    #[test]
452    fn test_exact_and_alias_and_fuzzy() {
453        let defs = vec![
454            ColumnDef::new("工厂名称").required(),
455            ColumnDef::new("工厂品号").alias("品号").required(),
456            ColumnDef::new("报价(USD)").kind(ColumnKind::Decimal),
457            ColumnDef::new("图片1").image(),
458        ];
459        let file = headers(&[" 工厂名称 ", "品 号", "报价(USD)(含税)", "备注", "图片1"]);
460        let map = resolve_headers(&file, &defs, &HeaderOptions::default());
461        assert_eq!(map.index_of("工厂名称"), Some(0));
462        assert_eq!(map.index_of("工厂品号"), Some(1));
463        assert_eq!(map.index_of("报价(USD)"), Some(2));
464        assert_eq!(map.index_of("图片1"), Some(4));
465        assert_eq!(map.missing_required(), Vec::<String>::new());
466        assert_eq!(map.unknown_columns(), vec!["备注".to_string()]);
467    }
468
469    #[test]
470    fn test_missing_required() {
471        let defs = vec![
472            ColumnDef::new("工厂名称").required(),
473            ColumnDef::new("品名").required(),
474        ];
475        let file = headers(&["工厂名称"]);
476        let map = resolve_headers(&file, &defs, &HeaderOptions::default());
477        assert_eq!(map.missing_required(), vec!["品名".to_string()]);
478    }
479
480    #[test]
481    fn test_strict_mode_rejects_fuzzy() {
482        let defs = vec![ColumnDef::new("报价(USD)")];
483        let file = headers(&["报价(USD)(含税)"]);
484        let loose = resolve_headers(&file, &defs, &HeaderOptions::default());
485        assert_eq!(loose.index_of("报价(USD)"), Some(0));
486        let strict = resolve_headers(&file, &defs, &HeaderOptions::strict());
487        assert_eq!(strict.index_of("报价(USD)"), None);
488    }
489
490    #[test]
491    fn test_excel_column_name() {
492        assert_eq!(excel_column_name(0), "A");
493        assert_eq!(excel_column_name(25), "Z");
494        assert_eq!(excel_column_name(26), "AA");
495        assert_eq!(excel_column_name(701), "ZZ");
496        assert_eq!(excel_column_name(702), "AAA");
497    }
498}