oneao/workspace

0 Fork 0

Files

T

oneao 182ed86966 20260916231505

2026-09-16 23:15:06 +08:00

5.0 KiB

Raw Blame History

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

1. 项目定位

项目暂定名称：

Web Report Designer

包名暂定：

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

项目定位：

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

重点解决：

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

明确不包含：

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

2. 总体架构

整体采用 Monorepo。

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

核心依赖关系：

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

插件：

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

3. 最重要的架构原则

3.1 Core 与 UI 完全分离

report-core：

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

这样可以：

Browser
Node.js
Electron
Server
CLI

都使用同一个 Core。

3.2 Designer 不负责报表业务逻辑

Designer 负责：

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

Core 负责：

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

Layout 负责：

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

Renderer 负责：

HTML
SVG
PDF

4. report-core 目录

初期：

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

这是整个系统的根。

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
}

其中：

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

6. Page 模型

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

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

默认：

mm

Page：

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
}

5.0 KiB Raw Blame History Unescape Escape