feat(ocr): prioritize direct DOCX parse to resolve Google Drive numbering...

feat(ocr): prioritize direct DOCX parse to resolve Google Drive numbering corruption, add text export + regex fallback for PDFs

app.py

 """
-Document Converter API Wrapper.
-- Any file type → convert via Google Drive OCR/export
+Document Converter API.
+- DOCX → direct parse (preserves original numbering)
+- PDF/Image → Google Drive OCR → text export → regex heading
 """
 
 import os
 import logging
-import inspect
 import re
 import tempfile
 
-import httpx
-from fastapi import FastAPI, File, Form, UploadFile
-from fastapi.responses import JSONResponse
-import pymupdf4llm
+from fastapi import FastAPI, File, UploadFile
+from fastapi.responses import JSONResponse, RedirectResponse
+from fastapi.staticfiles import StaticFiles
 from ocr_drive import get_drive_service, ocr_file
 from docx_converter import convert_docx_to_markdown
 
@@ -25,6 +24,15 @@ app = FastAPI(
     description="Wrapper API: Any file type -> Google Drive OCR/export",
 )
 
+# ── Serve static UI ──
+_static_dir = os.path.join(os.path.dirname(__file__), "static")
+if os.path.isdir(_static_dir):
+    app.mount("/static", StaticFiles(directory=_static_dir, html=True), name="static")
+
+@app.get("/")
+async def root():
+    return RedirectResponse(url="/static/index.html")
+
 
 def _looks_like_low_information_markdown(md_text: str) -> bool:
     """
@@ -51,49 +59,6 @@ def _looks_like_low_information_markdown(md_text: str) -> bool:
     return len(separator_lines) >= 3 and len(meaningful_lines) <= 1
 
 
-def _convert_pdf_markdown_best_effort(doc):
-    """
-    Convert PDF to markdown and retry with OCR when output seems empty.
-    """
-    sig = inspect.signature(pymupdf4llm.to_markdown)
-    params = sig.parameters
-
-    base_kwargs = {}
-    if "show_progress" in params:
-        base_kwargs["show_progress"] = False
-
-    md_text = pymupdf4llm.to_markdown(doc, **base_kwargs)
-    low_information = _looks_like_low_information_markdown(md_text)
-
-    ocr_attempted = False
-    ocr_used = False
-    ocr_error = None
-
-    # Retry once with OCR only when the first pass is likely useless.
-    if low_information and "use_ocr" in params:
-        ocr_attempted = True
-        ocr_kwargs = dict(base_kwargs)
-        ocr_kwargs["use_ocr"] = True
-        if "ocr_language" in params:
-            ocr_kwargs["ocr_language"] = os.getenv("OCR_LANGUAGE", "vie+eng")
-
-        try:
-            md_text_ocr = pymupdf4llm.to_markdown(doc, **ocr_kwargs)
-            if len(md_text_ocr.strip()) > len(md_text.strip()):
-                md_text = md_text_ocr
-                ocr_used = True
-                low_information = _looks_like_low_information_markdown(md_text)
-        except Exception as exc:
-            ocr_error = str(exc)
-
-    return md_text, {
-        "low_information": low_information,
-        "ocr_attempted": ocr_attempted,
-        "ocr_used": ocr_used,
-        "ocr_error": ocr_error,
-    }
-
-
 @app.get("/health")
 async def health():
     return {"status": "ok"}
@@ -104,8 +69,11 @@ async def convert_file(
     files: UploadFile = File(...),
 ):
     """
