elc-invoice-engine-cli 0.1.0__py3-none-any.whl

cli/auth.py

@@ -0,0 +1,44 @@
+"""SSO 认证：MD5 签名获取 token。"""
+from __future__ import annotations
+
+import hashlib
+import time
+import httpx
+from cli.config import BASE_URL, SSO_CONFIG, REQUEST_TIMEOUT
+
+
+def _sign(app_id: str, secret: str, timestamp: str) -> str:
+    return hashlib.md5(f"{app_id}{secret}{timestamp}".encode()).hexdigest()
+
+
+def fetch_token() -> tuple[str, int]:
+    """调用 /api/sso/kingdee/token，返回 (access_token, expires_in)。"""
+    app_id = SSO_CONFIG["app_id"]
+    secret = SSO_CONFIG["secret"]
+    timestamp = str(int(time.time() * 1000))
+
+    body = {
+        "domain":     SSO_CONFIG["domain"],
+        "appId":      app_id,
+        "timestamp":  timestamp,
+        "sign":       _sign(app_id, secret, timestamp),
+        "mobile":     SSO_CONFIG["mobile"],
+        "userName":   SSO_CONFIG["username"],
+        "workNumber": SSO_CONFIG["work_number"],
+        "orgNum":     SSO_CONFIG["org_num"],
+    }
+    body = {k: v for k, v in body.items() if v}
+
+    url = f"{BASE_URL}/api/sso/kingdee/token"
+    resp = httpx.post(url, json=body, timeout=REQUEST_TIMEOUT)
+    resp.raise_for_status()
+
+    result = resp.json()
+    data = result.get("data") or {}
+    token = data.get("accessToken")
+    expires_in = int(data.get("expiresIn", 7200))
+
+    if not token:
+        raise RuntimeError(f"SSO 登录失败：{result}")
+
+    return token, expires_in

cli/client.py

@@ -0,0 +1,53 @@
+"""HTTP 客户端：封装 httpx，统一注入认证头和 requestId。"""
+from __future__ import annotations
+
+import uuid
+import httpx
+from cli.config import BASE_URL, DEFAULT_HEADERS, REQUEST_TIMEOUT
+
+
+class ApiClient:
+    def __init__(self, token: str = ""):
+        self.base_url = BASE_URL
+        self.headers = dict(DEFAULT_HEADERS)
+        if token:
+            self.headers["Authorization"] = f"Bearer {token}"
+        self._client = httpx.Client(timeout=REQUEST_TIMEOUT)
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}/{path.lstrip('/')}"
+
+    def _req_headers(self) -> dict:
+        return {**self.headers, "X-Request-Id": uuid.uuid4().hex}
+
+    def get(self, path: str, params: dict = None) -> tuple[int, dict]:
+        r = self._client.get(self._url(path), headers=self._req_headers(), params=params or {})
+        return r.status_code, self._body(r)
+
+    def post(self, path: str, json: dict | list = None, params: dict = None) -> tuple[int, dict]:
+        r = self._client.post(self._url(path), headers=self._req_headers(), json=json, params=params or {})
+        return r.status_code, self._body(r)
+
+    def put(self, path: str, json: dict | list = None) -> tuple[int, dict]:
+        r = self._client.put(self._url(path), headers=self._req_headers(), json=json)
+        return r.status_code, self._body(r)
+
+    def delete(self, path: str, params: dict = None) -> tuple[int, dict]:
+        r = self._client.delete(self._url(path), headers=self._req_headers(), params=params or {})
+        return r.status_code, self._body(r)
+
+    @staticmethod
+    def _body(r: httpx.Response) -> dict:
+        try:
+            return r.json()
+        except Exception:
+            return {"raw": r.text}
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()

cli/commands/describe.py

