@@ -425,6 +425,17 @@ OLLAMA_BASE_URL=http://host.docker.internal:11434
 # DOCREADER_DOCX_MAX_PAGES=0
 # MarkItDown（重型解析器）并发 worker 数。0 关闭限流；默认 1 适合单机/GPU 受限。
 # DOCREADER_MARKITDOWN_MAX_WORKERS=1
+# ----- XLSX / Excel -----
+# 按显示格式物化百分比单元格。Excel 的百分比是显示格式而非存储值：单元格实存 0.6112，
+# 靠 "0.00%" 渲染成 61.12%，而 pandas/openpyxl 只读到分数，报表里的 61.12% 变成 0.6112
+# （100 倍偏差）。开启后百分比单元格变成字面量文本 "61.12%"。默认 false：开启会使单元格
+# 由数值变为字符串，改变下游排序/计算看到的内容；关闭时读取行为与升级前完全一致。
+# 单次上传可用 parser_engine_overrides.xlsx_percent_as_text 覆盖（true/false）。
+# DOCREADER_XLSX_PERCENT_AS_TEXT=false
+# 兜底：同一行有 >= N 个显式百分比格式单元格时，把该行漏标格式的 0<|v|<1 数字也按百分比
+# 处理（源文件偶有漏刷格式的格子，每命中一次打 INFO 日志）。仅在上一开关开启时生效；
+# 0=关闭该兜底（默认）。
+# DOCREADER_XLSX_PCT_ROW_HINT_MIN=0
 # 出站 HTTP/HTTPS 代理（抓取网页 / 远程图片时用）。
 # DOCREADER_EXTERNAL_HTTP_PROXY=
 # DOCREADER_EXTERNAL_HTTPS_PROXY=
 
@@ -463,6 +463,16 @@ services:
       # ========== 解析通用 ==========
       - DOCREADER_DOCX_MAX_PAGES=${DOCREADER_DOCX_MAX_PAGES:-0}
       - DOCREADER_MARKITDOWN_MAX_WORKERS=${DOCREADER_MARKITDOWN_MAX_WORKERS:-1}
+      # ========== XLSX / Excel ==========
+      # 按显示格式物化百分比单元格：Excel 的百分比是显示格式而非存储值，单元格实存
+      # 0.6112 靠 "0.00%" 渲染成 61.12%，而 pandas/openpyxl 只读到分数，报表里的
+      # 61.12% 会变成 0.6112（100 倍偏差）。开启后该单元格变成字面量文本 "61.12%"。
+      # 默认 false：开启会使单元格由数值变为字符串，改变下游排序/计算看到的内容，
+      # 存量部署行为保持不变。单次上传可用 parser_engine_overrides.xlsx_percent_as_text 覆盖。
+      - DOCREADER_XLSX_PERCENT_AS_TEXT=${DOCREADER_XLSX_PERCENT_AS_TEXT:-false}
+      # 同一行有 >= N 个显式百分比格式单元格时，把该行漏标格式的 0<|v|<1 数字也按百分比
+      # 处理（源文件偶有漏刷格式的格子）。仅在上一开关开启时生效；0=关闭（默认）。
+      - DOCREADER_XLSX_PCT_ROW_HINT_MIN=${DOCREADER_XLSX_PCT_ROW_HINT_MIN:-0}
       # 出站 HTTP/HTTPS 代理（抓取网页 / 远程图片时）
       - DOCREADER_EXTERNAL_HTTP_PROXY=${DOCREADER_EXTERNAL_HTTP_PROXY:-}
       - DOCREADER_EXTERNAL_HTTPS_PROXY=${DOCREADER_EXTERNAL_HTTPS_PROXY:-}
 
@@ -74,11 +74,16 @@ def __init__(
         file_name: str = "",
         file_type: str | None = None,
         xlsx_first_row_as_header: Any = False,
+        xlsx_percent_as_text: Any = None,
         **kwargs: Any,
     ):
         super().__init__(file_name=file_name, file_type=file_type, **kwargs)
         self.xlsx_first_row_as_header = _parse_bool(xlsx_first_row_as_header)
