Metadata-Version: 2.4
Name: tableforge
Version: 0.6.1
Summary: 智能表格排版与打印系统 — 从 Excel 到 Typst/PDF/Excel 的一站式工具
License: MIT
Keywords: table,excel,typst,pdf,printing,report
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: polars>=0.20
Requires-Dist: openpyxl>=3.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: jsonschema>=4.20
Requires-Dist: openai>=1.0

# TableForge v0.6.1

智能表格排版与打印系统。从 CSV/Excel 读取数据，通过 YAML 配置自动生成美观的 Typst/PDF 和打印友好 Excel。

## 安装

```bash
pip install tableforge
# 依赖: polars openpyxl pyyaml jsonschema openai
# PDF 需要 Typst CLI: https://github.com/typst/typst
# AI 生成需要: export DEEPSEEK_API_KEY="sk-..."
```

## 快速开始

```bash
# AI 智能生成配置（推荐）
tableforge ai-gen data.csv

# 交互式流程：AI 生成配置 → [Y] 生成 PDF 看效果
# → 查看 PDF → [M] 提修改意见 → AI 修改 → 重新生成 PDF
# → 满意后 [OK] 完成

# 一键生成（跳过确认）
tableforge ai-gen data.csv -y

# 或手动配置
tableforge init -o config/my.yaml
tableforge run config/my.yaml
```

## 功能特性

**数据输入**
- Excel 多级复杂表头自动解析（合并单元格 → 树状结构），JSON 缓存
- 多 sheet 支持 (`sheets: "*"` + `exclude_sheets`)
- 支持 CSV / Excel (.xlsx) / Markdown 表格
- 数据列类型自动识别（PK/数值/文本/日期）

**视图与排版**
- 按主键拆分视图，每视图独立纸张方向、字号、列宽
- 自适应引擎 v2：数据采样 → 列分类 → 决策树（换行→缩字→挤压→拆分）
- 强制挤压 (force-squeeze)：自动收紧 longtext/pk 列宽，优先一页显示
- 超宽自动拆分：仅当挤压后仍超 15% 时才拆分
- 纵向合并：`merge_repeated` 同列连续相同值自动合并（含空行继承）
- 手动列宽：绝对 mm 值或 `Nfr` 权重比例（如 `3fr`），精确填满页面

**格式化**
- 数字：千位符、小数位、货币前后缀 (`prefix`/`suffix`)、单位 (`unit`)
- 百分比：符号、小数位
- 日期：自定义格式
- 条件着色：正值绿 / 负值红（Typst + Excel）
- 空值占位符 (`null_placeholder`)
- 长文本：`type: longtext` 自动换行渲染（Typst 多行 / Excel 自动换行）

**样式**
- 5 套预置主题：`compact` / `academic` / `boardroom` / `mono` / `dashboard`
- 样式继承 (`inherits`) + 覆盖 (`overrides`) 深度合并
- 表格标题：黑体居中 + 单位注释

**输出**
- Typst：多级合并表头 (`colspan`/`rowspan`)、跨页表头重复、条件颜色、主题样式
- PDF：奇偶页交替页码、横向页面
- Excel：合并表头、冻结窗格、斑马纹、主题边框/字体、打印缩放、多 sheet Tab

**AI 智能配置生成 (v0.6.0 → v0.6.1)**
- `tableforge ai-gen <data-file>` 自动分析数据并生成配置
- DeepSeek V4 Pro 驱动，修改轮切 Flash 快速迭代
- **v0.6.1**: 同目录同名 yaml 检测 — 发现已有配置时询问从第二轮开始
- **v0.6.1**: 强制挤压 (force-squeeze) — 优先在一页显示，提高 auto_split 阈值
- **v0.6.1**: 提示词外置 — `config/prompts/system.md` + `user.md`，无需改代码
- **v0.6.1**: 全局 title 修复 — PDF/Excel 现正确使用配置中的 title
- 交互式多轮修改：生成 PDF → 查看效果 → 提意见 → AI 修改 → 循环至满意
- 配置文件双写至 `config/` 和源文件目录
- 纸张默认 A4 横向，长文本列压缩至 ~20 字符/行
- Schema 校验 + 自动重试修正（最多 3 次）

**工程**
- JSON Schema (Draft 2020-12) 配置校验，中文错误提示
- 结构化 `logging`，分级输出 (INFO/DEBUG/WARNING/ERROR)
- Parquet 数据缓存 (L1) + 视图缓存 (L2)，MD5 哈希校验
- SQLite 统计日志 (`tableforge stats` / `stats --run-id N`)
- 多版本管理（时间戳目录 + `latest` 链接 + 滚动清理）
- CLI 子命令：`run` / `preview` / `init` / `ai-gen` / `stats` / `version` / `cache`

## 配置示例

```yaml
source:
  file: "data/sales.xlsx"
  sheets: "*"                   # 所有 sheet
  exclude_sheets: ["封面"]
  header_rows: 2

primary_keys: ["区域", "日期"]

page:
  size: "a3"                    # 默认 A3 横向，优先一页显示
  orientation: landscape
  margin: [1.0, 1.0, 1.0, 1.0]
  numbering:
    enabled: true
    position: alternating

column_formats:
  target:
    type: number
    thousands: true
    decimals: 0
    unit: "万元"
  growth:
    type: percentage
    decimals: 1
    sign: true
    cond_color: true

split_views:
  - name: "业绩"
    data_columns: ["target", "actual", "growth"]
    column_widths:             # fr 权重精确填满页面
      区域: 1fr
      日期: 1fr
      target: 0.8fr
      actual: 0.8fr
      growth: 0.8fr

merge_repeated: ["区域"]
row_number: true
styling:
  theme: "compact"
```

## CLI 命令

```bash
tableforge run       <config>    # 完整流程
tableforge preview   <config>    # 适配预览（--dry-run）
tableforge ai-gen    <data>      # AI 智能生成配置
tableforge init      [-o PATH]   # 生成配置草案
tableforge stats     [--run-id]  # 运行统计
tableforge version   list|clean  # 版本管理
tableforge cache     list|clean  # 缓存管理

选项: --dry-run  -v  --no-cache  --refresh-data  --tag TAG
```

### AI 配置生成

```bash
# 交互生成（默认 V4 Pro，修改轮切 Flash 加速）
tableforge ai-gen data.csv

# 一键生成
tableforge ai-gen data.csv -y

# 自定义提示
tableforge ai-gen data.csv --title "销售报表" --hint "按区域分组，金额用万元"

# 指定模型
tableforge ai-gen data.csv -m deepseek-v4-flash

# 仅预览
tableforge ai-gen data.xlsx --dry-run

# 要求: export DEEPSEEK_API_KEY="sk-..."
# 支持: .csv / .xlsx / .md
```

## 开发

```bash
python -m pytest tests/ -v       # 24 tests
python scripts/generate_test_data.py
```

## 许可证

MIT