@@ -0,0 +1,138 @@
+"""describe 命令：输出当前 CLI 环境上下文，供 AI 使用。"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from cli.config import BASE_URL, SSO_CONFIG, DEFAULT_HEADERS
+from cli.token_store import load_token
+from cli.export.mapping_store import MAPPINGS_DIR
+
+app = typer.Typer(help="输出 CLI 环境上下文（供 AI 使用）")
+console = Console()
+
+
+@app.callback(invoke_without_command=True)
+def describe(
+    ctx: typer.Context,
+    output: str = typer.Option("json", "-o", help="输出格式：json / text"),
+):
+    """输出当前 CLI 环境、命令说明、接口行为和已知问题，供 AI 建立上下文。
+
+    在开始任何 ELC CLI 操作前，先运行此命令让 AI 了解当前环境。
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+
+    token = load_token()
+    logged_in = token is not None
+
+    # 已缓存的映射表
+    mappings = []
+    if MAPPINGS_DIR.exists():
+        for f in MAPPINGS_DIR.glob("*.json"):
+            try:
+                m = json.loads(f.read_text())
+                mappings.append({
+                    "template": m.get("template_path", ""),
+                    "created_at": m.get("created_at", ""),
+                    "header_fields": len(m.get("header_mapping", {})),
+                    "line_fields": len(m.get("line_mapping", {})),
+                })
+            except Exception:
+                pass
+
+    ctx_data = {
+        "env": {
+            "base_url":   BASE_URL,
+            "company_id": DEFAULT_HEADERS.get("X-Company-ID", ""),
+            "domain":     SSO_CONFIG.get("domain", ""),
+            "logged_in":  logged_in,
+            "token_file": str(Path.home() / ".elc" / "token.json"),
+        },
+        "cached_mappings": mappings,
+        "commands": {
+            "elc login":                     "交互式登录，token 保存到 ~/.elc/token.json",
+            "elc login status":              "查看登录状态",
+            "elc login logout":              "退出登录",
+            "elc invoice-request list":      "查询开票申请单列表，支持 --status / --source-system / --month 过滤",
+            "elc invoice-request get <id>":  "查询单条申请单详情（注意：/v2 单条接口有时返回 500，用 list 替代）",
+            "elc invoice-request create -f <xml>": "创建申请单，上传 KDUBL XML，自动生成幂等键",
+            "elc invoice-request update <id> -f <xml>": "更新申请单（状态需为 draft/validate_failed/pending）",
+            "elc invoice-request void <id>": "作废申请单",
+            "elc invoice-request issue <id>":"触发开票（状态需为 PENDING_INVOICE）",
+            "elc invoice-request invoices <id>": "查询申请单下的发票列表",
+            "elc invoice-request match-cn-create -f <xml>": "创建 Credit Note 蓝冲匹配任务",
+            "elc invoice-request match-cn-run <id>": "触发蓝冲匹配",
+            "elc invoice-request match-cn-results <id>": "查询匹配结果",
+            "elc invoice-request match-cn-unlink <id>": "解除匹配绑定",
+            "elc invoice get <id>":          "查询发票详情",
+            "elc invoice file-link <id>":    "获取发票文件下载链接（--type Humanreadable/Target/Source）",
+            "elc invoice download <id>":     "直接下载发票文件到本地（--type Source 下载 KDUBL XML）",
+            "elc invoice cancel <id>":       "取消发票（仅 MY，72小时内）",
+            "elc party list":                "查询注册主体列表",
+            "elc party upsert -f <json>":    "创建或更新注册主体",
+            "elc product list":              "查询商品列表",
+            "elc product upsert -f <json>":  "创建或更新商品",
+            "elc tax list":                  "查询税目列表",
+            "elc exchange list":             "查询汇率列表",
+            "elc exchange create":           "新增汇率",
+            "elc export init -t <tmpl>":     "采集模版列名和样本数据，供 AI 推断字段映射",
+            "elc export save-mapping -t <tmpl> -f <json>": "保存 AI 推断的字段映射到本地缓存",
+            "elc export invoice -t <tmpl>":  "导出发票数据到 Excel（需先 init + save-mapping）",
+            "elc describe":                  "输出本上下文（当前命令）",
+        },
+        "api_behaviors": {
+            "pagination": {
+                "type":        "cursor",
+                "param":       "cursor（整数，初始不传，后续传 nextCursor 的值）",
+                "page_size":   "pageSize（服务端固定每页20条，设置其他值无效）",
+                "has_more":    "hasMore: true 时继续翻页，false 时停止",
+                "example":     "第一页不传 cursor，返回 nextCursor=20，第二页传 cursor=20",
+            },
+            "time_filter": {
+                "params":  "updatedFrom / updatedTo（格式 YYYY-MM-DD）",
+                "note":    "按申请单 updatedTime 过滤，不是 createdTime",
+            },
+            "invoice_status": {
+                "INVOICED_SUCCESS": "开票成功，有关联 invoices[]",
+                "VALIDATION_FAILED": "校验失败，查看 failureDetails",
+                "PENDING_INVOICE":  "待开票，可调用 issue 触发",
+                "DRAFT":            "草稿，可更新",
+            },
+            "source_xml": {
+                "available":   "仅通过 /v2/invoice-requests（上传 KDUBL XML）创建的发票才有 Source 文件",
+                "endpoint":    "GET /v1/invoices/file/{invoiceId}?filetype=Source&fileFormat=xml",
+                "error_403004":"No file found — 该发票不是通过 XML 上传创建的，无 Source 文件",
+            },
+        },
+        "known_issues": {
+            "header_case":    "X-Company-ID（大写 ID），不是 X-Company-Id",
+            "get_single_ir":  "GET /v2/invoice-requests/{id} 有时返回 500，改用 list + sourceId 过滤",
+            "issue_500":      "issue 命令返回 500 时，检查申请单状态是否为 PENDING_INVOICE",
+            "xml_missing":    "SIT 环境大部分测试数据无 Source XML（通过 JSON 方式创建），正式数据通过 XML 上传则有",
+            "max_batches":    "export invoice 默认 --max-batches 500（每批20条），数据量大时适当调小",
+            "token_expiry":   "token 有效期约 7.5 小时，过期后自动重新登录",
+        },
+        "export_workflow": {
+            "step1": "elc export init -t <template> -o /tmp/sample.json",
+            "step2": "读取 /tmp/sample.json，AI 推断字段映射，生成 mapping JSON",
+            "step3": "elc export save-mapping -t <template> -f /tmp/mapping.json",
+            "step4": "elc export invoice -t <template> --month YYYY-MM --company BU-XXXXX --out <dir>",
+            "note":  "同一模版只需初始化一次，模版文件内容变更后需重新 init",
+        },
+    }
+
+    if output == "json":
+        console.print_json(json.dumps(ctx_data, ensure_ascii=False, indent=2))
+    else:
+        console.print(f"[bold cyan]ELC CLI 环境上下文[/bold cyan]")
+        console.print(f"BASE_URL:    {ctx_data['env']['base_url']}")
+        console.print(f"Company:     {ctx_data['env']['company_id']}")
+        console.print(f"Logged in:   {'✓' if logged_in else '✗ 请先运行 elc login'}")
+        console.print(f"\n[bold]已缓存映射表：[/bold] {len(mappings)} 个")
+        console.print(f"\n运行 elc describe -o json 获取完整上下文")