-    
+        # Tri-state: None (or an empty value) keeps the deployment default from
+        # DOCREADER_XLSX_PERCENT_AS_TEXT, an explicit value wins. Same
+        # precedence as the pdf_force_scanned parser override.
+        self.xlsx_percent_as_text = _parse_optional_bool(xlsx_percent_as_text)
+
     def parse_into_text(self, content: bytes) -> Document:
         """Parse Excel file bytes into a Document object.
         
@@ -100,7 +105,11 @@ def parse_into_text(self, content: bytes) -> Document:
         source_blocks: List[dict] = []
         start, end = 0, 0
 
-        excel_file = _open_excel_file(content, file_type=self.file_type)
+        excel_file = _open_excel_file(
+            content,
+            file_type=self.file_type,
+            percent_as_text=self.xlsx_percent_as_text,
+        )
 
         # Process each sheet in the Excel file
         for excel_sheet_name in excel_file.sheet_names:
@@ -205,15 +214,27 @@ def _parse_bool(value: Any) -> bool:
     return str(value).strip().lower() in {"1", "true", "yes", "on"}
 
 
-def _prepare_xlsx_bytes(data: bytes) -> bytes:
+def _parse_optional_bool(value: Any) -> bool | None:
+    """Parse a tri-state parser override; None keeps the deployment default."""
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return value
+    text = str(value).strip().lower()
+    if not text:
+        return None
+    return text in {"1", "true", "yes", "y", "on"}
+
+
+def _prepare_xlsx_bytes(data: bytes, percent_as_text: bool | None = None) -> bytes:
     repaired = repair_xlsx_bytes(data)
     if repaired is not None:
         data = repaired
     readable = strip_unreadable_ranges_xlsx(data)
     if readable is not None:
         data = readable
     try:
-        return fill_merged_cells_xlsx(data)
+        return fill_merged_cells_xlsx(data, percent_as_text=percent_as_text)
     except TypeError:
         # A non-conforming styles.xml (empty/malformed fills) makes openpyxl's
         # load_workbook raise before pandas ever sees the file (#3637).
@@ -222,10 +243,14 @@ def _prepare_xlsx_bytes(data: bytes) -> bytes:
         sanitized = sanitize_xlsx_styles(data)
         if sanitized is None:
             raise
-        return fill_merged_cells_xlsx(sanitized)
+        return fill_merged_cells_xlsx(sanitized, percent_as_text=percent_as_text)
 
 
-def _open_excel_file(content: bytes, file_type: str | None = None) -> pd.ExcelFile:
+def _open_excel_file(
+    content: bytes,
+    file_type: str | None = None,
+    percent_as_text: bool | None = None,
+) -> pd.ExcelFile:
     """Open an Excel workbook with explicit engine selection and fallbacks."""
     data = content
     converted_via_soffice = False
@@ -254,7 +279,7 @@ def _open_excel_file(content: bytes, file_type: str | None = None) -> pd.ExcelFi
 
         engine = engine_for_format(ext)
         if ext == "xlsx":
-            data = _prepare_xlsx_bytes(data)
+            data = _prepare_xlsx_bytes(data, percent_as_text=percent_as_text)
             engine = "openpyxl"
         try:
             return pd.ExcelFile(BytesIO(data), engine=engine)
@@ -269,7 +294,7 @@ def _open_excel_file(content: bytes, file_type: str | None = None) -> pd.ExcelFi
             if repaired is None:
                 raise
             logger.info("Repaired XLSX sharedStrings packaging before parse")
-            data = _prepare_xlsx_bytes(repaired)
+            data = _prepare_xlsx_bytes(repaired, percent_as_text=percent_as_text)
             continue
         except ValueError as exc:
             if converted_via_soffice or "cannot be determined" not in str(exc):
 
@@ -3,26 +3,207 @@
 from __future__ import annotations
 
 import logging
+import os
+import re
 import zipfile
 from io import BytesIO
 
 logger = logging.getLogger(__name__)
 
+# --- Percentage number formats (opt-in) --------------------------------------
+# Excel keeps a percentage as the stored fraction plus a display format: the
+# cell holds 0.61123366 and "0.00%" renders it as 61.12%. openpyxl and pandas
+# read only the fraction, so a value the user sees as 61.12% reaches the
+# pipeline as 0.6112 — a 100x error that a model will copy verbatim into a
+# report. When this switch is on, percentage cells are materialized as the
+# literal text the spreadsheet shows ("61.12%") instead.
+#
+# It is off by default on purpose: the cell changes from a number into a
+# string, so anything that sorts, aggregates or computes with it sees different
+# input. With it off, every workbook is read exactly as before. A single upload
+# can override it through parser_engine_overrides.xlsx_percent_as_text.
+PERCENT_AS_TEXT_ENV = "DOCREADER_XLSX_PERCENT_AS_TEXT"
 
-def fill_merged_cells_xlsx(content: bytes) -> bytes:
+# Only percentages are materialized. Currency and thousands separators change
+# how a number is displayed, not what it means ("1,234,567" and 1234567 are the
+# same number), so rewriting them would churn cells for no semantic gain, and
+# date formats are already converted to datetimes by openpyxl.
+
+# --- Same-row hint fallback (opt-in, off by default) -------------------------
+# Workbooks occasionally leave one cell of a percentage row without a
+# percentage format (a real financial statement had 折旧率 0.0592 formatted as
+# "0.00_ ;[Red]\-0.00\ "). When a row carries at least this many explicitly
+# percentage-formatted cells, an unformatted 0 < |value| < 1 number in that row
+# is treated as a percentage too. Only consulted while percent materialization
+# is on; 0 disables the fallback.
+ROW_HINT_MIN_ENV = "DOCREADER_XLSX_PCT_ROW_HINT_MIN"
+_DEFAULT_ROW_HINT_MIN = 0
+
+# Only materialize a known numeric percentage pattern. Excel literals, conditions,
+# scaling and arbitrary decorations require a full format renderer; leave those
+# values untouched rather than guessing that every '%' means multiply by 100.
+_PERCENT_PATTERN = re.compile(
+    r"(?P<sign>-?)(?P<open>\()?(?P<group>#,##)?0"
+    r"(?:\.(?P<decimals>0+))?%(?P<close>\))?"
+)
+_FORMAT_COLOR = re.compile(
+    r"\[(?:Black|Blue|Cyan|Green|Magenta|Red|White|Yellow|Color[0-9]+)\]", re.I
+)
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    value = os.environ.get(name)
+    if value is None or not str(value).strip():
+        return default
+    return str(value).strip().lower() in {"1", "true", "yes", "y", "on"}
+
+
+def _env_int(name: str, default: int) -> int:
+    try:
+        return int(str(os.environ.get(name, default)).strip())
+    except (TypeError, ValueError):
+        return default
+
+
+def percent_as_text_default() -> bool:
+    """Deployment-wide default for materializing percentage formats.
+
+    Read per call (not at import time) so the value can be flipped without a
+    module reload; a per-upload override still wins over it.
+    """
+    return _env_bool(PERCENT_AS_TEXT_ENV, False)
+
+
+def _format_percentage(value, number_format: str):
+    """Render supported Excel percentage formats, leaving other formats intact."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    if not number_format or "%" not in number_format:
+        return None
+    # Quoted/escaped percentages are literal text, not percentage operators.
+    # Reject unsupported conditions across all sections before selecting one.
+    cleaned = _FORMAT_COLOR.sub("", number_format)
+    if any(char in cleaned for char in ('"', "\\", "_", "*", "[", "]")):
+        return None
+    sections = cleaned.split(";")
+    if len(sections) > 4:
+        return None
+    section_index = 1 if value < 0 and len(sections) >= 2 else 0
+    if value == 0 and len(sections) >= 3:
+        section_index = 2
+    match = _PERCENT_PATTERN.fullmatch(sections[section_index].strip())
+    if not match or bool(match["open"]) != bool(match["close"]):
+        return None
+    decimals = len(match["decimals"] or "")
+    # Excel's negative section formats the magnitude; a single section instead
+    # supplies the minus sign automatically.
+    amount = abs(value) if section_index == 1 else value
+    grouping = "," if match["group"] else ""
+    try:
+        number = f"{float(amount) * 100:{grouping}.{decimals}f}"
+        return f"{match['sign']}{match['open'] or ''}{number}%{match['close'] or ''}"
+    except (TypeError, ValueError, OverflowError):
+        return None
+
+
+def _materialize_percentage_cells(ws, row_hint_min: int) -> tuple[int, int]:
+    """Rewrite the percentage-formatted numbers of *ws* as their display text.
+
+    Must run before merged ranges are filled: only the master cell of a merge
+    carries a number_format while the covered cells are General, so filling
+    first would copy a bare fraction into rows 2..n and leave it unconverted —
+    the same row would then show both "0.55%" and 0.005509433890047721.
+
+    Returns ``(materialized, hinted)`` cell counts.
+    """
+    row_hints: dict = {}
+    if row_hint_min > 0:
+        # Count the explicit percentage formats before converting anything:
+        # the conversion below resets number_format to General.
+        for row in ws.iter_rows():
+            count = sum(
+                1
+                for cell in row
+                if type(cell.value) in (int, float)  # noqa: E721 - excludes bool
+                and _format_percentage(cell.value, cell.number_format) is not None
+            )
+            if count:
+                row_hints[row[0].row] = count
+
+    materialized = 0
+    hinted = 0
+    for row in ws.iter_rows():
+        hint = row_hints.get(row[0].row, 0)
+        for cell in row:
+            if type(cell.value) not in (int, float):  # noqa: E721 - excludes bool
+                continue
+            text = _format_percentage(cell.value, cell.number_format)
+            if (
+                text is None
+                and "%" not in str(cell.number_format or "")
+                and hint >= row_hint_min > 0
+                and 0 < abs(cell.value) < 1
+            ):
+                # Fallback for a cell that lost its percentage format while its
+                # row kept one. Logged because it rewrites an unformatted value.
+                text = f"{float(cell.value) * 100:.2f}%"
+                hinted += 1
+                logger.info(
+                    "XLSX pre-parse: %s!%s%d has no percentage format but its row "
+                    "does; reading it as %.2f%% (stored value %r)",
+                    ws.title,
+                    cell.column_letter,
+                    cell.row,
+                    float(cell.value) * 100,
+                    cell.value,
+                )
+            if text is None:
+                continue
+            cell.value = text
+            cell.number_format = "General"
+            materialized += 1
+    return materialized, hinted
+
+
+def fill_merged_cells_xlsx(
+    content: bytes, percent_as_text: bool | None = None
+) -> bytes:
     """Unmerge ranges and copy the master cell value into every covered cell.
 
     openpyxl only stores values on the top-left cell of a merge; pandas then
     sees NaN in the rest. Filling makes row-wise RAG chunks retain context.
+
+    ``percent_as_text`` also materializes percentage-formatted numbers as the
+    text the spreadsheet displays ("0.6112" -> "61.12%"), because the stored
+    fraction is 100x off from what a reader sees. ``None`` (the default) uses
+    the ``DOCREADER_XLSX_PERCENT_AS_TEXT`` deployment default, which is off, so
+    the default path is unchanged.
     """