-    Convert uploaded file to markdown-compatible text using Google Drive OCR/export.
-    This endpoint intentionally routes every file type through Drive processing.
+    Convert uploaded file to markdown.
+
+    Strategy:
+      1. DOCX/DOC → parse trực tiếp (giữ đúng numbering gốc, không qua Drive)
+      2. PDF/Image/Scan → Google Drive OCR → text export → regex heading
     """
     filename = files.filename or "unknown"
     ext = os.path.splitext(filename)[1].lower() or ".bin"
@@ -120,46 +88,65 @@ async def convert_file(
         )
 
     try:
-        logger.info(f"Processing file via Google Drive OCR/export: {filename}")
-
-        # Save uploaded content to a temporary file before Drive upload.
-        with tempfile.NamedTemporaryFile(delete=False, suffix=ext) as tmp:
-            tmp.write(file_bytes)
-            tmp_path = tmp.name
-
-        try:
-            drive = get_drive_service()
-            docx_bytes = ocr_file(
-                drive,
-                tmp_path,
-                source_mime_type=files.content_type,
-                filename=filename,
-                export_mode="docx",
-            )
-
-            md_text = ""
-            if docx_bytes:
-                try:
-                    parsed = convert_docx_to_markdown(docx_bytes, filename)
+        md_text = ""
+        backend_used = "unknown"
+
+        # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        # STRATEGY 1: DOCX → Parse trực tiếp (không qua Drive)
+        # Giữ đúng numbering gốc (ĐIỀU 1., 4.1., 5.2.1.)
+        # Drive sẽ nhả loạn số + ăn chữ tiếng Việt
+        # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        if ext in (".docx", ".doc"):
+            logger.info(f"DOCX detected — parsing directly (no Drive)")
+            try:
+                if ext == ".docx":
+                    parsed = convert_docx_to_markdown(file_bytes, filename)
                     md_text = parsed.get("document", {}).get("md_content", "")
-                except Exception as parse_exc:
-                    logger.warning(
-                        f"DOCX parse after Drive export failed, fallback to text export: {parse_exc}"
-                    )
+                    backend_used = "direct_docx"
+                    logger.info(f"Direct DOCX parse: {len(md_text)} chars")
+
+                    # Nếu DOCX parse ra ít quá (VD: file scan, ảnh) → cũng fallback Drive  
+                    if md_text and _looks_like_low_information_markdown(md_text):
+                        logger.warning(f"DOCX parse returned low info ({len(md_text)} chars), will try Drive OCR")
+                        md_text = ""
+            except Exception as e:
+                logger.warning(f"Direct DOCX parse failed, will try Drive OCR: {e}")
+                md_text = ""
+
+        # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        # STRATEGY 2: Nếu direct parse thất bại hoặc file không phải DOCX
+        # → Google Drive OCR (text export, KHÔNG phải DOCX export)
+        # Text export giữ đúng numbering, DOCX export nhả loạn số
+        # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        if not md_text:
+            logger.info(f"Falling back to Google Drive OCR: {filename}")
+
+            with tempfile.NamedTemporaryFile(delete=False, suffix=ext) as tmp:
+                tmp.write(file_bytes)
+                tmp_path = tmp.name
 
-            if not md_text:
-                md_text = ocr_file(
+            try:
+                drive = get_drive_service()
+
+                # Export TEXT (không phải DOCX!) — text export giữ đúng numbering
+                raw_text = ocr_file(
                     drive,
                     tmp_path,
                     source_mime_type=files.content_type,
                     filename=filename,
                     export_mode="text",
                 )
-        finally:
-            if os.path.exists(tmp_path):
-                os.remove(tmp_path)
 
-        logger.info(f"Drive OCR/export conversion done: {len(md_text)} chars")
+                if raw_text:
+                    from text_to_markdown import text_to_markdown
+                    md_text = text_to_markdown(raw_text)
+                    backend_used = "google_drive_text"
+                    logger.info(f"Drive text export + regex: {len(md_text)} chars")
+            finally:
+                if os.path.exists(tmp_path):
+                    os.remove(tmp_path)
+
+        logger.info(f"Conversion done: {len(md_text)} chars via {backend_used}")
 
         response = {
             "document": {
@@ -168,19 +155,17 @@ async def convert_file(
             },
             "meta": {
                 "low_information": _looks_like_low_information_markdown(md_text),
-                "ocr_attempted": True,
-                "ocr_used": True,
-                "backend": "google_drive",
+                "backend": backend_used,
                 "source_content_type": files.content_type,
             },
         }
         if not md_text:
-            response["warning"] = "Google Drive did not extract text for this file."
+            response["warning"] = "Could not extract text from this file."
 
         return JSONResponse(content=response)
     except Exception as e:
-        logger.error(f"Drive OCR/export conversion failed: {str(e)}")
+        logger.error(f"Conversion failed: {str(e)}")
         return JSONResponse(
             status_code=500,
-            content={"error": f"Drive OCR/export conversion failed: {str(e)}"},
+            content={"error": f"Conversion failed: {str(e)}"},
         )

docx_converter.py

@@ -225,16 +225,36 @@ def _paragraph_to_markdown(
     if re.fullmatch(r"Trang\s+\d+(/\d+)?|Page\s+\d+(/\d+)?|\d+\s*-.*-.*|^\d+$", line, re.IGNORECASE):
         return ""
 
-    # Apply heading styles
+    # ── Detect heading level ──────────────────────────────
+    # Ưu tiên 1: Đọc outlineLvl trực tiếp từ XML (chính xác nhất, Word tự gắn)
+    # Ưu tiên 2: Đọc từ tên Style (Heading1, Heading2...)
+    # Ưu tiên 3: Regex nhận diện cấu trúc pháp lý VN (Phần, Chương, Điều, Mục...)
+    #            CHỈ áp dụng khi style có chứa "heading" hoặc "title"
+    # → Tuyệt đối KHÔNG bịa heading từ text bôi đậm thông thường.
+
     heading_level = 0
-    style_lower = style_name.lower()
-    if "heading" in style_lower:
-        for i in range(1, 7):
-            if str(i) in style_name:
-                heading_level = i
-                break
-        if heading_level == 0 and ("title" in style_lower or "heading" in style_lower):
-            heading_level = 1
+
+    # ── P1: outlineLvl trong XML (ưu tiên cao nhất) ──
+    if ppr is not None:
+        outline_el = ppr.find("w:outlineLvl", NS)
+        if outline_el is not None:
+            try:
+                raw_lvl = int(outline_el.get(f"{{{WORD_NS}}}val", "9"))
+                if 0 <= raw_lvl <= 5:
+                    heading_level = raw_lvl + 1  # outlineLvl 0 = H1, 1 = H2, ...
+            except ValueError:
+                pass
+
+    # ── P2: Style name (nếu outlineLvl không có) ──
+    if heading_level == 0:
+        style_lower = style_name.lower()
+        if "heading" in style_lower or "title" in style_lower:
+            for i in range(1, 7):
+                if str(i) in style_name:
+                    heading_level = i
+                    break
+            if heading_level == 0:
+                heading_level = 1  # Generic "Heading" hoặc "Title" → H1
 
     if heading_level > 0:
         return f"{'#' * heading_level} {line}"
@@ -260,6 +280,17 @@ def _paragraph_to_markdown(
             numbering_map.get(num_id, {}).get(ilvl, {}).get("start", 1) - 1,
         ) + 1
 
+        # ── CRITICAL: Reset sub-level counters when parent level changes ──
+        # Khi ĐIỀU 4 (ilvl 0) tăng counter, phải reset ilvl 1,2,3...
+        # Nếu không: 4.1 thành 4.10 vì counter ilvl 1 vẫn tiếp tục từ ĐIỀU trước
+        current_ilvl_int = int(ilvl)
+        if num_id in numbering_map:
+            for sub_ilvl in list(numbering_map[num_id].keys()):
+                if int(sub_ilvl) > current_ilvl_int:
+                    sub_key = f"{num_id}_{sub_ilvl}"
+                    if sub_key in list_counters:
+                        del list_counters[sub_key]
+
         # Render the full numbering text
         rendered = _render_lvl_text(
             lvl_text, list_counters, num_id, ilvl, numbering_map
@@ -370,6 +401,9 @@ def convert_docx_to_markdown(file_bytes: bytes, filename: str) -> dict:
         md_content = md_content.replace("\n\n\n", "\n\n")
     md_content = md_content.strip()
 
+    # ── Post-processing: fix heading levels dựa trên nội dung text ──
+    md_content = _postprocess_legal_headings(md_content)
+
     return {
         "document": {
             "filename": filename,
@@ -378,6 +412,79 @@ def convert_docx_to_markdown(file_bytes: bytes, filename: str) -> dict:
     }
 
 
+# ───────────────────────────────────────────────────────────────
+# Post-processing: regex-based heading detection trên markdown
+# ───────────────────────────────────────────────────────────────
+
+_RE_DIEU = re.compile(
+    r"^(?:#+\s+)?(?:\*{0,3})((?:ĐIỀU|Điều)\s+\d+[\.\:]?\s*.+?)(?:\*{0,3})\s*$",
+    re.MULTILINE | re.UNICODE,
+)
+_RE_H2_NUM = re.compile(
+    r"^(?:#+\s+)?(?:\*{0,3})(\d+\.\d+\.?\s+.+?)(?:\*{0,3})\s*$",
+    re.MULTILINE | re.UNICODE,
+)
+_RE_H3_NUM = re.compile(
+    r"^(?:#+\s+)?(?:\*{0,3})(\d+\.\d+\.\d+\.?\s+.+?)(?:\*{0,3})\s*$",
+    re.MULTILINE | re.UNICODE,
+)
+_RE_ALL_CAPS_LINE = re.compile(
+    r"^(?:#+\s+)?(?:\*{0,3})([A-ZÀ-Ỹ\s\-–:,\.]+)(?:\*{0,3})\s*$",
+    re.MULTILINE | re.UNICODE,
+)
+
+
+def _postprocess_legal_headings(md: str) -> str:
+    """
+    Post-process markdown: phát hiện cấu trúc pháp lý VN và gán đúng heading.
+    Chạy regex trên markdown text đã convert, bất kể DOCX heading style.
+    """
+    lines = md.split("\n")
+    result = []
+
+    for line in lines:
+        stripped = line.strip()
+        if not stripped:
+            result.append(line)
+            continue
+
+        # Bỏ heading markers hiện có để đánh giá lại
+        clean = re.sub(r"^#+\s+", "", stripped)
+        # Bỏ bold/italic markers để check text gốc
+        text_only = re.sub(r"\*{1,3}", "", clean).strip()
+
+        if not text_only or len(text_only) > 150:
+            result.append(line)
+            continue
+
+        # ── Priority 1: "ĐIỀU X." pattern → H1 ──
+        if re.match(r"^(?:ĐIỀU|Điều)\s+\d+[\.\:\s]", text_only, re.UNICODE | re.IGNORECASE):
+            result.append(f"# {clean}")
+            continue
+
+        # ── Priority 2: ALL CAPS short line → H1 ──
+        letters = [c for c in text_only if c.isalpha()]
+        if letters and all(c == c.upper() for c in letters) and len(text_only) < 100:
+            # Không phải dòng bảng hoặc list
+            if not text_only.startswith("|") and not text_only.startswith("-"):
+                result.append(f"# {clean}")
+                continue
+
+        # ── Priority 3: "X.Y.Z." pattern → H3 ──
+        if re.match(r"^\d+\.\d+\.\d+\.?\s", text_only):
+            result.append(f"### {clean}")
+            continue
+
+        # ── Priority 4: "X.Y." pattern → H2 ──
+        if re.match(r"^\d+\.\d+\.?\s", text_only):
+            result.append(f"## {clean}")
+            continue
+
+        result.append(line)
+
+    return "\n".join(result)
+
+
 def _extract_headers_footers(z: zipfile.ZipFile) -> List[str]:
     """Extract text from document headers and footers."""
     parts = []

final_test.txt

 Testing test/67_formatted.docx

format_contract.py

+"""
+format_contract.py
+------------------
+Phục hồi Heading style cho file DOCX sau khi Google Drive OCR export.
+Google Drive OCR hay xoá sạch heading styles VÀ bold formatting.
+
+Logic detect heading (không cần bold):
+  - ALL CAPS + < 120 ký tự           →  Heading 1
+  - Regex: "ĐIỀU X." / "Chương X"    →  Heading 1
+  - Regex: "X.Y." (sub-section)      →  Heading 2
+  - Bold + Mixed case + < 120 ký tự  →  Heading 2 (fallback)
+"""
+
+import re
+import shutil
+from io import BytesIO
+from pathlib import Path
+
+from docx import Document
+from docx.oxml import OxmlElement
+from docx.oxml.ns import qn
+from lxml import etree
+
+
+# ───────────────────────────────────────────────
+# Regex patterns cho cấu trúc pháp lý VN
+# ───────────────────────────────────────────────
+
+# Heading 1: "ĐIỀU 1.", "Điều 1.", "CHƯƠNG I", "Phần 1", etc.
+H1_PATTERNS = re.compile(
+    r"^(?:"
+    r"(?:ĐIỀU|Điều)\s+\d+[\.\:\s]"       # Điều 1. / ĐIỀU 1:
+    r"|(?:CHƯƠNG|Chương)\s+[IVXLCDM\d]+"  # Chương I / CHƯƠNG 2
+    r"|(?:PHẦN|Phần)\s+[IVXLCDM\d]+"      # Phần I / PHẦN 2
+    r"|(?:MỤC|Mục)\s+[IVXLCDM\d]+"        # Mục I / MỤC 2
+    r")",
+    re.IGNORECASE | re.UNICODE,
+)
+
+# Heading 2: "1.1.", "2.3.", "10.26." etc.
+H2_PATTERNS = re.compile(
+    r"^\d+\.\d+\.?\s",
+    re.UNICODE,
+)
+
+# Heading 3: "1.1.1.", "2.3.4." etc.
+H3_PATTERNS = re.compile(
+    r"^\d+\.\d+\.\d+\.?\s",
+    re.UNICODE,
+)
+
+
+# ───────────────────────────────────────────────
+# Helpers
+# ───────────────────────────────────────────────
+
+def _is_all_caps(text: str) -> bool:
+    """True nếu toàn bộ chữ cái trong text đều là hoa."""
+    letters = [c for c in text if c.isalpha()]
+    return len(letters) > 0 and all(c == c.upper() for c in letters)
+
+
+def _para_is_bold(para) -> bool:
+    """True nếu đoạn văn có ít nhất 1 run in đậm."""
+    return any(run.bold for run in para.runs if run.text.strip())
+
+
+def _ensure_heading_style(doc, style_id: str, style_name: str, outline_level: int, font_size: int):
+    """Thêm heading style vào document nếu chưa có."""
+    styles_el = doc.styles.element
+    for s in styles_el.findall(qn("w:style")):
+        if s.get(qn("w:styleId")) == style_id:
+            return
+
+    xml = f"""<w:style xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+        w:type="paragraph" w:styleId="{style_id}">
+      <w:name w:val="{style_name}"/>
+      <w:basedOn w:val="Normal"/>
+      <w:next w:val="Normal"/>
+      <w:pPr>
+        <w:outlineLvl w:val="{outline_level}"/>
+        <w:spacing w:before="240" w:after="120"/>
+      </w:pPr>
+      <w:rPr>
+        <w:b/>
+        <w:sz w:val="{font_size}"/>
+        <w:szCs w:val="{font_size}"/>
+      </w:rPr>
+    </w:style>"""
+    styles_el.append(etree.fromstring(xml))
+
+
+def _set_outline_level(para, level: int):
+    """Gán outlineLvl cho paragraph, tuân thủ XML Schema của Word."""
+    pPr = para._p.get_or_add_pPr()
+    for existing in pPr.findall(qn("w:outlineLvl")):
+        pPr.remove(existing)
+    el = OxmlElement("w:outlineLvl")
+    el.set(qn("w:val"), str(level))
+
+    # w:outlineLvl PHẢI nằm trước w:rPr để tránh nhao chữ
+    rPr = pPr.find(qn('w:rPr'))
+    if rPr is not None:
+        rPr.addprevious(el)
+    else:
+        sectPr = pPr.find(qn('w:sectPr'))
+        if sectPr is not None:
+            sectPr.addprevious(el)
+        else:
+            pPr.append(el)
+
+
+def _get_style(doc, primary: str, fallback: str):
+    """Lấy style từ document, thử primary trước rồi fallback."""
+    try:
+        return doc.styles[primary]
+    except KeyError:
+        try:
+            return doc.styles[fallback]
+        except KeyError:
+            return None
+
+
+# ───────────────────────────────────────────────
+# Core detection logic
+# ───────────────────────────────────────────────
+
+def _detect_heading_level(text: str, is_bold: bool) -> int:
+    """
+    Detect heading level dựa trên nội dung text và bold.
+    Returns: 0 = không phải heading, 1 = H1, 2 = H2, 3 = H3
+    """
+    if not text or len(text) >= 120:
+        return 0
+
+    # ── Ưu tiên 1: Regex cấu trúc pháp lý ──
+    # H3 check trước H2 vì H3 pattern (1.1.1.) cũng match H2 (1.1.)
+    if H3_PATTERNS.match(text):
+        return 3
+
+    if H1_PATTERNS.match(text):
+        return 1
+
+    if H2_PATTERNS.match(text):
+        return 2
+
+    # ── Ưu tiên 2: ALL CAPS = H1 (KHÔNG cần bold) ──
+    # Google Drive OCR thường xoá bold nhưng giữ nguyên chữ hoa
+    if _is_all_caps(text) and len(text) < 100:
+        return 1
+
+    # ── Ưu tiên 3: Bold + ngắn = H2 (fallback) ──
+    word_count = len(text.split())
+    if is_bold and word_count <= 15:
+        return 2
+
+    return 0
+
+
+# ───────────────────────────────────────────────
+# API: format từ bytes (dùng trong pipeline)
+# ───────────────────────────────────────────────
+
+def fix_headings_in_memory(docx_bytes: bytes) -> bytes:
+    """
+    Nhận DOCX bytes (từ Google Drive OCR export),
+    phục hồi heading styles, trả về DOCX bytes đã fix.
+    """
+    doc = Document(BytesIO(docx_bytes))
+    count = _apply_heading_fixes(doc)
+
+    if count == 0:
+        return docx_bytes
+
+    buf = BytesIO()
+    doc.save(buf)
+    buf.seek(0)
+    return buf.read()
+
+
+# ───────────────────────────────────────────────
+# API: format từ file path
+# ───────────────────────────────────────────────
+
+def format_contract(src_path: Path, dst_path: Path) -> int:
+    """Format 1 file DOCX trên disk. Trả về số heading đã fix."""
+    shutil.copy2(src_path, dst_path)
+    doc = Document(str(dst_path))
+    count = _apply_heading_fixes(doc)
+    doc.save(str(dst_path))
+    return count
+
+
+# ───────────────────────────────────────────────
+# Internal: áp dụng fix
+# ───────────────────────────────────────────────
+
+def _apply_heading_fixes(doc) -> int:
+    """Quét paragraphs và gán heading style. Trả về số heading đã fix."""
+    _ensure_heading_style(doc, "Heading1", "heading 1", 0, 28)
+    _ensure_heading_style(doc, "Heading2", "heading 2", 1, 24)
+    _ensure_heading_style(doc, "Heading3", "heading 3", 2, 22)
+
+    h1_style = _get_style(doc, "Heading 1", "Heading1")
+    h2_style = _get_style(doc, "Heading 2", "Heading2")
+    h3_style = _get_style(doc, "Heading 3", "Heading3")
+
+    if not h1_style or not h2_style:
+        return 0
+
+    style_map = {
+        1: (h1_style, 0),
+        2: (h2_style, 1),
+        3: (h3_style or h2_style, 2),
+    }
+
+    count = 0
+    for para in doc.paragraphs:
+        text = para.text.strip()
+        if not text:
+            continue
+
+        is_bold = _para_is_bold(para)
+        level = _detect_heading_level(text, is_bold)
+
+        if level == 0:
+            continue
+
+        # Luôn override heading style + outlineLvl dựa trên nội dung text
+        # (Google Drive hay gán sai level, ví dụ tất cả thành Heading 2)
+        heading_style, outline_val = style_map[level]
+        para.style = heading_style
+        _set_outline_level(para, outline_val)
+        for run in para.runs:
+            run.bold = True
+        count += 1
+
+    return count

out.txt

 1 | CỘNG HOÀ XÃ HỘI CHỦ NGHĨA VIỆT NAM

requirements.txt

@@ -6,3 +6,5 @@ pymupdf4llm==0.0.17
 google-api-python-client
 google-auth-httplib2
 google-auth-oauthlib
+python-docx
+lxml

static/index.html

+<!DOCTYPE html>
+<html lang="vi">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Document Converter — Upload & Preview</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
+  <style>
+    *,*::before,*::after{box-sizing:border-box;margin:0;padding:0}
+    :root{
+      --bg:#0f1117;--surface:#181b24;--surface2:#1f2330;
+      --border:#2a2e3b;--border-hover:#3d4258;
+      --accent:#6c63ff;--accent-glow:rgba(108,99,255,.25);
+      --text:#e4e6ef;--text-dim:#8b8fa3;
+      --success:#2dd4bf;--error:#f87171;
+      --radius:14px;
+    }
+    html{font-family:'Inter',system-ui,sans-serif;background:var(--bg);color:var(--text);height:100%}
+    body{display:flex;flex-direction:column;min-height:100vh}
+
+    /* ─── Header ─── */
+    .header{
+      padding:18px 32px;display:flex;align-items:center;gap:12px;
+      border-bottom:1px solid var(--border);background:var(--surface);
+    }
+    .header svg{width:28px;height:28px;color:var(--accent)}
+    .header h1{font-size:1.1rem;font-weight:600;letter-spacing:-.3px}
+    .header span{font-size:.75rem;color:var(--text-dim);margin-left:auto;background:var(--surface2);padding:4px 10px;border-radius:20px}
+
+    /* ─── Main layout ─── */
+    .main{display:flex;flex:1;overflow:hidden}
+
+    /* ─── Left panel ─── */
+    .panel-left{
+      width:360px;min-width:320px;padding:28px;
+      display:flex;flex-direction:column;gap:20px;
+      border-right:1px solid var(--border);background:var(--surface);
+      overflow-y:auto;
+    }
+
+    /* Upload zone */
+    .upload-zone{
+      border:2px dashed var(--border);border-radius:var(--radius);
+      padding:48px 24px;text-align:center;cursor:pointer;
+      transition:all .3s ease;position:relative;
+      display:flex;flex-direction:column;align-items:center;gap:16px;
+    }
+    .upload-zone:hover,.upload-zone.dragover{
+      border-color:var(--accent);background:var(--accent-glow);
+      transform:translateY(-2px);
+    }
+    .upload-zone svg{width:52px;height:52px;color:var(--accent);opacity:.85;transition:transform .3s}
+    .upload-zone:hover svg{transform:scale(1.1)}
+    .upload-zone p{font-size:.95rem;color:var(--text-dim);line-height:1.5}
+    .upload-zone p strong{color:var(--accent);font-weight:600}
+    .upload-zone input{position:absolute;inset:0;opacity:0;cursor:pointer}
+    .upload-zone .formats{font-size:.72rem;color:var(--text-dim);opacity:.7;margin-top:4px}
+
+    /* File info */
+    .file-info{
+      background:var(--surface2);border-radius:var(--radius);
+      padding:16px 18px;display:none;align-items:center;gap:14px;
+      border:1px solid var(--border);animation:slideUp .3s ease;
+    }
+    .file-info.active{display:flex}
+    .file-info .fi-icon{
+      width:42px;height:42px;border-radius:10px;
+      background:linear-gradient(135deg,var(--accent),#8b5cf6);
+      display:flex;align-items:center;justify-content:center;
+      flex-shrink:0;
+    }
+    .file-info .fi-icon svg{width:20px;height:20px;color:#fff}
+    .file-info .fi-details{flex:1;min-width:0}
+    .file-info .fi-name{font-size:.85rem;font-weight:600;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+    .file-info .fi-size{font-size:.72rem;color:var(--text-dim);margin-top:2px}
+    .file-info .fi-remove{
+      width:28px;height:28px;border-radius:8px;border:none;
+      background:transparent;color:var(--text-dim);cursor:pointer;
+      display:flex;align-items:center;justify-content:center;
+      transition:all .2s;
+    }
+    .file-info .fi-remove:hover{background:rgba(248,113,113,.15);color:var(--error)}
+
+    /* Convert button */
+    .btn-convert{
+      width:100%;padding:14px;border:none;border-radius:var(--radius);
+      font-family:inherit;font-size:.9rem;font-weight:600;
+      background:linear-gradient(135deg,var(--accent),#8b5cf6);
+      color:#fff;cursor:pointer;transition:all .3s;
+      display:flex;align-items:center;justify-content:center;gap:8px;
+    }
+    .btn-convert:hover{transform:translateY(-1px);box-shadow:0 8px 24px var(--accent-glow)}
+    .btn-convert:disabled{opacity:.4;cursor:not-allowed;transform:none;box-shadow:none}
+    .btn-convert .spinner{display:none;width:18px;height:18px;border:2px solid rgba(255,255,255,.3);border-top-color:#fff;border-radius:50%;animation:spin .6s linear infinite}
+    .btn-convert.loading .spinner{display:block}
+    .btn-convert.loading .btn-text{display:none}
+
+    /* Status */
+    .status-msg{
+      font-size:.8rem;padding:10px 14px;border-radius:10px;
+      display:none;line-height:1.4;
+    }
+    .status-msg.error{display:block;background:rgba(248,113,113,.1);color:var(--error);border:1px solid rgba(248,113,113,.2)}
+    .status-msg.success{display:block;background:rgba(45,212,191,.1);color:var(--success);border:1px solid rgba(45,212,191,.2)}
+
+    /* Stats */
+    .stats{display:flex;gap:10px;flex-wrap:wrap}
+    .stat-chip{
+      font-size:.72rem;padding:5px 11px;border-radius:20px;
+      background:var(--surface2);border:1px solid var(--border);color:var(--text-dim);
+    }
+    .stat-chip b{color:var(--text);margin-right:3px}
+
+    /* ─── Right panel ─── */
+    .panel-right{
+      flex:1;display:flex;flex-direction:column;background:var(--bg);
+      overflow:hidden;
+    }
+    .preview-toolbar{
+      padding:12px 24px;display:flex;align-items:center;gap:12px;
+      border-bottom:1px solid var(--border);background:var(--surface);
+    }
+    .preview-toolbar .tab{
+      padding:6px 14px;border-radius:8px;border:none;
+      font-family:inherit;font-size:.78rem;font-weight:500;
+      background:transparent;color:var(--text-dim);cursor:pointer;
+      transition:all .2s;
+    }
+    .preview-toolbar .tab.active{background:var(--accent);color:#fff}
+    .preview-toolbar .tab:hover:not(.active){background:var(--surface2)}
+
+    .preview-content{
+      flex:1;overflow-y:auto;padding:32px;
+    }
+
+    /* Empty state */
+    .empty-state{
+      display:flex;flex-direction:column;align-items:center;justify-content:center;
+      height:100%;color:var(--text-dim);gap:16px;text-align:center;
+    }
+    .empty-state svg{width:72px;height:72px;opacity:.25}
+    .empty-state p{font-size:.9rem;max-width:320px;line-height:1.6}
+
+    /* Rendered markdown */
+    .md-render{display:none;line-height:1.75;font-size:.92rem}
+    .md-render h1{font-size:1.5rem;font-weight:700;margin:28px 0 14px;color:#fff;border-bottom:1px solid var(--border);padding-bottom:10px}
+    .md-render h2{font-size:1.25rem;font-weight:600;margin:24px 0 10px;color:#e0e0ff}
+    .md-render h3{font-size:1.1rem;font-weight:600;margin:20px 0 8px;color:var(--accent)}
+    .md-render h4,.md-render h5,.md-render h6{font-size:1rem;margin:16px 0 6px;color:var(--text-dim)}
+    .md-render p{margin:8px 0}
+    .md-render table{width:100%;border-collapse:collapse;margin:16px 0;font-size:.85rem}
+    .md-render th{background:var(--surface2);font-weight:600;text-align:left}
+    .md-render th,.md-render td{padding:10px 14px;border:1px solid var(--border)}
+    .md-render tr:nth-child(even){background:var(--surface)}
+    .md-render ul,.md-render ol{padding-left:24px;margin:8px 0}
+    .md-render li{margin:4px 0}
+    .md-render strong{color:#fff}
+    .md-render em{color:var(--text-dim)}
+    .md-render hr{border:none;border-top:1px solid var(--border);margin:20px 0}
+
+    /* Raw markdown */
+    .md-raw{
+      display:none;white-space:pre-wrap;word-break:break-word;
+      font-family:'JetBrains Mono',monospace,Consolas;font-size:.82rem;
+      color:var(--text-dim);background:var(--surface);
+      padding:24px;border-radius:var(--radius);border:1px solid var(--border);
+      line-height:1.7;
+    }
+
+    /* ─── Animations ─── */
+    @keyframes spin{to{transform:rotate(360deg)}}
+    @keyframes slideUp{from{opacity:0;transform:translateY(8px)}to{opacity:1;transform:translateY(0)}}
+
+    /* ─── Responsive ─── */
+    @media(max-width:768px){
+      .main{flex-direction:column}
+      .panel-left{width:100%;min-width:0;border-right:none;border-bottom:1px solid var(--border)}
+    }
+  </style>
+</head>
+<body>
+
+<!-- Header -->
+<header class="header">
+  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><line x1="16" y1="13" x2="8" y2="13"/><line x1="16" y1="17" x2="8" y2="17"/><polyline points="10 9 9 9 8 9"/></svg>
+  <h1>Document Converter</h1>
+  <span>v1.0 — Upload & Preview</span>
+</header>
+
+<div class="main">
+  <!-- ─── Left Panel ─── -->
+  <aside class="panel-left">
+    <div class="upload-zone" id="dropZone">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="17 8 12 3 7 8"/><line x1="12" y1="3" x2="12" y2="15"/></svg>
+      <p>Kéo thả file vào đây<br/>hoặc <strong>Click để chọn</strong></p>
+      <span class="formats">.docx · .pdf · .doc · .pptx · .xlsx · Ảnh</span>
+      <input type="file" id="fileInput" accept=".docx,.doc,.pdf,.pptx,.xlsx,.xls,.png,.jpg,.jpeg,.bmp,.tiff,.webp" />
+    </div>
+
+    <div class="file-info" id="fileInfo">
+      <div class="fi-icon">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"/><polyline points="13 2 13 9 20 9"/></svg>
+      </div>
+      <div class="fi-details">
+        <div class="fi-name" id="fileName">—</div>
+        <div class="fi-size" id="fileSize">—</div>
+      </div>
+      <button class="fi-remove" id="fileRemove" title="Xoá file">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+      </button>
+    </div>
+
+    <button class="btn-convert" id="btnConvert" disabled>
+      <span class="spinner"></span>
+      <span class="btn-text">🚀 Chuyển đổi & Xem</span>
+    </button>
+
+    <div class="status-msg" id="statusMsg"></div>
+
+    <div class="stats" id="stats" style="display:none">
+      <div class="stat-chip"><b id="statChars">0</b> ký tự</div>
+      <div class="stat-chip"><b id="statLines">0</b> dòng</div>
+      <div class="stat-chip"><b id="statHeadings">0</b> headings</div>
+      <div class="stat-chip"><b id="statTables">0</b> bảng</div>
+    </div>
+  </aside>
+
+  <!-- ─── Right Panel ─── -->
+  <section class="panel-right">
+    <div class="preview-toolbar" id="previewToolbar" style="display:none">
+      <button class="tab active" data-view="render">📄 Preview</button>
+      <button class="tab" data-view="raw">{ } Markdown</button>
+    </div>
+
+    <div class="preview-content">
+      <div class="empty-state" id="emptyState">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="18" height="18" rx="2" ry="2"/><line x1="3" y1="9" x2="21" y2="9"/><line x1="9" y1="21" x2="9" y2="9"/></svg>
+        <p>Chọn file bên trái và nhấn <strong>Chuyển đổi</strong> để xem nội dung tài liệu tại đây.</p>
+      </div>
+      <div class="md-render" id="mdRender"></div>
+      <pre class="md-raw" id="mdRaw"></pre>
+    </div>
+  </section>
+</div>
+
+<script>
+// ── Markdown → HTML (lightweight) ──────────────────
+function mdToHtml(md) {
+  let html = md
+    // Headings
+    .replace(/^###### (.+)$/gm, '<h6>$1</h6>')
+    .replace(/^##### (.+)$/gm, '<h5>$1</h5>')
+    .replace(/^#### (.+)$/gm, '<h4>$1</h4>')
+    .replace(/^### (.+)$/gm,  '<h3>$1</h3>')
+    .replace(/^## (.+)$/gm,   '<h2>$1</h2>')
+    .replace(/^# (.+)$/gm,    '<h1>$1</h1>')
+    // Bold + Italic
+    .replace(/\*\*\*(.+?)\*\*\*/g, '<strong><em>$1</em></strong>')
+    .replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
+    .replace(/\*(.+?)\*/g, '<em>$1</em>')
+    // HR
+    .replace(/^-{3,}$/gm, '<hr/>')
+
+  // Tables
+  html = html.replace(/((?:^\|.+\|$\n?)+)/gm, (block) => {
+    const rows = block.trim().split('\n').filter(r => r.trim());
+    if (rows.length < 2) return block;
+    let table = '<table>';
+    rows.forEach((row, i) => {
+      if (i === 1 && /^\|\s*-/.test(row)) return;
+      const cells = row.split('|').slice(1, -1).map(c => c.trim());
+      const tag = i === 0 ? 'th' : 'td';
+      const tr = i === 0 ? 'thead' : (i === 2 ? 'tbody' : '');
+      if (i === 0) table += '<thead>';
+      if (i === 2) table += '<tbody>';
+      table += '<tr>' + cells.map(c => `<${tag}>${c}</${tag}>`).join('') + '</tr>';
+      if (i === 0) table += '</thead>';
+    });
+    table += '</tbody></table>';
+    return table;
+  });
+
+  // Paragraphs: wrap bare lines
+  html = html.split('\n').map(line => {
+    const t = line.trim();
+    if (!t) return '';
+    if (/^<(h[1-6]|table|thead|tbody|tr|th|td|hr|ul|ol|li|div|pre|blockquote)/.test(t)) return t;
+    if (t.startsWith('- ')) return `<li>${t.slice(2)}</li>`;
+    return `<p>${t}</p>`;
+  }).join('\n');
+
+  // Wrap consecutive <li> in <ul>
+  html = html.replace(/((?:<li>.+<\/li>\n?)+)/g, '<ul>$1</ul>');
+
+  return html;
+}
+
+// ── DOM refs ──
+const dropZone   = document.getElementById('dropZone');
+const fileInput   = document.getElementById('fileInput');
+const fileInfo    = document.getElementById('fileInfo');
+const fileName    = document.getElementById('fileName');
+const fileSize    = document.getElementById('fileSize');
+const fileRemove  = document.getElementById('fileRemove');
+const btnConvert  = document.getElementById('btnConvert');
+const statusMsg   = document.getElementById('statusMsg');
+const stats       = document.getElementById('stats');
+const emptyState  = document.getElementById('emptyState');
+const mdRender    = document.getElementById('mdRender');
+const mdRaw       = document.getElementById('mdRaw');
+const toolbar     = document.getElementById('previewToolbar');
+
+let selectedFile = null;
+
+// ── Drag & Drop ──
+dropZone.addEventListener('dragover',  e => { e.preventDefault(); dropZone.classList.add('dragover'); });
+dropZone.addEventListener('dragleave', () => dropZone.classList.remove('dragover'));
+dropZone.addEventListener('drop', e => {
+  e.preventDefault(); dropZone.classList.remove('dragover');
+  if (e.dataTransfer.files.length) { selectFile(e.dataTransfer.files[0]); }
+});
+fileInput.addEventListener('change', () => { if (fileInput.files.length) selectFile(fileInput.files[0]); });
+
+function fmtSize(b) {
+  if (b < 1024) return b + ' B';
+  if (b < 1048576) return (b/1024).toFixed(1) + ' KB';
+  return (b/1048576).toFixed(1) + ' MB';
+}
+
+function selectFile(file) {
+  selectedFile = file;
+  fileName.textContent = file.name;
+  fileSize.textContent = fmtSize(file.size);
+  fileInfo.classList.add('active');
+  btnConvert.disabled = false;
+  statusMsg.className = 'status-msg';
+}
+
+fileRemove.addEventListener('click', () => {
+  selectedFile = null;
+  fileInput.value = '';
+  fileInfo.classList.remove('active');
+  btnConvert.disabled = true;
+});
+
+// ── Convert ──
+btnConvert.addEventListener('click', async () => {
+  if (!selectedFile) return;
+  btnConvert.classList.add('loading');
+  btnConvert.disabled = true;
+  statusMsg.className = 'status-msg';
+  stats.style.display = 'none';
+
+  const fd = new FormData();
+  fd.append('files', selectedFile);
+
+  try {
+    const res = await fetch('/v1/convert/file', { method: 'POST', body: fd });
+    const data = await res.json();
+
+    if (!res.ok) throw new Error(data.error || 'Server error');
+
+    const md = data.document?.md_content || '';
+    if (!md.trim()) {
+      statusMsg.className = 'status-msg error';
+      statusMsg.textContent = '⚠️ File không trích xuất được nội dung nào.';
+      return;
+    }
+
+    // Render
+    mdRender.innerHTML = mdToHtml(md);
+    mdRaw.textContent = md;
+    emptyState.style.display = 'none';
+    mdRender.style.display = 'block';
+    mdRaw.style.display = 'none';
+    toolbar.style.display = 'flex';
+
+    // Stats
+    const lines = md.split('\n');
+    document.getElementById('statChars').textContent = md.length.toLocaleString();
+    document.getElementById('statLines').textContent = lines.length;
+    document.getElementById('statHeadings').textContent = lines.filter(l => /^#{1,6}\s/.test(l)).length;
+    document.getElementById('statTables').textContent = (md.match(/^\|/gm) || []).length > 0 ? Math.max(1, Math.floor((md.match(/^\|---/gm) || []).length)) : 0;
+    stats.style.display = 'flex';
+
+    statusMsg.className = 'status-msg success';
+    statusMsg.textContent = `✅ Chuyển đổi thành công! (${data.meta?.backend || 'local'})`;
+
+  } catch (err) {
+    statusMsg.className = 'status-msg error';
+    statusMsg.textContent = `❌ Lỗi: ${err.message}`;
+  } finally {
+    btnConvert.classList.remove('loading');
+    btnConvert.disabled = false;
+  }
+});
+
+// ── Tab switching ──
+toolbar.addEventListener('click', e => {
+  const tab = e.target.closest('.tab');
+  if (!tab) return;
+  toolbar.querySelectorAll('.tab').forEach(t => t.classList.remove('active'));
+  tab.classList.add('active');
+  const view = tab.dataset.view;
+  mdRender.style.display = view === 'render' ? 'block' : 'none';
+  mdRaw.style.display    = view === 'raw'    ? 'block' : 'none';
+});
+</script>
+
+</body>
+</html>

test_drive_ocr.txt

 Testing test/67_formatted.docx

test_e2e.py

+"""Test E2E: kiểm tra cấu trúc ĐIỀU / 1.1 / 1.2.1 có ra đúng heading không."""
+import sys
+import io
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+
+import httpx
+
+filepath = "test/67_formatted.docx"
+with open(filepath, "rb") as f:
+    resp = httpx.post(
+        "http://localhost:8000/v1/convert/file",
+        files={"files": (filepath, f, "application/vnd.openxmlformats-officedocument.wordprocessingml.document")},
+        timeout=60,
+    )
+
+md = resp.json().get("document", {}).get("md_content", "")
+
+# Chỉ in các dòng có heading (#) hoặc chứa "Điều"/"ĐIỀU"
+for i, line in enumerate(md.split("\n")):
+    if line.startswith("#") or "điều" in line.lower() or "ĐIỀU" in line:
+        print(f"{i+1:3d} | {line}")

test_out.txt

 # **CỘNG HOÀ XÃ HỘI CHỦ NGHĨA VIỆT NAM**

text_to_markdown.py

+"""
+text_to_markdown.py
+-------------------
+Convert plain text (from Google Drive text export) to structured Markdown.
+Google Drive text export giữ đúng numbering (ĐIỀU 1., 1.1., 4.1., 5.2.1.)
+trong khi DOCX export bị nhả loạn số.
+
+Pipeline:
+  1. Detect tab-separated rows → convert thành markdown tables
+  2. Detect heading patterns (ĐIỀU, X.Y., X.Y.Z., ALL CAPS) → gán #/##/###
+  3. Detect bullet lists (a), (b), -, • etc.
+  4. Clean up formatting
+"""
+
+import re
+from typing import List, Tuple
+
+
+# ───────────────────────────────────────────────
+# Heading patterns cho hợp đồng pháp lý VN
+# ───────────────────────────────────────────────
+
+RE_DIEU = re.compile(
+    r"^((?:ĐIỀU|Điều)\s+\d+[\.\:]?\s*.*)$",
+    re.UNICODE,
+)
+
+RE_CHUONG = re.compile(
+    r"^((?:CHƯƠNG|Chương|PHẦN|Phần|MỤC|Mục)\s+[IVXLCDM\d]+[\.\:]?\s*.*)$",
+    re.UNICODE | re.IGNORECASE,
+)
+
+# X.Y.Z. pattern (H3) - check TRƯỚC X.Y. vì X.Y.Z cũng match X.Y
+RE_H3 = re.compile(r"^(\d+\.\d+\.\d+\.?\s)", re.UNICODE)
+
+# X.Y. pattern (H2)
+RE_H2 = re.compile(r"^(\d+\.\d+\.?\s)", re.UNICODE)
+
+
+def _is_all_caps(text: str) -> bool:
+    """True nếu toàn bộ chữ cái đều viết hoa."""
+    letters = [c for c in text if c.isalpha()]
+    return len(letters) > 3 and all(c == c.upper() for c in letters)
+
+
+def _is_table_block(lines: List[str], start: int) -> Tuple[bool, int]:
+    """
+    Detect một block tab-separated (bảng) bắt đầu từ dòng start.
+    Returns (is_table, end_index).
+    Bảng = ít nhất 2 dòng liên tiếp có >= 2 tabs.
+    """
+    count = 0
+    i = start
+    while i < len(lines):
+        if lines[i].count("\t") >= 2:
+            count += 1
+            i += 1
+        else:
+            break
+
+    return count >= 2, i
+
+
+def _tab_block_to_markdown_table(lines: List[str]) -> str:
+    """Convert tab-separated lines thành markdown table."""
+    rows = []
+    max_cols = 0
+
+    for line in lines:
+        cells = [c.strip() for c in line.split("\t")]
+        # Loại bỏ trailing empty cells
+        while cells and not cells[-1]:
+            cells.pop()
+        if cells:
+            rows.append(cells)
+            max_cols = max(max_cols, len(cells))
+
+    if not rows or max_cols < 2:
+        return "\n".join(lines)
+
+    # Normalize row lengths
+    for row in rows:
+        while len(row) < max_cols:
+            row.append("")
+
+    md_lines = []
+    # Header row
+    md_lines.append("| " + " | ".join(rows[0]) + " |")
+    md_lines.append("| " + " | ".join(["---"] * max_cols) + " |")
+    # Data rows
+    for row in rows[1:]:
+        md_lines.append("| " + " | ".join(row) + " |")
+
+    return "\n".join(md_lines)
+
+
+def _detect_heading(line: str) -> Tuple[int, str]:
+    """
+    Detect heading level từ nội dung text.
+    Returns: (level, clean_text) where level=0 means not a heading.
+    """
+    text = line.strip()
+    if not text or len(text) > 200:
+        return 0, text
+
+    # ── Priority 1: "ĐIỀU X." → H1 ──
+    if RE_DIEU.match(text):
+        return 1, text
+
+    # ── Priority 2: "CHƯƠNG/PHẦN/MỤC" → H1 ──
+    if RE_CHUONG.match(text):
+        return 1, text
+
+    # ── Priority 3: ALL CAPS short line → H1 ──
+    # Loại trừ các dòng trong bảng, dòng quá ngắn (<5 chars), bullets
+    if (_is_all_caps(text)
+        and len(text) < 120
+        and not text.startswith("|")
+        and not text.startswith("-")
+        and not text.startswith("•")
+        and "\t" not in text):
+        return 1, text
+
+    # ── Priority 4: "X.Y.Z." → H3 ──
+    if RE_H3.match(text):
+        return 3, text
+
+    # ── Priority 5: "X.Y." → H2 ──
+    if RE_H2.match(text):
+        return 2, text
+
+    return 0, text
+
+
+def _clean_line(line: str) -> str:
+    """Clean up a single line: normalize tabs thành spaces cho non-table lines."""
+    # Giữ nguyên nếu là table (nhiều tabs)
+    if line.count("\t") >= 2:
+        return line
+
+    # Thay tabs đơn thành spaces cho readability
+    return line.replace("\t", " ").strip()
+
+
+def text_to_markdown(text: str) -> str:
+    """
+    Convert plain text (từ Google Drive text export) thành structured Markdown.
+
+    - Detect tab-separated tables → markdown tables
+    - Detect heading patterns → # / ## / ###
+    - Detect bullets → - list items
+    - Clean formatting
+    """
+    if not text or not text.strip():
+        return ""
+
+    lines = text.split("\n")
+    result = []
+    i = 0
+
+    while i < len(lines):
+        line = lines[i]
+
+        # ── Check tab-separated table block ──
+        is_table, table_end = _is_table_block(lines, i)
+        if is_table:
+            table_md = _tab_block_to_markdown_table(lines[i:table_end])
+            result.append("")
+            result.append(table_md)
+            result.append("")
+            i = table_end
+            continue
+
+        # ── Clean the line ──
+        cleaned = _clean_line(line)
+
+        if not cleaned:
+            result.append("")
+            i += 1
+            continue
+
+        # ── Lọc page numbers / headers ──
+        if re.fullmatch(r"\d{1,3}", cleaned):
+            i += 1
+            continue
+        if re.fullmatch(r"Trang\s+\d+(/\d+)?|Page\s+\d+(/\d+)?", cleaned, re.IGNORECASE):
+            i += 1
+            continue
+
+        # ── Detect heading ──
+        level, text_clean = _detect_heading(cleaned)
+        if level > 0:
+            result.append(f"{'#' * level} {text_clean}")
+            i += 1
+            continue
+
+        # ── Detect bullet patterns: (a), (b), -, • ──
+        if re.match(r"^\([a-z]\)\s", cleaned):
+            result.append(cleaned)  # Keep as-is, already looks like a list
+            i += 1
+            continue
+
+        # ── Normal text ──
+        result.append(cleaned)
+        i += 1
+
+    # Clean up excessive blank lines
+    md = "\n".join(result)
+    while "\n\n\n" in md:
+        md = md.replace("\n\n\n", "\n\n")
+
+    return md.strip()