cli/commands/exchange.py

@@ -0,0 +1,82 @@
+"""exchange-rates 命令组。"""
+from __future__ import annotations
+
+import typer
+from typing import Optional
+from cli.session import get_client
+from cli.output import print_result
+
+app = typer.Typer(help="汇率管理")
+
+
+@app.command("list")
+def exchange_list(
+    currency_from: Optional[str] = typer.Option(None, "--from", help="源货币代码"),
+    currency_to: Optional[str] = typer.Option(None, "--to", help="目标货币代码"),
+    page: int = typer.Option(1, help="页码"),
+    page_size: int = typer.Option(20, "--page-size", help="每页条数"),
+    output: str = typer.Option("table", "-o", help="输出格式：table / json"),
+):
+    """查询汇率列表。"""
+    params = {"pageNum": page, "pageSize": page_size}
+    if currency_from:
+        params["currencyFrom"] = currency_from
+    if currency_to:
+        params["currencyTo"] = currency_to
+    status, body = get_client().get("/api/exchange-rates/list", params=params)
+    print_result(status, body, output, rows_key="rows",
+                 columns=["id", "currencyFrom", "currencyTo", "exchangeRate", "rateDate", "status"])
+
+
+@app.command("latest")
+def exchange_latest(
+    currency_from: str = typer.Argument(..., help="源货币代码，如 USD"),
+    currency_to: str = typer.Argument(..., help="目标货币代码，如 CNY"),
+    output: str = typer.Option("table", "-o", help="输出格式：table / json"),
+):
+    """查询最新汇率。"""
+    status, body = get_client().get(
+        "/api/exchange-rates/latest",
+        params={"currencyFrom": currency_from, "currencyTo": currency_to},
+    )
+    print_result(status, body, output)
+
+
+@app.command("create")
+def exchange_create(
+    currency_from: str = typer.Option(..., "--from", help="源货币代码"),
+    currency_to: str = typer.Option(..., "--to", help="目标货币代码"),
+    rate: float = typer.Option(..., "--rate", help="汇率"),
+    rate_date: str = typer.Option(..., "--date", help="生效日期，格式 YYYY-MM-DD"),
+    output: str = typer.Option("json", "-o", help="输出格式：table / json"),
+):
+    """新增汇率记录。"""
+    payload = {
+        "currencyFrom": currency_from,
+        "currencyTo": currency_to,
+        "exchangeRate": rate,
+        "rateDate": rate_date,
+        "baseAmount": 1,
+        "rateSource": "MANUAL",
+        "status": 1,
+    }
+    status, body = get_client().post("/api/exchange-rates", json=payload)
+    print_result(status, body, output)
+
+
+@app.command("delete")
+def exchange_delete(
+    id: int = typer.Argument(..., help="汇率记录 ID"),
+):
+    """删除汇率记录。"""
+    status, body = get_client().delete(f"/api/exchange-rates/{id}")
+    print_result(status, body, "json")
+
+
+@app.command("currencies")
+def exchange_currencies(
+    output: str = typer.Option("table", "-o", help="输出格式：table / json"),
+):
+    """查询支持的货币代码列表。"""
+    status, body = get_client().get("/api/exchange-rates/currencies")
+    print_result(status, body, output)