+    if percent_as_text is None:
+        percent_as_text = percent_as_text_default()
+
     if not zipfile.is_zipfile(BytesIO(content)):
         return content
 
     from openpyxl import load_workbook
 
     wb = load_workbook(BytesIO(content), data_only=True)
     changed = False
+    materialized_cells = 0
+    hinted_cells = 0
+    row_hint_min = (
+        _env_int(ROW_HINT_MIN_ENV, _DEFAULT_ROW_HINT_MIN) if percent_as_text else 0
+    )
+
     for ws in wb.worksheets:
+        if percent_as_text:
+            # Before the merge fill below — see _materialize_percentage_cells.
+            materialized, hinted = _materialize_percentage_cells(ws, row_hint_min)
+            materialized_cells += materialized
+            hinted_cells += hinted
+            if materialized:
+                changed = True
+
         if not ws.merged_cells.ranges:
             continue
         for merge_range in list(ws.merged_cells.ranges):
@@ -52,5 +233,13 @@ def fill_merged_cells_xlsx(content: bytes) -> bytes:
 
     out = BytesIO()
     wb.save(out)
+    if materialized_cells:
+        logger.info(
+            "Materialized %d percentage cell(s) in XLSX before parse "
+            "(%d recovered by the same-row hint fallback, threshold=%d)",
+            materialized_cells,
+            hinted_cells,
+            row_hint_min,
+        )
     logger.info("Filled merged cells in XLSX before parse")
     return out.getvalue()