# 飞书原表导出工作流设计与部署说明

## 目标

在飞书多维表中触发“导出原表格式 Excel”，由云端 Node 服务生成 `.xlsx` 文件，并返回可下载链接。

## 当前已实现的后端接口

线上路径统一挂在：

```text
https://wwyl.yipeng.online/finance/
```

接口：

```text
GET  /finance/health
GET  /finance/api/export/original.xlsx
POST /finance/api/workflow/export
GET  /finance/exports/<fileName>.xlsx
```

`POST /finance/api/workflow/export` 供飞书工作流调用，需要请求头：

```text
Authorization: Bearer <EXPORT_WORKFLOW_TOKEN>
```

返回示例：

```json
{
  "ok": true,
  "fileName": "财务原表格式导出_20260530T170806Z.xlsx",
  "downloadUrl": "https://wwyl.yipeng.online/finance/exports/...xlsx",
  "bytes": 123456
}
```

## 第一版导出策略

第一版优先满足“格式和参考表一致”：

1. 使用 `source/万物有灵项目利润分配表2026_原始参考.xlsx` 作为模板。
2. 生成文件时复制该模板，保留 sheet 名、公式、样式、列宽、冻结、合并等 Excel 原格式。
3. 后续再逐步将飞书多维表结构化数据写回指定单元格/行列，实现“数据来自飞书，格式沿用原表”。

当前第一版的边界：

- 已提供工作流调用接口和可下载 Excel 文件。
- 目前导出的内容等同模板数据；不是完整的“把所有飞书表最新改动重算回 13 个 sheet”。
- 后续需要补充字段到原表单元格的映射规则，尤其是个人/项目组明细、报销、内部调整、双口径公共账户等。

## 飞书多维表建议触发方式

建议新增/使用 `导出请求表`：

字段：

- `请求标题`：文本
- `导出状态`：文本，例如 `待导出`、`导出成功`、`导出失败`
- `下载链接`：文本/URL
- `错误信息`：文本
- `触发时间`：文本/时间

飞书工作流逻辑：

1. 当 `导出请求表` 新增记录，或 `导出状态` 改为 `待导出`；
2. 调用外部 HTTP：`POST https://wwyl.yipeng.online/finance/api/workflow/export`；
3. 请求头带 `Authorization: Bearer <EXPORT_WORKFLOW_TOKEN>`；
4. 解析返回 JSON；
5. 回填当前记录：
   - `导出状态` = `导出成功`
   - `下载链接` = `downloadUrl`
   - 如果失败，`导出状态` = `导出失败`，`错误信息` = 错误信息。

## 环境变量

见 `.env.example`。

生产服务关键值：

```text
TEMPLATE_WORKBOOK_PATH=/srv/studio-finance/current/source/万物有灵项目利润分配表2026_原始参考.xlsx
EXPORT_DIR=/srv/studio-finance/current/exports
PUBLIC_BASE_URL=https://wwyl.yipeng.online/finance
EXPORT_WORKFLOW_TOKEN=<server-secret>
```

## 验收命令

本地：

```bash
npm run typecheck
npm test -- --run
npm run build
```

服务器：

```bash
curl -sS https://wwyl.yipeng.online/finance/health
curl -sS -D /tmp/headers.txt -o /tmp/export.xlsx https://wwyl.yipeng.online/finance/api/export/original.xlsx
file /tmp/export.xlsx
```