---
name: backend-excel
description: Excel 导入导出规范（基于 PhpSpreadsheet）
globs:
  - "core/excel/**/*.php"
---

## 导出

```php
use core\excel\ExcelExportService;

$params = [
    'filename' => '数据导出',
    'sheetName' => '数据导出',
    'format' => 'xlsx',
    'isHeader' => true,
    'fields' => [
        ['field' => 'name', 'title' => '名称'],
        ['field' => 'status', 'title' => '状态'],
    ],
];

ExcelExportService::export($params, static function (callable $chunkHandler): void {
    $chunkHandler([
        ['name' => '名称', 'status' => '启用'],
    ]);
});
```

### 明细数组按行导出

`app\adminapi\controller\Crud::export()` 在写入 Excel 前会调用可覆写的 `expandExportRows(iterable $items)`。当一条主记录包含多个明细（如维修记录的 `parts`）时，在对应控制器覆盖该方法并为每项明细 `yield` 一条数组：主记录字段重复，明细字段取当前项。不要将多项明细拼接成同一个单元格，以保证 Excel 可筛选、复制和统计。

## 导入

```php
use core\excel\ExcelImportService;

$rows = ExcelImportService::import($filePath, [
    'name' => 'required',
    'status' => 'integer',
]);
```

## 检查清单

- [ ] 导出列名是否与数据键名一致
- [ ] 大数据量是否分页导出
- [ ] 导入是否有数据校验
- [ ] 导入是否有事务保护