# Web Report Designer 初期架构设计方案 V1

## 1. 项目定位

项目暂定名称：

```text
Web Report Designer
```

包名暂定：

```text
@xxx/report-core
@xxx/report-designer
@xxx/report-designer-vue
```

项目定位：

> 一个面向业务系统的、纯 Web 的、可嵌入、可扩展、插件式的报表设计与渲染平台。

重点解决：

- 固定版式业务报表
- 打印单据
- A4/A5/自定义纸张
- 主表 + 子表
- 动态明细
- 多页打印
- 页眉页脚
- 分组
- 合计
- 数据绑定
- 表达式
- PDF
- HTML
- 浏览器打印

明确不包含：

```text
BI
Dashboard
OLAP
数据分析
数据立方体
指标体系
大屏
```

------

# 2. 总体架构

整体采用 Monorepo。

```text
report-designer/
│
├── apps/
│   └── report-designer/
│
├── packages/
│   │
│   ├── report-core/
│   │
│   ├── report-expression/
│   │
│   ├── report-layout/
│   │
│   ├── report-renderer/
│   │   ├── html/
│   │   ├── svg/
│   │   └── pdf/
│   │
│   ├── report-designer/
│   │
│   ├── report-designer-vue/
│   │
│   └── plugins/
│       ├── qrcode/
│       ├── barcode/
│       ├── chart/
│       └── ...
│
├── examples/
│
├── pnpm-workspace.yaml
├── package.json
└── README.md
```

核心依赖关系：

```text
                       report-core
                           ▲
             ┌─────────────┼─────────────┐
             │             │             │
       report-expression report-layout renderer
                           ▲
                           │
                    report-designer
                           ▲
                           │
                  report-designer-vue
```

插件：

```text
             report-plugin-qrcode
                      │
             ┌────────┼────────┐
             ▼        ▼        ▼
        report-core  designer renderer
```

------

# 3. 最重要的架构原则

## 3.1 Core 与 UI 完全分离

`report-core`：

```text
纯 TypeScript
无 Vue
无 React
无 DOM
无浏览器 API
无 UI 框架
```

这样可以：

```text
Browser
Node.js
Electron
Server
CLI
```

都使用同一个 Core。

------

## 3.2 Designer 不负责报表业务逻辑

Designer 负责：

```text
选择
拖拽
缩放
对齐
属性编辑
复制粘贴
撤销重做
快捷键
画布
```

Core 负责：

```text
报表模型
数据模型
样式模型
序列化
插件注册
```

Layout 负责：

```text
尺寸计算
换行
表格展开
动态高度
分页
```

Renderer 负责：

```text
HTML
SVG
PDF
```

------

# 4. report-core 目录

初期：

```text
packages/report-core/
│
├── src/
│   │
│   ├── model/
│   │   ├── report.ts
│   │   ├── page.ts
│   │   ├── element.ts
│   │   ├── table.ts
│   │   ├── style.ts
│   │   ├── dataset.ts
│   │   ├── datasource.ts
│   │   ├── parameter.ts
│   │   └── common.ts
│   │
│   ├── plugin/
│   │   ├── plugin.ts
│   │   ├── context.ts
│   │   ├── registry.ts
│   │   ├── element-plugin.ts
│   │   ├── datasource-plugin.ts
│   │   └── exporter-plugin.ts
│   │
│   ├── document/
│   │   ├── create.ts
│   │   ├── clone.ts
│   │   └── normalize.ts
│   │
│   ├── serialization/
│   │   ├── serialize.ts
│   │   ├── deserialize.ts
│   │   └── migrate.ts
│   │
│   ├── schema/
│   │   ├── version.ts
│   │   ├── defaults.ts
│   │   └── validation.ts
│   │
│   ├── utils/
│   │   ├── id.ts
│   │   └── deep.ts
│   │
│   └── index.ts
│
└── tests/
```

------

# 5. ReportDocument

这是整个系统的根。

```ts
export interface ReportDocument {
  schemaVersion: number

  id: string

  name: string

  page: PageSettings

  styles: Record<string, StyleDefinition>

  dataSources: Record<string, DataSource>

  datasets: Record<string, Dataset>

  parameters: Record<string, ReportParameter>

  elements: ReportElement[]

  plugins?: ReportPluginReference[]

  metadata?: ReportMetadata
}
```

其中：

```ts
export interface ReportMetadata {
  author?: string
  description?: string
  createdAt?: string
  updatedAt?: string
}
```

------

# 6. Page 模型

内部建议统一使用物理单位。

```ts
export type ReportUnit =
  | "mm"
  | "pt"
  | "px"
```

默认：

```text
mm
```

Page：

```ts
export interface PageSettings {
  width: number
  height: number

  unit: ReportUnit

  orientation: "portrait" | "landscape"

  margin: PageMargin

  background?: string
}
export interface PageMargin {
  top: number
  right: number
  bottom: number
  left: number
}
```