cli/commands/export.py

@@ -0,0 +1,329 @@
+"""export 命令组：elc export init / elc export save-mapping / elc export invoice。"""
+from __future__ import annotations
+
+import calendar
+import json
+import os
+from datetime import date, datetime
+from pathlib import Path
+from typing import Optional
+
+import httpx
+import typer
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn, TaskProgressColumn
+from rich.table import Table
+
+from cli.config import BASE_URL, REQUEST_TIMEOUT
+from cli.export.excel_writer import apply_mapping, write_excel
+from cli.export.mapping_store import load_mapping, mapping_exists, save_mapping
+from cli.export.xml_parser import extract_fields, flatten_xml_fields
+from cli.session import get_client
+
+app = typer.Typer(help="发票数据导出")
+console = Console()
+
+
+# ── 工具函数 ──────────────────────────────────────────────────────────────────
+
+def _read_template_cols(template_path: str) -> tuple[list[tuple], list[tuple]]:
+    """读取模版两个 Sheet 的列名，返回 [(英文, 中文), ...]。"""
+    from openpyxl import load_workbook
+    wb = load_workbook(template_path, read_only=True)
+
+    def _pairs(ws) -> list[tuple[str, str]]:
+        row1 = [c.value or "" for c in list(ws.iter_rows(min_row=1, max_row=1))[0]]
+        row2 = [c.value or "" for c in list(ws.iter_rows(min_row=2, max_row=2))[0]]
+        return [(str(a), str(b)) for a, b in zip(row1, row2) if a]
+
+    return _pairs(wb["表头信息"]), _pairs(wb["商品详情"])
+
+
+def _month_range(month_str: str) -> tuple[str, str]:
+    """'2026-06' → ('2026-06-01', '2026-06-30')"""
+    d = datetime.strptime(month_str, "%Y-%m")
+    last_day = calendar.monthrange(d.year, d.month)[1]
+    return f"{d.year:04d}-{d.month:02d}-01", f"{d.year:04d}-{d.month:02d}-{last_day:02d}"
+
+
+def _fetch_source_xml(invoice_id: str, token: str, company_id: str) -> bytes | None:
+    """下载 KDUBL Source XML，返回原始字节。"""
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "X-Company-Id":  company_id,
+    }
+    url = f"{BASE_URL}/v1/invoices/file/{invoice_id}"
+    params = {"filetype": "Source", "fileFormat": "xml"}
+    try:
+        resp = httpx.get(url, headers=headers, params=params, timeout=REQUEST_TIMEOUT)
+        if resp.status_code == 200:
+            ct = resp.headers.get("content-type", "")
+            if "xml" in ct or resp.content.strip().startswith(b"<"):
+                return resp.content
+    except Exception:
+        pass
+    return None
+
+
+def _collect_invoices(month_str: str, max_batches: int = 500) -> list[dict]:
+    """分页拉取本月 INVOICED_SUCCESS 的 invoice 对象列表。"""
+    client = get_client()
+    updated_from, updated_to = _month_range(month_str)
+
+    all_invoices: list[dict] = []
+    seen_invoice_ids: set = set()
+    cursor = None
+    batch = 0
+
+    while batch < max_batches:
+        params: dict = {
+            "pageSize":    20,
+            "updatedFrom": updated_from,
+            "updatedTo":   updated_to,
+        }
+        if cursor is not None:
+            params["cursor"] = cursor
+
+        status, body = client.get("/v2/invoice-requests", params=params)
+        if status != 200 or body.get("code") not in (None, "0000"):
+            console.print(f"[red]查询失败：{body}[/red]")
+            break
+
+        data = body.get("data") or {}
+        requests = data.get("invoiceRequests", [])
+        batch += 1
+
+        for ir in requests:
+            if ir.get("invoiceRequestStatus") != "INVOICED_SUCCESS":
+                continue
+            for inv in ir.get("invoices", []):
+                if inv.get("issueStatus") == "SUCCESS":
+                    inv_id = inv["invoiceId"]
+                    if inv_id not in seen_invoice_ids:
+                        seen_invoice_ids.add(inv_id)
+                        all_invoices.append({
+                            "invoiceId":        inv_id,
+                            "sourceSystem":     ir.get("sourceSystem", ""),
+                            "invoiceRequestId": ir.get("invoiceRequestId", ""),
+                        })
+
+        if not data.get("hasMore"):
+            break
+
+        next_cursor = data.get("nextCursor")
+        if next_cursor is None or next_cursor == cursor:
+            break
+        cursor = next_cursor
+
+    console.print(f"  共查询 {batch} 批，找到 {len(all_invoices)} 张不重复发票")
+
+    return all_invoices
+
+
+# ── 命令：init（采集样本数据，输出给 Claude 推断）────────────────────────────
+
+@app.command("init")
+def export_init(
+    template: str = typer.Option(..., "--template", "-t", help="Excel 模版路径"),
+    company: Optional[str] = typer.Option(None, "--company", "-c", help="公司 ID"),
+    output: Optional[str] = typer.Option(None, "--output", "-o",
+                                          help="将样本数据输出到文件（默认打印到终端）"),
+):
+    """采集模版列名和真实发票样本，输出给 Claude 推断字段映射。
+
+    使用步骤：
+      1. 运行此命令，将输出复制给 Claude
+      2. Claude 推断映射后生成 JSON
+      3. 运行 elc export save-mapping 保存映射
+    """
+    template = str(Path(template).expanduser().resolve())
+    if not Path(template).exists():
+        console.print(f"[red]模版文件不存在：{template}[/red]")
+        raise typer.Exit(1)
+
+    company = company or os.environ.get("X_COMPANY_ID", "")
+
+    console.print("[cyan]正在读取模版列名...[/cyan]")
+    header_cols, line_cols = _read_template_cols(template)
+
+    # 拉一条真实发票样本
+    console.print("[cyan]正在获取样本数据...[/cyan]")
+    client = get_client()
+    status, body = client.get("/v2/invoice-requests", params={"pageSize": 20})
+    requests = (body.get("data") or {}).get("invoiceRequests", [])
+    sample_ir = next(
+        (r for r in requests
+         if r.get("invoiceRequestStatus") == "INVOICED_SUCCESS" and r.get("invoices")),
+        None,
+    )
+    if not sample_ir:
+        console.print("[red]未找到已开票成功的申请单，无法采集样本。[/red]")
+        raise typer.Exit(1)
+
+    inv_id = sample_ir["invoices"][0]["invoiceId"]
+    _, inv_body = client.get(f"/v2/invoices/{inv_id}")
+    invoice_json = inv_body.get("data") or inv_body
+
+    # 下载 KDUBL XML
+    console.print("[cyan]正在下载 KDUBL XML 样本...[/cyan]")
+    token = client.headers.get("Authorization", "").removeprefix("Bearer ")
+    xml_bytes = _fetch_source_xml(inv_id, token, company)
+    xml_fields_list = flatten_xml_fields(xml_bytes) if xml_bytes else []
+
+    # 构建输出数据
+    result = {
+        "template_path": template,
+        "header_columns": [{"en": en, "zh": zh} for en, zh in header_cols],
+        "line_columns":   [{"en": en, "zh": zh} for en, zh in line_cols],
+        "sample_invoice_json": invoice_json,
+        "sample_xml_fields":   xml_fields_list[:80],  # 限制长度
+    }
+
+    out_str = json.dumps(result, ensure_ascii=False, indent=2)
+
+    if output:
+        Path(output).write_text(out_str)
+        console.print(f"[green]✓ 样本数据已保存到：{output}[/green]")
+        console.print("请将文件内容提供给 Claude，让其推断字段映射。")
+    else:
+        console.print("\n[bold yellow]── 样本数据（请复制给 Claude 推断映射）──[/bold yellow]\n")
+        console.print(out_str)
+        console.print(f"\n[dim]模版路径：{template}[/dim]")
+
+
+# ── 命令：save-mapping（保存 Claude 推断的映射表）──────────────────────────────
+
+@app.command("save-mapping")
+def export_save_mapping(
+    template: str = typer.Option(..., "--template", "-t", help="Excel 模版路径"),
+    mapping_file: Optional[str] = typer.Option(None, "--file", "-f",
+                                                help="包含映射 JSON 的文件路径"),
+    mapping_json: Optional[str] = typer.Option(None, "--json", "-j",
+                                                help="直接传入映射 JSON 字符串"),
+):
+    """保存字段映射表到本地缓存（~/.elc/mappings/）。
+
+    映射 JSON 格式：
+      {
+        "header_mapping": {"*invoiceNo": {"source": "json", "path": "invoiceNo"}, ...},
+        "line_mapping":   {"*itemName":  {"source": "json", "path": "itemName"},  ...}
+      }
+    """
+    template = str(Path(template).expanduser().resolve())
+    if not Path(template).exists():
+        console.print(f"[red]模版文件不存在：{template}[/red]")
+        raise typer.Exit(1)
+
+    if mapping_file:
+        mapping = json.loads(Path(mapping_file).expanduser().read_text())
+    elif mapping_json:
+        mapping = json.loads(mapping_json)
+    else:
+        console.print("[red]需要 --file 或 --json 参数[/red]")
+        raise typer.Exit(1)
+
+    if "header_mapping" not in mapping or "line_mapping" not in mapping:
+        console.print("[red]映射 JSON 格式错误，需包含 header_mapping 和 line_mapping[/red]")
+        raise typer.Exit(1)
+
+    save_mapping(template, mapping)
+
+    # 展示摘要
+    hm = mapping["header_mapping"]
+    lm = mapping["line_mapping"]
+    json_count = sum(1 for r in {**hm, **lm}.values() if r.get("source") == "json")
+    xml_count  = sum(1 for r in {**hm, **lm}.values() if r.get("source") == "xml")
+    none_count = sum(1 for r in {**hm, **lm}.values() if r.get("source") == "none")
+
+    console.print(f"[green]✓ 映射表已保存[/green]（JSON字段：{json_count}，XML字段：{xml_count}，无映射：{none_count}）")
+    console.print(f"  缓存位置：~/.elc/mappings/")
+
+
+# ── 命令：invoice（导出发票到 Excel）─────────────────────────────────────────
+
+@app.command("invoice")
+def export_invoice(
+    template: str = typer.Option(..., "--template", "-t", help="Excel 模版路径"),
+    month: Optional[str] = typer.Option(None, "--month", "-m",
+                                         help="月份，如 2026-06，默认当月"),
+    company: Optional[str] = typer.Option(None, "--company", "-c", help="公司 ID"),
+    out: str = typer.Option(".", "--out", "-o", help="输出目录"),
+    max_batches: int = typer.Option(500, "--max-batches", help="最大查询批次（每批20条），防止数据量过大"),
+):
+    """导出发票数据到 Excel。
+
+    需先运行 elc export init 并通过 elc export save-mapping 保存映射。
+    """
+    template = str(Path(template).expanduser().resolve())
+    if not Path(template).exists():
+        console.print(f"[red]模版文件不存在：{template}[/red]")
+        raise typer.Exit(1)
+
+    if not mapping_exists(template):
+        console.print("[red]映射表未初始化，请先运行：[/red]")
+        console.print(f"  elc export init --template {template}")
+        console.print("  （然后将输出给 Claude，让其生成映射，再运行 elc export save-mapping）")
+        raise typer.Exit(1)
+
+    mapping = load_mapping(template)
+    company = company or os.environ.get("X_COMPANY_ID", "")
+    month   = month or date.today().strftime("%Y-%m")
+
+    console.print(f"[cyan]导出月份：{month}，公司：{company}[/cyan]")
+
+    # ① 收集 invoiceId 列表
+    inv_metas = _collect_invoices(month, max_batches=max_batches)
+    if not inv_metas:
+        console.print("[yellow]未找到符合条件的发票，退出。[/yellow]")
+        raise typer.Exit(0)
+    console.print(f"共找到 [bold]{len(inv_metas)}[/bold] 张发票")
+
+    # ② 判断是否需要下载 XML
+    xml_xpath_map = {
+        col: rule["xpath"]
+        for col, rule in {**mapping.get("header_mapping", {}), **mapping.get("line_mapping", {})}.items()
+        if rule.get("source") == "xml" and rule.get("xpath")
+    }
+    need_xml = bool(xml_xpath_map)
+
+    client = get_client()
+    token = client.headers.get("Authorization", "").removeprefix("Bearer ")
+
+    invoices_out: list[dict] = []
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TaskProgressColumn(),
+        console=console,
+    ) as progress:
+        task = progress.add_task("处理发票...", total=len(inv_metas))
+
+        for meta in inv_metas:
+            inv_id = meta["invoiceId"]
+            progress.update(task, description=f"处理 {inv_id[:16]}...")
+
+            # 拉发票详情 JSON
+            _, inv_body = client.get(f"/v2/invoices/{inv_id}")
+            invoice_json = inv_body.get("data") or inv_body
+            invoice_json["sourceSystem"] = meta.get("sourceSystem", "")
+
+            # 下载 XML（按需）
+            xml_fields: dict = {}
+            if need_xml:
+                xml_bytes = _fetch_source_xml(inv_id, token, company)
+                if xml_bytes:
+                    xml_fields = extract_fields(xml_bytes, xml_xpath_map)
+
+            row = apply_mapping(invoice_json, xml_fields, mapping)
+            invoices_out.append(row)
+            progress.advance(task)
+
+    # ③ 写 Excel
+    ym = month.replace("-", "")
+    out_path = str(Path(out).expanduser() / f"invoice_export_{ym}.xlsx")
+    count = write_excel(invoices_out, template, out_path, mapping)
+
+    console.print(f"\n[green]✓ 导出完成：{out_path}[/green]")
+    console.print(f"  共导出 [bold]{count}[/bold] 张发票")