Metadata-Version: 2.4
Name: structviz
Version: 0.2
Summary: 声明式股权图与组织架构图生成工具 — YAML 驱动，D2/Graphviz/Excalidraw 三引擎
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0
Requires-Dist: graphviz>=0.20
Requires-Dist: click>=8.0
Requires-Dist: jinja2>=3.0

# StructViz

声明式股权图与组织架构图生成工具。YAML 定义结构，一键输出 PNG / PDF / SVG / HTML / Excalidraw 图表。

双引擎：**D2**（直角线 SVG） + **Graphviz DOT**（自动布局） + **Excalidraw**（精确定位）。

## 安装

```bash
# D2 引擎
sudo pacman -S d2              # Arch
# 或从 https://github.com/terrastruct/d2/releases 下载

# DOT 引擎
sudo pacman -S graphviz        # Arch
sudo apt install graphviz      # Debian

# Python 包
pip install structviz
```

## 快速开始

```bash
# D2 引擎（直角线 SVG）
structviz examples/org_siku.yaml -t org -f d2 -o output/

# DOT 引擎
structviz examples/org_bingong.yaml -t org -f png,pdf -p a4 -o output/

# Excalidraw 引擎
structviz examples/org_bingong.yaml -t org -f excalidraw -o output/

# 股权图
structviz examples/equity_sample.yaml -t equity -f png -o output/
```

## CLI

```
structviz YAML_FILE [OPTIONS]

Options:
  -t, --type [equity|org]   图表类型 (必填)
  -f, --formats TEXT        输出格式: png,pdf,svg,html,excalidraw,d2
  -o, --output TEXT         输出目录
  -p, --papersize TEXT      纸张: a4|a3|letter 或自定义 "W,H[mm|in]"
  -d, --dpi INTEGER         输出 DPI
```

## YAML 结构

### 组织架构图 (org)

```yaml
meta:
  type: org
  title: "组织架构"
  theme: corporate
  papersize: a4
  dpi: 150
  layout:                    # 全局布局参数
    max_columns: 3           # 底族每行最多数
    nodesep: 0.3             # 同行节点间距 (英寸)
    ranksep: 0.6             # 行间距 (英寸)
    block_pad: 0.15          # block 内边距
    row_gap: 1               # 换行间距 (minlen)
    # D2 专用
    deputy_gap: 40           # 中心领导框内间距
    wrap_width: 12           # 部门名自动换行宽度（0=不换）
    dept_gap: 6              # 板块内部门间距
    dept_width: 150          # 部门节点宽度

groups:
  - level: 0
    label: "权力机构"
    gap: 0.8                 # 到下层间距
    nodes:
      - id: 股东大会
        title: "股东大会"
        style: large         # large | default | external

  - level: 1
    label: "决策层"
    blocks:
      - id: 专业委员会
        position: right      # right=同行右侧 | bottom=下一行 | left=同行左侧
        max_columns: 3       # 块内每行节点数
        block_align: left    # left | center
        edge_from: 董事会    # 箭头到块边框
        nodes:
          - id: 战略委员会
            title: "战略委员会"

  - level: 2
    gap: 1.5
    nodesep: 3               # 本层节点间距 (覆盖全局)
    nodes:
      - id: 业务运营
        title: "业务运营"
        style: large
        reports_to: 总经理   # 自动连线

  - level: 3
    blocks:
      - id: 业务运营板块
        position: bottom
        max_columns: 2
        edge_from: 业务运营
        nodes:
          - id: 债贷业务部
            title: "债贷业务部"
```

### OrgNode 字段

| 字段 | 说明 |
|------|------|
| `id` | 唯一标识 |
| `title` | 显示标题，`\n` 换行 |
| `name` | 副标题 (可选) |
| `role` | 小字职务 (可选) |
| `style` | `large`(居中加粗) / `default` / `external`(橙色) |
| `reports_to` | 上级节点 id |
| `is_cluster_head` | 板块标题 (仅 block 内) |

### OrgGroup 布局参数

| 字段 | 说明 |
|------|------|
| `gap` | 到下层垂直间距 |
| `offset` | 水平偏移 (英寸) |
| `nodesep` | 本层节点间距 (覆盖全局) |
| `max_columns` | blocks 每行数 (覆盖全局) |
| `max_right_columns` | right_nodes 每行数 |

### OrgBlock 字段

| 字段 | 说明 |
|------|------|
| `position` | `right` / `bottom` / `left` |
| `max_columns` | 块内每行节点数 |
| `row_gap` | 块内换行间距 (minlen) |
| `block_align` | `left` / `center` |
| `edge_from` | 箭头源节点 id |

## 纸张尺寸

| 预设 | 尺寸 |
|------|------|
| a4 | 210×297mm |
| a3 | 297×420mm |
| letter | 8.5×11in |
| 自定义 | `"200,260"` (mm) 或 `"8.5,11in"` |

## 输出文件

| 引擎 | 格式 | 文件 |
|------|------|------|
| D2 | d2 | `name.d2` (源码) + `name_d2.svg` |
| DOT | png, pdf, svg | `name.png`, `name.svg` |
| DOT | html | `name.html` |
| Excalidraw | excalidraw | `name.excalidraw` + `name_ex.png` |

## 项目结构

```
structviz/
├── pyproject.toml
├── README.md
├── examples/
│   ├── equity_sample.yaml
│   ├── org_siku.yaml
│   └── org_bingong.yaml
└── structviz/
    ├── models.py               # Pydantic 模型
    ├── themes.py               # 主题 + 纸张
    ├── cli.py                  # CLI 入口
    ├── render.py               # DOT 渲染
    ├── d2_render.py            # D2 渲染 + 直角后处理
    ├── html_wrapper.py         # HTML 包装
    ├── excalidraw_render.py    # Excalidraw → PNG
    └── generators/
        ├── equity.py           # 股权图 DOT
        ├── org.py              # 组织架构 DOT
        ├── d2.py               # 组织架构 D2
        └── excalidraw.py       # 组织架构 Excalidraw
```

## 许可

MIT
