# fillin-reportsheet

**Repository Path**: GrapeCity-Spreadsheet-Component/fillin-reportsheet

## Basic Information

- **Project Name**: fillin-reportsheet
- **Description**: ReportSheet设计器操作教程中，用于演示填报报表的示例工程。
前端采用Vue3，服务端使用NodeJS，同时包含其它演示视频的测试sjs文件。
可根据工程中的readme启动工程
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-14
- **Last Updated**: 2026-04-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SpreadJS OrdersDataManager 教学Demo

基于 Vue3 + Vite + Node.js + Express 的全栈报表教学工程，集成葡萄城 SpreadJS **Workbook Designer** V19.0.1，专注于订单数据的增删改查和批量操作演示。

---

## 工程结构

```
report-demo/
├── package.json              # 根包，统一启动脚本
├── scripts/
│   └── dev.js                # 并发启动前后端
├── client/                   # 前端 Vue3 工程
│   ├── vite.config.js        # Vite 配置（含代理 + SpreadJS 优化）
│   └── src/
│       ├── main.js           # SpreadJS + Designer 注册 + 中文语言
│       ├── api/
│       │   └── report.js     # 订单接口封装
│       ├── components/
│       │   ├── ReportSheet.vue        # Designer 组件封装
│       │   └── OrdersDataManager.vue  # 订单 DataManager 组件
│       └── views/
│           └── HomeView.vue  # 首页
└── server/                   # 后端 Node.js 工程
    ├── app.js                # Express 入口
    ├── routes/
    │   └── report.js         # 路由定义
    ├── controllers/
    │   └── reportController.js  # 业务逻辑
    └── data/
        └── orders.json       # 订单数据（120条，2025全年）
```

---

## 快速启动

### 环境要求

- Node.js >= 18.0
- npm >= 9.0

### 第一步：安装依赖

```bash
cd report-demo
npm run install:all
```

### 第二步：启动开发服务

```bash
npm run dev
```

终端输出示例：
```
[SERVER] 后端服务运行在 http://localhost:3000
[SERVER] 健康检查: http://localhost:3000/api/health
[CLIENT] VITE v5.x  ready in 800ms
[CLIENT] → Local:  http://localhost:5173/
```

### 第三步：打开浏览器

访问 [http://localhost:5173](http://localhost:5173)

---

## API 接口说明

所有接口基础路径：`http://localhost:3000`

### 健康检查

```
GET /api/health
```

用于验证后端服务是否正常运行。

---

### 订单数据接口

#### 1. 读取订单列表

```
GET /api/report/orders
```

**用途**：获取所有订单数据

**响应格式**：
```json
{
  "data": [...],
  "total": 120
}
```

---

#### 2. 新增订单（autoSync 模式）

```
POST /api/report/orders
```

**用途**：创建新订单（SpreadJS DataManager autoSync 模式）

**请求体**：
```json
{
  "region": "华东",
  "city": "上海",
  "customer": "新客户",
  "category": "食品饮料",
  "amount": 10000
}
```

**响应**：返回创建的完整订单数据（自动生成 order_id）

---

#### 3. 更新订单（autoSync 模式）

```
PUT /api/report/orders
```

**用途**：更新订单数据（SpreadJS Designer URL 配置方式）

**说明**：
- 支持从请求体中获取 `order_id`（SpreadJS Designer URL 配置方式）

**请求体**：
```json
{
  "order_id": "ORD-2025-00001",
  "amount": 20000,
  "status": "已完成"
}
```

---

#### 4. 删除订单（autoSync 模式）

```
DELETE /api/report/orders
```

**用途**：删除订单（SpreadJS Designer URL 配置方式）

**说明**：
- 支持从请求体中获取 `order_id`（单个对象或数组）

**请求体（单个对象）**：
```json
{
  "order_id": "ORD-2025-00001"
}
```

**请求体（数组）**：
```json
[
  { "order_id": "ORD-2025-00001" },
  { "order_id": "ORD-2025-00002" }
]
```

---

#### 5. 批量操作（batch 模式）

```
POST /api/report/datamanager/batch
```

**用途**：SpreadJS DataManager 标准批量操作接口

**说明**：在一次请求中执行多个 insert、update、delete 操作

**请求体**：
```json
[
  {
    "type": "insert",
    "dataItem": {
      "region": "华东",
      "customer": "新客户",
      "amount": 50000
    }
  },
  {
    "type": "update",
    "dataItem": {
      "order_id": "ORD-2025-00001",
      "amount": 60000
    }
  },
  {
    "type": "delete",
    "dataItem": {
      "order_id": "ORD-2025-00002"
    }
  }
]
```

**响应格式**：
```json
[
  { "succeed": true, "data": { "order_id": "ORD-2025-00121", ... } },
  { "succeed": true },
  { "succeed": true }
]
```

---

## SpreadJS Designer URL 配置说明

### autoSync 模式配置

在 SpreadJS Designer 中使用 autoSync 模式时，使用以下 URL：

| 操作 | URL | Method | 说明 |
|------|-----|--------|------|
| read | `/api/report/orders` | GET | 读取数据 |
| create | `/api/report/orders` | POST | 新增订单 |
| update | `/api/report/orders` | PUT | 更新订单（从请求体获取 order_id） |
| delete | `/api/report/orders` | DELETE | 删除订单（从请求体获取 order_id） |

### batch 模式配置

在 SpreadJS Designer 中使用 batch 模式时，使用以下 URL：

| 操作 | URL | Method | 说明 |
|------|-----|--------|------|
| read | `/api/report/orders` | GET | 读取数据 |
| batch | `/api/report/datamanager/batch` | POST | 批量操作（insert/update/delete） |

**重要说明**：
- SpreadJS Designer 不支持在 URL 中配置路径参数（如 `:order_id`）
- autoSync 模式：每次操作立即同步到服务器，适合低频操作
- batch 模式：累积多个操作后手动提交，适合高频操作
- 后端接口已优化，同时支持 URL 路径参数和请求体参数两种方式
- 详细配置指南请参考：
  - [DESIGNER_URL_CONFIG.md](DESIGNER_URL_CONFIG.md) - Designer URL 配置
  - [DATAMANAGER_MODES.md](DATAMANAGER_MODES.md) - 两种模式对比

---

## 其他命令

```bash
# 单独启动前端
npm run client

# 单独启动后端
npm run server
```

---

## 数据说明

| 文件 | 内容 | 条数 | 字段说明 |
|------|------|------|---------|
| `orders.json` | 订单主表 | 120条 | 订单ID、日期、大区、城市、销售员、客户、品类、品牌、金额、成本、利润、数量、状态、渠道等 |

数据覆盖：**2025 全年 12 个月，5 大区，8 位销售员，5 品类**，含双十一销售高峰、春节食品旺季等真实规律。

---

## 相关文档

- [DESIGNER_URL_CONFIG.md](DESIGNER_URL_CONFIG.md) - SpreadJS Designer URL 配置详细指南
- [DATAMANAGER_MODES.md](DATAMANAGER_MODES.md) - DataManager 两种模式配置指南